pfuAddClipTextureToPipes(3pf)NAME
pfuAddMPClipTextureToPipes, pfuAddMPClipTexturesToPipes,
pfuInitClipTexConfig, pfuMakeClipTexture, pfuFreeClipTexConfig,
pfuInitImgCacheConfig, pfuMakeImageCache, pfuFreeImgCacheConfig - Connect
an MPClipTexture to one or more Pipes
FUNCTION SPECIFICATION
#include <Performer/pfutil.h>
pfGroup * pfuAddMPClipTextureToPipes(pfMPClipTextures *master,
pfPipe *masterpipe, pfPipe *pipes[]);
pfGroup * pfuAddMPClipTexturesToPipes(pfList *mpcliptextures,
pfPipe *masterpipe, pfPipe *pipes[]);
void pfuInitClipTexConfig(pfuClipTexConfig *config);
void pfuMakeClipTexture(pfuClipTexConfig *config);
void pfuFreeClipTexConfig(pfuClipTexConfig *config);
void pfuInitImgCacheConfig(pfuImgCacheConfig *config);
void pfuMakeImageCache(pfuImgCacheConfig *config);
void pfuFreeImgCacheConfig(pfuImgCacheConfig *config);
DESCRIPTION
pfMPClipTextures must be attached to pipes if they are to update
properly. In order to connect the same pfMPClipTexture to more than one
pipe, the pfMPClipTexture must be cloned; the original pfMPClipTexture
becomes the master, and the new pfMPClipTexture becomes the slave.
This is done automatically if the same pfMPClipTexture is added to more
than one pipe. This routine makes the process more convenient, by
allowing the user to specify which pipe should contain the master
cliptexture, what set of pipes should have the pfMPClipTextures attached,
and the pfMPClipTexture(s) that should be attached.
This routine does additional checking to avoid erroneous operations. For
example, it checks to avoid common mistakes such as; trying to attach the
same pfMPClipTexture to the same pfPipe more than once, not adding a
slave to a pfPipe that already contains the slave's master, etc. This
makes it possible to run the routine multiple times without generating
warnings.
pfuAddMPClipTextureToPipes takes a pointer to an pfMPClipTexture master
which is put in masterpipe. All other pipes in pipes are given slaves to
this cliptexture.
Both the masterpipe and pipes arguments can be NULL. If masterpipe is
NULL, the first available pfPipe is used to contain the master (if it
Page 1
pfuAddClipTextureToPipes(3pf)
isn't already attached to a different pipe). If pipes is NULL, then all
the pfPipes have the pfMPClipTexture or its slaves attached to it.
If only a single pfMPClipTexture needs to be attached, use the
pfuAddMPClipTextureToPipes routine. If a number of pfMPClipTextures need
to be attached to pfPipes, you can call pfuAddMPClipTextureToPipes
multiple times or create a list of them and pass it to
pfuAddMPClipTexturesToPipes using mpcliptextures. This is particulary
convenient if you are using the clipcenter nodes, since
pfuProcessClipCenters fills in the pfList you give it with the list of
pfMPClipTexture objects in the scene graph.
pfuInitClipTexConfig, pfuMakeClipTexture, and pfuFreeClipTexConfig are
used together to create and configure clip textures. These routines are
used by pfdLoadClipTexture, and can be used by applications to build
cliptextures dynamically or to design custom clip texture configuration
file formats. pfuMakeClipTexture takes a single argument, a pointer to a
properly filled in pfuClipTexConfig structure, and uses the information
in it to create and configure a cliptexture, its image caches, and its
pyramid image tiles. The pfuInitClipTexConfig called before
pfuMakeClipTexture; it's purpose is to fill in the pfuClipTexConfig
structure with default values. pfuFreeClipTexConfig is called last, after
the cliptexture has been created. It correctly frees any elements of the
structure that have been created (although it doesn't free the structure
itself).
The recommended proceedure is to allocate a pfuClipTexConfig structure,
call pfuInitClipTexConfig to initialize it, fill in the values of the
structure to describe the clip texture desired, then call
pfuMakeClipTexture with a pointer to the initialized and filled in
structure. Finally, call pfuFreeClipTexConfig to free any structure
elements, then delete the pfuClipTexConfig structure itself. The
advantage of this proceedure is that structure elements are filled in
with reasonable default values, allowing optional values to be left out.
It also improves error checking, since the error checking code knows what
the default values should be, allowing it to warn the application if
mandatory values weren't filled in.
The pfuClipTexConfig structure has three types of values: configuration
data for the cliptexture itself, function pointers to user-supplied
functions that load the image caches and image tiles that the clip
texture requires, and pointers to user-defined data structures used by
the user-supplied configuration functions.
The user-supplied image cache configuration function should be an
argument of the following format: pfImageCache *func(pfClipTexture *ct,
int level, pfuClipTexConfig *config)
This function should use pfuInitImgCacheConfig, pfuMakeImageCache, and
pfuFreeImgCacheConfig in the same way as was done for configuring
cliptextures, and return a pointer to the created and configured image
cache. This function can access the user-supplied data in the icData
Page 2
pfuAddClipTextureToPipes(3pf)
element of the _pfuClipTexConfig structure for additional information.
The user-supplied image tile configuration function should be an argument
of the following format: pfImageTile *func(pfClipTexture *ct, int level,
pfuClipTexConfig *config)
This function should create and configure the required image tile and
return a pointer to it. This function can access the user-supplied data
in the tileData element of the _pfuClipTexConfig structure for additional
information.
The configuration functions allow the application to customize how image
caches and image tiles are configured when an clip texture is created.
The pfdLoadImage.c file uses this functionality and should be used as an
example.
The pfuInitImgCacheConfig, pfuMakeImageCache, and pfuFreeImgCacheConfig
functions are used in the same way as described for pfuInitClipTexConfig,
pfuMakeClipTexture, and pfuFreeClipTexConfig. The major difference is
that the pfuImgCacheConfig structure doesn't require user-supplied
function or data pointers.
NOTES
ClipTexture functionality is not supported under Linux.
The libpfutil source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
BUGSSEE ALSO
pfuProcessClipCenters, pfuNewClipCenterNode, pfClipTexture, pfImageCache,
pfImageTile, pfMPClipTexture, pfMPImageCache, pfTexLoad, pfTexture,
pfuGetClosestPoint
Page 3
