pfuTex(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuTex(3pf)NAME
pfuNewSharedTex, pfuGetSharedTexList, pfuMakeTexList,
pfuMakeSceneTexList, pfuDownloadTexList, pfuGetTexSize, pfuNewTexList,
pfuLoadTexListFiles, pfuLoadTexListFmt, pfuNewProjector,
pfuProjectorPreDrawCB, pfuProjectorMovie, pfuGetProjectorHandle,
pfuProjectorHandle, pfuGetProjectorScreenList, pfuAddProjectorScreen,
pfuRemoveProjectorScreen, pfuReplaceProjectorScreen,
pfuLoadDetailTextures - Create and initialize textures, create and
display movies.
FUNCTION SPECIFICATION
#include <Performer/pfutil.h>
pfTexture * pfuNewSharedTex(const char *filename, void *arena);
pfList * pfuGetSharedTexList(void);
pfList * pfuMakeTexList(pfNode *node);
pfList * pfuMakeSceneTexList(pfScene *scene);
void pfuDownloadTexList(pfList *list, int style);
int pfuGetTexSize(pfTexture *tex);
void pfuNewTexList(pfTexture *tex);
pfList * pfuLoadTexListFiles(pfList *movieTexList,
char nameList[][PF_MAXSTRING], int len);
pfList * pfuLoadTexListFmt(pfList *movieTexList,
const char *fmtStr, int start, int end);
pfSequence * pfuNewProjector(pfTexture *handle);
int pfuProjectorPreDrawCB(pfTraverser *trav, void *travData);
void pfuProjectorMovie(pfSequence *proj, pfList *movie);
pfTexture * pfuGetProjectorHandle(pfSequence *proj);
void pfuProjectorHandle(pfSequence *proj, pfTexture *new);
pfList * pfuGetProjectorScreenList(pfSequence *proj);
void pfuAddProjectorScreen(pfSequence *proj,
pfTexture *screen);
void pfuRemoveProjectorScreen(pfSequence *proj,
pfTexture *screen);
Page 1
pfuTex(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuTex(3pf)
void pfuReplaceProjectorScreen(pfSequence *proj,
pfTexture *old, pfTexture *new);
void pfuLoadDetailTextures(pfList *list, pfuDetailInfo *di,
int ndi);
DESCRIPTION
These utilities assist in the sharing and downloading of textures.
For consistent frame rates, it is very important to download textures
into the graphics pipeline's physical texture memory before beginning
simulation. This is so that there is no momentary pause while the
textures are processed (texdef) and downloaded (texbind).
An example of the use of these functions can be found in
/usr/share/Performer/src/sample/C/common/generic.c which is used by a
number of sample applications including the OpenGL Performer perfly
sample application.
pfuNewSharedTex examines the application's global list of previously
allocated textures for the file filename. If the file has already been
loaded, the address of the existing pfTexture structure is returned; if
not, a new pfTexture is allocated in arena, the named file is read, and
the address is returned for reference in future requests.
pfuGetSharedTexList returns the list of all textures allocated using the
pfuNewSharedTex texture-sharing mechanism described above during the
current execution of the process. The list returned is useful for many
things including texture downloading.
pfuMakeTexList constructs a list of textures by recursively traversing
the OpenGL Performer scene graph rooted by node. Since this traversal is
exhaustive no texture will be missed.
Performer supports the notion of a scene pfGeoState to represent common
rendering state for a pfScene. When this mechanism is used, the texture
list built by pfuMakeTexList will not include the texture defined by the
scene pfGeoState. The function pfuMakeSceneTexList duplicates the
function of pfuMakeTexList and adds the scene pfGeoState's texture to the
list if the scene pfGeoState defines a texture.
pfuDownloadTexList visits each texture in the list provided in list and
performs one of the following functions:
PFUTEX_APPLY
Download each texture without any on-screen fanfare.
PFUTEX_SHOW
Show each texture in the screen while downloading. This is the
source of the "slide-show" seen as the OpenGL Performer perfly
program starts up.
Page 2
pfuTex(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuTex(3pf)
PFUTEX_DEFINE
Perform a partial download, performing only the texdef
operation and not the subsequent texbind. This can be used as
the basis of simple texture paging mechanisms.
In most cases, pfuDownloadTexList will be called in the first traversal
through the channel draw callback on each configured pfPipe. This
function must be called from the draw process since it makes direct
graphics function calls.
pfuGetTexSize queries the number of bytes of texture used in tex.
pfuNewTexList preallocates a sequence of 16 frames on a pfTexture for
animation.
pfuLoadTexListFiles fills a list within a pfTexture from the array of
file names, nameList, which contains len names. If movieTexList is passed
as NULL, a new list is automatically allocated. The filled list is
returned.
pfuLoadTexListFmt fills a list within a pfTexture from a sequence of
files indicated by the printf-style format string fmtStr.
pfuLoadTexListFmt uses sprintf and fmtStr to construct filenames ranging
sequentially from start to end and adds the textures in these files to
the list.
The following routines are used to create and display a movie. A movie
has a projector (a pfSequence node with a special pfUserData and pre-draw
callback), a default base frame (a pfTexture*), one or more screens (-
pfTexture*'s) and a reel of movie frames (a pfList of pfTexture*).
The pfSequence API is used to run the projector and control the movie
display. Screens can be added, removed, or replaced at will. Each
projector can have any number of screens but each screen should be in
only one projector. The projector node should be the first child of the
pfScene node. It draws no geometry, but only configures its pfTexture*
screen to display the correct image when accessed later via traversal of
the normal scene graph (or a direct pfApplyTex).
pfuNewProjector creates and returns a pfSequence containing the list of
textures in handle, with the textures stored as the leaves under the
pfSequence and installs pfuProjectorPreDrawCB as the default pre-draw
stage callback.
pfuProjectorMovie sets the pfSequence passed in proj to the list of
textures passed in movie. This enables movie to be played in all the
screens of proj.
pfuProjectorHandle sets the pfSequence passed in proj to the list of
textures contained in the pfTexture handle new.
pfuGetProjectorHandle returns the pfTexture handle from the pfSequence
Page 3
pfuTex(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuTex(3pf)
passed in proj.
pfuGetProjectorScreenList returns the list of screens in the pfSequence
passed in proj.
pfuAddProjectorScreen adds tex to the screen list of proj. This causes
tex to reference proj's movie as its list of frames.
pfuRemoveProjectorScreen removes the screen screen from the movie proj.
This sets screen's texture list to NULL and its frame to -1.
pfuReplaceProjectorScreen replaces the screen old in the movie proj with
the screen mew. This sets old's texture list to NULL and its frame to -1.
The following code fragment shows how a movie can be created.
Example 1:
/* create a projector with a pfTexture handle for the movie tape.
* The reel base texture can also be used as a base screen.
* The movie can be the texture list on the handle here, or can
* be added/replaced later with pfuProjectorMovie(proj, tape) or with
* pfuProjectorHandle(proj, newHandle);
*/
pfTexture *handle = pfNewTex(pfGetSharedArena());
pfSequence *proj = pfuNewProjector(handle);
/* set AUTO_IDLE mode on the handle - new screens on the projector inherit
* this mode from the handle
*/
pfTexLoadMode(handle, PFTEX_LIST_AUTO_IDLE, 1);
/* Create a pfList to hold the frames of the movie */
pfList *tape = pfuLoadTexListFmt(NULL, fmtStr)
/* or pfuLoadTexListFiles(NULL, fileNameList); */
/* put the movie in the projector */
pfuProjectorMovie(proj, tape);
pfuLoadDetailTextures will define the detail textures according to their
associations specified with di to the base textures found in list.
typedef struct {
char *texname;
char *detailname;
int level;
pfTexture *detailtex;
int setSpline;
pfVec2 spline[4];
} pfuDetailInfo;
Page 4
pfuTex(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuTex(3pf)NOTES
The libpfutil source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
SEE ALSO
pfApplyTex, pfList, pfScene, pfSequence, pfTexture, pfUserData, printf,
sprintf
Page 5
