pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfNewClipTexture, pfGetClipTextureClassType, pfClipTextureCenter,
pfGetClipTextureCenter, pfGetClipTextureCurCenter, pfClipTextureLevel,
pfGetClipTextureLevel, pfClipTextureClipSize, pfGetClipTextureClipSize,
pfClipTextureVirtualSize, pfGetClipTextureVirtualSize,
pfGetClipTextureNumClippedLevels, pfClipTextureInvalidBorder,
pfGetClipTextureInvalidBorder, pfClipTextureVirtualLODOffset,
pfGetClipTextureVirtualLODOffset, pfClipTextureNumEffectiveLevels,
pfGetClipTextureNumEffectiveLevels, pfClipTextureMaster,
pfGetClipTextureMaster, pfGetClipTextureSlaves,
pfClipTextureLevelPhaseMargin, pfGetClipTextureLevelPhaseMargin,
pfClipTextureLevelPhaseShift, pfGetClipTextureLevelPhaseShift,
pfGetClipTextureOffset, pfUpdateClipTexture, pfApplyClipTexture,
pfClipTextureLODRange, pfGetClipTextureLODRange,
pfGetClipTextureCurLODRange, pfClipTextureDTRFadeCount,
pfGetClipTextureDTRFadeCount, pfClipTextureDTRMode,
pfGetClipTextureDTRMode, pfClipTextureTexLoadTime,
pfGetClipTextureTexLoadTime, pfClipTextureDTRBlurMargin,
pfGetClipTextureDTRBlurMargin, pfInvalidateClipTexture,
pfClipTextureLODBias, pfGetClipTextureLODBias,
pfGetClipTextureCurLODBias, pfClipTextureNumAllocatedLevels,
pfGetClipTextureNumAllocatedLevels, pfGetClipTextureMinDTRLOD,
pfIsClipTextureVirtual, pfClipTextureLODOffsetLimit,
pfGetClipTextureLODOffsetLimit, pfClipTextureNumEffectiveLevelsLimit,
pfGetClipTextureNumEffectiveLevelsLimit, pfClipTextureMinLODLimit,
pfGetClipTextureMinLODLimit, pfClipTextureMaxLODLimit,
pfGetClipTextureMaxLODLimit, pfClipTextureLODBiasLimit,
pfGetClipTextureLODBiasLimit, pfGetClipTextureMaxClipSize,
pfIsClipTextureEmulated, pfClipTextureCteAttr, pfGetClipTextureCteAttr -
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.h>
pfClipTexture * pfNewClipTexture(void *arena);
pfType * pfGetClipTextureClassType(void);
void pfClipTextureCenter(pfClipTexture* clip, int s, int t,
int r);
void pfGetClipTextureCenter(pfClipTexture* clip, int *s,
int *t, int *r);
void pfGetClipTextureCurCenter(pfClipTexture* clip, int *s,
int *t, int *r);
void pfClipTextureLevel(pfClipTexture* clip, int lvl,
pfObject *levelObj);
Page 1
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfObject * pfGetClipTextureLevel(pfClipTexture* clip, int lvl);
void pfClipTextureClipSize(pfClipTexture* clip,
int clipSize);
int pfGetClipTextureClipSize(pfClipTexture* clip);
void pfClipTextureVirtualSize(pfClipTexture* clip,
int width, int height, int depth);
void pfGetClipTextureVirtualSize(pfClipTexture* clip,
int *width, int *height, int *depth);
int pfGetClipTextureNumClippedLevels(pfClipTexture* clip);
void pfClipTextureInvalidBorder(pfClipTexture* clip,
int nTexels);
int pfGetClipTextureInvalidBorder(pfClipTexture* clip);
void pfClipTextureVirtualLODOffset(pfClipTexture* clip,
int offset);
int pfGetClipTextureVirtualLODOffset(pfClipTexture* clip);
void pfClipTextureNumEffectiveLevels(pfClipTexture* clip,
int levels);
int -
pfGetClipTextureNumEffectiveLevels(pfClipTexture* clip);
void pfClipTextureMaster(pfClipTexture* clip,
pfClipTexture *master);
pfClipTexture * pfGetClipTextureMaster(pfClipTexture *slave);
pfList * pfGetClipTextureSlaves(pfClipTexture *master);
void pfClipTextureLevelPhaseMargin(pfClipTexture *clip,
int level, int size);
int pfGetClipTextureLevelPhaseMargin(pfClipTexture *clip,
int level);
void pfClipTextureLevelPhaseShift(pfClipTexture *clip,
int level, int shiftS, int shiftT, int shiftR);
void pfGetClipTextureLevelPhaseShift(pfClipTexture *clip,
int level, int *shiftS, int *shiftT, int *shiftR);
Page 2
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfGetClipTextureOffset(int *s, int *t, int *r);
void pfUpdateClipTexture(pfClipTexture* clip);
void pfApplyClipTexture(pfClipTexture* clip);
void pfClipTextureLODRange(pfClipTexture* clip, float min,
float max);
void pfGetClipTextureLODRange(pfClipTexture* clip,
float *min, float *max);
void pfGetClipTextureCurLODRange(pfClipTexture* clip,
float *min, float *max);
void pfClipTextureDTRFadeCount(pfClipTexture *tex,
int count);
int pfGetClipTextureDTRFadeCount(pfClipTexture *tex);
void pfClipTextureDTRMode(pfClipTexture *tex, uint DTRMode);
uint pfGetClipTextureDTRMode(pfClipTexture *tex);
void pfClipTextureTexLoadTime(pfClipTexture *tex,
float time);
float pfGetClipTextureTexLoadTime(pfClipTexture *tex);
void pfClipTextureDTRBlurMargin(pfClipTexture *tex,
float margin);
float pfGetClipTextureDTRBlurMargin(pfClipTexture *tex);
void pfInvalidateClipTexture(pfClipTexture *tex);
void pfClipTextureLODBias(float biasS, float biasT,
float biasR);
void pfGetClipTextureLODBias(float *biasS, float *biasT,
float *biasR);
void pfGetClipTextureCurLODBias(float *biasS, float *biasT,
float *biasR);
void pfClipTextureNumAllocatedLevels(pfClipTexture *tex,
int levels);
int pfGetClipTextureNumAllocatedLevels(pfClipTexture *tex,
int levels);
Page 3
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
float pfGetClipTextureMinDTRLOD(void);
int pfIsClipTextureVirtual(void);
void pfClipTextureLODOffsetLimit(pfClipTexture* clip,
int lo, int hi);
void pfGetClipTextureLODOffsetLimit(pfClipTexture* clip,
int *lo, int *hi);
void -
pfClipTextureNumEffectiveLevelsLimit(pfClipTexture* clip,
int lo, int hi);
void -
pfGetClipTextureNumEffectiveLevelsLimit(pfClipTexture* clip,
int *lo, int *hi);
void pfClipTextureMinLODLimit(pfClipTexture* clip, float lo,
float hi);
void pfGetClipTextureMinLODLimit(pfClipTexture* clip,
float *lo, float *hi);
void pfClipTextureMaxLODLimit(pfClipTexture* clip, float lo,
float hi);
void pfGetClipTextureMaxLODLimit(pfClipTexture* clip,
float *lo, float *hi);
void pfClipTextureLODBiasLimit(pfClipTexture* clip,
float Slo, float Shi, float Tlo, float Thi,
float Rlo, float Rhi);
void pfGetClipTextureLODBiasLimit(pfClipTexture* clip,
float *Slo, float *Shi, float *Tlo, float *Thi,
float *Rlo, float *Rhi);
int pfGetClipTextureMaxClipSize(int bytespertexel);
int pfIsClipTextureEmulated(pfClipTexture* clip);
void pfClipTextureCteAttr(pfClipTexture* clip, int which,
void* val);
void* pfGetClipTextureCteAttr(pfClipTexture* clip,
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. Casting an object
Page 4
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
of class pfClipTexture to an object of class pfTexture is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfTexture.
void pfTexName(pfTexture *tex, const char *name);
void pfTexMultiName(pfTexture *tex, const char *name,
int imageIndex);
const char * pfGetTexName(const pfTexture *tex);
const char * pfGetTexMultiName(const pfTexture *tex, int imageIndex);
void pfTexImage(pfTexture *tex, uint* image, int comp, int ns,
int nt, int nr);
void pfTexMultiImage(pfTexture *tex, uint* image,
int imageIndex, int comp, int ns, int nt, int nr);
void pfGetTexImage(const pfTexture *tex, uint **image,
int *comp, int *ns, int *nt, int *nr);
void pfGetTexMultiImage(const pfTexture *tex, uint **image,
imageIndex, int *comp, int *ns, int *nt, int *nr);
void pfTexFormat(pfTexture *tex, int format, int type);
int pfGetTexFormat(const pfTexture *tex, int format);
void pfTexFilter(pfTexture *tex, int filt, int type);
void pfTexAnisotropy(pfTexture *tex, int degree);
int pfGetTexAnisotropy(pfTexture *tex);
int pfGetTexFilter(const pfTexture *tex, int filt);
void pfTexRepeat(pfTexture *tex, int wrap, int type);
int pfGetTexRepeat(const pfTexture *tex, int wrap);
void pfTexBorderColor(pfTexture* tex, pfVec4 clr);
void pfGetTexBorderColor(pfTexture* tex, pfVec4 *clr);
void pfTexBorderType(pfTexture* tex, int type);
int pfGetTexBorderType(pfTexture* tex);
void pfTexSpline(pfTexture *tex, int type, pfVec2 *pts,
float clamp);
void pfGetTexSpline(const pfTexture *tex, int type,
pfVec2 *pts, float *clamp);
void pfTexDetail(pfTexture *tex, int level, pfTexture *detail);
void pfGetTexDetail(const pfTexture *tex, int *level,
pfTexture **detail);
pfTexture * pfGetTexDetailTex(const pfTexture *tex);
void pfDetailTexTile(pfTexture *tex, int j, int k, int m,
int n, int scram);
void pfGetDetailTexTile(const pfTexture *tex, int *j, int *k,
int *m, int *n, int *scram);
void pfTexList(pfTexture *tex, pfList *list);
pfList * pfGetTexList(const pfTexture *tex);
void pfTexFrame(pfTexture *tex, float frame);
float pfGetTexFrame(const pfTexture *tex);
void pfTexLoadMode(pfTexture *tex, int mode, int val);
int pfGetTexLoadMode(const pfTexture *tex, int mode);
void pfTexLevel(pfTexture *tex, int level, pfTexture *ltex);
pfTexture * pfGetTexLevel(pfTexture *tex, int level);
void pfTexLODRange(pfTexture* tex, float min, float max);
Page 5
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfGetTexLODRange(pfTexture* tex, float *min, float *max);
void pfGetCurTexLODRange(pfTexture* tex, float *min,
float *max);
void pfGetTexLODRange(pfTexture* tex, float *biasS,
float *biasT, float *biasR);
void pfGetTexLODBias(pfTexture* tex, float *biasS,
float *biasT, float *biasR);
void pfTexLODBias(pfTexture* tex, float biasS, float biasT,
float biasR);
void pfGetCurTexLODBias(pfTexture* tex, float *biasS,
float *biasT, float *biasR);
void pfTexLoadOrigin(pfTexture *tex, int which, int xo,
int yo);
void pfGetTexLoadOrigin(pfTexture *tex, int which, int *xo,
int *yo);
void pfTexLoadSize(pfTexture *tex, int xs, int ys);
void pfGetTexLoadSize(const pfTexture *tex, int *xs, int *ys);
void pfApplyTex(pfTexture *tex);
void pfFormatTex(pfTexture *tex);
void pfLoadTex(pfTexture *tex);
void pfTexLoadImage(pfTexture* tex, uint *image);
uint * pfGetTexLoadImage(const pfTexture* tex);
void pfLoadTexLevel(pfTexture *tex, int level);
int pfLoadTexFile(pfTexture *tex, char *fname);
int pfLoadMultiTexFile(pfTexture *tex, char *fname,
int imageIndex);
void pfSaveTexFile(pfTexture *tex, char *fname);
void pfSaveMultiTexFile(pfTexture *tex, char *fname,
int imageIndex);
void pfSubloadTex(pfTexture* tex, int source, uint *image,
int xsrc, int ysrc, int srcwid, int xdst, int ydst,
int xsize, int ysize);
void pfSubloadMultiTex(pfTexture* tex, int source, uint *image,
int imageIndex, int xsrc, int ysrc, int srcwid,
int xdst, int ydst, int xsize, int ysize);
void pfSubloadTexLevel(pfTexture* tex, int source, uint *image,
int xsrc, int ysrc, int srcwid, int xdst, int ydst,
int xsize, int ysize, int level);
void pfSubloadTexMultiLevel(pfTexture* tex, int source,
uint *image, int imageIndex, int xsrc, int ysrc,
int srcwid, int xdst, int ydst, int xsize, int ysize,
int level);
void pfIdleTex(pfTexture *tex);
int pfIsTexLoaded(const pfTexture *tex);
int pfIsTexFormatted(const pfTexture *tex);
void pfApplyTexMinLOD(float min);
void pfApplyTexMaxLOD(float min);
void pfApplyTexLODBias(float biasS, float biasT, float biasR);
pfTexture* pfGetCurTex(void);
void pfApplyTMat(pfMatrix *mat);
Page 6
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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 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 pfClipTexture can also be used with these
functions designed for objects of class pfMemory.
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 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
Page 7
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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
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.
pfNewClipTexture creates and returns a handle to a new pfClipTexture.
arena specifies a malloc arena out of which the pfClipTexture is
allocated or NULL for allocation from the calling process' heap.
pfClipTextures can be deleted with pfDelete.
pfClipTextureCenter 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
pfGetClipTextureCenter 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
pfGetClipTextureCurCenter The get center calls fill in their pointer
arguments, s, t, and r. If one or more of the values aren't needed, a
Page 8
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
null value may be used instead of an integer pointer, in which case the
argument value is ignored.
pfClipTextureClipSize 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 pfClipTextureCenter. pfGetClipTextureClipSize returns the
maximum size for the image used to represent any level of the MIP-map
pyramid stored with a pfClipTexture.
pfClipTextureLevel 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 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 pfClipTextureCenter. 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.
pfGetClipTextureLevel returns the pfObject (either a pfImageCache or a
pfImageTile as defined above) which is currently being used as the lvlth
level of the pfClipTexture.
pfClipTextureVirtualSize 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.
pfGetClipTextureVirtualSize returns the virtual size. Any of the
arguments width,height,depth may be NULL in which case it is ignored.
pfGetClipTextureNumClippedLevels returns the number of roaming cliplevels
of cliptexture. This is equal to log2(virtualSize/clipSize).
pfClipTextureInvalidBorder 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 pfClipTextureClipSize 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. pfGetClipTextureInvalidBorder returns the current value
used to shrink the valid region of each clipped MIP-map level in a
pfClipTexture.
Page 9
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfClipTextureVirtualLODOffset 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. pfGetClipTextureVirtualLODOffset
returns the virtual LOD Offset currently being used by the clip texture.
These functions have no effect on emulated cliptextures.
pfClipTextureNumEffectiveLevels 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 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. pfGetClipTextureNumEffectiveLevels
returns the number of effective levels currently being used by the clip
texture. These functions have no effect on emulated cliptextures.
pfClipTextureMaster 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.
pfGetClipTextureMaster
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.
pfGetClipTextureSlave 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.
pfClipTextureLevelPhaseShift 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 pfClipTextureLevelPhaseMargin) 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). pfGetClipTextureLevelPhaseShift 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.
Page 10
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfClipTextureLevelPhaseMargin 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.
pfGetClipTextureLevelPhaseMargin 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.
pfGetClipTextureOffset 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.
pfUpdateClipTexture 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 pfClipTextureCenter. 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.
pfApplyClipTexture causes the pfClipTexture to be updated via
pfUpdateClipTexture and then actually services the generated list of
texture downloads to update the GL/texture hardware based on the new
center.
pfClipTexLODRange 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. pfGetClipTextureLODRange 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.
pfGetClipTextureCurLODRange 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
Page 11
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
defaults will be returned. NULL arguments to pfGetClipTextureLODRange
and pfGetClipTextureCurLODRange are legal (they are ignored). Note that
when setting LOD range for an emulated cliptexture, the maxLOD value will
be clamped up to numClippedLevels.
pfClipTextureDTRMode 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 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.
pfGetClipTextureDTRMode can be used to get the currently set DTR mode.
Note that PF_DTR_READSORT is not yet implemented for emulated
cliptextures.
pfClipTextureTexLoadTime 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.
pfGetClipTextureTexLoadTime 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.
pfClipTextureDTRFadeCount 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
Page 12
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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.
pfGetClipTextureDTRFadeCount 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 pfClipTextureDTRBlurMargin. 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.
pfGetClipTextureDTRBlurMargin returns the currently set DTRBlurMargin
value. The default value is .5.
Page 13
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
Note that smooth transition (fading) between levels is not yet
implemented for emulated cliptextures, and thus
pfGetClipTextureDTRFadeCount and pfClipTextureDTRBlurMargin have no
effect on emulated cliptextures.
pfGetClipTextureMinDTRLOD 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.
pfInvalidateClipTexture 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.
pfClipTextureLODBias 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.
pfGetClipTextureLODBias returns the current S, T, and R bias values saved
in the pfClipTexture object. The default values are all zero.
pfGetClipTextureCurLODBias returns the current S, T, and R bias values
saved in the pfTexture rather than the pfClipTexture object. The default
values are all zero.
pfClipTextureNumAllocatedLevels 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.
pfGetClipTextureNumAllocatedLevels return the value previously set by
pfClipTextureNumAllocatedLevels. The default value is 1000.
pfIsClipTextureVirtual 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.
Page 14
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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.
Note that the 32K by 32K size limit does not apply to emulated
cliptextures.
The functions pfClipTextureLODOffsetLimit,
pfClipTextureNumEffectiveLevelsLimit, pfClipTextureMinLODLimit,
pfClipTextureMaxLODLimit, pfClipTextureLODBiasLimit and corresponding
query functions pfGetClipTextureLODOffsetLimit,
pfGetClipTextureNumEffectiveLevelsLimit, pfGetClipTextureMinLODLimit,
pfGetClipTextureMaxLODLimit, pfGetClipTextureLODBiasLimit 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 Limit
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.
pfGetClipTextureMaxClipSize 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.
pfIsClipTextureEmulated returns TRUE if cliptexture is emulated or FALSE
if cliptexture is using hardware cliptexture support.
pfClipTextureCteAttr and pfGetClipTextureCteAttr will be used to set and
get cliptexture emulation specific parameters in future releases, and
have currently no effect.
Page 15
pfClipTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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
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 16
