pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAMEpfClipTexture - Create, modify, and update a virtual texture via a cache
in texture memory and main memory, as well as management of disk paging.
FUNCTION SPECIFICATION
#include <Performer/pr/pfClipTexture.h>
pfClipTexture::pfClipTexture();
static pfType * pfClipTexture::getClassType(void);
void pfClipTexture::setCenter(int s, int t, int r);
void pfClipTexture::getCenter(int *s, int *t, int *r);
void pfClipTexture::getCurCenter(int *s, int *t, int *r);
void pfClipTexture::setLevel(int lvl, pfObject* levelObj);
pfObject * pfClipTexture::getLevel(int lvl);
void pfClipTexture::setClipSize(int clipSize);
int pfClipTexture::getClipSize(void);
void pfClipTexture::setVirtualSize(int width, int height,
int depth);
void pfClipTexture::getVirtualSize(int *width, int *height,
int *depth);
int pfClipTexture::getNumClippedLevels(void);
void pfClipTexture::setInvalidBorder(int nTexels);
int pfClipTexture::getInvalidBorder(void);
void pfClipTexture::setVirtualLODOffset(int offset);
int pfClipTexture::getVirtualLODOffset(void);
void pfClipTexture::setNumEffectiveLevels(int levels);
int pfClipTexture::getNumEffectiveLevels(void);
void pfClipTexture::setMaster(pfClipTexture *master);
pfClipTexture * pfClipTexture::getMaster(void);
pfList * pfClipTexture::getSlaves(void);
Page 1
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfClipTexture::setLevelPhaseMargin(int level,
int size);
int pfClipTexture::getLevelPhaseMargin(int level);
void pfClipTexture::setLevelPhaseShift(int level,
int phaseShiftS, int phaseShiftT, int phaseShiftR);
void pfClipTexture::getLevelPhaseShift(int level,
int *phaseShiftS, int *phaseShiftT,
int *phaseShiftR);
void pfClipTexture::getOffset(int *s, int *t, int *r);
void pfClipTexture::setLODRange(float min, float max);
void pfClipTexture::getLODRange(float *min, float *max);
void pfClipTexture::getCurLODRange(float *min, float *max);
void pfClipTexture::update(void);
void pfClipTexture::apply(void);
void pfClipTexture::setDTRFadeCount(int count);
int pfClipTexture::getDTRFadeCount(void);
void pfClipTexture::setDTRMode(pfClipTexture *tex,
uint DTRMode);
uint pfClipTexture::getDTRMode(pfClipTexture *tex);
void pfClipTexture::setDTRBlurMargin(float margin);
float pfClipTexture::getDTRBlurMargin(void);
void pfClipTexture::setTexLoadTime(float time);
float pfClipTexture::getTexLoadTime(void);
void pfClipTexture::invalidate(void);
void pfClipTexture::setLODBias(float biasS, float biasT,
float biasR)
void pfClipTexture::getLODBias(float *biasS, float *biasT,
float *biasR)
void pfClipTexture::getCurLODBias(float *biasS,
float *biasT, float *biasR)
Page 2
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfClipTexture::setNumAllocatedLevels(int levels);
int pfClipTexture::getNumAllocatedLevels(int levels);
float pfClipTexture::getMinDTRLOD(void);
int pfClipTexture::isVirtual(void);
void pfClipTexture::setLODOffsetLimit(int lo, int hi);
void pfClipTexture::getLODOffsetLimit(int *lo, int *hi);
void pfClipTexture::setNumEffectiveLevelsLimit(int lo,
int hi);
void pfClipTexture::getNumEffectiveLevelsLimit(int *lo,
int *hi);
void pfClipTexture::setMinLODLimit(float lo, float hi);
void pfClipTexture::getMinLODLimit(float *lo, float *hi);
void pfClipTexture::setMaxLODLimit(float lo, float hi);
void pfClipTexture::getMaxLODLimit(float *lo, float *hi);
void pfClipTexture::setLODBiasLimit(float Slo, float Shi,
float Tlo, float Thi, float Rlo, float Rhi);
void pfClipTexture::getLODBiasLimit(float *Slo, float *Shi,
float *Tlo, float *Thi, float *Rlo, float *Rhi);
static int pfClipTexture::getMaxClipSize(int bytespertexel);
int pfClipTexture::isEmulated(void);
void pfClipTexture::setCteAttr(int which, void* val);
void* pfClipTexture::getCteAttr(int which);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfClipTexture is derived from the parent class
pfTexture, so each of these member functions of class pfTexture are also
directly usable with objects of class pfClipTexture. This is also true
for ancestor classes of class pfTexture.
void pfTexture::setName(const char *name);
void pfTexture::setMultiName(const char *name, int imageIndex);
const char * pfTexture::getName(void);
const char * pfTexture::getMultiName(int imageIndex);
Page 3
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfTexture::setImage(uint* image, int comp, int ns, int nt,
int nr);
void pfTexture::setMultiImage(uint* image, int imageIndex,
int comp, int ns, int nt, int nr);
void pfTexture::getImage(uint **image, int *comp, int *ns,
int *nt, int *nr);
void pfTexture::getMultiImage(uint **image, int imageIndex,
int *comp, int *ns, int *nt, int *nr);
void pfTexture::setFormat(int format, int type);
int pfTexture::getFormat(int format);
void pfTexture::setFilter(int filt, int type);
int pfTexture::getFilter(int filt);
void pfTexture::setAnisotropy(int degree);
int pfTexture::getAnisotropy();
void pfTexture::setRepeat(int wrap, int type);
int pfTexture::getRepeat(int wrap);
void pfTexture::setBorderColor(pfVec4 clr);
void pfTexture::getBorderColor(pfVec4 *clr);
void pfTexture::setBorderType(int type);
int pfTexture::getBorderType(void);
void pfTexture::setSpline(int type, pfVec2 *pts, float clamp);
void pfTexture::getSpline(int type, pfVec2 *pts, float *clamp);
void pfTexture::setDetail(int level, pfTexture *detail);
void pfTexture::getDetail(int *level, pfTexture **detail);
pfTexture * pfTexture::getDetailTex(void);
void pfTexture::setDetailTexTile(int j, int k, int m, int n,
int scram);
void pfTexture::getDetailTexTile(int *j, int *k, int *m,
int *n, int *scram);
void pfTexture::setList(pfList *list);
pfList * pfTexture::getList(void);
void pfTexture::setFrame(float frame);
float pfTexture::getFrame(void);
void pfTexture::setLoadMode(int mode, int val);
int pfTexture::getLoadMode(int mode);
void pfTexture::setLevel(int level, pfTexture *ltex);
pfTexture * pfTexture::getLevel(int level);
void pfTexture::setLODRange(float min, float max);
void pfTexture::getLODRange(float *min, float *max);
void pfTexture::getCurLODRange(float *min, float *max);
void pfTexture::setLODBias(float biasS, float biasT,
float biasR);
void pfTexture::getLODBias(float *biasS, float *biasT,
float *biasR);
void pfTexture::getCurLODBias(float *biasS, float *biasT,
float *biasR);
void pfTexture::setLoadImage(uint* image);
uint * pfTexture::getLoadImage(void);
void pfTexture::setLoadOrigin(int which, int xo, int yo);
void pfTexture::getLoadOrigin(int which, int *xo, int *yo);
Page 4
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfTexture::setLoadSize(int xs, int ys);
void pfTexture::getLoadSize(int *xs, int *ys);
void pfTexture::apply(void);
void pfTexture::format(void);
void pfTexture::load(void);
void pfTexture::loadLevel(int level);
void pfTexture::subload(int source, uint *image, int xsrc,
int ysrc, int srcwid, int xdst, int ydst, int xsize,
int ysize);
void pfTexture::subloadMulti(int source, uint *image,
int imageIndex, int xsrc, int ysrc, int srcwid,
int xdst, int ydst, int xsize, int ysize);
void pfTexture::subloadLevel(int source, uint *image, int xsrc,
int ysrc, int srcwid, int xdst, int ydst, int xsize,
int ysize, int level);
void pfTexture::subloadMultiLevel(int source, uint *image,
imageIndex, int xsrc, int ysrc, int srcwid, int xdst,
int ydst, int xsize, int ysize, int level);
int pfTexture::loadFile(char *fname);
int pfTexture::loadMultiFile(char *fname, int imageIndex);
int pfTexture::saveFile(char *fname);
int pfTexture::saveMultiFile(char *fname, int imageIndex);
void pfTexture::freeImage(void);
void pfTexture::idle(void);
int pfTexture::isLoaded(void);
int pfTexture::isFormatted(void);
void pfTexture::applyMinLOD(float min);
void pfTexture::applyMaxLOD(float min);
void pfTexture::applyLODBias(float biasS, float biasT,
float biasR);
pfTexture* pfGetCurTex(void);
void pfApplyTMat(pfMatrix *mat);
Since the class pfTexture is itself derived from the parent class
pfObject, objects of class pfClipTexture can also be used with these
functions designed for objects 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);
int pfObject::getNumUserData();
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfClipTexture can also be used with these
functions designed for objects of class pfMemory.
Page 5
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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 pfClipTexture is used to represent a very large texture image with a
modest amount of texture memory supplemented by a moderate amount of main
memory and a correspondingly greater quantity of backing store on disk.
Limits to the size of this large disk-based virtual texture image are
determined by texture hardware coordinate precision considerations,
implementation details (see pfQuerySys PFQSYS_MAX_CLIPTEXTURE_SIZE for
more information about this), and by available disk storage.
The implementation approach is to keep only a small area of interest of
each level of a MIP-map in the hardware texture cache at any one time.
This stack of subimages then forms a cached sub-volume of the normal
pyramid of hierarchical resolutions stored within a MIP-map. This sub-
volume of the MIP-map pyramid is chosen such that the image generated
from a particular view can be rendered as if the entire MIP-map pyramid
were present. Thus the fundamental assumption is that for any given
viewpoint, a predetermined amount of texture (based on screen resolution
and possibly affected by perspective) can be used to approximate an
arbitrarily large texture. The relevant work, then, is to choose an area
of interest or 'center' of resolution. This 'center' is chosen such that
a subset of each MIP-map level aligned by the center will yield a correct
final image. This assumption is valid because of the way that MIP-mapped
textures address texture memory; no more than screen resolution can be
used from any single map level in the MIP-map resolution pyramid. To
simplify the calculations and concept, each level of a clipmap is clamped
(clipped) to a predetermined size. Also note that because of the nature
of this data structure, several levels contain the same number of texels,
but each coarser level represents four times the area of the finer level
in the texture space. At some point, levels no longer are clipped and
the subset of data stored within the level actually contains the entire
map. This means that all of the original data is present at some
Page 6
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
resolution.
The model used to implement a 'clipmap' is a one in which each clipped
level of the clipmap can be thought of as performing a toroidal image
roam through a larger virtual texture. The center of resolution of the
clipmap defines the current origin of roaming for each level via a shift
and mask operation. Each clipped level is represented by a pfImageCache
and is generally independent of the other levels, the exception being
that the pfClipTexture forces an alignment of the center of each level's
pfImageCache so that the graphics library and texture hardware are able
to understand exactly what subset of image data is available at each
level at all times.
new(arena) allocates a pfClipTexture from the specified memory arena, or
from the process heap if arena is NULL. new allocates a pfClipTexture
from the default memory arena (see pfGetSharedArena). Like other
pfObjects, pfClipTextures cannot be created statically, automatically on
the stack or in arrays and should be deleted with pfDelete rather than
the delete operator.
pfClipTexture::setCenter sets the center of resolution for the virtual
texture. s,t,and r specify the location in finest map level texels
around which the clipmap should align itself. Due to hardware
constraints, this center can only be set on certain texel boundaries and
these boundaries are automatically enforced by Performer (see pfQuerySys
PFQSYS_CLIPTEXTURE_CENTER_ALIGNMENT for more details). Note that the
center of the finest level actually defines the center of each clipped
level of the clipmap by the shift and mask relationship:
CenterLevelN = (Center>>N) & CENTER_ALIGNMENT_MASK
pfClipTexture::getCenter returns the center of resolution for the virtual
texture represented by this clipmap. This is the value that was last set
by the application. Since the center must be processed before it's
effects become visible, this value may not be the value of the center
currently in use. To get the in-use center value, call
pfClipTexture::getCurCenter The get center calls fill in their pointer
arguments, s, t, and r. If one or more of the values aren't needed, a
null value may be used instead of an integer pointer, in which case the
argument value is ignored.
pfClipTexture::setClipSize sets the maximum size of the image used to
represent any level of a pfClipTexture. MIP-map levels which would have
normally been larger than this size are clipped to clipSize based on the
center set via pfClipTexture::setCenter. pfClipTexture::getClipSize
returns the maximum size for the image used to represent any level of the
MIP-map pyramid stored with a pfClipTexture.
pfClipTexture::setLevel(int lvl, pfObject *lvlObject) sets the
pfImageCache or pfImageTile to use for a particular level of a clipmap.
Each level which would normally have a MIP-mapped size greater than the
clipped size of the pfClipTexture must specify a pfImageCache which can
Page 7
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
be used by the clipmap to extract the appropriate subset of the image
necessary for level based on the current center of resolution as defined
by pfClipTexture::setCenter. Each level below the 'clipped' portion of
the clipmap can be specified as either a pfImageCache or a pfImageTile.
Note when using pfImageCache's for these levels, the cache's valid region
should be the entire image.
pfClipTexture::getLevel returns the pfObject (either a pfImageCache or a
pfImageTile as defined above) which is currently being used as the lvlth
level of the pfClipTexture.
pfClipTexture::setVirtualSize sets the overall virtual size of the
pfClipTexture. This size currently can not exceed the maximum supported
hardware size of a texture (see pfQuerySys PFQSYS_MAX_CLIPTEXTURE_SIZE
for more details). Note that this size represents the coordinate system
in which the pfClipTexture will be represented when drawing. For
instance, even if the clipped size of the pfClipTexture is 1024x1024x1, a
texture coordinate of (.5,.25,0) will refer to the texel at 16384,8192,0
if the virtual size of the texture was 32768x32768x1.
pfClipTexture::getVirtualSize returns the virtual size. Any of the
arguments width,height,depth may be NULL in which case it is ignored.
pfClipTexture::getNumClippedLevels returns the number of roaming
cliplevels of cliptexture. This is equal to log2(virtualSize/clipSize).
pfClipTexture::setInvalidBorder sets a border region for each clipped
level that the hardware is not to use. This invalid border essentially
shrinks the stack size set by pfClipTexture::setClipSize when the
pfClipTexture is drawn. This border can be interactively set to lessen
the incremental texture paging necessary to keep the hardware cache of
texture up to date. This border must be set to a minimum value because
of hardware constraints (see pfQuerySys
PFQSYS_MIN_CLIPTEXTURE_INVALID_BORDER to find out minimum border size).
Note the border should also be a multiple of
PFQSYS_CLIPTEXTURE_CENTER_ALIGNMENT. Thus a pfClipTexture which has a
stack size of 1024 with an invalid border of 16 has an effective stack
size of 992. pfClipTexture::getInvalidBorder returns the current value
used to shrink the valid region of each clipped MIP-map level in a
pfClipTexture.
pfClipTextures::setVirtualLODOffset This value offsets from the top
(highest resolution) level of actual stack to define the top level of a
virtual stack. This allows for a deeper cliptexture stack than can be
directly supported by the hardware. Setting the LOD offset to zero makes
the top level of the actual and virtual clip texture stack the same; this
is the default value. pfClipTexture::getVirtualLODOffset returns the
virtual LOD Offset currently being used by the clip texture. These
functions have no effect on emulated cliptextures.
pfClipTexture::setNumEffectiveLevels sets the number of levels the
hardware will use when using a cliptexture. This routine is used in
conjunction with virtualLODoffset to define a subset of the actual clip
Page 8
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
texture so that clip textures larger than can be supported in hardware
can be used. The number of effect levels starts from the top (highest
resolution) level as defined by virtualLODoffset.
pfClipTexture::getNumEffectiveLevels returns the number of effective
levels currently being used by the clip texture. These functions have no
effect on emulated cliptextures.
pfClipTexture::setMaster establishes a master/slave relationship between
two mpcliptextures. The cliptexture that is called becomes a slave to the
one given as an argument. This function has no effect on emulated
cliptextures.
Master and slave cliptextures are used to render mpcliptextures across
multiple pipes. The masters and slaves have corresponding master and
slave cliptextures and image caches. Only the master image cache controls
the disk downloads and the image cache tiles in memory. Each slave uses
those tiles to do its own downloading to texture memory. Note that
cliptexture emulation is not yet supported in multipipe mode.
pfClipTexture::getMaster returns the master clip texture of this mp clip
texture, if this clip texture is a slave. If the clip texture is not a
slave, it returns NULL.
pfClipTexture::getSlave returns a pfList containing a list of all the
slave cliptextures using the given cliptexture as its master. If the clip
texture is not a master, the call returns NULL.
pfClipTexture::setLevelPhaseShift sets an offset to the center of a
particular clipped level. This offset means that this level could (and
should) be misaligned relative to other clipped levels so that its
texture paging will happen at different increments (and hopefully in
different frames) than other levels. However phase offset also requires
a corresponding increase in level size (see
pfClipTexture::setLevelPhaseMargin) to account for the phase shift. This
needs to happen so that actual clipped size + phase shift texels will be
present in the hardware cache (of which only clipped size will be used).
pfClipTexture::getLevelPhaseShift gets the previously described phase
shift for the given level Any of the arguments s,t,r may be NULL in which
case it is ignored. The default phase shift for level i is 2^(i+2) - 4;
most applications should not need to change this. These functions have
no effect on emulated cliptextures.
pfClipTexture::setLevelPhaseMargin sets an extra border of texture that
each clipped level should attempt to keep valid. This provides headroom
so that all levels have their real 'clipped' regions valid in texture
hardware even if they are being updated out of phase.
pfClipTexture::getLevelPhaseMargin returns the current extra frame of
texture in use by the given clipped level. The default phase margin is 0
for level 0, and 8 for all other levels; most applications should not
need to change this. These functions have no effect on emulated
cliptextures.
Page 9
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfClipTexture::getOffset returns the current offset being used to offset
each level toroidally during incremental texture loading of the
pfClipTexture. Any of the arguments s,t,r may be NULL in which case it
is ignored. This offset defines the effective origin of the imagery
within a map level of a pfClipTexture. It is assumed that each map level
is represented toroidally based on this origin such that effective
coordinates relative to a particular map level are generated via this
equation.
((S+offS)%clipSize, (T+offT)%clipSize, (R+offR)%clipSize)
Note that the offset for each level of the pfClipTexture on
InfiniteReality can be had by taking the returned offset and modifying it
as follows:
OffsetN = (Offset>>N) & ~7.
pfClipTexture::update causes the pfClipTexture to update all of its data
structure based on the new center of the pfClipTexture. These updates
include preparing a work list of texture loads to be performed in order
to force the hardware texture cache to be consistent based on the new
center of resolution as defined by pfClipTexture::setCenter. It also
causes all of the pfImageCache's used to represent levels within the
pfClipTexture to have their cache origin and valid region origin updated
based on this new center. This will subsequently cause any needed cache
tiles to be paged in from disk as defined in the pfImageCache api.
pfClipTexture::apply causes the pfClipTexture to be updated via
pfClipTexture::update and then actually services the generated list of
texture downloads to update the GL/texture hardware based on the new
center.
pfClipTexture::setLODRange extends the notion of the pfTexture routine of
the same name. Since pfClipTextures can change the min LOD value as part
of DTR load control, this routine saves the set value separately.
pfClipTextures then take the maximum (blurrier) of the DTR and and set
values when setting LOD Range each frame. pfClipTexture::getLODRange
will return the texture LOD range set on the pfClipTexture. If the range
is unset the value PFTEX_DEFAULT will be returned in min and max.
pfClipTexture::getCurLODRange will return the current effective LOD range
being applied to the given pfClipTexture and considers values inherited
from the current global state. If the values are completely unset, GL
defaults will be returned. NULL arguments to pfClipTexture::getLODRange
and pfClipTexture::getCurLODRange are legal (they are ignored). Note
that when setting LOD range for an emulated cliptexture, the maxLOD value
will be clamped up to numClippedLevels.
pfClipTexture::setDTRMode Is used to control DTR (dynamic texture
resolution) or clip texture load control. Clip texture DTR consists of a
number of independent load control modes, control 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
Page 10
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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, 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 PF_DTR_MEMLOAD|PF_DTR_TEXLOAD|PF_DTR_READSORT.
pfClipTexture::getDTRMode can be used to get the currently set DTR mode.
Note that PF_DTR_READSORT is not yet implemented for emulated
cliptextures.
pfClipTexture::setTexLoadTime sets the time allowed to download all of
the cliptexture updates for a particular cliptexture. DTR (Dynamic
Texture Resolution) has a mode, PF_DTR_TEXLOAD, where it estimates the
amount of time necessary to perform the texture subloads to update the
cliptexture for the current frame. This time is summed up over all the
subloads in all the clipped levels of the cliptexture. The estimate uses
the size of the texture downloads and a cost table, which contains
download times for different size subregions. There are multiple cost
tables available. The one appropriate to the machine in use is chosen. As
the cost of the downloads necessary to update the cliptexture are
computed, level by level, from coarsest to finest, the running total is
compared against the maximum allowed cost. When a level is reached that
would cause the total to exceed the maximum allowed cost, DTR blurs down
to the next lower level. This way the time in the DRAW process is
rationed.
This call can adjust the maximum allowed time for cliptexture downloads.
The default value is 6. The value is a non-negative floating point amount
of milliseconds. This value has no effect unless PF_DTR_TEXLOAD is set.
If it is not set, there is no time rationing.
pfClipTexture::getTexLoadTime is used to get the currently set maximum
download time. Since the value is set in the CULL process, and the
effects will be seen in the DRAW process, there may be a delay of up to 1
frame before changes take effect.
pfClipTexture::setDTRFadeCount is used to adjust the number of frames it
takes to fade in a new level of the cliptexture. When DTR's
PF_DTR_TEXLOAD mode is on, the sharpest visible level (minDTRLOD) is
adjusted based on which levels have tile files available and have the
draw process time to download them into texture memory. When a new, finer
level becomes available, DTRFadeCount is used to keep the new level or
levels from appearing too abruptly. Each frame, the value of minDTRLOD
is faded in towards the new target level by an amount that is
1/DTRFadeCount of the distance from the current (fractional) value to the
target value. Note that since this process causes the current value to
change every frame, the fade-in does not linearly converge to the target
value in DTRFadeCount frames as one might expect; rather, it converges
exponentially to the target value without ever actually reaching it, and
DTRFadeCount controls how slowly this exponential function converges.
Page 11
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfClipTexture::getDTRFadeCount can be used to get the currently set DTR
fade count. The default fade count is 5.
Note that the DTRFadeCount as described above is sufficient to smooth out
the value of minDTRLOD when the minimum texloaded level decreases
(becomes finer); however, there are times when the min loaded level that
can be loaded within the currently allotted DTR tex load time increases
(becomes coarser) due to increasing disk or texload demands, typically
when speed of motion of the clip center is increased. Simply fading out
to the new integer level over many frames does not work, since the levels
finer than the new target level are not in texture memory; attempts to
show these levels will result in displaying the garbage contents of
uninitialized texture memory. So in order to smooth out the increases,
DTR must uss an additional predictive technique. It does this using a
parameter called DTRBlurMargin which the program can set by calling the
member function pfClipTexture::setDTRBlurMargin. DTRBlurMargin should be
a value between 0 and 1 inclusive; roughly speaking, a higher blur margin
means more cushioning-- transitions will be smoother (less "DTR
flickering"), but minDTRLOD will tend to hover higher (coarser) for any
given speed of the clip center.
The exact way this is implemented is as follows. Each frame, when the
levels are loaded from coarse to fine until the current DTR tex load time
is reached (as described above under TexLoadTime), the algorithm takes
note of exactly what level has been reached when the smaller time
DTRTexLoadTime*(1.-DTRBlurMargin) has elapsed. In general this happens
at some fractional point between two levels' completions, so the result
is a fractional level; this fractional level is used as the target of the
exponential fade-in (or out) function used to set minDTRLOD (as described
above under DTRBlurMargin), instead of the actual integer min texloaded
level for that frame. Thus, in particular, setting DTRBlurMargin=0 means
disabling this technique entirely. The default value of DTRBlurMargin is
.5, which empirically tends to keep the target at an average of roughly 1
level coarser than the integer min texloaded level, thereby allowing the
min texloaded level to increase to the next higher integer without
forcing a corresponding jump in the visible minDTRLOD. Higher values of
DTRBlurMargin can be used to tolerate bigger jumps in the min texloaded
level.
pfClipTexture::getDTRBlurMargin returns the currently set DTRBlurMargin
value. The default value is .5.
Note that smooth transition (fading) between levels is not yet
implemented for emulated cliptextures, and thus
pfClipTexture::getDTRFadeCount and pfClipTexture::setDTRBlurMargin have
no effect on emulated cliptextures.
pfClipTexture::getMinDTRLOD return the min LOD value computed by the
pfClipTexture's load control system described above. The actual min LOD
value used by the cliptexture is the maximum of the DTR min LOD and the
min LOD set by the application.
Page 12
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfClipTexture::invalidate caused the cliptexture to mark all of it's
clipped levels as invalid and forces a complete reload of the texture
memory owned by the cliptexture's image caches. Note that invalidate
doesn't force a reload of texture data from disk to the system memory
cache; there is a utility function pfuReallyInvalidateClipTexture() which
does that.
pfClipTexture::setLODBias sets the S, T, and R bias values on the
pfClipTexture object. Setting the the bias values with the
pfClipTexture's method rather than the pfTexture's guarantees that the
bias values will be sent to the pfTexture object and the pfTexture is
applied when the pfClipTexture is applied. Using the pfTexture is less
certain, since setting the pfTexture state is not frame accurate. This
function has no effect on emulated cliptextures.
pfClipTexture::getLODBias returns the current S, T, and R bias values
saved in the pfClipTexture object. The default values are all zero.
pfClipTexture::getCurLODBias returns the current S, T, and R bias values
saved in the pfTexture rather than the pfClipTexture object. The default
values are all zero.
pfClipTexture::setNumAllocatedLevels places an upper bound on the number
of levels in the pfClipTexture that will actually be stored in texture
memory, starting at level 0 (the finest level). This only has an effect
when the pfClipTexture is a virtual clip texture and numAllocatedLevels
is less than the number of virtual levels. The levels in use will always
be restricted to a subset of the levels that are allocated in texture
memory. This function has no effect on emulated cliptextures.
pfClipTexture::getNumAllocatedLevels return the value previously set by
pfClipTexture::setNumAllocatedLevels. The default value is 1000.
pfClipTexture::isVirtual returns non-zero if the pfClipTexture is
configured to be virtual. A pfClipTexture is considered virtual if it
configured with fewer effective levels than there are levels in the
entire pfCliptexture. A virtual pfClipTexture can only display a
contiguous subset of its levels at a time. The set of displayable levels
can be shifted by changing the pfClipTexture's virtual lod offset value.
The number of displayable levels can be changed through the effective
levels parameter. Note that this function always returns FALSE for
emulated cliptextures.
Virtual pfClipTextures allow the application to exceed the 32K by 32K
size limit of non-virtual pfClipTextures at the expense of extra
callbacks in the scene graph and higher texture memory usage for the
pyramid levels. See the Cliptextures chapter of the programming guide for
details. For information on various bugs and limitations inherent in
virtual clipmaps on InfiniteReality, see the document
/usr/share/Performer/doc/clipmap/IRClipmapBugs.html or
/usr/share/Performer/doc/clipmap/IRClipmapBugs.txt which is included with
the Performer sample source code.
Page 13
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
Note that the 32K by 32K size limit does not apply to emulated
cliptextures.
The functions setLODOffsetLimit, setNumEffectiveLevelsLimit,
setMinLODLimit, setMaxLODLimit, setLODBiasLimit and corresponding query
functions getLODOffsetLimit, getNumEffectiveLevelsLimit, getMinLODLimit,
getMaxLODLimit, getLODBiasLimit are for applications (such as the clipfly
example program) to modify or override the values set by callbacks (such
as those installed by the .spherepatch and .ct scene file loaders) that
control the corresponding clip center parameters. The intended use is
for the application to call the setLimit functions (based on GUI slider
input, for example), and then the intelligent callback functions of the
loaders call the corresponding getLimit functions and use the results to
modify their selection of the final parameters sent to the pfClipTexture.
The limits are not enforced by pfClipTexture; they are provided merely to
facilitate communication from the application to the callback function
controlling the parameters. That function is free to ignore or only
partially honor the limits if it wishes (but failing to honor the limits
will of course make it more difficult for a user to browse and debug a
texture using the clipfly controls).
Note that the above functions have no effect on emulated cliptextures,
and the default values are returned by all the get functions.
pfClipTexture::getMaxClipSize returns the maximum clipsize that is
supported on the system in use. Note that the value returned by this
function can be overridden by setting the environment variable
PFCLIPTEXTURE_MAX_CLIPSIZE.
pfClipTexture::isEmulated returns TRUE if cliptexture is emulated or
FALSE if cliptexture is using hardware cliptexture support.
pfClipTexture::setCteAttr and pfClipTexture::getCteAttr will be used to
set and get cliptexture emulation specific parameters in future releases,
and have currently no effect.
NOTES
pfClipTextures are currently supported in hardware only on Onyx and Onyx2
with InfiniteReality graphics systems. Current values for hardware
specific constraints on this system are:
PFQSYS_MAX_CLIPTEXTURE_SIZE = 32768
PFQSYS_CLIPTEXTURE_CENTER_ALIGNMENT = 8
PFQSYS_MIN_CLIPTEXTURE_INVALID_BORDER = 16
On systems without hardware support for cliptextures, pfClipTextures are
implemented through software emulation. The software emulation
implementation manages a list of independant texture objects: one
Page 14
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
mipmapped texture stores all pyramid levels of cliptexture (up to and
including the first level of size clipsize), and other (non-mipmapped)
textures store the data associated with each roaming level. Performer
will automatically compute and store texture coordinate bounds for each
pfGeoSet that is to be rendered with a cliptexture. Then, on each frame,
depending on the size and position of texcoord bounds with respect to
current clipcenter position, the texture associated with the highest
resolution level which completely covers pfGeoSet's geometry (in texture
space) will be used for rendering the pfGeoSet.
This emulation scheme has direct implications in terms of geometry
tessellation requirements. A high resolution level, if available in
texture ram, will only be used to render pfGeoSets whose texcoord bounds
are completely inside valid area of such level. This implies that for
any given pfGeoSet, the size of its texcoord bounds imposes a limit on
the highest resolution texture that the implementation will ever use to
render it.
See pfGeoSet man pages for more information on cliptexture emulation.
SEE ALSO
pfImageCache, pfImageTile, pfQuerySys, pfTexLoad, pfTexture,
pfuReallyInvalidateClipTexture, pfGeoSet
Page 15
