pfDispList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfNewDList, pfGetDListClassType, pfOpenDList, pfResetDList, pfCloseDList,
pfGetDListSize, pfGetDListType, pfAddDListCmd, pfAppendDList,
pfDListCallback, pfDrawDList, pfCompileDList, pfPreprocessDList,
pfDListMode, pfGetDListMode, pfDrawGLObj, pfGetCurDList - Create and
control a display list
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfDispList * pfNewDList(int type, int size, void *arena);
pfType * pfGetDListClassType(void);
void pfOpenDList(pfDispList *dlist);
void pfResetDList(pfDispList *dlist);
void pfCloseDList(void);
int pfGetDListSize(const pfDispList *dlist);
int pfGetDListType(const pfDispList *dlist);
void pfAddDListCmd(int cmd);
int pfAppendDList(pfDispList* dlist, const pfDispList *src);
void pfDListCallback(pfDListFuncType callback, int nbytes,
void *data);
int pfDrawDList(pfDispList *dlist);
int pfCompileDList(pfDispList *dlist);
int pfPreprocessDList(pfDispList *dlist, int flag);
void pfDListMode(pfDispList *dlist, int mode, int value);
int pfGetDListMode(pfDispList *dlist, int mode);
void pfDrawGLObj(GLOBJECT obj);
pfDispList * pfGetCurDList(void);
typedef void (*pfDListFuncType)(void *data);
Page 1
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfDispList is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfDispList. Casting an object of
class pfDispList 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 pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfDispList 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);
PARAMETERS
dlist identifies a pfDispList.
DESCRIPTION
A pfDispList is a reusable display list that captures certain libpr
commands. pfNewDList creates and returns a handle to a new pfDispList.
The arguments specify the type and size of the display list. pfDispLists
can be deleted with pfDelete.
type is a symbolic token that specifies a type of pfDispList and is
either PFDL_FLAT or PFDL_RING. A PFDL_FLAT display list is a linear list
Page 2
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
of commands and data while a PFDL_RING is configured as a ring buffer
(FIFO). A ring buffer is provided for multiprocessed paired producer and
consumer applications where the producer writes to the buffer while the
consumer simultaneously reads from, and draws the buffer. OpenGL
Performer automatically ensures ring buffer consistency by providing
synchronization and mutual exclusion to processes on ring buffer full or
empty conditions. pfGetDListType returns the type of dlist.
pfGetDListClassType returns the pfType* for the class pfDispList. The
pfType* returned by pfGetDListClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfDispList.
Because OpenGL Performer allows subclassing of built-in types, when
decisions are made based on the type of an object, it is usually better
to use pfIsOfTypeto test if an object is of a type derived from a
Performer type rather than to test for strict equality of the pfType*'s.
The size argument to pfNewDList gives a hint in words about how much
storage the pfDispList will require. If more storage is required, OpenGL
Performer will automatically grow the pfDispList by size words at a time.
arena specifies the malloc arena out of which the pfDispList is allocated
or NULL for allocation off the heap. pfGetDListSize returns the size of
dlist that was requested by pfNewDList, not its current size.
pfOpenDList opens dlist for appending and puts the calling process into
display list mode. When in display list mode, display-listable libpr
commands are recorded in the currently active display list rather than
being executed immediately. libpr commands that may be recorded in a
pfDispList say so in their respective man pages. Only one pfDispList may
be open at a time. pfGetCurDList returns the currently active display
list or NULL if the calling process is in immediate mode.
The currently active pfDispList is a global value but is stored in the
PRDA process header so that share group processes (see sproc) need not
share the same currently active pfDispList.
The contents of one pfDispList may be appended to a second pfDispList
with the function pfAppendDList. All pfDispList elements in src are
appended to the pfDispList dlist.
Each pfDispList maintains head and tail pointers that indicate where in
the list commands are to be appended and evaluated respectively.
Commands entered into the display list are appended after the head
pointer and increment the head pointer appropriately. Commands drawn by
pfDrawDList increment the tail pointer but do not remove commands from
the list. In the PFDL_RING case, OpenGL Performer ensures that the tail
pointer does not overrun the head pointer and vice versa by spinning
processes.
Both head and tail pointers are reset to the beginning of the pfDispList
by pfResetDList so that any additions to the current pfDispList will
overwrite previously entered commands. The tail pointers of flat lists
are automatically reset by pfDrawDList when the tail pointer reaches the
Page 3
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
head pointer so that the pfDispList may be rendered again from the
beginning.
pfCloseDList 'closes' the active pfDispList and returns the application
to immediate mode.
For PFDL_FLAT display lists, pfDrawDList traverses dlist from the tail to
the head pointer, and then resets the tail pointer to the beginning of
dlist. If the pfDispList is a PFDL_RING, pfDrawDList will continually
draw the display list, returning control to the application only on
PFDL_END_OF_FRAME or PFDL_RETURN commands (see pfAddDListCmd). After
returning, a subsequent call to pfDrawDList will restart drawing from the
previous position in the list.
pfDrawDList interprets the commands and data in dlist and executes libpr
state routines that in turn execute graphics library commands that send
command tokens down the graphics pipeline. pfDrawDList is itself a
display-listable command provided dlist is not the currently active
pfDispList. The return value is the end of frame, PFDL_END_OF_FRAME,
forced return PFDL_RETURN, or end of list PFDL_END_OF_LIST token will be
returned or else -1 if an error is encountered. If the current
pfDispList mode is PFDL_MODE_COMPILE_GL, the PFDL_END_OF_LIST token will
be returned.
pfCompileDList will compile a pfDispList into a GL display list. The
return value is that from pfDrawDList and will be -1 if an error is
encountered. Note that user callback functions in pfDispLists are only
exectued upon display list creation.
pfDListMode sets the specified mode to the given value. The supported
mode is PFDL_MODE_COMPILE_GL and when set to 1, this causes the
associated GL display list to be drawn when pfDrawDList is called and a
new GL display list will be auto-created if one does not exist or of the
current display list is dirty. By default, PFDL_MODE_COMPILE_GL is false.
User callback functions in pfDispLists are only exectued upon display
list creation. pfGetDListMode returns the current value of mode.
The following example draws a pfGeoSet into a pfDispList and then
subsequently draws the pfDispList:
/* Open DList and append GSet */
pfOpenDList(dlist);
pfEnable(PFEN_WIREFRAME);
pfDrawGSet(gset);
/* Close DList and return to immediate mode */
pfCloseDList();
/* Draw 'gset' in wireframe */
pfDrawDList(dlist);
Page 4
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfDListCallback allows custom rendering in the middle of a display list
by putting a function callback and data in the current display list. Up
to 64 bytes of user-data may be copied into the display list. nbytes
specifies the length of data that data references. When a callback token
is encountered while drawing a display list, the function callback will
be called with a pointer to the user data that is cached in the display
list. A callback may call pfPushState upon entering and pfPopState when
leaving to ensure that any state changes made in the callback will be not
inherited by subsequent geometry.
pfAddDListCmd adds cmd to the currently active display list. cmd is one
of the following symbolic tokens, both of which return control to the
application but indicate different situations.
PFDL_RETURN
PFDL_END_OF_FRAME
pfDrawGLObj will directly draw the graphics library display list object
identified by obj (glCallList in OpenGL) if there is no active
pfDispList. If there is an open pfDispList, then pfDrawGLObj will simply
add the identifier and command to the active pfDispList.
OpenGL Performer optimizes pfDispList's when they are being built by
eliminating redundant mode changes and by unwinding pfGeoStates into
their component parts. As a result, modifications to objects after they
are placed in a pfDispList may be ignored by the pfDispList. To be safe,
do not modify any objects that were placed in one or more pfDispLists.
Here is an example of this phenomenon:
/* Attach gstate0 to gset */
pfGSetGState(gset, gstate0);
/* Open dlist as current pfDispList */
pfOpenDList(dlist);
pfDrawGSet(gset);
/* Return to immediate mode */
pfCloseDList();
/* Attach gstate1 to gset */
pfGSetGState(gset, gstate1);
/*
* dlist will use gstate0 and not be aware that gset was modified to
* use gstate1.
*/
pfDrawDList(dlist);
Page 5
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
Preprocessing a Display List
The following routines are useful in libpr-only applications; libpf
applications do not need to call these routines. Preprocessing of the
light point display list is automatically managed by the libpf Light
Point process (see pfConfig).
pfPreprocessDList is used to preprocess the dlist display list in order
to accelerate it's handling in the draw process. This call must be
encapsulated between the open and close of another pfDispList. It is
just like drawing a pfDispList into another one.
The flag is a bit field that indicates which preprocessing is to be done.
Currently only PFDL_PREPROCESS_LPSTATE (which computes the appearance of
each light point) is defined. See pfLPointState and pfCalligraphic for
further information.
Preprocessing makes sense only if it is done in a separate process, so
that these computations can be done while the Draw Process is drawing
other display lists. Typically, the Draw Process will draw the polygons
of the scene while the Preprocessing process is performing the light
point computations. This is what the Light Point Process does in libpf.
Given that lpointDrawDList is an empty RING Display List, and that
lpointPreprocessDList is a FLAT Display List that contains all the
pfGeoset that have to be preprocessed, the typical code for the Light
Point Process is:
/* select the pfCalligraphic to render with (optional) */
pfSelectCalligraphic(calligraphic);
/* set the performer View Matrix */
/* used to compute the intensity of each light */
pfViewMat(viewMat);
/* can be obtain from pfInvertOrthoNMatMat.invertOrthoN(viewMat,invViewMat); */
/* and also not mandatory. Will be computed from viewMat if not given */
/* used to do the 3D->2D projection for the calligraphics lights points */
pfInvViewMat(invViewMat);
pfNearPixDist(nearPixDist);
/* can use getGLProjMat from a Frustum to get this matrix */
pfProjMat(projMat);
/* Open the Draw RING Display List */
pfOpenDList(lpointDrawDList);
/* preprocess the LPoint FLAT Display List */
pfPreprocessDList(lpointPreprocessDList,PFDL_PREPROCESS_LPSTATE);
/* Post an end of frame token in the ring Dlist */
pfAddDListCmd(PFDL_END_OF_FRAME);
/* Close the Draw RING Display List */
pfCloseDList();
Note that pfSelectCalligraphic, pfViewMat, pfInvViewMat, pfNearPixDist
Page 6
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
and pfProjMat are all Display List-able, and should not go in the
lpointDrawDList, as they are needed to configure the preprocessing.
Also, processing of pfLPointState requires that the pfModelMat() matrix
are stored in the lpointPreprocessDList each time the model matrix
changes before drawing a pfGeoSet. This is done automatically by the
Culler in a libpf application.
So, the Draw Process simply looks like this:
/* do usual Channel settings */
/* including pfPixScale if using DVR */
pfPixScale(scale);
/* draw the polygons */
pfDrawDList(polygonDList);
/* draw the light point Draw Ring DLIST */
pfDrawDList(lpointDrawDList);
/* will exit at the EndOfFrame token */
/* whatever */
/* then swapbuffer */
Note that in the case of calligraphic light points it is mandatory that
the lpoints are the last geometric elements sent to the graphic pipe.
SEE ALSO
pfCalligraphic, pfDelete, pfGeoState, pfLPointState, pfObject, pfState,
callobj, sproc
Page 7
