pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NAME
pfNewMPClipTexture, pfGetMPClipTextureClassType,
pfMPClipTextureClipTexture, pfGetMPClipTextureClipTexture,
pfMPClipTextureCenter, pfGetMPClipTextureCenter,
pfMPClipTextureInvalidBorder, pfGetMPClipTextureInvalidBorder,
pfMPClipTextureVirtualLODOffset, pfGetMPClipTextureVirtualLODOffset,
pfMPClipTextureNumEffectiveLevels, pfGetMPClipTextureNumEffectiveLevels,
pfMPClipTextureMaster, pfGetMPClipTextureMaster,
pfMPClipTextureShareMask, pfGetMPClipTextureShareMask,
pfMPClipTextureLODRange, pfGetMPClipTextureLODRange,
pfMPClipTextureMagFilter, pfGetMPClipTextureMagFilter,
pfMPClipTextureLODBias, pfGetMPClipTextureLODBias, pfApplyMPClipTexture,
pfGetMPClipTexturePipe, pfMPClipTextureDTRFadeCount,
pfGetMPClipTextureDTRFadeCount, pfMPClipTextureDTRMode,
pfGetMPClipTextureDTRMode, pfMPClipTextureTexLoadTime,
pfGetMPClipTextureTexLoadTime, pfGetMPClipTextureCurTexLoadTime,
pfGetMPClipTextureSlaves, pfMPClipTextureTexLoadTimeFrac,
pfGetMPClipTextureTexLoadTimeFrac, pfMPClipTextureDTRBlurMargin,
pfGetMPClipTextureDTRBlurMargin, pfMPClipTextureLODOffsetLimit,
pfGetMPClipTextureLODOffsetLimit, pfMPClipTextureNumEffectiveLevelsLimit,
pfGetMPClipTextureNumEffectiveLevelsLimit, pfMPClipTextureMinLODLimit,
pfGetMPClipTextureMinLODLimit, pfMPClipTextureMaxLODLimit,
pfGetMPClipTextureMaxLODLimit, pfMPClipTextureLODBiasLimit,
pfGetMPClipTextureLODBiasLimit - Create, modify, and query a libpf
multiprocessing shadow for pfClipTextures
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfMPClipTexture *
pfNewMPClipTexture(void);
pfType * pfGetMPClipTextureClassType(void);
void pfMPClipTextureClipTexture(pfMPClipTexture* mpclip,
pfClipTexture *clip);
pfClipTexture *
pfGetMPClipTextureClipTexture(pfMPClipTexture* mpclip);
void pfMPClipTextureCenter(pfMPClipTexture* mpclip, int s,
int t, int r);
void pfGetMPClipTextureCenter(pfMPClipTexture* mpclip, int *s,
int *t, int *r);
void pfMPClipTextureInvalidBorder(pfMPClipTexture* mpclip,
int iborder);
int pfGetMPClipTextureInvalidBorder(pfMPClipTexture* mpclip);
Page 1
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
void pfMPClipTextureVirtualLODOffset(pfMPClipTexture *mpclip,
int offset);
int -
pfGetMPClipTextureVirtualLODOffset(pfMPClipTexture *mpclip);
void pfMPClipTextureNumEffectiveLevels(pfMPClipTexture *mpclip,
int levels);
int -
pfGetMPClipTextureNumEffectiveLevels(pfMPClipTexture *mpclip);
void pfMPClipTextureMaster(pfMPClipTexture *mpclip,
pfMPClipTexture *master);
pfMPClipTexture *
pfGetMPClipTextureMaster(pfMPClipTexture *mpclip);
void pfMPClipTextureShareMask(pfMPClipTexture *mpclip,
uint mask);
uint pfGetMPClipTextureShareMask(pfMPClipTexture *mpclip);
void pfMPClipTextureLODRange(pfMPClipTexture *mpclip,
float min, float max);
void pfGetMPClipTextureLODRange(pfMPClipTexture *mpclip,
float *min, float *max);
void pfMPClipTextureMagFilter(pfMPClipTexture *mpclip,
uint filter);
uint pfGetMPClipTextureMagFilter(pfMPClipTexture *mpclip);
void pfMPClipTextureLODBias(pfMPClipTexture *mpclip,
float biasS, float biasT, float biasR);
void pfGetMPClipTextureLODBias(pfMPClipTexture *mpclip,
float *biasS, float *biasT, float *biasR);
void pfApplyMPClipTexture(pfMPClipTexture* mpclip);
pfPipe * pfGetMPClipTexturePipe(pfMPClipTexture *mpclip);
void pfMPClipTextureDTRFadeCount(pfMPClipTexture *tex,
int count);
int pfGetMPClipTextureDTRFadeCount(pfMPClipTexture *tex);
void pfMPClipTextureDTRMode(pfMPClipTexture *tex,
uint DTRMode);
Page 2
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
uint pfGetMPClipTextureDTRMode(pfMPClipTexture *tex);
void pfMPClipTextureTexLoadTime(pfMPClipTexture *tex,
float time);
float pfGetMPClipTextureTexLoadTime(pfMPClipTexture *tex);
float pfGetMPClipTextureCurTexLoadTime(pfMPClipTexture *tex);
pfList * pfGetMPClipTextureSlaves(pfMPClipTexture *tex);
void pfMPClipTextureTexLoadTimeFrac(pfMPClipTexture *tex,
float fraction);
float pfGetMPClipTextureTexLoadTimeFrac(pfMPClipTexture *tex);
void pfMPClipTextureDTRBlurMargin(pfMPClipTexture *tex,
float margin);
float pfGetMPClipTextureDTRBlurMargin(pfMPClipTexture *tex);
void pfMPClipTextureLODOffsetLimit(pfMPClipTexture* tex,
int lo, int hi);
void pfGetMPClipTextureLODOffsetLimit(pfMPClipTexture* tex,
int *lo, int *hi);
void -
pfMPClipTextureNumEffectiveLevelsLimit(pfMPClipTexture* tex,
int lo, int hi);
void -
pfGetMPClipTextureNumEffectiveLevelsLimit(pfMPClipTexture* tex,
int *lo, int *hi);
void pfMPClipTextureMinLODLimit(pfMPClipTexture* tex, float lo,
float hi);
void pfGetMPClipTextureMinLODLimit(pfMPClipTexture* tex,
float *lo, float *hi);
void pfMPClipTextureMaxLODLimit(pfMPClipTexture* tex, float lo,
float hi);
void pfGetMPClipTextureMaxLODLimit(pfMPClipTexture* tex,
float *lo, float *hi);
void pfMPClipTextureLODBiasLimit(pfMPClipTexture* tex,
float Slo, float Shi, float Tlo, float Thi, float Rlo,
float Rhi);
Page 3
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
void pfGetMPClipTextureLODBiasLimit(pfMPClipTexture* tex,
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. Casting an
object of class pfMPClipTexture to an object of class pfObject is taken
care of automatically. This is also true for casts to objects of
ancestor classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfDeleteGLHandle(pfObject *obj);
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.
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 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.
After setting up a pfMPClipTexture, it should be attached to a pfPipe via
the pfPipe routine pfAddMPClipTexture. This will force the pfPipe to
Page 4
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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
pfApplyMPClipTexture. 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.
pfNewMPClipTexture creates and returns a handle to a pfMPClipTexture.
pfMPClipTextures are always allocated from shared memory and can be
deleted using pfDelete.
pfGetMPClipTextureClassType returns the pfType* for the class
pfMPClipTexture. The pfType* returned by pfGetMPClipTextureClassType is
the same as the pfType* returned by invoking pfGetType 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 pfIsOfType to test if an object is of a type
derived from a Performer type rather than to test for strict equality of
the pfType*'s.
pfMPClipTextureClipTexture 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. pfGetMPClipTextureClipTexture returns the libpr
pfClipTexture that this pfMPClipTexture is driving safely through
Performer's multiprocessed environment.
pfMPClipTextureCenter sets the center to be applied to the shadowed libpr
pfClipTexture in a frame accurate manner based on Performer's current
multiprocessing configuration pfGetMPClipTextureCenter 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.
pfMPClipTextureInvalidBorder 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.
pfGetMPClipTextureInvalidBorder returns the invalid border which will
currently be used for this frame.
pfMPClipTextureVirtualLODOffset pfGetMPClipTextureVirtualLODOffset
returns the virtual LOD Offset currently being used by the
pfMPClipTexture.
pfMPClipTextureNumEffectiveLevels pfGetMPClipTextureNumEffectiveLevels
returns the number of effective levels currently being used by the
pfMPClipTexture.
pfMPClipTextureMaster establishes a master/slave relationship between two
mpcliptextures. It also establishes the same relationship between both
mpcliptextures' corresponding cliptextures and image caches. The
Page 5
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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.
pfGetMPClipTextureMaster
returns the master pfMPClipTexture of this pfMPClipTexture, if this
pfMPClipTexture is a slave. If the pfMPClipTexture is not a slave, it
returns NULL.
pfGetMPClipTextureSlaves 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.
pfMPClipTextureShareMask 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.
pfGetMPClipTextureShareMask
returns the share mask currently being used by a slave pfMPClipTexture.
The value returned by the master is meaningless.
pfMPClipTextureLODRange 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.
pfGetMPClipTextureLODRange
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.
pfGetMPClipTexturePipe 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.
pfMPClipTextureMagFilter sets the pfMPClipTexture magnification filter
Page 6
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
type. See the pfTexFilter man page for details on the filter argument.
pfGetMPClipTextureMagFilter returns the current magnifying filter type
for the pfMPClipTexture.
pfMPClipTextureLODBias sets the pfMPClipTexture texture bias parameters.
These parameters are used to alter the level of detail computations. See
the pfTexLODBias man page for more details on the biasS, biasT, and biasR
arguments. pfGetTexLODBias 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.
pfMPClipTextureDTRFadeCount 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.
pfGetMPClipTextureDTRFadeCount 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.
pfMPClipTextureDTRMode 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. pfGetMPClipTextureDTRMode
can be used to get the currently set DTR mode.
pfMPClipTextureTexLoadTime 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
Page 7
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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. pfGetMPClipTextureTexLoadTime 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.
pfGetMPClipTextureCurTexLoadTime 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
pfMPClipTextureTexLoadTimeFrac.
pfMPClipTextureTexLoadTimeFrac. 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.
pfGetMPClipTextureTexLoadTimeFrac. returns the current value of the
pfMPClipTexture's tex download time fraction. The default value is 1.
pfMPClipTextureDTRBlurMargin. 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
cause DTR to show a blurrier level than necessary for a given center
speed.
Page 8
pfMPClipTexture(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
pfGetMPClipTextureDTRBlurMargin. return the current blur margin value
being used by DTR. The default value is .5.
The functions pfMPClipTextureLODOffsetLimit,
pfMPClipTextureNumEffectiveLevelsLimit, pfMPClipTextureMinLODLimit,
pfMPClipTextureMaxLODLimit, pfMPClipTextureLODBiasLimit and corresponding
query functions pfMPGetClipTextureLODOffsetLimit,
pfMPGetClipTextureNumEffectiveLevelsLimit, pfMPGetClipTextureMinLODLimit,
pfMPGetClipTextureMaxLODLimit, pfMPGetClipTextureLODBiasLimit 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 9
