pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
NAME
pfdImageCacheNodeUpdate, pfdLoadImageCache, pfdLoadImageCacheState - Read
Configuration File to Configure an Image Cache
FUNCTION SPECIFICATION
#include <Performer/pfdu.h>
int pfdImageCacheNodeUpdate(pfTraverser *trav,
void *userData);
pfImageCache * pfdLoadImageCache(const char *fileName,
pfTexture *texture, int level)
pfImageCache * pfdLoadImageCacheState(const char *fileName,
pfTexture *texture, int level,
pfuImgCacheConfig *state)
DESCRIPTION
pfdImageCacheNodeUpdate is a simple callback function that can be
attached to a node to update an image cache in a simple incremental way.
This function is designed solely for testing purposes but shows how a
user might use the image cache centering api to update a pfImageCache.
pfdLoadImageCacheState works like pfdLoadImageCache except that it takes
an additional argument, a pointer to a pfuImgCacheConfig structure.
Normally the parser creates and initializes its own pfuImgCacheConfig
structure to the default values set by pfuInitImgCacheConfig. This
function uses the the structure passed by the state parameter as its
starting point. This allows the application to set its own state values
programmatically, and use the parser to fill in the remaining ones. The
parser doesn't check the state values, so it will overwrite a value set
in the state structure if it encounters the corresponding token in its
config file.
pfdLoadImageCache accepts the string fileName containing the path to a
configuration file describing a pfImageCache (an IC). It configures and
loads level level of the pfTexture texture with the Image Cache
information.
An Image Cache is a roamable texture level. It allows OpenGL Performer to
roam through a texture much larger than can be held in hardware texture
memory. Image caches are also used as levels of ClipTextures.
An Image Cache is composed of pfImageTiles arranged in a rectangular
grid. Each image tile in an image cache has a fixed size and format. The
texel dimensions of the entire Image Cache is the Cache's ICache Size.
Only a subset of the Image Cache tiles are kept in system memory at any
given time. The number of tiles in memory is described by the Mem Region
Size. A subset of texels in system memory are loaded into the graphics
hardware. This subset is called the Tex Region and is measured in texels.
Both the mem region and tex region and be dynamically resized and
translated to roam the image cache.
Page 1
pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
The Image Cache Configuration File contains descriptions and locations of
the files containing the image cache, the dimensions of various sizes,
and information on mapping tiles within the cache to stream devices
containing the cache's texel data.
The configuration files contain a tokenized format; Each data field is
identified by a token followed by the data. The version token must start
the configuration file. It allows configuration files to be automatically
classified. The current implementation requires that tokens be surrounded
by whitespace. All tokens other than the version token can be in
arbitrary order in the file, but the data associated with a token must
immediately follow it.
Comments start with a comment token. They can start anywhere a token
would expected, except before the version token. There are a number of
different comment tokens, for stylistic convenience. They are:
"#" (shell-style comment)
"//" (C++ style comment)
";" (LISP-style comment)
"comment" (ALGOL-style comment)
"rem" (BASIC-style comment for die-hards)
A comment starts with a comment token and continues until the end of the
current line.
Some tokens and their data fields may be omitted if the default value is
desired. These are marked with asterisks (*) in the list below. If a
token is in the file, its data field must be included.
Some tokens form groups. Tokens that are normally optional may not be if
another token in it's group is specified with a non-default value. The
interdependencies are described below.
Image Cache Configuration Format
Version 1.0
ic_version1.0 <no data field> (starts file: identify and version)
ext_format <string> (external format of stored texels)
int_format <string> (internal format used by graphics hw)
img_format <string> (image format of stored texels)
virt_size <int> <int> <int> (width, height, depth of icache in texels)
cache_size <int> <int> <int> (number of rows and columns of tiles in memory)
valid_region <int> <int> <int> (area x, y, z in texels in texture h/w)
Page 2
pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
*header_offset <int> (byte offset to skip user's file header)
*tiles_in_file <int> <int> <int> (image tile arrangement in each file)
tile_size <int> <int> <int> (width, height, depth in texels of tile)
*tile_base <file path string> (root of tile filenames)
*tile_format <scanf string> (tile filename format)
*num_tile_params <int> (number of parameter token arguments)
*tile_params <string list> (format parameter tokens in order)
*num_streams <int> <int> <int> (number of s, t, and r stream servers)
*s_streams <string list> (list of S stream servers)
*t_streams <string list> (list of T stream servers)
*r_streams <string list> (list of R stream servers)
*default_tile <file path string> (use this one if tile missing)
Version 2.0
ic_version2.0 <no data field> (starts file: identify and version)
ext_format <string> (external format of stored texels)
int_format <string> (internal format used by graphics hw)
img_format <string> (image format of stored texels)
icache_size <int> <int> <int> (s, t, r texel size of icache)
mem_region_size <int> <int> <int> (s, t, r sizes of tile array)
tex_region_size <int> <int> <int> (s, t, r texel sizes of tex region)
*header_offset <int> (byte offset to skip user's file header)
*tiles_in_file <int> <int> <int> (image tile layout in each file)
tile_size <int> <int> <int> (s, t, r texel size of each tile)
*tile_base <file path string> (root of tile filenames)
*tile_format <scanf string> (tile filename format)
*num_tile_params <int> (number of parameter token arguments)
*tile_params <string list> (format parameter tokens in order)
*s_streams <string list> (list of S stream servers)
*t_streams <string list> (list of T stream servers)
*r_streams <string list> (list of R stream servers)
*read_func <1 or 2 strings> (custom read function, dso library its in)
*lookahead <int> extra tiles surrounding tex region in mem region
*default_tile <file path string> (use this one if tile missing)
Configuration Details
Page 3
pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
ic_version1.0 and ic_version2.0 have no corresponding data fields. One
or the other must start the configuration file. This token allows
programs to determine the type and version of the configuration file. The
parser will read both version1 and version2 files. We recommend you
convert to version2.
ext_format expects a performer external format type. This can be a token
name, such as PFTEX_PACK_8, or a numeric value.
int_format expects a performer internal format type. This can be a token
name, such as PFTEX_RGB_8, or a numeric value.
img_format expects a performer image format type. This can be a token
name, such as PFTEX_RGB, or a numeric value.
icache_size (was virt_size) takes three integer arguments, which describe
the s, t, and r dimensions of the entire image cache, measured in texels.
This value is mandatory.
mem_region_size (was cache_size) takes three integer arguments, which
describe the number of tiles to keep cached in system memory. They
describe the number of tiles in the s, t, and are dimensions, in units of
tiles. Note that the mem_region_size multiplied by tile_size should not
exceed the icache__size, for any dimension. This value is mandatory.
tex_region_size (was valid_region) takes three integer arguments, s, t,
and r, describing the dimensions of the texture region of the image cache
(the region that should be kept in in hardware texture memory). This
value is mandatory.
header_offset is the size, in bytes, of any application-specific header
information at the beginning of each file. If there is no application
header information, this value should be set to 0, which is the default
value if this field is omitted.
tiles_in_file takes three integers, s, t, and r, describing the layout of
tiles in each image tile file. Each component describes the number of
tiles in each dimension, in units of tiles. The tiles are stored in the
tiles in row-order. If this field is omitted, the s, t, and r values all
default to 1, indicating a single tile in each file.
tile_size takes three integers, s, t, and r, describing the dimensions of
each tile that makes up the image cache, in units of texels. All tiles in
the image cache must be this.
tile_base defines the directory path and constant beginning of the image
cache tile filenames. It is a convenience feature, making it easy to
repoint a configuration file to data in a different directory. If
omitted, tile_base defaults to "" (empty string). The tile_base token is
obsolecent; its use is discouraged.
The tile_base field can start with an optional environment variable name.
Page 4
pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
The environment variable name must start the field, and start with a '$'
(dollar sign) character. The environment variable name can be delineated
in the usual way, using parenthesis or braces; for example $(FNAME) or
${FNAME}. The $FNAME style format can be used if the variable name is
unambiguous in the field. The environment variable name will be replaced
by its value in the field. If the variable is undefined, it will be
expanded to "" (the empty string). To specify a default value to be used
in the case that the variable is not set, use the form ${FNAME:-DEFAULT}
or $(FNAME:-DEFAULT).
The tile_base field can be a relative pathname. The pathname is expanded
relative to where the configuration file was found.
tile_format is a printf-style string containing a description of the
variable part of the image cache tile filenames. If you omit tile_format
you must also omit num_tile_params and tile_params, and accept the
default filename format.
If no tile_base is defined, the tile_format field can start with an
optional environment variable name. The environment variable name must
start the field, and start with a '$' (dollar sign) character. The
environment variable name can be delineated in the usual way, using
parenthesis or braces; for example $(FNAME) or ${FNAME}. The $FNAME
style format can be used if the variable name is unambiguous in the
field. The environment variable name will be replaced by its value in the
field. If the variable is undefined, it will be expanded to "" (the empty
string). To specify a default value to be used in the case that the
variable is not set, use the form ${FNAME:-DEFAULT} or $(FNAME:-DEFAULT).
If no tile_base is defined, the tile_format field can be a relative
pathname. The pathname is expanded relative to where the configuration
file was found.
If tile_format is omitted, the default filename string is
"%s%s.%d.r%03d.c%03d.raw888". By default, this string uses the following
arguments in order:
PFIMAGECACHE_TILE_FILENAMEARG_STREAMSERVERNAME
This token indicates that the corresponding %s segment of the
filepath will be filled in by calculating the appropriate stream
path. Streams are selected as a function of the tile's s, t, r tile
coordinates in the image cache.
PFIMAGECACHE_TILE_FILENAMEARG_CACHENAME
This token indicates that the corresponding %s segment of the
filepath will be filled in from the string associated with the
tile_base token. Any environment variables in the base string will
be expanded.
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_S
This token indicates that the corresponding %d segment of the
filename will be filled with the size of the image cache in its S
Page 5
pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
dimension.
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_T
This token indicates that the corresponding %03d segment of the
filename will be filled with the T coordinate of the file's
corresponding tile location in the image cache.
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_S
This token indicates that the corresponding %03d segment of the
filename will be filled with the S coordinate of the file's
corresponding tile location in the image cache.
num_tile_params is followed by an integer listing the number of data
elements used by icache_format. It should match the number of format
parameters (%parameter_specification) in the format string. This value is
mandatory if there are any parameter specifications in the tile_format
string.
tile_params is followed by a whitespace separated list containing some
combination of the following token names:
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_S
Corresponds to the size of the image cache in the S dimension.
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_T
Corresponds to the size of the image cache in the T dimension.
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_R
Corresponds to the size of the image cache in the R dimension.
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_S
Corresponds to the S coordinate of the file's corresponding tile
location (in tile coordinates) in the image cache.
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_T
Corresponds to the T coordinate of the file's corresponding tile
location (in tile coordinates) in the image cache.
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_R
Corresponds to the R coordinate of the file's corresponding tile
location (in tile coordinates) in the image cache.
PFIMAGECACHE_TILE_FILENAMEARG_TILEORG_S
Corresponds to the S texel coordinate of the file's corresponding
tile origin in the image cache.
PFIMAGECACHE_TILE_FILENAMEARG_TILEORG_T
Corresponds to the T texel coordinate of the file's corresponding
tile origin in the image cache.
PFIMAGECACHE_TILE_FILENAMEARG_TILEORG_R
Page 6
pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
Corresponds to the R texel coordinate of the file's corresponding
tile origin in the image cache.
PFIMAGECACHE_TILE_FILENAMEARG_STREAMSERVERNAME
Corresponds to the appropriate stream pathname. The stream pathname
is a function of the file's corresponding tile's location in the
image cache. If streams aren't specified, it defaults to the empty
string.
PFIMAGECACHE_TILE_FILENAMEARG_CACHENAME
Corresponds to the string associated with the tile_base token. If
not specified, it defaults to the empty string.
PFIMAGECACHE_TILE_FILENAMEARG_FILENUM_S
Corresponds to the S coordinate of the file's corresponding origin
tile location (in tile coordinates) in the image cache. This value
will differ from PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_S if there
are multiple tiles per file in the S direction.
PFIMAGECACHE_TILE_FILENAMEARG_FILENUM_T
Corresponds to the T coordinate of the file's corresponding origin
tile location (in tile coordinates) in the image cache. This value
will differ from PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_T if there
are multiple tiles per file in the T direction.
PFIMAGECACHE_TILE_FILENAMEARG_FILENUM_R
Corresponds to the R coordinate of the file's corresponding origin
tile location (in tile coordinates) in the image cache. This value
will differ from PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_R if there
are multiple tiles per file in the R direction.
The number of items on the list must match the value of num_icache_params
and the number of parameter specifications in the icache_format string.
This list is mandatory if there are any parameter specifications in the
icache_format string.
num_streams is now obsolete, and ignored by the parser. The number of
streams in s, t, and r are computed directly by the parser. For high-
performance applications, the texel data for an image cache can be spread
out over a number of stream devices (disks). The image cache determines
which disk the access by using each tile's grid position, in s, t, and r
coordinates, in units of tiles. The tile's s, t, and r position, modulo
the corresponding s t or r number from num_streams, is used to determine
the stream device needed to load that tile.
The numbering can be such that more than one stream device may contain
the information for a given tile. In this case, the least busy stream
device is accessed.
s_streams, t_streams, and r_streams are each followed by a whitespace-
separated list of pathnames, corresponding to the appropriate dimension.
The number of pathnames in each list must exactly match the corresponding
Page 7
pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
component of num_streams.
The stream server pathnames are accessed by
PFIMAGECACHE_TILE_FILENAMEARG_STREAMSERVERNAME if it is used by the
tile_format filename string (as it is by the default format string). If
no stream server pathnames have been specified, the default pathname is
"" (the empty string).
default_tile is followed by the filename of the file to use if the image
cache can't find a file using the filename format. It can be used to fill
out an image cache. If this field is missing, there is no default tile.
This field is prepended with tile_base before used.
lookahead takes a single integer, which indicates the number of extra
rows and columns of (beyond the amount needed to cover the tex region)
tiles used to compute the mem region size. The configuration system uses
the mem region size if it is supplied, or computes the size based on the
tile size and tex region size. It chooses a mem region size so that the
tex region can be covered, even if it is not aligned with the tile
boundaries.
The default lookahead value 1 one, which means there is an extra row and
column of tiles in the mem region beyond the minimum required to prevent
errors. Setting a lookahead value in the cliptexture configuration file
sets the lookahead for all the cliptexture's image caches, unless the
value is set in an image cache config file. In that case, the image cache
lookahead value takes precidence for that image cache.
read_func takes one or two arguments. If the custom read function is in
the application's executable, then a single argument giving the function
name is sufficient. Otherwise two arguments should be provided, one for
the DSO library containing the custom read function, the second being the
function name itself. If supplied the custom read function will be used
in place of the default in the clip texture's read queue.
Example Configuration Files
ic_version2.0
//
// Simple configuration File. RGB, 8 bits per pixel. Using default
// values for most optional fields. 1 tile per file, and all of
// image cache texture is stored in system memory, in a 4 by 4 grid
// of 512 x 512 tiles.
//
ext_format PFTEX_PACK_8
int_format PFTEX_RGB_8
img_format PFTEX_RGB
icache_size 2048 2048 1
mem_region_size 4 4 1
tex_region_size 512 512 1
tile_size 512 512 1
Page 8
pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
tile_base /usr/share/Performer/data/clipdata/hl
ic_version2.0
//
// More elaborate version of the same configuration file.
// icache format and parameters are the same as the default.
// stream servers, since they are not listed, default to
// "" (empty string).
//
ext_format PFTEX_PACK_8
int_format PFTEX_RGB_8
img_format PFTEX_RGB
icache_size 2048 2048 1
mem_region_size 4 4 1
tex_region_size 512 512 1
tile_size 512 512 1
tile_base /usr/share/Performer/data/clipdata/hl
tile_format %s%s.%d.r%03d.c%03d.raw888
num_tile_params 5
tile_params
PFIMAGECACHE_TILE_FILENAMEARG_STREAMSERVERNAME
PFIMAGECACHE_TILE_FILENAMEARG_CACHENAME
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_S
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_T
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_S
ic_version2.0
// This example assumes there are a number disks mounted
// under /usr/{s,t}disks{0,1}. That contains multiple copies
// of the image tile files. This type of configuration allows
// higher disk bandwidth.
// The $(DATAFIELDS) part of the icache_base field will be
// replaced with the current value of DATAFIELDS environment
// variable, or removed if the variable isn't defined.
ext_format PFTEX_PACK_8
int_format PFTEX_RGB_8
img_format PFTEX_RGB
icache_size 2048 2048 1
mem_region_size 4 4 1
tex_region_size 512 512 1
tile_size 512 512 1
tile_base $DATAFILES/usr/share/Performer/data/clipdata/hl
tile_format %s%s.%d.r%03d.c%03d.raw888
num_tile_params 5
tile_params
PFIMAGECACHE_TILE_FILENAMEARG_STREAMSERVERNAME
PFIMAGECACHE_TILE_FILENAMEARG_CACHENAME
Page 9
pfdLoadImageCache(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_S
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_T
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_S
s_streams
/usr/sdisks0
/usr/sdisks1
t_streams
/usr/tdisks0
/usr/tdisks1
/usr/tdisks1
BUGS
The parser that reads configuration files is very limited. In particular,
it only allows comments where it would be expecting a token.
SEE ALSO
pfImageCache, pfMPImageCache, pfClipTexture, pfMPClipTexture, pfTexture,
pfdLoadClipTexture
Page 10
