pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
NAME
pfdLoadClipTexture, pfdLoadClipTextureState, pfdClipTextureNodeUpdate -
Read Configuration File to Configure a Clip Texture
FUNCTION SPECIFICATION
#include <Performer/pfdu.h>
pfClipTexture * pfdLoadClipTexture(const char *fileName)
pfClipTexture * pfdLoadClipTextureState(const char *fileName,
pfuClipTexConfig *state)
int pfdClipTextureNodeUpdate(pfTraverser *trav,
void *userData);
DESCRIPTION
pfdClipTextureNodeUpdate is a simple callback function that can be
attached to a node to update a clip texture in a simple incremental way.
This function is designed solely for testing purposes but shows how a
user might use the clip centering api to update a clipmap.
pfdLoadClipTextureState works like pfdLoadClipTexture except that it
takes an additional argument, a pointer to a pfuClipTexConfig structure.
Normally the parser creates and initializes its own pfuClipTexConfig
structure to the default values set by pfuInitClipTexConfig. 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.
pfdLoadClipTexture accepts a string containing the path to a
configuration file describing a pfClipTexture. It configures and creates
a clip texture, and then returns a pointer to it.
A clip texture is a type of texture map used for representing very large
textures. Large clipmap levels are composed of image caches, which
require only a part of a texture level to be in the graphics hardware's
texture memory.
The clip texture configuration file contains a description of the clip
texture, including the locations of the clip texture image files, the
tile files for the smaller levels, as well as the clip texture's size,
format, and other details.
The configuration files are in 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.
Comments start with a comment token. They can start anywhere a token
Page 1
pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
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 that
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, it's data field must be included. The current
implementation requires that the tokens that do appear in the
configuration file follow the ordering shown in the list below.
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.
Clip Texture Configuration Format
ct_version1.0 or ct_version2.0 must be at top of file
ext_format <format string> (external format of stored texels)
int_format <format string> (internal format used by graphics hw)
img_format <format string> (image format of stored texels)
virt_size <int> <int> <int> (size of entire texture)
clip_size <int> (size of square of texture levels in hardware)
*effective_levels <int> (number of effective levels of virtual clip texture)
*allocated_levels <int> (number of levels with texture memory allocated)
*invalid_border <int> (width of clip region perimeter not to use)
*smallest_icache <int> <int> <int> (smallest icache level dimensions)
*icache_base <file path string> (root of icache config filenames)
*icache_format <scanf string> (icache fnames: no field? list files)
*num_icache_params <int> (obsolete; ignored by parser)
*icache_params <string list> (format tokens in order)
*header_offset <int> (byte offset to skip user's tile file headers)
*tile_base <file path string> (root of pyramid tile filenames)
*tile_format <scanf string> (tile fnames: no field? list tile files)
*tile_params <string list> (format tokens in order)
Page 2
pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
*icache_files <list of filenames> (only if icache_format is default )
*tile_files <list of filenames> (pyramid; only if tile_format default)
*tile_size <int> <int> <int> if no image cache config files
*read_func <1 or 2 strings> (custom read function, dso library its in)
*lookahead <int> extra tiles surrounding tex region in mem region
*page_size <int> system memory alignment; improves memory tile allocation
Configuration Details
ct_version1.0 and ct_version2.0 have no corresponding data fields. One
of these tokens must start the configuration file. These tokens allow
programs to determine the type and version of the configuration file.
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.
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.
clip_size takes a single integer argument, which describes the texel
dimensions of the square part of each level of the clip texture kept
resident in hardware texture memory.
invalid_border takes a single integer argument, describing how many
texels the clip size should be shrunk in each dimension. This value is
used to ensure a smooth transition between the clip texture levels.
effective_levels takes a single integer argument, describing how many
effective levels the clipmap should have. Making the number of effective
levels less than the number of virtual levels (log2(virt_size)+1) makes
the clip texture virtual, requiring intelligent runtime setting of the
virtual LOD offset to trade between high precision and high spatial
range. The default value is 16. On InfiniteReality, the maximum number
of effective levels is 16, so a clip texture of size greater than 32Kx32K
is always virtual. Note also that on InfiniteReality, there is a
significant increase in texture memory required when a clip texture is
virtual: every pyramid level, no matter how small, takes up a full
clip_size worth of texture memory.
allocated_levels takes a single integer argument, describing how many
clip texture levels actually have texture memory allocated for them.
Page 3
pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
Virtual cliptextures can only display levels that are allocated in
texture memory. The texture levels are allocated starting from level
zero.
smallest_icache takes three integer values, describing the dimensions of
the smallest icache level in the clip texture. Every level smaller than
these dimensions are described by individual image tile filenames. The s
and t dimensions of smallest_icache must be exactly proportional to the s
and t dimensions of virt_size differing only by a power of two ratio. If
smallest_icache is omitted, the first level whose largest dimension
matches tile_size is the largest image tile level. Thus the maximum
default value of smallest_icache would be clip_size * 2.
icache_base defines the directory path and constant beginning of the
image cache file names. It is a convenience feature, making it easy to
repoint a configuration file to data in a different directory. If
omitted, icache_base defaults to "" (empty string).
The icache_base 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). The icache_base token is
obsolecent; its use is discouraged.
The icache_base field can be a relative pathname. The pathname is
expanded relative to where the configuration file was found.
icache_format is a printf-style string containing a description of the
variable part of the image cache filenames. If you omit icache_format,
you must also omit icache_params, and include icache_files, explicitly
listing all of the image cache files.
If no icache_base is defined, the icache_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 icache_base is defined, the icache_format field can be a relative
pathname. The pathname is expanded relative to where the configuration
file was found.
Page 4
pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
If icache_format is omitted, the default filename string is "%s%s". By
default, this string uses the icache_base for the first argument (or ""
the empty string if there no icache_base argument), followed by one of
the image cache filenames provided by icache_files. The clip texture is
created by using each image cache file name in order, one for each image
cache level. The first image cache filename in icache_files is used for
the first (largest) image cache level in the clip texture.
num_icache_params is obsolete and is ignored by the parser.
icache_params is followed by a whitespace separated list containing some
combination of the following token names:
PFCLIPTEX_FNAMEARG_LEVEL
PFCLIPTEX_FNAMEARG_LEVEL_SIZE
PFCLIPTEX_FNAMEARG_IMAGE_CACHE_BASE
PFCLIPTEX_FNAMEARG_TILE_BASE
The number of items on the list must match 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.
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. The header offset is only applied to the
image tiles described in the cliptexture. Header offsets for the files
used in clip texture's image caches are described in the image cache
configuration files.
tile_base defines the directory path and constant beginning of the image
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.
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).
The tile_base field can be a relative pathname. The pathname is expanded
relative to where the configuration file was found.
Page 5
pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
tile_format is a printf-style string containing a description of the
variable part of the image tile filenames. If you omit icache_format, you
must also omit tile_params, and include tile_files, explicitly listing
all of the image cache files.
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).
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". By
default, this string uses the tile_base for the first argument (or "" the
empty string if there no tile_base argument), followed by one of the
image tile file filenames provided by tile_files. The clip texture is
created by using each image tile filename in order, one for each tile
level. The first tile file filename in tile_files is used for the first
(largest) image tile level in the clip texture.
num_tile_params is obsolete and ignored by the parser.
tile_params is followed by a whitespace separated list containing some
combination of the following token names:
tile_size should be set if the application doesn't use image cache
configuration files. Image cache configuration files can be dispensed
with if the image caches in the cliptexture differ only in size from
level to level. If no image cache config files are supplied, the tile
format supplied in the clip texture configuration file is used to find
disk files for both the image tile levels and the image tiles used in the
configuration files. Image cache configuration files should not be
referenced in the clip texture configuration file if the application
doesn't want to use them.
page_size takes a single integer value. This value is by the system when
allocating image tile texel data memory. The data is aligned to the page
size so that direct i/o reads from disk are possible. Setting the proper
page size value can improve memory usage over the default conservative
value.
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
Page 6
pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
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.
PFCLIPTEX_FNAMEARG_LEVEL
PFCLIPTEX_FNAMEARG_LEVEL_SIZE
PFCLIPTEX_FNAMEARG_IMAGE_CACHE_BASE
PFCLIPTEX_FNAMEARG_TILE_BASE
The number of items on the list must match the number of parameter
specifications in the tile_format string. This list is mandatory if
there are any parameter specifications in the tile_format string.
icache_files is followed by a whitespace separated list of image cache
filenames. This entry should only be present if icache_format is missing.
Each filename in the list is used, in order to create the icache levels
of the cliptexture. They should be ordered from largest to smallest
icache level. The filenames are pre-pended with icache_base before used.
tile_files is followed by a whitespace separated list of image tile file
filenames. This entry should only be present if tile_format is missing.
Each filename in the list is used, in order to create the tile (pyramid)
levels of the cliptexture. They should be ordered from largest to
smallest tile level. The filenames are pre-pended with tile_base before
used.
Example Configuration Files
ct_version2.0
//
// Simple version of clip texture configuration file that uses
// explicit filenames for both image cache and tile (pyramid)
// level filenames.
//
Page 7
pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
// This example defines a 4K by 4K RGB clip texture with 8 bits
// per color component. The maximum area of the clip texture's
// top level is 512 by 512 texels, because the clip_size is 512.
//
ext_format PFTEX_PACK_8 // 8 bits Red, Green and Blue
int_format PFTEX_RGB_8
img_format PFTEX_RGB
virt_size 4096 4096 1
clip_size 512
invalid_border 16 // to get rid of edges
tile_base /usr/share/Performer/data/clipdata/
// NOTE: no icache_base or tile_format or icache_format entries
icache_files
hl.4096.ic
hl.2048.ic
hl.1024.ic
tile_files
hl.512.r000.c000.raw888
hl.256.r000.c000.raw888
hl.128.r000.c000.raw888
hl.64.r000.c000.raw888
hl.32.r000.c000.raw888
hl.16.r000.c000.raw888
hl.8.r000.c000.raw888
hl.4.r000.c000.raw888
hl.2.r000.c000.raw888
hl.1.r000.c000.raw888
ct_version2.0
//
// This is the same clip texture, using automatically generated image
// cache and tile file filenames. Note that there is no icache_files
// or tile_files entries.
//
ext_format PFTEX_PACK_8
int_format PFTEX_RGB_8
img_format PFTEX_RGB
virt_size 4096 4096
clip_size 512
invalid_border 16
icache_base /usr/share/Performer/data/clipdata/hl
icache_format %s.%d.ic
icache_params
PFCLIPTEX_FNAMEARG_ICACHE_BASE
PFCLIPTEX_FNAMEARG_LEVEL_SIZE
tile_base /usr/share/Performer/data/clipdata/hl
Page 8
pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
tile_format %s.%d.r000.c000.raw888
tile_params
PFCLIPTEX_FNAMEARG_TILE_BASE
PFCLIPTEX_FNAMEARG_LEVEL_SIZE
ct_version2.0
// Same clip texture. Putting image caches
// in part of pyramid allows easy adjustment of clip size.
// 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. The same is true for the
// $DATAFIELDS part of tile_base
ext_format PFTEX_PACK_8 // 8 bits Red, Green and Blue
int_format PFTEX_RGB_8
img_format PFTEX_RGB
virt_size 4096 4096 1
clip_size 512
invalid_border 16 // to get rid of hard edges
smallest_icache 32 32 1
icache_base ${DATAFIELDS}/usr/share/Performer/data/clipdata/
icache_format %shl.%d.ic
icache_params
PFCLIPTEX_FNAMEARG_ICACHE_BASE
PFCLIPTEX_FNAMEARG_LEVEL_SIZE
tile_base $DATAFIELDS/usr/share/Performer/data/clipdata/
tile_format %shl.%d.r000.c000.raw888
tile_params
PFCLIPTEX_FNAMEARG_TILE_BASE
PFCLIPTEX_FNAMEARG_LEVEL_SIZE
ct_version2.0
ext_format PFTEX_PACK_8 # 8 bits Red, Green and Blue
int_format PFTEX_RGB_8
img_format PFTEX_RGB
virt_size 4096 4096 1
clip_size 512
invalid_border 16 # to get rid of hard edges
smallest_icache 64 64 1
tile_base $PFCLIPDATA
tile_size 512 512 1
tile_format %s/hl.%d.r%03d.c%03d.raw888
tile_params
PFIMAGECACHE_TILE_FILENAMEARG_CACHENAME
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_S
PFIMAGECACHE_TILE_FILENAMEARG_FILENUM_T
PFIMAGECACHE_TILE_FILENAMEARG_FILENUM_S
Page 9
pfdLoadClipTexture(3pf) OpenGL Performer 3.2.2 libpfdu Reference Pages
ct_version2.0
ext_format PFTEX_UNSIGNED_SHORT_5_5_5_1 # 5 bits Red, Green, Blue, 1 Alpha
int_format PFTEX_RGB5_A1
img_format PFTEX_RGBA
virt_size 4096 4096 1
clip_size 512
invalid_border 16 # to get rid of hard edges
smallest_icache 64 64 1
icache_base $PFCLIPDATA
icache_format %s/hl.%d.5551.ic
icache_params
PFCLIPTEX_FNAMEARG_IMAGE_CACHE_BASE
PFCLIPTEX_FNAMEARG_LEVEL_SIZE
tile_base $PFCLIPDATA
tile_format %s/hl.%d.r000.c000.raw5551
tile_params
PFCLIPTEX_FNAMEARG_TILE_BASE
PFCLIPTEX_FNAMEARG_LEVEL_SIZE
NOTES
ClipTexture functionality is not supported under Linux.
BUGS
The parser that reads configuration files is very limited. In particular,
it only allows comments where it would be expecting a token.
The the use of cliptexture configuration files without image cache
configuration files is not well tested.
SEE ALSO
pfImageCache, pfMPImageCache, pfClipTexture, pfMPClipTexture, pfTexture,
pfLoadClipTexture
Page 10
