pfPipe(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfPipe(3pf)NAME
pfGetPipeSize, pfGetPipeClassType, pfPipeScreen, pfGetPipeScreen,
pfPipeWSConnectionName, pfGetPipeWSConnectionName, pfGetPipePWin,
pfMovePWin, pfPipeSwapFunc, pfGetPipeSwapFunc, pfGetPipeLoad,
pfGetPipeNumPWins, pfGetPipeNumChans, pfGetPipeChan, pfBindPipeVChans,
pfUnbindPipePVChans, pfGetPipeCompositor, pfIsCompositorMasterPipe,
pfGetPipeCompositorChildIndex, pfPipeIncrementalStateChanNum,
pfGetPipeIncrementalStateChanNum, pfAddMPClipTexture,
pfRemoveMPClipTexturePipe, pfGetPipeNumMPClipTextures,
pfGetPipeMPClipTexture, pfPipeTotalTexLoadTime,
pfGetPipeTotalTexLoadTime, pfGetPipeNum, pfGetPipeDrawCount,
pfGetLastPipeFrameCount - Initialize and get window information for a
pfPipe.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
void pfGetPipeSize(const pfPipe *pipe, int *xsize,
int *ysize);
pfType * pfGetPipeClassType(void);
void pfPipeScreen(pfPipe *pipe, int screen);
int pfGetPipeScreen(const pfPipe *pipe);
void pfPipeWSConnectionName(pfPipe *pipe,
const char *name);
const char * pfGetPipeWSConnectionName(const pfPipe *pipe);
pfPipeWindow * pfGetPipePWin(const pfPipe *pipe, int which);
int pfMovePWin(pfPipe* pipe, int where,
pfPipeWindow *pwin);
void pfPipeSwapFunc(pfPipe* pipe,
pfPipeSwapFuncType func);
pfPipeSwapFuncType pfGetPipeSwapFunc(const pfPipe* pipe);
float pfGetPipeLoad(const pfPipe* pipe);
int pfGetPipeNumPWins(const pfPipe *pipe);
int pfGetPipeNumChans(const pfPipe *pipe);
pfChannel * pfGetPipeChan(const pfPipe *pipe, int which);
void pfBindPipeVChans(pfPipe* pipe);
Page 1
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfPipe(3pf)
void pfUnbindPipePVChans(pfPipe* pipe);
pfCompositor* pfGetPipeCompositor(pfPipe* _pipe);
int pfIsCompositorMasterPipe(pfPipe* _pipe);
int pfGetPipeCompositorChildIndex(pfPipe* _pipe);
void pfPipeIncrementalStateChanNum(pfPipe* pipe,
int num);
int -
pfGetPipeIncrementalStateChanNum(const pfPipe* pipe);
void pfAddMPClipTexture(pfPipe* pipe,
pfMPClipTexture *clip);
int pfRemoveMPClipTexturePipe(pfPipe* pipe,
pfMPClipTexture *clip);
int pfGetPipeNumMPClipTextures(pfPipe* pipe);
pfMPClipTexture* pfGetPipeMPClipTexture(pfPipe* pipe, int which);
void pfPipeTotalTexLoadTime(float msecs);
float pfGetPipeTotalTexLoadTime(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);
PARAMETERS
pipe identifies a pfPipe.
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).
Page 2
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfPipe(3pf)
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.
The following is an example pfPipe->pfPipeWindow->pfChannel
configuration.
Example 1:
The screen:
hardware screen/graphics pipeline
+-----------------------------------------------+
| pfPipe |
| |
| pfPipeWindow1 |
| +----------------+ |
| | | |
| | | |
| | | |
| | | |
| | pfChannel2 | |
| | | |
| pfPipeWindow0 | | |
| +--------------------+ | |
| | | | | |
| | | |-----------+ |
| | pfChannel0 | blank | |
| | | | |
| |--------------------| |
Page 3
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfPipe(3pf)
| | | |
| | pfChannel1 | |
| | | |
| +--------------------+ |
| |
| |
+-----------------------------------------------+
The hierarchy:
screen0 ....
|
|
pfPipe0 ---------------------+
/ \ |
/ \ |
/ \ |
pfPipeWindow0 pfPipeWindow1 |
/ \ \ |
/ \ \ |
pfChannel0 pfChannel1 pfChannel2 pfChannel3
(not drawn)
The code: (in application process)
/* Calls that create the hierarchy: */
pfPipe *pipe = pfGetPipe(0);
pfPipeWindow *pwin0 = pfNewPWin(pipe);
pfPipeWindow *pwin1 = pfNewPWin(pipe);
pfChannel *chan0 = pfNewChan(pipe);
pfChannel *chan1 = pfNewChan(pipe);
pfChannel *chan2 = pfNewChan(pipe);
pfAddChan(pwin0, chan0);
pfAddChan(pwin0, chan1);
pfAddChan(pwin1, chan2);
/* Calls that cause the window to be opened at next pfFrame() */
pfOpenPWin(pwin0);
pfOpenPWin(pwin1);
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.
pfGetPipeClassType returns the pfType* for the class pfPipe. The pfType*
Page 4
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfPipe(3pf)
returned by pfGetPipeClassType is the same as the pfType* returned by
invoking pfGetType 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 pfIsOfType 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.
pfPipeScreen specifies the hardware screen, screen, (graphics pipeline)
used for rendering by the pfPipe, pipe. The screen of the pfPipe may be
specified in the application process before the call to open or configure
any pfPipeWindows (pfOpenPWin, pfConfigPWin) on pipe, 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
happen at the first call to pfFrame. See the pfGetCurWSConnection
reference page for more details on how to manage X display connections.
pfPipeWSConnectionName 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.
pfGetPipeWSConnectionName 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.
pfGetPipeScreen can be used to get the screen of a pfPipe. A return
value of (-1) indicates that the screen of the pfPipe is undefined.
pfGetPipeSize returns the size of the screen used by pipe.
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,
pfPipeSwapFunc will register func as the buffer swapping function for
pipe. Instead of swapping buffers, func will be called and will be
expected to swap the color buffers of the provided pfPipeWindow.
Page 5
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfPipe(3pf)
pfGetPipeSwapFunc returns the buffer swapping function of pipe 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.
pfGetPipePWin returns the pointer to the pfPipeWindow at the location
specified by which in the pfPipeWindow list on pipe.
pfGetPipeNumPWins returns the number of pfPipeWindows that have been
created on pipe. pfGetPipeNumChans returns the number of pfChannels that
have been created on pipe.
pfMovePWin moves the specified pfPipeWindow pwin to the location
specified by where in the pfPipeWindow list on pipe. 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 pipe, (-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 returned by
pfGetPipeNumPWins(), or else (-1) is returned and no move is executed.
pfGetPipeChan returns the pointer to the pfChannel at location which in
the list of pfChannels on pipe.
pfGetPipeLoad 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.
pfBindPipeVChans binds all pfPipeVideoChannels associated with the pfPipe
pipe to the video hardware. pfUnbindPipePVChans performs the opposite
action, unbinding each from the video hardware.
Example 2: How to frame lock pfPipes
leftChan = pfNewChan(pfGetPipe(0));
rightChan = pfNewChan(pfGetPipe(1));
/* BPFCHAN_SWAPBUFFERS is shared by default */
pfAttachChan(leftChan, rightChan);
/* Pipe 0 and pipe 1 are now frame-locked */
Page 6
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfPipe(3pf)
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.
pfGetPipeCompositor returns a pointer to the pfCompositor object managing
the pfPipe, or NULL if pipe is not composited.
pfIsCompositorMasterPipe 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.
pfGetPipeCompositorChildIndex 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.
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.
pfPipeIncrementalStateChanNum 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.
pfGetPipeIncrementalStateChanNum returns the channel with which all
incremental state attached to the pfPipe will be processed.
pfAddMPClipTexture 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.
Page 7
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfPipe(3pf)
pfRemoveMPClipTexture 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.
pfGetNumMPClipTextures returns the number of pfMPClipTextures that have
been attached to the pfPipe.
pfGetMPClipTexture returns the whichth pfMPClipTexture that has been
attached to the pfPipe.
pfPipeTotalTexLoadTime 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.
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 pfMPClipTextureTexLoadTimepfGetPipeTotalTexLoadTime
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.
Page 8
pfPipe(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfPipe(3pf)SEE ALSO
pfAttachChan, pfNewChan, pfCompositor, pfConfig, pfMultipipe,
pfMultiprocess, pfPipeWindow, pfGetCurWSConnection, pfMPClipTexture
Page 9
