pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAMEpfImageCache - 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/pfImageCache.h>
pfImageCache::pfImageCache();
static pfType *
pfImageCache::getClassType(void);
void pfImageCache::setName(const char *name);
const char * pfImageCache::getName(void);
void pfImageCache::setImageSize(int sizeS, int sizeT,
int sizeR);
void pfImageCache::getImageSize(int *sizeS, int *sizeT,
int *sizeR);
void pfImageCache::setProtoTile(pfImageTile *tile);
pfImageTile * pfImageCache::getProtoTile(void);
void pfImageCache::setMemRegionSize(int nTilesS, int nTilesT,
int nTilesR);
void pfImageCache::getMemRegionSize(int *nTilesS, int *nTilesT,
int *nTilesR);
void pfImageCache::getCurMemRegionSize(int *nTilesS,
int *nTilesT, int *nTilesR);
void pfImageCache::setMemRegionOrg(int s, int t, int r);
void pfImageCache::getMemRegionOrg(int *s, int *t, int *r);
void pfImageCache::getCurMemRegionOrg(int *s, int *t, int *r);
void pfImageCache::setTexRegionSize(int sizeS, int sizeT,
int sizeR);
void pfImageCache::getTexRegionSize(int *sizeS, int *sizeT,
int *sizeR);
void pfImageCache::getCurTexRegionSize(int *sizeS, int *sizeT,
int *sizeR);
Page 1
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfImageCache::setTexRegionOrg(int s, int t, int r);
void pfImageCache::getTexRegionOrg(int *s, int *t, int *r);
void pfImageCache::getCurTexRegionOrg(int *s, int *t, int *r);
void pfImageCache::getValidRegionOffset(int *s, int *t,
int *r);
void pfImageCache::setTex(void *dst, int lvl, int type);
void pfImageCache::getTex(void **dst, int *lvl, int *type);
void pfImageCache::setTexSize(int s, int t, int r);
void pfImageCache::getTexSize(int *s, int *t, int *r);
void -
pfImageCache::setReadQueueFunc(pfImageCacheReadQueueFuncType func);
void -
pfImageCache::setTileFileNameFunc(pfImageCacheTileFileNameFuncType func);
pfImageCacheReadQueueFuncType
pfImageCache::getReadQueueFunc(void);
pfImageCacheTileFileNameFuncType
pfImageCache::getTileFileNameFunc(void);
void pfImageCache::setFileStreamServer(int dim, int which,
const char *device);
const char * pfImageCache::getFileStreamServer(int dim, int which);
void pfImageCache::setStreamServerQueue(int dim, int which,
pfQueue *q);
pfQueue * pfImageCache::getStreamServerQueue(int dim, int which);
pfQueue * -
pfImageCache::getStreamServerQueueByName(const char *name);
void pfImageCache::setTileFileNameFormat(const char *fmtString,
int nArgs, int *argList);
void -
pfImageCache::getTileFileNameFormat(const char **fmtString,
int *nArgs, const int **argList);
int pfImageCache::getNumStreamServers(int dim);
Page 2
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfImageCache::setMode(int mode, int val);
int pfImageCache::getMode(int mode);
pfImageTile * pfImageCache::getTile(int s, int t, int r);
const pfList* pfImageCache::getLoadUpdates(void);
int pfImageCache::isValid(int s, int t, int r, int sizeS,
int sizeT, int sizeR);
int pfImageCache::isValid(void);
void pfImageCache::apply(void);
void pfImageCache::apply(float time);
void pfImageCache::setMaster(pfImageCache *master);
pfImageCache * pfImageCache::getMaster(void);
pfList * pfImageCache::getSlaves(void);
void pfImageCache::invalidate(void);
void pfImageCache::calcTexRegion(int *_orgS, int *_orgT,
int *_orgR, int *_sizeS, int *_sizeT, int *_sizeR);
void pfImageCache::calcMemRegion(int *_orgS, int *_orgT,
int *_orgR, int *_sizeS, int *_sizeT, int *_sizeR);
void pfImageCache::setDTRMode(uint mode);
uint pfImageCache::getDTRMode(void);
int pfImageCache::isTexRegChanged(void);
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. This is also true
for ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
Page 3
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
int pfObject::getNumUserData();
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.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
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.
new(arena) allocates a pfImageCache from the specified memory arena, or
from the process heap if arena is NULL. new allocates a pfImageCache
from the default memory arena (see pfGetSharedArena). Like other
Page 4
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfObjects, pfImageCaches cannot be created statically, automatically on
the stack or in arrays and should be deleted with pfDelete rather than
the delete operator.
pfImageCache::getClassType returns the pfType* for the class
pfImageCache. The pfType* returned by pfImageCache::getClassType is the
same as the pfType* returned by invoking the virtual function getType on
any instance of class pfImageCache. When decisions are made based on the
type of an object, it is usually better to use the member function
isOfType 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.
pfImageCache::setName sets the name of the pfImageCache to name while
pfImageCache::getName returns the name of the pfImageCache.
pfImageCache CACHE CONFIGURATION
pfImageCache::setImageSize 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. pfImageCache::getImageSize returns the virtual size of the
pfImageCache. Any of the arguments s,t,r may be NULL in which case it
will be ignored.
pfImageCache::setProtoTile 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. pfImageCache::getProtoTile
returns the prototypical tile used to store information within the
pfImageCache.
pfImageCache::setMemRegionSize 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 pfImageCache::setProtoTile
in each dimension of the cache. pfImageCache::getMemRegionSize 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,
pfImageCache::getCurMemRegionSize 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.
Page 5
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfImageCache::setMemRegionOrg 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. pfImageCache::getMemRegionOrg 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,
pfImageCache::getCurMemRegionOrg returns the mem region origin currently
in use.
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.
pfImageCache::setTex 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. pfImageCache::getTex 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.
pfImageCache::setTexSize 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. pfImageCache::getTexSize 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
Page 6
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
application is not interested in the results.
pfImageCache::setTexRegionSize 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. pfImageCache::getTexRegionSize 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,
pfImageCache::getCurTexRegionSize returns the tex region size currently
in use.
pfImageCache::setTexRegionOrg 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 pfImageCache::apply is
called. pfImageCache::getTexRegionOrg 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,
pfImageCache::getCurTexRegionOrg returns the tex region origin currently
in use.
pfImageCache::getTexRegionOffset 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
Page 7
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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.
pfImageCache::setReadQueueFunc and pfImageCache::getReadQueueFunc 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.
This call provides the ultimate ability for users to control exactly what
process's serve what loads of pfImageTiles.
pfImageCache::setTileFileNameFunc and pfImageCache::getTileFileNameFunc
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.
pfImageCache::setTileFileNameFormat 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:
Page 8
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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
name for the pfImageTile:
"/usr/data/Terrain/TerrainTexture/texture.16384.r004.c016.raw888"
pfImageCache::getTileFileNameFormat 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.
pfImageCache::setFileStreamServer 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.
pfImageCache::getFileStreamServer returns the current server name
associated with the whichth stream server of the dim dimension of the
pfImageCache.
pfImageCache::setStreamServerQueue 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 pfImageCache::setFileStreamServer, this pfQueue can
be created automatically. pfImageCache::getStreamServerQueue returns the
current pfQueue associated with the whichth stream server of the dim
dimension of the pfImageCache.
pfImageCache::getStreamServerQueueByName returns the pfQueue associated
with the given stream server name. This function is useful for obtain
pointers to pfQueues that were automatically created using
Page 9
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfImageCache::setFileStreamServer.
pfImageCache::getNumStreamServers 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.
pfImageCache::setMode 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.
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.
pfImageCache::getMode will return the value of any of the previously
mentioned pfImageCache modes.
pfImageCache::isValid 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.
pfImageCache::isValid 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
pfImageCache::apply 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
Page 10
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfImageCache::apply(float) 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.
pfImageCache::setMaster 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
pair. See pfClipTexture::setMaster for more details.
pfImageCache::getMaster 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.
pfImageCache::getSlaves 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.
pfImageCache::getTile 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.
pfImageCache::invalidate 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.
pfImageCache::calcTexRegion 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
Page 11
pfImageCache(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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.
pfImageCache::calcMemRegion 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.
pfImageCache::setDTRMode Is used to control DTR (dynamic texture
resolution) 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).
pfImageCache::getDTRMode can be used to get the currently set DTR mode.
pfImageCache::isTexRegChanged 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 12
