pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NAME
pfNewCompositor, pfGetCompositorClassType, pfGetNumHWCompositors,
pfGetHWCompositorNetworkId, pfGetHWCompositorNumInputs,
pfGetHWCompositorInputType, pfGetHWCompositorInputPipeName,
pfGetHWCompositorInputNetworkId, pfGetHWCompositorPfCompositor,
pfGetNumCompositedPipes, pfGetNumCompositors, pfGetCompositor,
pfGetCompositorNetworkId, pfCompositorAutoSetup, pfCompositorAddChild,
pfCompositorAddCompositor, pfGetCompositorNumChildren,
pfGetCompositorChildType, pfGetCompositorChildCompositor,
pfGetCompositorChildPipe, pfGetCompositorChildPipeName,
pfGetCompositorChildPipeId, pfGetCompositorParent,
pfGetCompositorNumActiveChildren, pfCompositorNumActiveChildren,
pfCompositorViewport, pfGetCompositorViewport, pfCompositorVal,
pfGetCompositorVal, pfCompositorMode, pfGetCompositorMode,
pfCompositorLoadBalancer, pfGetCompositorLoadBalancer,
pfCompositorChildViewport, pfGetCompositorChildViewport,
pfResetCompositorChildrenViewports, pfGetCompositorMasterPipe,
pfGetCompositorMasterPipeId, pfGetCompositorNumPipes,
pfGetCompositorPipe, pfGetCompositorPWin, pfGetCompositorChan,
pfGetCompositorRoot, pfCompositorChannelClipped,
pfGetCompositorChannelClipped, pfCompositorAntialiasJitter,
pfGetCompositorAntialiasJitter, pfGetCompositorDefaultChanShareMask,
pfCompositorDefaultChanShareMask - Set and get pfCompositor definition
parameters.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfCompositor* pfNewCompositor(int netId);
pfType* pfGetCompositorClassType(void);
int pfGetNumHWCompositors(void);
int pfGetHWCompositorNetworkId(int c);
int pfGetHWCompositorNumInputs(int c);
int pfGetHWCompositorInputType(int c, int i);
char* pfGetHWCompositorInputPipeName(int c, int i);
int pfGetHWCompositorInputNetworkId(int c, int i);
pfCompositor* pfGetHWCompositorPfCompositor(int c);
int pfGetNumCompositedPipes(void);
int pfGetNumCompositors(void);
Page 1
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
pfCompositor* pfGetCompositor(int i);
int pfGetCompositorNetworkId(pfCompositor* comp);
void pfCompositorAutoSetup(pfCompositor* comp,
int num_inputs);
int pfCompositorAddChild(pfCompositor* comp,
char* pipe_name);
int pfCompositorAddCompositor(pfCompositor* comp,
pfCompositor *child);
int pfGetCompositorNumChildren(pfCompositor* comp);
int pfGetCompositorChildType(pfCompositor* comp, int index);
pfCompositor* pfGetCompositorChildCompositor(pfCompositor* comp,
int index);
pfPipe* pfGetCompositorChildPipe(pfCompositor* comp, int index);
char* pfGetCompositorChildPipeName(pfCompositor* comp,
int index);
int pfGetCompositorChildPipeId(pfCompositor* comp,
int index);
pfCompositor* pfGetCompositorParent(pfCompositor* comp);
int pfGetCompositorNumActiveChildren(pfCompositor* comp);
int pfCompositorNumActiveChildren(pfCompositor* comp,
int n);
void pfCompositorViewport(pfCompositor* comp, float left,
float right, float bottom, float top);
void pfGetCompositorViewport(pfCompositor* comp, float *left,
float *right, float *bot, float *top);
void pfCompositorVal(pfCompositor* comp, int what,
float val);
float pfGetCompositorVal(pfCompositor* comp, int what);
void pfCompositorMode(pfCompositor* comp, int what, int val);
int pfGetCompositorMode(pfCompositor* comp, int what);
Page 2
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
void pfCompositorLoadBalancer(pfCompositor* comp,
pfLoadBalance *balancer);
pfLoadBalance* pfGetCompositorLoadBalancer(pfCompositor* comp);
void pfCompositorChildViewport(pfCompositor* comp, int i,
float left, float right, float bot, float top);
void pfGetCompositorChildViewport(pfCompositor* comp, int i,
float* l, float* r, float* b, float* t);
void pfResetCompositorChildrenViewports(pfCompositor* comp);
pfPipe* pfGetCompositorMasterPipe(pfCompositor* comp);
int pfGetCompositorMasterPipeId(pfCompositor* comp);
int pfGetCompositorNumPipes(pfCompositor* comp);
pfPipe* pfGetCompositorPipe(pfCompositor* comp, int p);
pfPipeWindow* pfGetCompositorPWin(pfCompositor* comp, int p);
pfChannel* pfGetCompositorChan(pfCompositor* comp, int p, int c);
pfCompositor* pfGetCompositorRoot(pfCompositor* comp);
void pfCompositorChannelClipped(pfCompositor* comp,
int chan_num, int clip );
unsigned char pfGetCompositorChannelClipped(pfCompositor* comp,
int chan_num);
int pfCompositorAntialiasJitter(pfCompositor* comp, int n,
float* jitter );
int pfGetCompositorAntialiasJitter(pfCompositor* comp,
int n, float* jitter );
uint pfGetCompositorDefaultChanShareMask(void);
void pfCompositorDefaultChanShareMask(uint mask);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfCompositor is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfCompositor. Casting an object of
class pfCompositor 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.
Page 3
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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 pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfCompositor 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);
DESCRIPTION
A compositor is a hardware device that takes a number of video inputs and
combines them to produce a single video output. The video inputs can be
divided spatially or blended together to form one output.
The pfCompositor class transparently distributes rendering across
multiple hardware pipes and combines their outputs by either feeding them
to a hardware compositor device, or through software composition.
Several different spatial composition modes are supported, as well as an
Anti-Alias mode in which channel frustums on composited pipes are
slightly jittered and the outputs blended together by the hardware
compositor.
pfCompositor also supports dynamic load balancing. When enabled, the
spatial subdivision of the compositor's inputs will be updated on each
frame based on the load of each contributing pfpipe. Load balancing is
disabled by default, and can be enabled through pfCompositorMode .
During initialization, the pfCompositor class will perform a system
Page 4
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
topology query to determine the availability of hardware compositors.
The results of this query can be examined by the application through the
following static methods:
pfGetNumHWCompositors returns the number of available hardware
compositors found on the system.
pfGetHWCompositorNetworkId returns the network Id of the c-th hardware
compositor, or -1 if c is not a valid index.
pfGetHWCompositorNumInputs returns the number of inputs physicaally
connected to the c-th hardware compositor. Each input can either be a
single-pipe or the output of another hardware compositor. If c is not a
valid index, -1 is returned.
pfGetHWCompositorInputType returns PFCOMP_INPUTTYPE_PIPE if the i-th
input of the c-th hardware compositor is a single-pipe, or
PFCOMP_INPUTTYPE_COMPOSITOR if it is another hardware compositor. If c is
not a valid index, 0 is returned.
If the i-th input of the c-th hardware compositor is a single-pipe,
pfGetHWCompositorInputPipeName returns the string identifying the Display
of that pipe (eg ":0.0"). If c or i are not valid indices, or if the i-
th input of the c-th compositor is not a single-pipe, NULL is returned.
If the i-th input of the c-th hardware compositor is a compositor,
pfGetHWCompositorInputNetworkId returns its network Id. If c or i are
not valid indices, or if the i-th input of the c-th compositor is not a
compositor, -1 is returned.
pfGetHWCompositorPfCompositor returns a pointer to the pfCompositor
object managing the c-th hardware compositor, if one exists. Otherwise,
or if c is not a valid index, NULL is returned.
The pfCompositor class makes it extremely easy to configure and manage
multiple graphics pipes. Most of the work is done transparently behind
the scenes through a mechanism of automatic call-propagation.
All the application has to do is create a pfCompositor object before
pfConfig, then after pfConfig, obtain a pointer to the compositor's
master pipe, and treat it as if it were a single-pipe.
Currently only one full-screen pfPipeWindow is supported on composited
pfPipes. Only the pfPipeWindow on compositor's master pipe should be
created by the application. pfPipeWindows on compositor's slave pipes
will be created automatically.
Similarly, the application should only create pfChannels on compositor's
master pipe. Channels will automatically be created on all other
composited pipes.
By default, most methods of the pfChannel class have no effect if called
Page 5
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
on compositor slave channels (ie pfChannels on compositor slave pipes).
Instead, the application should address channels in compositor master
pipe alone, and methods will automatically propagate to all associated
compositor slaves.
The global mask specifying which pfChannel methods will be propagated by
default can be queried through pfGetCompositorDefaultChanShareMask
and can be set through pfCompositorDefaultChanShareMask compositor-share
tokens which can be combined (using the logical 'or' operator) to form
the mask argument:
PFCOMP_SHARE_FOV
PFCOMP_SHARE_VIEW
PFCOMP_SHARE_NEARFAR
PFCOMP_SHARE_SCENE
PFCOMP_SHARE_STRESS
PFCOMP_SHARE_STRESSFILTER
PFCOMP_SHARE_LOD
PFCOMP_SHARE_EARTHSKY
PFCOMP_SHARE_SWAPBUFFERS
PFCOMP_SHARE_VIEW_OFFSETS
PFCOMP_SHARE_STATS_DRAWMODE
PFCOMP_SHARE_APPFUNC
PFCOMP_SHARE_CULLFUNC
PFCOMP_SHARE_DRAWFUNC
PFCOMP_SHARE_VIEWPORT
PFCOMP_SHARE_SWAPBUFFERS_HW
PFCOMP_SHARE_CULL_VOLUME
PFCOMP_SHARE_GSTATE
PFCOMP_SHARE_PRICLASS_LIST
PFCOMP_SHARE_LPOINTFUNC
PFCOMP_SHARE_POSTLPOINTFUNC
PFCOMP_SHARE_BIN_ORDER
PFCOMP_SHARE_TRAV_MODE
A pfCompositor is created through pfNewCompositor(netId), where netId is
the network Id identifying the hardware compositor device that will be
managed by the new pfCompositor. If netId is PFCOMP_SOFTWARE, no hardware
compositor device will be involved, and composition will be carried out
through software readbacks.
We will refer to pfCompositors utilizing software composition as software
compositors, while pfCompositors associated with a hardware compositor
device will be referred to as hardware compositors.
A global list of all pfCompositors that have been created is maintained
by the pfCompositor class. pfGetNumCompositors returns the number of
pfCompositor objects in this list.
pfGetCompositor returns a pointer to the i-th pfCompositor object from
Page 6
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
the global list of pfCompositors. pfCompositors are added to this list in
the order they are created.
pfGetCompositorNetworkId will return the network Id identifying the
hardware compositor device managed by a pfCompositor object, or
PFCOMP_SOFTWARE if the pfCompositor uses software composition.
pfCompositorAddChild adds a pipe child to a pfCompositor. If the
pfCompositor is a hardware compositor, pipe_name must match the display
string of one of the hardware pipes physically connected to the
compositor device. If the compositor is a software compositor, then
pipe_name can be any valid display string. The pfPipes configured by the
software compositor will be created on the specified displays through
calls to pfPipe::setWSConnectionName. pipe_name can also be "" (empty
string) for software compositors, in which case pipes will be created on
the default screens (:0.0, :0.1, etc).
pfCompositorAddCompositor adds a compositor child to a pfCompositor,
creating a compositor hierarchy. Currently only hardware compositor
parents and software compositor children are supported. Care must be
taken in configuring compositor hierarchies to ensure that the first
child of the software compositor child (its master pipe) is physically
connected to the compositor device managed by the parent pfCompositor.
The following example creates a compositor hierarchy managing 8 pipes,
with a single hardware compositor as root, and four software compositors,
each managing two pipes, as inputs. Here we assume that the hardware
compositor has a networkId of 0, and pipes :0.0, :0.1, :0.2 and :0.3 are
physically connected to it:
pfCompositor *hwcomp, *swcomp;
hwcomp = pfNewCompositor(0);
swcomp = pfNewCompositor(PFCOMP_SOFTWARE);
pfCompositorAddChild(swcomp, ":0.0");
pfCompositorAddChild(swcomp, ":0.4");
pfCompositorAddCompositor(hwcomp, swcomp);
swcomp = pfNewCompositor(PFCOMP_SOFTWARE);
pfCompositorAddChild(swcomp, ":0.1");
pfCompositorAddChild(swcomp, ":0.5");
pfCompositorAddCompositor(hwcomp, swcomp);
swcomp = pfNewCompositor(PFCOMP_SOFTWARE);
pfCompositorAddChild(swcomp, ":0.2");
pfCompositorAddChild(swcomp, ":0.6");
pfCompositorAddCompositor(hwcomp, swcomp);
swcomp = pfNewCompositor(PFCOMP_SOFTWARE);
pfCompositorAddChild(swcomp, ":0.3");
pfCompositorAddChild(swcomp, ":0.7");
Page 7
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
pfCompositorAddCompositor(hwcomp, swcomp);
pfCompositorAutoSetup can be used to easily configure a pfCompositor with
the desired number of inputs. For hardware compositors, num_inputs cannot
exceed the number of inputs physically connected to the hardware device.
A zero or negative value of num_inputs will cause all physically
connected inputs to be configured. For software compositors, num_inputs
will be clamped to the number of available hardware pipes. If num_inputs
is less than one, all available hardware pipes on the system will be
configured.
Note that pfCompositorAutoSetup will take no action at all if
pfCompositor already has one or more children.
pfCompositorAutoSetup is called within pfConfig for all pfCompositor
objects, in order to automatically configure them if the application has
not done so already.
pfGetNumCompositedPipes returns the total number of pfPipes which are (or
will be) managed by pfCompositor objects. This is known with certainty
only after pfConfig, as until then pipes may be added to existing
compositors. However, if called before pfConfig, this method will
attempt to make a reasonable guess by assuming that pfCompositors with no
explicitely assigned children will end up being (automatically)
configured with all the inputs which are physically connected to them.
This can be useful when an application creates one or more single pipes
in addition to pipes managed by pfCompositors. In such cases the
application is required to make a call to pfMultipipe providing the total
number of pipes to be created. pfGetNumCompositedPipes will quickly
return the total number of composited pipes, to which the desired number
of single-pipes may be added.
pfGetCompositorNumChildren returns the number of children (inputs) that
have been added to a pfCompositor. Each child can either be a single-pipe
or a pfCompositor. pfGetCompositorChildType returns PFCOMP_INPUTTYPE_PIPE
if the i-th child is a single pipe, or PFCOMP_INPUTTYPE_COMPOSITOR if it
is a pfCompositor. If i is not a valid index, 0 is returned.
If the i-th child of a pfCompositor is a pfCompositor,
pfGetCompositorChildCompositor will return a pointer to it. If i is not a
valid index, or if the i-th child is not a compositor, NULL is returned.
If the i-th child of a pfCompositor is a single-pipe,
pfGetCompositorChildPipe will return a pointer to it (This can only be
called after pfConfig); pfGetCompositorChildPipeName will return its
display-string. Note that for software compositors,
pfGetCompositorChildPipeName will return an empty string ("") for all
children unless a display string was explicitely assigned by application
Page 8
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
through a call to pfCompositorAddChild. pfGetCompositorChildPipeId
returns the Performer Id of the pipe-child, and should only be called
after pfConfig.
pfGetCompositorParent returns a pointer to a pfCompositor parent (another
pfCompositor) if the first has been added to the latter as a child
through a call to pfCompositorAddCompositor. If a pfCompositor has no
parent, NULL is returned.
Not all configured children must partecipate to composited image at all
times. The pfCompositor class supports dynamic changes to the number of
active children through pfCompositorNumActiveChildren. There must be at
least one active child, and no more than the total number of configured
children.
pfGetCompositorNumActiveChildren returns the number of currently active
children.
Note that children are activated from first to last, meaning that when
there are n active children, these will be children 0 to (n-1); thus
child 0 is always active.
pfGetCompositorMasterPipe returns a pointer to the master pfPipe for a
pfCompositor. The master pipe is the pipe that the application should
use to create a pipe-window and one or more channels. pfPipeWindows and
pfChannels are created automatically on all other composited pipes (slave
pipes) by the pfCompositor class.
In a single-tier compositor (one with no compositor parent and no
compositor children), the master pipe will be its first child. In a
compositor hierarchy, all pfCompositors will share a single master pipe.
pfGetCompositorMasterPipeId returns the Performer pipe Id of
pfCompositor's master pipe.
Each pfCompositor object maintains a list of all the pfPipes contributing
to its output. This includes all single-pipe children, as well as all
pipes connected to compositor-children.
pfGetCompositorNumPipes returns the total number of pfPipes contributing
to a pfCompositor. For a single-tier compositor, this is equal to the
number of its children. In a compositor hierarchy, pipes contributing to
leaf- compositors (bottom of the hierarchy) also contribute to root-
compositor, so if called on the root-compositor of a compositor
hierarchy, pfGetCompositorNumPipes will return the total number of pipes
in hierarchy.
pfGetCompositorPipe returns a pointer to the p-th pfPipe in a
pfCompositor's pipe-list. If p is an invalid index, NULL is returned.
pfGetCompositorPWin returns a pointer to the pfPipeWindow on the p-th
pipe in a pfCompositor's pipe-list. Currently only one (fullscreen)
Page 9
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
pipe-window is supported on composited pipes. If p is an invalid index,
NULL is returned.
pfGetCompositorChan returns a pointer to the c-th pfChannel on the p-th
pipe in a pfCompositor's pipe-list. If p or c are invalid indices, NULL
is returned.
pfGetCompositorRoot returns a pointer to the pfCompositor at the root of
the compositor hierarchy to which compositor belongs. For a parent-less
pfCompositor, getRoot will return a pointer to the compositor itself.
For a compositor-child, getRoot will return parent->getRoot.
A pfCompositor requires a pfLoadBalance object for carrying out load
balancing computations. The pfLoadBalance class determines the resulting
workload for each of the compositor's children. The behavior can be
customized by subclassing pfLoadBalance and overriding the appropriate
methods. A pfCompositor can use a customized pfLoadBalance object
specified through the pfCompositorLoadBalancer method. If a load balancer
is not specified, one will be automatically created and used.
pfGetCompositorLoadBalancer returns a pointer to the pfLoadBalancer
object used by the compositor.
See the pfLoadBalance manual page for more information.
pfCompositorMode accepts the following tokens as its first argument:
PFLOAD_BALANCE
Enables or disables dynamic load balancing. The second argument
must be PF_ON or PF_OFF.
PFCOMP_CLIPPING
Enables or disables channel-clipping for all channels on all
pipes managed by this compositor. By default, channel-clipping
is enabled, and the viewports of pfChannels in composited pipes
are clipped to the screen region assigned to each pipe by the
compositor. If channel- clipping is disabled, all pipes will
render all channels in their full (original) size. Note that
clipping is not carried out when in AntiAlias mode.
PFCOMP_SWAPBARRIER
Specifies the swap_barrier to which pipes contributing to
pfCompositor should bind. The second argument should be a valid
swap_barrier id (see glXQueryMaxSwapBarriersSGIX). By default,
all pfCompositors will bind to swap_barrier 1 (if the
swap_barrier extension is supported). Binding to swap_barrier
can be disabled by passing a value smaller than 1. If the
specified barrier_id is out of range, the call to setMode has
Page 10
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
no effect.
PFCOMP_COMPOSITION_MODE
Specifies the composition mode used by the pfCompositor. The
second argument can be one of:
PFCOMP_COMPMODE_HORIZ_STRIPES PFCOMP_COMPMODE_VERT_STRIPES
PFCOMP_COMPMODE_LEFT_TILES PFCOMP_COMPMODE_RIGHT_TILES
PFCOMP_COMPMODE_BOTT_TILES PFCOMP_COMPMODE_TOP_TILES
PFCOMP_COMPMODE_ANTIALIAS
All composition modes are valid for any number of active children. This
is how one to four inputs are laid out for each composition mode:
PFCOMP_COMPMODE_HORIZ_STRIPES:
_____________ ______________ ______________ ______________
| | | | | | | 3 |
| | | 1 | | 2 | |______________|
| | | | |______________| | 2 |
| 0 | |______________| | 1 | |______________|
| | | | |______________| | 1 |
| | | 0 | | | |______________|
| | | | | 0 | | 0 |
|_____________| |______________| |______________| |______________|
PFCOMP_COMPMODE_VERT_STRIPES:
_____________ ______________ ______________ _______________
| | | | | | | | | | | | | |
| | | | | | | | | | | | | |
| | | | | | | | | | | | | |
| 0 | | 0 | 1 | | 0 | 1 | 2 | | 0 | 1 | 2 | 3 |
| | | | | | | | | | | | | |
| | | | | | | | | | | | | |
| | | | | | | | | | | | | |
|_____________| |_______|______| |____|____|____| |___|___|___|___|
PFCOMP_COMPMODE_LEFT_TILES:
_____________ ______________ ______________ _______________
| | | | | | | | | | |
| | | | | | | 2 | | | 3 |
| | | | | | | | | 1 |________|
| 0 | | 0 | 1 | | 0 |________| | | |
| | | | | | | | |______| |
| | | | | | | 1 | | | 2 |
| | | | | | | | | 0 | |
|_____________| |_______|______| |_____|________| |______|________|
Page 11
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
PFCOMP_COMPMODE_RIGHT_TILES:
_____________ ______________ ______________ ______________
| | | | | | | | | | |
| | | | | | 2 | | | | 3 |
| | | | | | | | | 1 |_______|
| 0 | | 0 | 1 | |_______| 0 | | | |
| | | | | | | | |______| |
| | | | | | 1 | | | | 2 |
| | | | | | | | | 0 | |
|_____________| |______|_______| |_______|______| |______|_______|
PFCOMP_COMPMODE_BOTT_TILES:
_____________ ______________ ______________ ______________
| | | | | | | | | |
| | | 1 | | | | | 2 | 3 |
| | | | | 1 | 2 | | | |
| 0 | |______________| | | | |_____|________|
| | | | |_______|______| | | |
| | | 0 | | | | 0 | 1 |
| | | | | 0 | | | |
|_____________| |______________| |______________| |_______|______|
PFCOMP_COMPMODE_TOP_TILES:
_____________ ______________ ______________ ______________
| | | | | | | | |
| | | 1 | | 0 | | 2 | 3 |
| | | | |______________| | | |
| 0 | |______________| | | | |_____|________|
| | | | | | | | | |
| | | 0 | | 1 | 2 | | 0 | 1 |
| | | | | | | | | |
|_____________| |______________| |______|_______| |_______|______|
pfGetCompositorMode can be called to query pfCompositor values. The
following tokens are allowed:
PFLOAD_BALANCE
The returned value is 1 if dynamic load balancing is enabled, 0
if it is disabled.
PFCOMP_CLIPPING
The returned value is 1 if channel-clipping is enabled, or 0 if
it is disabled.
Page 12
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
PFCOMP_SOFTWARE
The returned value is 1 if pfCompositor uses software
composition, or 0 if pfCompositor controls a hardware
compositor device.
PFCOMP_SWAPBARRIER
The returned value is the index of the swap_barrier to which
pipes will bind (or have bound). If binding to swap barriers
has been (or will be) skipped, return value is 0.
PFCOMP_COMPOSITION_MODE
The returned value is the current composition moce used by the
pfCompositor and can be one of:
PFCOMP_COMPMODE_HORIZ_STRIPES PFCOMP_COMPMODE_VERT_STRIPES
PFCOMP_COMPMODE_LEFT_TILES PFCOMP_COMPMODE_RIGHT_TILES
PFCOMP_COMPMODE_BOTT_TILES PFCOMP_COMPMODE_TOP_TILES
PFCOMP_COMPMODE_ANTIALIAS
pfCompositorVal currently only accepts PFLOAD_COEFF, and passes the value
onto the pfLoadBalance class. This coefficient determines how quickly the
balancer transitions from the current state to the desired balanced
state. This load-balancing filter coefficient should be in the range
(0..1]. The smaller its value, the slower load balancing follows pipe
load, and the less noise-sensitive it is.
pfGetCompositorVal also only accepts PFLOAD_COEFF, and returns the
current value of the filter coefficient used by the pfLoadBalance object
associated with the pfCompositor.
pfCompositorViewport specifies the screen-space bounds of the region
managed by a pfCompositor. The viewports assigned to all pipes managed by
this compositor will be clipped to this region. The default viewport for
a pfCompositor is: 0.0, 1.0, 0.0, 1.0 (the whole screen).
pfCompositorViewport should not be called for compositor-children in
compositor hierarchies (use pfCompositorChildViewport on parent
compositor instead).
pfGetCompositorViewport returns the screen-space bounds of the region
managed by a pfCompositor.
pfCompositorChildViewport specifies the screen-space bounds of the 2d
region assigned to the i-th child of the pfCompositor. The specified
viewport is automatically clipped to the viewport of the compositor, and
aligned horizontally to a four-pixel boundary (required by hardware
compositor devices). The default viewports of a pfCompositor's children
are determined based on the number of active children and on the current
composition mode (see pfCompositorMode above).
Page 13
pfCompositor(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
Note that when dynamic load balancing is active, setting children
viewports through pfCompositorChildViewport will have no effect.
pfGetCompositorChildViewport returns the screen-space bounds of the 2d
region managed by the i-th child of the pfCompositor. This region will
always be contained by the viewport of the pfCompositor itself.
Note that all viewports are specified in normalized screen coordinates,
with 0.0,0.0 being the bottom-left corner of the screen, and 1.0,1.0
being the top-right corner.
pfCompositorChannelClipped specifies whether channel-clipping should be
enabled for the i-th channel. Channel clipping is enabled on all channels
by default. Channel clipping is not performed if it is globally disabled
through a call to setMode. Disabling clipping on a pfChannel can be
useful in certain situations. For example, perfly's GUI channel has
clipping disabled and is rendered entirely on master pipe. Note that
perfly also assignes a non-full-screen viewport to the pfCompositor when
the GUI is displayed.
pfGetCompositorChannelClipped returns 1 if channel-clipping is enabled
for the i-th channel, or 0 otherwise (or if i is not a valid index).
A pfCompositor maintains a list of jitter patterns to be used for
AntiAlias mode depending on the number of active children. A jitter
pattern is encoded as an array of sub-pixel offsets, with two floats
(horizontal and vertical offset) for each contributing child.
pfCompositorAntialiasJitter specifies the jitter pattern to be used for
anti-alias composition, when there are n active children. jitter must
point to an array of floats containing 2*n values, specifying sub-pixel
offsets (horizontal and vertical) for each of the n contributing inputs.
pfGetCompositorAntialiasJitter returns the jitter pattern to be used for
anti-alias composition when there are n active children. jitter must
point to an array of floats with at least 2*n elements, which will
contain the queried jitter values on return.
BUGS
Compositor hierarchies are not supported in Performer 3.2
SEE ALSO
pfLoadBalance, pfChannel, pfMultipipe, glXQueryHyperpipeNetworkSGIX,
glXBindHyperpipeSGIX, glXBindSwapBarrierSGIX
Page 14
