pfPipe(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfPipe(3pf)NAME
pfPipe, pfGetPipeNum, pfGetPipeDrawCount, pfGetLastPipeFrameCount -
Initialize and get window information for a pfPipe.
FUNCTION SPECIFICATION
#include <Performer/pf/pfPipe.h>
void pfPipe::getSize(int *xsize, int *ysize);
static pfType * pfPipe::getClassType(void);
void pfPipe::setScreen(int screen);
int pfPipe::getScreen(void);
int pfPipe::movePWin(pfPipeWindow *pwin);
pfPipeWindow * pfPipe::getPWin(int which);
void pfPipe::setSwapFunc(pfPipeSwapFuncType func);
pfPipeSwapFuncType pfPipe::getSwapFunc(void);
float pfPipe::getLoad(void);
int pfPipe::getNumPWins(void);
int pfPipe::getNumChans(void);
pfChannel * pfPipe::getChan(int which);
void pfPipe::bindVChans(void);
void pfPipe::unbindPVChans(void);
pfCompositor* pfPipe::getCompositor(void);
int pfPipe::isCompositorMaster(void);
int pfPipe::getCompositorChildIndex(void);
void pfPipe::setIncrementalStateChanNum(int num);
int pfPipe::getIncrementalStateChanNum(void);
void pfPipe::addMPClipTexture(pfMPClipTexture *clip);
int pfPipe::removeMPClipTexture(pfMPClipTexture *clip);
int pfPipe::getNumMPClipTextures(void);
Page 1
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfPipe(3pf)
pfMPClipTexture* pfPipe::getMPClipTexture(int which);
void pfPipe::setTotalTexLoadTime(float msec);
float pfPipe::getTotalTexLoadTime(void);
int pfGetPipeNum(void);
void pfGetPipeDrawCount(int pnum);
void pfGetLastPipeFrameCount(int pnum);
/* pfPipe-specific types */
typedef void (*pfPipeFuncType)(pfPipe *p);
typedef void (*pfPipeSwapFuncType)(pfPipe *p, pfPipeWindow *pw);
DESCRIPTION
A pfPipe is a software rendering pipeline which renders one or more
pfChannels into one or more pfPipeWindows. A pfPipe can be configured as
multiple processes for increased throughput on multiprocessor systems.
Multiple pfPipes can operate in parallel in support of platforms with
multiple graphics pipelines. The number of pfPipes and the
multiprocessing mode used are set by pfMultipipe and pfMultiprocess
respectively (see pfConfig).
A pfPipe references one or more pfPipeWindows which in turn reference one
or more pfChannels. A pfChannel is simply a view of a scene which is
rendered into a viewport of a pfPipeWindow. A pfPipeWindow is a graphics
window managed by its parent pfPipe.
pfPipes, pfPipeWindows, and pfChannels form a hierarchy with the
following rules:
1. A screen (i.e. hardware graphics display) can have multiple
pfPipes but should only have one drawing to it
2. A pfPipe may only draw to one screen
3. A pfPipe may render to multiple pfPipeWindows
4. A pfPipeWindow belongs to a single fixed pfPipe and thus also
to a single fixed screen
5. A pfPipeWindow may have multiple pfChannels
6. A pfChannel always belongs to a pfPipe but may change
pfPipeWindows or might not belong to any pfPipeWindow. a
channel not assigned to a pfPipeWindow is culled but not drawn.
Page 2
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfPipe(3pf)
The following is an example pfPipe->pfPipeWindow->pfChannel
configuration.
Example 1:
The screen:
hardware screen/graphics pipeline
+-----------------------------------------------+
| pfPipe |
| |
| pfPipeWindow1 |
| +----------------+ |
| | | |
| | | |
| | | |
| | | |
| | pfChannel2 | |
| | | |
| pfPipeWindow0 | | |
| +--------------------+ | |
| | | | | |
| | | |-----------+ |
| | pfChannel0 | blank | |
| | | | |
| |--------------------| |
| | | |
| | pfChannel1 | |
| | | |
| +--------------------+ |
| |
| |
+-----------------------------------------------+
The hierarchy:
screen0 ....
|
|
pfPipe0 ---------------------+
/ \ |
/ \ |
/ \ |
pfPipeWindow0 pfPipeWindow1 |
/ \ \ |
/ \ \ |
pfChannel0 pfChannel1 pfChannel2 pfChannel3
(not drawn)
Page 3
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfPipe(3pf)
The code: (in application process)
/* Calls that create the hierarchy: */
pfPipe *pipe = pfGetPipe(0);
pfPipeWindow *pwin0 = new pfPipeWindow(pipe);
pfPipeWindow *pwin1 = new pfPipeWindow(pipe);
pfChannel *chan0 = new pfChannel(pipe);
pfChannel *chan1 = new pfChannel(pipe);
pfChannel *chan2 = new pfChannel(pipe);
pwin0->addChan(chan0);
pwin0->addChan(chan1);
pwin1->addChan(chan2);
/* Calls that cause the window to be opened at next pfFrame() */
pwin0->open();
pwin1->open();
pfFrame();
If a pfPipe has no windows at the time pfFrame is called, a full screen
pfPipeWindow will be opened for pipe and all pfChannels of pipe will be
assigned to that pfPipeWindow.
pfPipe::getClassType returns the pfType* for the class pfPipe. The
pfType* returned by pfPipe::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfPipe. 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 isOfType 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.
pfPipe::setScreen specifies the hardware screen, screen, (graphics
pipeline) used for rendering by the pfPipe, the pfPipe. The screen of
the pfPipe may be specified in the application process before the call to
open or configure any pfPipeWindows (pfPipeWindow::open,
pfPipeWindow::config) on the pfPipe, or may be specified implicitly by
the screen of the first opened pfPipeWindow. A pfPipe is tied to a
specific hardware pipeline and the screen of a pfPipe cannot be changed
once determined. For single pipe operation, if the screen of a pfPipe or
pfPipeWindow is never explicitly set in single pipe configuration, the
screen will be taken from the default screen of the current
pfWSConnection, or current X Display. For multipipe operation, if the
screen of a pfPipe or pfPipeWindow is never explicitly set and
pfMultipipe() has been used to configure multiple pfPipes, then pfPipes
will automatically be assigned to hardware screens in order, i.e.,
pfGetPipe(0) -> screen 0, pfGetPipe(1) -> screen 1, etc. If a custom
mapping of pfPipes to screens is desired, the screens of all pfPipes must
be specified before the configuration of the first pfPipe which will
Page 4
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfPipe(3pf)
happen at the first call to pfFrame. See the pfGetCurWSConnection
reference page for more details on how to manage X display connections.
pfPipe::setWSConnectionName allows you to specify both a window server
target and screen for the pfPipe. This is useful for doing remote
rendering, or for running on a system with multiple window servers. This
call should be made in the application process, before the first call to
pfFrame. pfPipe::getWSConnectionName will return the current window
server target name. A window server target specified on a pfPipe will
take precedence over any such targets specified on pfPipeWindows of that
pfPipe. If the window server target of a pfPipe has not been set, it may
be implicitly set from the first such setting on a child pfPipeWindow.
The window server target of a pfPipe may not be changed after the first
call to pfFrame. See the pfGetCurWSConnection reference page for more
details on how to manage X display connections.
pfPipe::getScreen can be used to get the screen of a pfPipe. A return
value of (-1) indicates that the screen of the pfPipe is undefined.
pfPipe::getSize returns the size of the screen used by the pfPipe.
For best performance only one pfPipe should render to a given hardware
pipeline. If multiple views on a single screen are desired, use multiple
pfChannels, and if necessary, multiple pfPipeWindows.
Normally a pfPipe swaps the color buffers at the end of each frame.
However, if special control is needed over buffer swapping,
pfPipe::setSwapFunc will register func as the buffer swapping function
for the pfPipe. Instead of swapping buffers, func will be called and
will be expected to swap the color buffers of the provided pfPipeWindow.
pfPipe::getSwapFunc returns the buffer swapping function of the pfPipe or
NULL if none is set.
If you wish to frame lock multiple pfPipes so that each pfPipe swaps its
color buffers at the same time, then you should create a channel group
consisting of one or more pfChannels on each pfPipe and make sure
PFCHAN_SWAPBUFFERS is shared. In addition, separate hardware graphics
pipelines *must* be genlocked for proper frame-locking.
pfPipe::getPWin returns the pointer to the pfPipeWindow at the location
specified by which in the pfPipeWindow list on the pfPipe.
pfPipe::getNumPWins returns the number of pfPipeWindows that have been
created on the pfPipe. pfPipe::getNumChans returns the number of
pfChannels that have been created on the pfPipe.
pfPipe::movePWin moves the specified pfPipeWindow pwin to the location
specified by where in the pfPipeWindow list on the pfPipe. The move
includes removing pwin from its current location by moving up the
elements in the list that follow it and then inserting pwin into its new
location. If pwin is attached to the pfPipe, (-1) is returned and pwin
is not inserted into the list. Otherwise, where is returned to indicate
success. where must be within the range [0 .. n] where n is the number
Page 5
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfPipe(3pf)
returned by pfPipe::getNumPWins(), or else (-1) is returned and no move
is executed.
pfPipe::getChan returns the pointer to the pfChannel at location which in
the list of pfChannels on the pfPipe.
pfPipe::getLoad returns the current instantaneous load (ratio of time
required to process a frame and the time allotted for that frame's
processing) for the pipe.
pfPipe::bindVChans binds all pfPipeVideoChannels associated with the
pfPipe to the video hardware. pfPipe::unbindPVChans performs the
opposite action, unbinding each from the video hardware.
Example 2: How to frame lock pfPipes
leftChan = new pfChannel(pfGetPipe(0));
rightChan = new pfChannel(pfGetPipe(1));
/* BPFCHAN_SWAPBUFFERS is shared by default */
leftChan->attach(rightChan);
/* Pipe 0 and pipe 1 are now frame-locked */
COMPOSITORS
When developing multi-pipe application through the pfCompositor class and
related API, an application is typically required to address only one of
the composited pipes (the master pipe) while operations carried out on
master pipe (such as the creation of pfPipeWinodws and pfChannels) will
be automatically propagated to all compositor-slave pipes.
pfPipe::getCompositor returns a pointer to the pfCompositor object
managing the pfPipe, or NULL if pipe is not composited.
pfPipe::isCompositorMaster returns 1 if pfPipe is the master-pipe of a
pfCompositor, or 0 is pipe is a slave-pipe of a pfCompositor, or if it is
not composited at all.
pfPipe::getCompositorChildIndex returns the index of pipe in it's
pfCompositor's children-list. If pipe is not composited, this method
returns -1.
See man pfCompositor for more details on setting up multi-pipe composited
applictions.
Page 6
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfPipe(3pf)
USING PFPIPES TO APPLY INCREMENTAL GRAPHICS
pfPipe's are also the level at which hardware pipeline specific graphics
state can be applied. The only two currently supported incremental
graphics state elements that can be applied on a per-pipe basis are
pfMPClipTexture's. Both of the libpf primitives provide support for
incrementally paging texture from memory into texture memory which
contains a texture cache that differs on a per frame basis. Thus by
attaching these structures to a pfPipe, the pfPipe will provide frame
accurate applying and downloading of these texture primitives. Note that
this incremental downloading should be attached to a channel such that
loading statistics can be accumulated.
pfPipe::setIncrementalStateChanNum sets the channel with which the
incremental state should be processed. If unspecified the first channel
enabled for drawing will be used to process the incremental state.
pfPipe::getIncrementalStateChanNum returns the channel with which all
incremental state attached to the pfPipe will be processed.
pfPipe::addMPClipTexture is used to associate a pfMPClipTexture with a
particular pfPipe. This association forces the pfPipe to apply the
pfMPClipTexture and download the resulting incremental texture changes in
a frame accurate manner. If a pfMPClipTexture is added to a pipe that is
already connected to another pipe, the function silently creates a new
pfMPClipTexture, makes it a slave of the pfMPClipTexture that is already
connected to another pipe, and adds the slave to the pipe in place of the
one passed as an argument to the function.
pfPipe::removeMPClipTexture is used to remove the association of a
pfMPClipTexture from a pfPipe such that the pfPipe will no longer manage
the incremental application of the pfMPClipTexture. If a pfMPClipTexture
is removed that is the master of other pfMPClipTextures, the slaves will
be removed from their pipes as well.
pfPipe::getNumMPClipTextures returns the number of pfMPClipTextures that
have been attached to the pfPipe.
pfPipe::getMPClipTexture returns the whichth pfMPClipTexture that has
been attached to the pfPipe.
pfPipe::setTotalTexLoadTime sets the total amount of texture download
time in (milliseconds) allocated for all the pfMPClipTextures attached to
this pfPipe. This download time is used by the pfMPClipTexture's DTR
load control system to update texture memory as the pfMPClipTexture's
center is moved.
The total download time is distributed among the pfMPClipTextures
attached to the pfPipe by examining the value of each pfMPClipTexture's
load time fraction parameter. This floating point number is queried from
each pfMPClipTexture attached to the pfPipe and the results are summed.
The resulting value used to normalize each pfMPClipTexture's load time
fraction value.
Page 7
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfPipe(3pf)
Each pfMPClipTexture's normalized load time fraction value is used to
scale the total download time. The result is the download time available
for that pfMPClipTexture. If the pfMPClipTexture has had a texture
download time set via pfMPClipTexture::setTexLoadTime, then that value
takes precedence, and the the scaled total download time is ignored by
that pfMPClipTexture.
pfPipe::getTotalTexLoadTime return the current value for total texture
download time. The default value is 6 milliseconds.
pfGetPipeNum returns the pipeline number for the current OpenGL Performer
pipeline process. pfGetPipeNum returns (-1) if invoked in a process that
isn't associated with a pfPipe. Only the CULL, DRAW, and LPOINT
processes have valid pipe numbers.
pfGetPipeDrawCount will return the frame count of the last draw to
complete for the pfPipe. This can be called in the application process to
find out where the draw is.
pfGetLastPipeFrameCount will return the frame count of the last process
associated between ISECT and the DRAW of pipe to finish. This can tell
you what processes might be using old pfGeoSets in the scene graph.
NOTES
pfPipes cannot be deleted.
SEE ALSO
pfChannel, pfCompositor, pfConfig, pfMultipipe, pfMultiprocess,
pfPipeWindow, pfGetCurWSConnection, pfMPClipTexture
Page 8
