pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
NAME
pfMPClipTexture, pfGetMPClipTexture - Create, modify, and query a libpf
multiprocessing shadow for pfClipTextures
FUNCTION SPECIFICATION
#include <Performer/pf/pfMPClipTexture.h>
pfMPClipTexture::pfMPClipTexture()
pfType * pfMPClipTexture::getClassType(void);
void pfMPClipTexture::setClipTexture(pfClipTexture *clip);
pfClipTexture *
pfMPClipTexture::getClipTexture(void);
void pfMPClipTexture::setCenter(int s, int t, int r);
void pfMPClipTexture::getCenter(int *s, int *t, int *r);
void pfMPClipTexture::setInvalidBorder(int border);
int pfMPClipTexture::getInvalidBorder(void);
void pfMPClipTexture::setVirtualLODOffset(int offset);
int pfMPClipTexture::getVirtualLODOffset(void);
void pfMPClipTexture::setNumEffectiveLevels(int levels);
int pfMPClipTexture::getNumEffectiveLevels(void);
void pfMPClipTexture::setMaster(pfMPClipTexture *master);
pfMPClipTexture *
pfMPClipTexture::getMaster(void);
void pfMPClipTexture::setShareMask(uint mask);
uint pfMPClipTexture::getShareMask(void);
void pfMPClipTexture::setLODRange(float min, float max);
void pfMPClipTexture::getLODRange(float *min, float *max);
void pfMPClipTexture::setMagFilter(uint filter);
uint pfGetMPClipTexture::getMagFilter(void);
void pfMPClipTexture::setLODBias(float biasS, float biasT,
float biasR);
Page 1
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
void pfGetMPClipTexture::getLODBias(float *biasS, float *biasT,
float *biasR);
void pfMPClipTexture::apply(void);
pfPipe * pfMPClipTexture::getPipe(void);
void pfMPClipTexture::setDTRFadeCount(int count);
int pfMPClipTexture::getDTRFadeCount(void);
void pfMPClipTexture::setDTRMode(pfClipTexture *tex,
uint DTRMode);
uint pfMPClipTexture::getDTRMode(pfClipTexture *tex);
void pfMPClipTexture::setTexLoadTime(float time);
float pfMPClipTexture::getTexLoadTime(void);
float pfMPClipTexture::getCurTexLoadTime(void);
pfList * pfMPClipTexture::getSlaves(void);
void pfMPClipTexture::setTexLoadTimeFrac(float fraction);
float pfMPClipTexture::getTexLoadTimeFrac(void);
void pfMPClipTexture::setDTRBlurMargin(float margin);
float pfMPClipTexture::getDTRBlurMargin(void);
void pfMPClipTexture::setLODOffsetLimit(int lo, int hi);
void pfMPClipTexture::getLODOffsetLimit(int *lo, int *hi);
void pfMPClipTexture::setNumEffectiveLevelsLimit(int lo,
int hi);
void pfMPClipTexture::getNumEffectiveLevelsLimit(int *lo,
int *hi);
void pfMPClipTexture::setMinLODLimit(float lo, float hi);
void pfMPClipTexture::getMinLODLimit(float *lo, float *hi);
void pfMPClipTexture::setMaxLODLimit(float lo, float hi);
void pfMPClipTexture::getMaxLODLimit(float *lo, float *hi);
Page 2
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
void pfMPClipTexture::setLODBiasLimit(float Slo, float Shi,
float Tlo, float Thi, float Rlo, float Rhi);
void pfMPClipTexture::getLODBiasLimit(float *Slo, float *Shi,
float *Tlo, float *Thi, float *Rlo, float *Rhi);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfMPClipTexture is derived from the parent
class pfObject, so each of these member functions of class pfObject are
also directly usable with objects of class pfMPClipTexture. This is also
true for ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
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 pfMPClipTexture 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 pfMPClipTexture is a libpf wrapper used to allow for the multi-process
operation of a pfClipTexture. A pfMPClipTexture allows user to center
the pfClipTexture (or change its invalid border) in the app, have all of
the work to determine the necessary disk and texture loading done in the
cull, and have all of texture loads applied frame accurately in the draw.
Page 3
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
After setting up a pfMPClipTexture, it should be attached to a pfPipe via
the pfPipe routine pfAddMPClipTexture. This will force the pfPipe to
automatically perform all necessary applying of the pfClipTexture at the
correct times and in the correct processes. Therefore, normal users of
pfMPClipTextures should NOT call nor have any reason to call
pfMPClipTexture::apply Note that all of the settable fields on a
pfMPClipTexture mirror a subset of those found on a pfClipTexture. Thus,
see the pfClipTexture man page for more detailed description of these
fields.
new pfMPClipTexture creates and returns a handle to a pfMPClipTexture.
pfMPClipTextures are always allocated from shared memory and cannot be
created statically, on the stack, or in arrays. pfMPClipTextures should
be deleted using pfDelete rather than the delete operator.
pfMPClipTexture::getClassType returns the pfType* for the class
pfMPClipTexture. The pfType* returned by pfMPClipTexture::getClassType
is the same as the pfType* returned by invoking the virtual function
getType on any instance of class pfMPClipTexture. Because OpenGL
Performer allows subclassing of built-in types, when decisions are maded
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.
pfMPClipTexture::setClipTexture sets the libpr pfClipTexture that this
pfMPClipTexture should multiprocess. Thus for all pfMPClipTextures, a
libpr pfClipTexture should be created and configured and the attached to
a pfMPClipTexture. pfMPClipTexture::getClipTexture returns the libpr
pfClipTexture that this pfMPClipTexture is driving safely through
Performer's multiprocessed environment.
pfMPClipTexture::setCenter sets the center to be applied to the shadowed
libpr pfClipTexture in a frame accurate manner based on Performer's
current multiprocessing configuration pfMPClipTexture::getCenter returns
the current center set for the pfMPClipTexture. Any of the arguments
s,t,r may be NULL in which case it will be ignored.
pfMPClipTexture::setInvalidBorder sets the invalid border to be used by
libpr pfClipTexture for the current frame. This invalid border is used
for load management. See pfClipTextureInvalidBorder and the notes
section of the libpr pfClipTexture man page for more details.
pfMPClipTexture::getInvalidBorder returns the invalid border which will
currently be used for this frame.
pfMPClipTexture::setVirtualLODOffset pfMPClipTexture::getVirtualLODOffset
returns the virtual LOD Offset currently being used by the
pfMPClipTexture.
pfMPClipTexture::setNumEffectiveLevels
pfMPClipTexture::getNumEffectiveLevels returns the number of effective
levels currently being used by the pfMPClipTexture.
Page 4
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
pfMPClipTexture::setMaster establishes a master/slave relationship
between two mpcliptextures. It also establishes the same relationship
between both mpcliptextures' corresponding cliptextures and image caches.
The pfMPClipTexture that is called becomes a slave to the mpcliptexture
given as an argument. See the description of pfClipTextureMaster and the
notes section of the libpr pfClipTexture man page for more details.
pfMPClipTexture::getMaster returns the master pfMPClipTexture of this
pfMPClipTexture, if this pfMPClipTexture is a slave. If the
pfMPClipTexture is not a slave, it returns NULL.
pfMPClipTexture::getSlaves returns a pointer to a pfList. If the
mpcliptexture is a master, the list contains pointers to pfMPClipTextures
that are slaves of this master. If the mpcliptexture isn't a master, the
pointer value returned is NULL.
pfMPClipTexture::setShareMask is used to set a bitwise "and" of the
control flags used to determine the amount of optional data sharing
between masters and slave mpcliptextures. Currently only one bit is
defined; PFMPCLIPTEXTURE_SHARE_CENTER, which is set "on" by default.
Giving zero indicates no sharing beyond the mandatory sharing of disk and
system memory image caches.
If PFMPCLIPTEXTURE_SHARE_CENTER is set, then the slaves will get updated
whenever the master gets its center changed. Changing slave centers will
be ignored by the slave, and will have no effect on the master. Center
sharing can be individually toggled on each slave. Changing the status of
center sharing on the master has no effect.
Sharing mask values have no effect pfMPClipTextures that aren't masters
or slaves.
pfMPClipTexture::getShareMask returns the share mask currently being used
by a slave pfMPClipTexture. The value returned by the master is
meaningless.
pfMPClipTexture::setLODRange sets the minimum and maximum LOD range to be
used in the virtual mpcliptextures. These values are clamped by the
current effective levels setting. The minimum and maximum LOD range
values are defined in terms of the virtual texture; so they are not
affected by the value of virtual LOD offset.
See the description of pfLODRange in the libpr pfTexture man page for
more details.
pfMPClipTexture::getLODRange returns the LOD Range currently being used
by the pfMPClipTexture. Either of the arguments min,max may be NULL in
which case it will be ignored.
pfMPClipTexture::getPipe returns the a pointer to the pfPipe that the
pfMPClipTexture has been added to. If the pfMPClipTexture currently
connected to any pipe, it returns NULL.
Page 5
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
pfMPClipTexture::setMagFilter sets the pfMPClipTexture magnification
filter type. See the pfTexture::setFilter man page for details on the
filter argument. pfMPClipTexture::getMagFilter returns the current
magnifying filter type for the pfMPClipTexture.
pfMPClipTexture::setLODBias sets the pfMPClipTexture texture bias
parameters. These parameters are used to alter the level of detail
computations. See the pfTexture::setLODBias man page for more details on
the biasS, biasT, and biasR arguments. pfTexture::getLODBias gets the
current LOD Bias values in the pfMPClipTexture. Any of the arguments
biasS,biasT,biasR may be NULL in which case it will be ignored.
pfMPClipTexture::setDTRFadeCount is used to adjust the number of frames
it takes to fade in a new level of the cliptexture. DTR (clip texture
load control) adjusts the sharpest visible level 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 from appearing too abruptly.
It fades in the new level or levels over the number of frames specified
by DTRFadeCount. The default fade count is 5. This call can be used to
change the fade count to any non-negative value. If the fade count is set
to zero, new levels appear immediately, with no fading.
pfMPClipTexture::getDTRFadeCount is used to query the currently set DTR
fade count. Since the count is set in the APP process, used in the CULL,
and the results appear in the DRAW, changes to the DTR fade count may
have up to 2 frames of latency before taking effect.
pfMPClipTexture::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
following bits: PF_DTR_MEMLOAD, PF_DTR_TEXLOAD, PF_DTR_READSORT, and
PF_DTR_TEXSIZE. 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, and PF_DTR_TEXSIZE allows adjustment of the effective
clipsize (changed by adjusting the invalid border) to allow finer levels,
albeit at a smaller than normal size, when choosing which cliptexture
levels to make visible. These modes can be set singly or in any
combination. The default value is
PF_DTR_MEMLOAD|PF_DTR_TEXLOAD|PF_DTR_READSORT.
pfMPClipTexture::getDTRMode can be used to get the currently set DTR
mode.
pfMPClipTexture::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
Page 6
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
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 shrinks all
the levels or gives up and blurs down to the next lower level, depending
on whether PF_DTR_TEXSIZE is set in the mode bit (see minClipSizeRatio
for details). 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.
pfMPClipTexture::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.
pfMPClipTexture::getCurTexLoadTime return the tex load time actually
being used by the pfMPClipTexture DTR load control system. This value is
either the tex load time set on the pfMPClipTexture, or if no value was
set their, the total tex load time set on the pfMPClipTexture's pipe
scaled by the normalized down load time frac value, set by calling
pfMPClipTexture::setTexLoadTimeFrac.
pfMPClipTexture::setTexLoadTimeFrac. sets the fractional values used to
scale the total tex load time on the pfPipe that this pfMPClipTexture is
attached to. The product of the pfPipe's total tex load time and the
pfMPClipTexture's tex load time frac provides the pfMPClipTexture with a
download time to use with its DTR load control system.
The tex load time frac values for all the pfMPClipTextures attached to a
given pfPipe are summed together and normalized. The normalization factor
is applied when the frac value is used to compute a pfMPClipTexture's
texture download time.
pfMPClipTexture::getTexLoadTimeFrac. returns the current value of the
pfMPClipTexture's tex download time fraction. The default value is 1.
pfMPClipTexture::setDTRBlurMargin. sets the blur margin value used to
control DTR load control hysteresis. This hysterisis controls LOD
flickering when the remaining download time is nearly equal to the time
it will take to download the next finer level.
The blur margin value is used by DTR to compute a cushion of extra time
that must be available before sharpening to the next level. This cushion
of time helps average out the small differences in download time caused
by different tile boundary alignments from frame to frame. The
pfMPClipTexture will show the image at a constant, blurrier level, rather
then oscillate between that level and the next finest one. The larger the
blur margin value, the more cushion. An excessive blur margin value will
Page 7
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
cause DTR to show a blurrier level than necessary for a given center
speed.
pfMPClipTexture::getDTRBlurMargin. return the current blur margin value
being used by DTR. The default value is .5.
The functions setLODOffsetLimit, setNumEffectiveLevelsLimit,
setMinLODLimit, setMaxLODLimit, setLODBiasLimit and corresponding query
functions getLODOffsetLimit, getNumEffectiveLevelsLimit, getMinLODLimit,
getMaxLODLimit, getLODBiasLimit are analogous to the corresponding
functions of pfClipTexture (see the pfClipTexture man page for more
details). The limits are passed down from the APP process to the CULL
process and stored in the pfClipTexture at the beginning of the CULL's
frame, so callback functions in the CULL can frame-accurately query the
values from either the pfMPClipTexture or the pfClipTexture. This
technique is used by clip texture scene loaders such as .spherepatch and
.ct to communicate with applications such as the clipfly program (see the
sample source code for clipfly and these loaders for details.)
NOTES
ClipTexture functionality is not supported under Linux.
BUGS
pfMPClipTextures do not work (they should be no-ops) in Performer's
CULLoDRAW multiprocessing mode.
SEE ALSO
pfPipe, pfClipTexture, pfImageCache
Page 8
