pfDispList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAME
pfDispList, pfDrawGLObj, pfGetCurDList - Create and control a display
list
FUNCTION SPECIFICATION
#include <Performer/pr/pfDispList.h>
pfDispList::pfDispList(int type, int size)
static pfType * pfDispList::getClassType(void);
void pfDispList::open(void);
void pfDispList::reset(void);
static void pfDispList::close(void);
int pfDispList::getSize(void);
int pfDispList::getDListType(void);
static void pfDispList::addCmd(int cmd);
int pfDispList::append(const pfDispList *src);
static void pfDispList::callback(pfDListFuncType callback,
int nbytes, void *data);
int pfDispList::draw(void);
int pfDispList::compile(void);
int pfDispList::preprocess(int flag);
void pfDispList::setMode(int mode, int value);
int pfDispList::getMode(int mode);
void pfDrawGLObj(GLOBJECT obj);
pfDispList * pfGetCurDList(void);
typedef void (*pfDListFuncType)(void *data);
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. This is also true for
ancestor classes of class pfObject.
Page 1
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
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 pfDispList 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 pfDispList is a reusable display list that captures certain libpr
commands. new(arena) allocates a pfDispList from the specified memory
arena, or from the process heap if arena is NULL. new allocates a
pfDispList from the default memory arena (see pfGetSharedArena). Like
other pfObjects, pfDispLists cannot be created statically, automatically
on the stack or in arrays. The arguments to the constructor specify the
type and size of the display list. pfDispLists should be deleted with
pfDelete rather than the delete operator.
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
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
Page 2
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
synchronization and mutual exclusion to processes on ring buffer full or
empty conditions. pfDispList::getDListType returns the type of a
pfDispList.
pfDispList::getClassType returns the pfType* for the class pfDispList.
The pfType* returned by pfDispList::getClassType is the same as the
pfType* returned by invoking the virtual function getType 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 the member function isOfTypeto 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 new pfDispList 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. pfDispList::getSize returns the
size of dlist that was requested by new pfDispList, not its current size.
pfDispList::open opens the pfDispList 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 pfDispList::append. All pfDispList elements in src are
appended to the pfDispList on which the append method is invoked.
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
pfDispList::draw 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 the pfDispList::reset member function so that any additions to the
current pfDispList will overwrite previously entered commands. The tail
pointers of flat lists are automatically reset by pfDispList::draw when
the tail pointer reaches the head pointer so that the pfDispList may be
rendered again from the beginning.
Page 3
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
The member function pfDispList::close 'closes' the active pfDispList and
returns the application to immediate mode.
For PFDL_FLAT display lists, pfDispList::draw traverses the pfDispList
from the tail to the head pointer, and then resets the tail pointer to
the beginning of the pfDispList. If the pfDispList is a PFDL_RING,
pfDispList::draw will continually draw the display list, returning
control to the application only on PFDL_END_OF_FRAME or PFDL_RETURN
commands (see pfDispList::addCmd). After returning, a subsequent call to
the member function pfDispList::draw will restart drawing from the
previous position in the list.
The pfDispList::draw member function interprets the commands and data in
the pfDispList and executes libpr state routines that in turn execute
graphics library commands that send command tokens down the graphics
pipeline. pfDispList::draw is itself a display-listable command provided
that pfDispList object 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.
pfDispList::compile will compile a pfDispList into a GL display list. The
return value is that from pfDispList::draw and will be -1 if an error is
encountered. Note that user callback functions in pfDispLists are only
exectued upon display list creation.
pfDispList::setMode 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 pfDispList::draw 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. pfDispList::getMode 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 */
dlist->open();
pfEnable(PFEN_WIREFRAME);
gset->draw();
/* Close DList and return to immediate mode */
pfDispList::close();
/* Draw 'gset' in wireframe */
dlist->draw();
pfDispList::callback allows custom rendering in the middle of a display
Page 4
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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.
pfDispList::addCmd 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 */
gset->setGState(gstate0);
/* Open dlist as current pfDispList */
dlist->open();
gset->draw();
/* Return to immediate mode */
pfDispList::close();
/* Attach gstate1 to gset */
gset->setGState(gstate1);
/*
* dlist will use gstate0 and not be aware that gset was modified to
* use gstate1.
*/
dlist->draw();
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).
pfDispList::preprocess is used to preprocess a 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
pfViewMat(viewMat);
// can be obtain from invMat.invertOrthoN(viewMat);
// and also not mandatory. Will be computed from viewMat if not given
pfInvViewMat(invViewMat);
// needed to compute true projected pixel size
pfNearPixDist(nearPixDist);
// can use getGLProjMat from a Frustum to get this matrix
pfProjMat(projMat);
// Open the Draw RING Display List
lpointDrawDList->open();
// preprocess the LPoint FLAT Display List
lpointPreprocessDList->preprocess(PFDL_PREPROCESS_LPSTATE);
// Post an end of frame token in the ring Dlist
pfDispList::addCmd(PFDL_END_OF_FRAME);
// Close the Draw RING Display List
pfDispList::close();
Note that pfSelectCalligraphic, pfViewMat, pfInvViewMat, pfNearPixDist
and pfProjMat are all Display List-able, and should not go in the
Page 6
pfDispList(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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
polygonDList->draw();
// draw the light point Draw Ring DLIST
lpointDrawDList->draw();
// 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
