pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfNewImageCache, pfGetImageCacheClassType, pfImageCacheName,
pfGetImageCacheName, pfImageCacheImageSize, pfGetImageCacheImageSize,
pfImageCacheProtoTile, pfGetImageCacheProtoTile,
pfImageCacheMemRegionSize, pfGetImageCacheMemRegionSize,
pfGetImageCacheCurMemRegionSize, pfImageCacheMemRegionOrg,
pfGetImageCacheMemRegionOrg, pfGetImageCacheCurMemRegionOrg,
pfImageCacheTexRegionSize, pfGetImageCacheTexRegionSize,
pfGetImageCacheCurTexRegionSize, pfImageCacheTexRegionOrg,
pfGetImageCacheTexRegionOrg, pfGetImageCacheCurTexRegionOrg,
pfGetImageCacheTexRegionOffset, pfImageCacheTex, pfGetImageCacheTex,
pfImageCacheTexSize, pfGetImageCacheTexSize, pfImageCacheReadQueueFunc,
pfImageCacheTileFileNameFunc, pfGetImageCacheReadQueueFunc,
pfGetImageCacheTileFileNameFunc, pfImageCacheFileStreamServer,
pfGetImageCacheFileStreamServer, pfImageCacheStreamServerQueue,
pfGetImageCacheStreamServerQueue, pfGetImageCacheStreamServerQueueByName,
pfImageCacheTileFileNameFormat, pfGetImageCacheTileFileNameFormat,
pfGetImageCacheNumStreamServers, pfImageCacheMode, pfGetImageCacheMode,
pfGetImageCacheLoadUpdates, pfIsImageCacheValid, pfIsValidImageCache,
pfApplyImageCache, pfDTRApplyImageCache, pfImageCacheMaster,
pfGetImageCacheMaster, pfGetImageCacheSlaves, pfGetImageCacheTile,
pfInvalidateImageCache, pfImageCacheCalcTexRegion,
pfImageCacheCalcMemRegion, pfImageCacheDTRMode, pfGetImageCacheDTRMode,
pfIsImageCacheTexRegChanged - Create, modify and update a multilevel
tiled cache useful for roaming through large tiled images by continuously
updating a rectangular image representing one valid region of the image.
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfImageCache * pfNewImageCache(void *arena);
pfType * pfGetImageCacheClassType(void);
void pfImageCacheName(pfImageCache* imagecache,
const char *name);
const char * pfGetImageCacheName(pfImageCache* imagecache);
void pfImageCacheImageSize(pfImageCache* imagecache, int sizeS,
int sizeT, int sizeR);
void pfGetImageCacheImageSize(pfImageCache* imagecache,
int *sizeS, int *sizeT, int *sizeR);
void pfImageCacheProtoTile(pfImageCache* imagecache,
pfImageTile *tile);
pfImageTile * pfGetImageCacheProtoTile(pfImageCache* imagecache);
Page 1
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfImageCacheMemRegionSize(pfImageCache* imagecache,
int nTilesS, int nTilesT, int nTilesR);
void pfGetImageCacheMemRegionSize(pfImageCache* imagecache,
int *nTilesS, int *nTilesT, int *nTilesR);
void pfGetImageCacheCurMemRegionSize(pfImageCache* imagecache,
int *nTilesS, int *nTilesT, int *nTilesR);
void pfImageCacheMemRegionOrg(pfImageCache* imagecache, int s,
int t, int r);
void pfGetImageCacheMemRegionOrg(pfImageCache* imagecache,
int *s, int *t, int *r);
void pfGetImageCacheCurMemRegionOrg(pfImageCache* imagecache,
int *s, int *t, int *r);
void pfImageCacheTexRegionSize(pfImageCache* imagecache,
int sizeS, int sizeT, int sizeR);
void pfGetImageCacheTexRegionSize(pfImageCache* imagecache,
int *sizeS, int *sizeT, int *sizeR);
void pfGetImageCacheCurTexRegionSize(pfImageCache* imagecache,
int *sizeS, int *sizeT, int *sizeR);
void pfImageCacheTexRegionOrg(pfImageCache* imagecache, int s,
int t, int r);
void pfGetImageCacheTexRegionOrg(pfImageCache* imagecache,
int *s, int *t, int *r);
void pfGetImageCacheCurTexRegionOrg(pfImageCache* imagecache,
int *s, int *t, int *r);
void pfGetImageCacheTexRegionOffset(pfImageCache* imagecache,
int *s, int *t, int *r);
void pfImageCacheTex(pfImageCache* imagecache, void *dst,
int lvl, int type);
void pfGetImageCacheTex(pfImageCache* imagecache, void **dst,
int *lvl, int *type);
void pfImageCacheTexSize(pfImageCache *imagecache, int s,
int t, int r);
void pfGetImageCacheTexSize(pfImageCache *imagecache, int *s,
int *t, int *r);
Page 2
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfImageCacheReadQueueFunc(pfImageCache* imagecache,
pfImageCacheReadQueueFuncType func);
void pfImageCacheTileFileNameFunc(pfImageCache* imagecache,
pfImageCacheTileFileNameFuncType func);
pfImageCacheReadQueueFuncType
pfGetImageCacheReadQueueFunc(pfImageCache* imagecache);
pfImageCacheTileFileNameFuncType
pfGetImageCacheTileFileNameFunc(pfImageCache* imagecache);
void pfImageCacheFileStreamServer(pfImageCache* imagecache,
int dim, int which, const char *device);
const char * pfGetImageCacheFileStreamServer(pfImageCache* imagecache,
int dim, int which);
void pfImageCacheStreamServerQueue(pfImageCache* imagecache,
int dim, int which, pfQueue *q);
pfQueue * pfGetImageCacheStreamServerQueue(pfImageCache* imagecache,
int dim, int which);
pfQueue * -
pfGetImageCacheStreamServerQueueByName(pfImageCache* imagecache,
const char *name);
void pfImageCacheTileFileNameFormat(pfImageCache* imagecache,
const char *fmtString, int nArgs, int *argList);
void -
pfGetImageCacheTileFileNameFormat(pfImageCache* imagecache,
const char **fmtString, int *nArgs,
const int **argList);
int pfGetImageCacheNumStreamServers(pfImageCache* imagecache,
int dim);
void pfImageCacheMode(pfImageCache* imagecache, int mode,
int val);
int pfGetImageCacheMode(pfImageCache* imagecache, int mode);
const pfList * pfGetImageCacheLoadUpdates(pfImageCache* imagecache);
int pfIsImageCacheValid(pfImageCache* imagecache, int s,
int t, int r, int sizeS, int sizeT, int sizeR);
int pfIsValidImageCache(void);
Page 3
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfApplyImageCache(pfImageCache* imagecache);
void pfDTRApplyImageCache(pfImageCache* imagecache,
float *time);
void pfImageCacheMaster(pfImageCache* master);
pfImageCache * pfGetImageCacheMaster(void);
pfList * pfGetImageCacheSlaves(void);
pfImageTile * pfGetImageCacheTile(int s, int t, int r);
void pfInvalidateImageCache(void);
void pfImageCacheCalcTexRegion(int *_orgS, int *_orgT,
int *_orgR, int *_sizeS, int *_sizeT, int *_sizeR);
void pfImageCacheCalcMemRegion(int *_orgS, int *_orgT,
int *_orgR, int *_sizeS, int *_sizeT, int *_sizeR);
void pfImageCacheDTRMode(pfImageCache *imagecache, uint mode);
uint pfGetImageCacheDTRMode(pfImageCache *imagecache);
int pfIsImageCacheTexRegChanged(pfImageCache *imagecache);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfImageCache is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfImageCache. Casting an object of
class pfImageCache to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfImageCache can also be used with these
functions designed for objects of class pfMemory.
Page 4
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
DESCRIPTION
A pfImageCache allows a selected subset of an arbitrarily large tiled
image to be cached in main memory and incrementally updated from disk or
other file system devices as the origin of the selected subset is
changed.
The basic notion of a pfImageCache is to hold an MxNxO grid of tiles in
main memory while providing access to the complete set of tiles on disk
as needed. Further, pfImageCache's support the ability to define a valid
region within the currently valid portion of the pfImageCache. This
valid region is of a certain size and can be roamed independently of the
tile boundaries defined by the disk-based tiles in which the image is
stored. This valid region is also represented in texture memory and is
efficiently updated in a toroidal manner through simple calls defining
the new origin of the valid region. In use, a pfImageCache is a
multilevel cache used to roam a valid 'region' or 'window' through a
large virtual texture via a texture memory cache of the current window
and a main memory cache consisting of a slightly larger tiled rectangular
region where this region is constantly being updated by bring new tiles
from disk to main memory.
pfNewImageCache creates and returns a handle to a new pfImageCache.
arena specifies a malloc arena from which the pfImageCache is allocated
or NULL for allocation from the calling process' heap. pfImageCaches can
be deleted with pfDelete.
pfGetImageCacheClassType returns the pfType* for the class pfImageCache.
The pfType* returned by pfGetImageCacheClassType is the same as the
pfType* returned by invoking pfGetType on any instance of class
pfImageCache. When decisions are made based on the type of an object, it
is usually better to use pfIsOfType to test if an object is of a type
derived from a Performer type rather than to test for strict equality of
the pfType*'s.
pfImageCacheName sets the name of the pfImageCache to name while
Page 5
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfGetImageCacheName returns the name of the pfImageCache.
pfImageCache CACHE CONFIGURATION
pfImageCacheImageSize sets the image size to be represented by the
pfImageCache. This image size is specified in texels and must be some
multiple of the tile size for the pfImageCache. This size is specified
in texels. pfGetImageCacheImageSize returns the virtual size of the
pfImageCache. Any of the arguments s,t,r may be NULL in which case it
will be ignored.
pfImageCacheProtoTile sets the prototype for the pfImageTiles that will
be used to store the image information within the pfImageCache. This
tile will be copied and assigned a specific cached subregion of the image
represented by the pfImageCache. pfGetImageCacheProtoTile returns the
prototypical tile used to store information within the pfImageCache.
pfImageCacheMemRegionSize sets the size of the memory region of image
within the pfImageCache. Thus the cache size is specified in terms of
the number of prototype tiles specified via pfImageCacheProtoTile in each
dimension of the cache. pfGetImageCacheMemRegionSize will return the
last size values set by the application in each dimension of the
pfImageCache. This size is specified in terms of the number of
prototypical pfImageTiles required to specify the cache. Any of the
pointer arguments nTilesS, nTilesT, nTilesR may be NULL, which indicates
the application is not interested in those values.
Since there is some latency between size values being set used,
pfGetImageCurMemRegionSize returns the mem region size currently in use.
As an example, a pfImageCache might be configured to an image size
32768x32768x1 with a prototypical tile that had size of 512x512x1 and a
cache size of 4x4x1. Such a cache would always contain a 2048x2048x1
image in the cache by holding a grid of 4x4x1 pfImageTiles where each
pfImageTile represented a specific 512x512x1 subregion which was loaded
independently.
pfImageCacheMemRegionOrg sets the current origin (specified in terms of
the number of prototypical tiles from the lower left corner of the image)
for the pfImageCache. Changing this origin will cause incremental
loading of pfImageTiles based on the previous origin and size of the
pfImageCache, verses the new origin and size of the pfImageCache's memory
region. pfGetImageCacheMemRegionOrg returns the last origin values set
by the application of the pfImageCache's memory region. Any of the
pointer arguments nTilesS, nTilesT, nTilesR may be NULL, in which
indicates that the application is not interested in their values.
Since there is some latency between origin values being set and used,
pfGetImageCurMemRegionOrg returns the mem region origin currently in use.
Page 6
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfImageCache TEXTURE REGION
Each pfImageCache contains a destination texture region which is the
region that is to be present in texture memory. This 'tex region' is
defined by a size and origin which define the subset of the image
represented by the pfImageCache to be held in texture memory. The tex
region also has a destination pfTexture and texture level that define how
to update the tex region as its origin changes. If the tex region origin
has changed when a pfImageCache is applied, then a list of incremental
texture loads are generated that will update the tex region in texture
memory. These updates are aligned on tile and texture boundaries and are
set up to update the destination texture in a toroidal fashion. In this
way, only the difference in texture between the previous valid region and
the current one need to be loaded for any given apply operation. The
list of loads corresponding to the aforementioned difference is applied
to the appropriate level of the destination texture when the pfImageCache
is applied. Note that the loading the texture toroidally requires the
notion of an offset to accounted for in the current origin within the
texture. This origin can be used to set the gl Texture matrix such that
the toroidal nature of the texture loading is not visible to the user.
pfImageCacheTex sets the destination texture and texture level for the
pfImageCache. Currently only pfTextures are supported as valid
destination and so dstType must be set to PFTLOAD_DST_TEXTURE. Note that
this texture will be incrementally updated to contain the 'tex region'
within the pfImageCache. pfGetImageCacheTex returns the current
destination texture, texture level, and type for the texture region for
the pfImageCache. Any of the arguments dst,level,type may be NULL, in
which case it will be ignored.
pfImageCacheTexSize sets the size in texels of the destination texture
that the pfImageCache will write into. This destination size should be
set to the full level size for destination pfTexture. Note that this
size is completely independent from the texture region size which
represents the amount of texture being updated during every frame in the
texture cache. pfGetImageCacheTexSize returns the size of the
destination texture level that the pfImageCache modifies. Any of the
pointer arguments s, t, and r may be NULL, which indicates that the
application is not interested in the results.
pfImageCacheTexRegionSize sets the size in texels of the texture region
for the pfImageCache. This size should be no larger than the destination
texture level for the texture region. Changing this size can be used to
control load by decreasing the size of the cached piece of texture in
texture memory. pfGetImageCacheTexRegionSize returns the last size
values of the texture region for the pfImageCache set by the application
(or the default if they were never set). Any of the pointer arguments
sizeS, sizeT, and sizeR may be NULL, which indicates that the application
is not interested in those values.
Since there is some latency between size values being set and used,
pfGetImageCurTexRegionSize returns the tex region size currently in use.
Page 7
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfImageCacheTexRegionOrg is used to control the origin of the texture
region that should be represented in texture memory. The new origin for
the texture region is not applied until pfApplyImageCache is called.
pfGetImageCacheTexRegionOrg return the latest setting of the
forementioned origin of the current texture region for the pfImageCache.
Any of the pointer arguments s, t, and r may be NULL, which indicates
that the application is not interested in those values.
Since there is some latency between origin values being set and used,
pfGetImageCurTexRegionOrg returns the tex region origin currently in use.
pfGetImageCacheTexRegionOffset get the current toroidal offset used in
represent the texture region in the destination texture. Any of the
arguments s,t,r may be NULL, in which case it will be ignored. The
offset is implied solely by the position of the texture region origin and
thus there is no way to set the texture region offset. To display an
pfImageCache as a single contiguous roaming texture the user should apply
the pfImageCache and then set the GL texture matrix based on the offset.
For Example, a toroidal offset of 16,32,0 on a valid region of size
512,512,1 would dictate a translate in the GL texture matrix of
(16/512.0f, 32/512.0f, 0/1.0f).
pfImageCache Advanced Tile Loading
It is possible to control the reading from disk of pfImageTiles needed by
the pfImageCache by specifying parallel work queues on which pfImageTiles
should be placed when they need to be loaded. These read queues are
implemented using the pfQueue functions and are configured with a
function to read each pfImageTile as it is removed from the pfQueue. For
advanced users, it is possible to establish multiple pfQueues to take
care of the loading of different pfImageTiles when the pfImageCache
wishes to page those pfImageTiles in. There are three levels of support
in pfImageCache for these queues. First, users can simply set a single
read queue and corresponding disk thread by assigning a work queue to the
prototypical tile assigned to the pfImageCache. In this basic case, a
simple call to pfGetGlobalReadQueue, can be used to configure this single
global read queue which can then be assigned to the prototype pfImageTile
for the pfImageCache. Alternately, for more advanced applications, the
pfImageTiles that the cache will need can be stored on different disks
such that different queues serviced by different threads can page in
these tiles from the disks in simultaneously. At this level the user as
the ability to specify 'StreamServers' that will be used to service tiles
of center numbers. For example, a user with four disks might choose to
put every fourth tile on disk 0, every second tile of four on disk 1,
every third tile of four on disk 2, and every fourth of four on disk 3.
In this way, she could achieve greater parallelism when reading tiles
from different disks at the same time.
pfImageCacheReadQueueFunc and pfGetImageCacheReadQueueFunc are used to
set and get a callback function used to set the read queue for a
particular pfImageTile before the pfImageCache requests it to be loaded.
Page 8
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
This call provides the ultimate ability for users to control exactly what
process's serve what loads of pfImageTiles.
pfImageCacheTileFileNameFunc and pfGetImageCacheTileFileNameFunc are used
to set and get a callback function used to set the filename for a
pfImageTile's before the pfImageCache requests it to be loaded. This
call provides the ultimate flexibility for users to control file naming
conventions.
pfImageCacheTileFileNameFormat sets a sprintf like format string that
will be used to set the filename of each pfImageTile before it is loaded.
fmtString represents the sprintf format string that will be used to set
the filename, however note that the arguments to sprintf must be defined
via the nArgs and argList parameters. nArgs simply represents the number
of arguments that should be passed to sprintf while argList is a list of
integer tokens that describe each argument. ONLY the following list of
arguments is available:
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_S - integer
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_T - integer
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_R - integer
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_S - integer
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_T - integer
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_R - integer
PFIMAGECACHE_TILE_FILENAMEARG_TILEORG_S - integer
PFIMAGECACHE_TILE_FILENAMEARG_TILEORG_T - integer
PFIMAGECACHE_TILE_FILENAMEARG_TILEORG_R - integer
PFIMAGECACHE_TILE_FILENAMEARG_STREAMSERVERNAME - string
PFIMAGECACHE_TILE_FILENAMEARG_CACHENAME - string
PFIMAGECACHE_TILE_FILENAMEARG_FILENUM_S - integer
PFIMAGECACHE_TILE_FILENAMEARG_FILENUM_T - integer
PFIMAGECACHE_TILE_FILENAMEARG_FILENUM_R - integer
For example, the default values for fmtString, nArgs, and argList are as
follows:
fmtString = "%s%s.%d.r%03d.c%03d.raw888"
nArgs = 5
argList =
{
PFIMAGECACHE_TILE_FILENAMEARG_STREAMSERVERNAME,
PFIMAGECACHE_TILE_FILENAMEARG_CACHENAME,
PFIMAGECACHE_TILE_FILENAMEARG_VSIZE_S,
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_T,
PFIMAGECACHE_TILE_FILENAMEARG_TILENUM_S
}
Thus for a pfImageCache with a stream server name of "/", a cache name of
"usr/data/Terrain/TerrainTexture/texture", a virtual size of
16384x16384x1, which was trying to load a 512x512x1 pfImageTile with an
origin of 8192,2048,0, the pfImageCache would generate the following file
Page 9
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
name for the pfImageTile:
"/usr/data/Terrain/TerrainTexture/texture.16384.r004.c016.raw888"
pfGetImageCacheTileFileNameFormat will return by reference the format
string, number of arguments, and argument list currently being used by
the pfImageCache. Note these references should not be altered as they
are currently being used by the pfImageCache.
dim has one of the following values for the stream server functions
associated with pfImageCaches:
PFIMAGECACHE_S_DIMENSION,
PFIMAGECACHE_T_DIMENSION,
PFIMAGECACHE_R_DIMENSION.
pfImageCacheFileStreamServer sets a string name to serve as the
PFIMAGECACHE_TILE_FILENAMEARG_STREAMSERVERNAME if the whichth stream
server associated with dim is used to load in a pfImageTile. Note that
if the pfImageCache mode BPFIMAGECACHE_AUTOCREATE_STREAMSERVER_QUEUES is
set to PF_ON, then a pfQueue will be created and associated with each
unique File Stream Server name assigned to the pfImageCache.
pfGetImageCacheFileStreamServer returns the current server name
associated with the whichth stream server of the dim dimension of the
pfImageCache.
pfImageCacheStreamServerQueue sets a pfQueue to act as a possible stream
server for every tile loaded where the tile number in dimension dim mod
the number of stream servers in that dimension is equal to which. Note
that when using pfImageCacheFileStreamServer, this pfQueue can be created
automatically. pfGetImageCacheStreamServerQueue returns the current
pfQueue associated with the whichth stream server of the dim dimension of
the pfImageCache.
pfGetImageCacheStreamServerQueueByName returns the pfQueue associated
with the given stream server name. This function is useful for obtain
pointers to pfQueues that were automatically created using
pfImageCacheFileStreamServer.
pfGetImageCacheNumStreamServers returns the number of stream servers
currently being used by the pfImageCache for dimension dim. This is the
effective modulo that will be used to determine the potential stream
server for a particular pfImageTile for a particular dimension.
pfImageCacheMode sets one of the following modes affecting the behavior
of the pfImageCache:
PFIMAGECACHE_AUTOCENTER - currently not implemented, but in future
releases will force the cache to be centered around the valid region.
PFIMAGECACHE_AUTOCREATE_STREAMSERVER_QUEUES - when using the file stream
server functionality of a pfImageCache, this will cause a separate
pfQueue/ Read thread to be created for every unique stream server name.
Page 10
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
PFIMAGECACHE_AUTOSET_TILE_FILENAME - This mode describes whether or not
the pfImageCache should automatically set each pfImageTile's filename
before it is loaded.
PFIMAGECACHE_AUTOSET_TILE_READQUEUE - This mode describes whether or not
the pfImageCache should automatically set each pfImageTile's read queue
before it is loaded.
pfGetImageCacheMode will return the value of any of the previously
mentioned pfImageCache modes.
pfIsImageCacheValid will return whether or not all the tiles included in
the box, (s,t,r) to (s+sizeS-1,t+sizeT-1,r+sizeR-1), are in the cache and
are validated.
pfIsValidImageCache returns non-zero if the tex region portion of the mem
region is completely covered with valid tiles. A valid tile in the mem
region is valid if it has been loaded with the approprate texel data from
disk.
pfImageCache Application
pfApplyImageCache is the mechanism for causing the pfImageCache to update
itself based on a new cache origin and new valid region origin. This
apply must happen either in the draw process, or while a pfDispList has
been opened. This apply will first update the pfImageCache's cache
origin and initiate any tile loading that needs to happen in order for
the cache to be updated. Next, it will generate a list of pfTexLoad's
that need to be applied to the valid region's destination texture in
order for the texture to contain an accurate representation of the new
valid region. Lastly, it traverses through that list of updates applying
each pfTexLoad, which in turn will cause downloading of all of the
incremental portions of tiles.
If the PF_DTR_TEXLOAD DTR mode is set, then the alternative form of apply
pfDTRApplyImageCache should be called. This version of apply takes a
single float argument, which is the time, in milliseconds, available for
downloading new texture into texture memory. This time value is used by
the image cache to shrink the tex region in order to ration the amount of
download time to conform to the time limit supplied by this version of
apply. Under normal circumstances, this apply is only called by the image
cache's cliptexture when the PF_DTR_TEXLOAD DTR mode is enabled. The
application should normall never call this function directly unless it is
using pfImageCaches in a standalone fashion.
pfImageCacheMaster establishes a master/slave relationship between this
pfImageCache (the slave) and the pfImageCache specified to be the master.
Slave pfImageCaches use the master's pfImageCache image tile array in
memory, but do their own downloading into texture memory. This is used
for multipipe applications, where the same pfImageCache should be used in
multiple windows. This relationship is usually part of a set of
master/slave pfImageCaches that are part of a master/slave cliptexture
Page 11
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pair. See pfClipTextureMaster for more details.
pfGetImageCacheMaster returns a pointer to the pfImageCache that is the
master of this pfImageCache, if this image cache is a slave. If the
pfImageCache is not a slave, then NULL is returned. pfImageCaches can be
in one of three states, master, slave, or neither.
pfGetImageCacheSlaves returns a pointer to pfList. The list contains
pointers to pfImageCaches that are slaves of this pfImageCache, if this
image cache is a master. If the pfImageCache is not a master, then NULL
is returned. pfImageCaches can be in one of three states, master, slave,
or neither.
pfGetImageCacheImageTile will return a pointer the pfImageTile in the
pfImageCache's array of tiles in system memory. The particular tile
requested is specified in s, t, and r dimensions, using tile units. For
example requesting tile 1, 0, 0 will return the second tile in the first
row in the first level of the pfImageCache tile array.
pfInvalidateImageCache invalidates the valid region of an pfImageCache.
This will force a full download of the the valid region defined by the
most recently set valid region origin. This will only affect the
download from pfImageCache memory tiles to texture memory. It does not
force new downloads of tiles from disk.
pfImageCacheCalcTexRegion takes pointers to the origin and size of a
user-supplied pfImageCache Texture Region and modifies them so the region
is 1. entirely contained within the image cache itself, 2. is no larger
than the destination texture, and 3. Conforms to the texture subload
alignment requirements of the host machine. Whenever possible, Texture
Regions are translated, rather than shrunk, to stay within the Image
Cache boundaries. Texture alignment requirements are met by "rounding
out" to machine alignment boundaries; the left and bottom (minimum value)
edges are rounded down, while the right and top (maximum value) edges are
rounded up. This routine is used internally by pfImageCache when a new
Texture Region is supplied. pfImageCache users are strongly encouraged to
use this routine to check Texture Region parameters before sending them
to a pfImageCache. Note that in general, the routine will modify the
values of all its arguments.
pfImageCacheCalcMemRegion takes pointers to the origin and size of a
user-supplied pfImageCache Memory Region and modifies them so the region
is 1. entirely contained within the image cache itself, and 2. is no
larger than the maximum memregion size, currently 128 by 128 texture
tiles. Whenever possible, Memory Regions are translated, rather than
shrunk, to stay within the Image Cache boundaries. This routine is used
internally by pfImageCache when a new Memory Region is supplied.
pfImageCache users are strongly encouraged to use this routine to check
Memory Region parameters before sending them to a pfImageCache. Note that
in general, the routine will modify the values of all its arguments.
pfImageCacheDTRMode Is used to control DTR (dynamic texture resolution)
Page 12
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
or image cache load control. DTR consists of a number of independent load
control modes, controlled by the DTRMode bitmask, and a number of user-
settable parameters, all of which have reasonable default values.
Currently, the DTR bitmask can be any combination of the folowing bits:
PF_DTR_MEMLOAD, PF_DTR_TEXLOAD, and PF_DTR_READSORT. PF_DTR_MEMLOAD uses
image tile availability to adjust load control, PF_DTR_TEXLOAD uses
estimated texture subload time to adjust load control, and
PF_DTR_READSORT turns on sorting in the image tile read queue. These
modes can be set singly or in any combination. The default value is the
logical or of all three values.
Image Cache load control is controlled by clip texture load control when
image caches are used as levels in clip textures (the normal situation
for image caches). The DTR mode values are the same for both objects.
It is only necessary to set DTR modes on image caches when the image
cache is being used in a standalone fashion. In the vast majority of
cases, the application should control DTR modes through the clip texture
(in libpf applications, in the MPClipTexture).
pfGetImageCacheDTRMode can be used to get the currently set DTR mode.
pfIsImageCacheTexRegChanged returns non-zero if DTR (image cache load
control) has changed the size of the tex region in order to meet download
bandwidth and tile availability requirements. It is used internally by
DTR. The value will be zero if the tex region is at its originally
configured dimensions, or if the PF_DTR_TEXLOAD DTR mode bit isn't set.
SEE ALSO
pfTexture, pfTexLoad, pfImageTile, pfClipTexture, pfQueue
Page 13
