pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NAME
pfNewPVChan, pfGetPVChanClassType, pfPVChanAreaScale, pfPVChanCallig,
pfPVChanDVRMode, pfPVChanFullRect, pfPVChanId, pfGetPVChanLoad,
pfPVChanMaxDecScale, pfPVChanMaxIncScale, pfPVChanMaxScale,
pfPVChanMinDecScale, pfPVChanMinIncScale, pfPVChanMinScale, pfPVChanMode,
pfPVChanOutputOrigin, pfPVChanOutputSize, pfPVChanScale, pfPVChanStress,
pfPVChanStressFilter, pfPVChanWSWindow, pfGetPVChanAreaScale,
pfGetPVChanId, pfGetPVChanCallig, pfGetPVChanDVRMode, pfGetPVChanInfo,
pfGetPVChanMaxDecScale, pfGetPVChanMaxIncScale, pfGetPVChanMaxScale,
pfGetPVChanMinDecScale, pfGetPVChanMinDeltas, pfGetPVChanMinIncScale,
pfGetPVChanMinScale, pfGetPVChanMode, pfGetPVChanOrigin,
pfGetPVChanOutputOrigin, pfGetPVChanOutputSize, pfGetPVChanPipe,
pfGetPVChanPWin, pfGetPVChanPWinIndex, pfGetPVChanScale, pfGetPVChanSize,
pfGetPVChanScreen, pfGetPVChanStress, pfGetPVChanStressFilter,
pfGetPVChanWSWindow, pfApplyPVChan, pfBindPVChan, pfSelectPVChan,
pfUnbindPVChan, pfIsPVChanBound, pfIsPVChanActive - Multiprocessed video
channel hookup for pfPipes, pfWindows, and pfChannels
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfPipeVideoChannel *
pfNewPVChan(pfPipe *pipe);
pfType * pfGetPVChanClassType(void);
void pfPVChanAreaScale(pfPipeVideoChannel* pvchan, float s);
void pfPVChanCallig(pfPipeVideoChannel* pvchan,
pfCalligraphic* callig);
void pfPVChanDVRMode(pfPipeVideoChannel* pvchan, int mode);
void pfPVChanFullRect(pfPipeVideoChannel* pvchan);
void pfPVChanId(pfPipeVideoChannel* pvchan, int index);
float pfGetPVChanLoad(const pfPipeVideoChannel* pvchan);
void pfPVChanMaxDecScale(pfPipeVideoChannel* pvchan, float xs,
float ys);
void pfPVChanMaxIncScale(pfPipeVideoChannel* pvchan, float xs,
float ys);
void pfPVChanMaxScale(pfPipeVideoChannel* pvchan, float xs,
float ys);
void pfPVChanMinDecScale(pfPipeVideoChannel* pvchan, float xs,
float ys);
Page 1
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
void pfPVChanMinIncScale(pfPipeVideoChannel* pvchan, float xs,
float ys);
void pfPVChanMinScale(pfPipeVideoChannel* pvchan, float xs,
float ys);
void pfPVChanMode(pfPipeVideoChannel* _pvchan, int _mode,
int _val);
void pfPVChanOutputOrigin(pfPipeVideoChannel* pvchan, int xo,
int yo);
void pfPVChanOutputSize(pfPipeVideoChannel* pvchan, int xs,
int ys);
void pfPVChanScale(pfPipeVideoChannel* pvchan, float xs,
float ys);
void pfPVChanStress(pfPipeVideoChannel* pvchan, float stress);
void pfPVChanStressFilter(pfPipeVideoChannel* pvchan,
float frac, float low, float high,
float pipeLoadScale, float stressScale, float max);
void pfPVChanWSWindow(pfPipeVideoChannel* pvchan,
pfWSWindow wsWin);
float pfGetPVChanAreaScale(pfPipeVideoChannel* pvchan);
int pfGetPVChanId(pfPipeVideoChannel* pvchan);
pfCalligraphic*
pfGetPVChanCallig(const pfPipeVideoChannel*pvchan);
float pfGetPVChanDVRMode(pfPipeVideoChannel* pvchan);
pfWSVideoChannelInfo
pfGetPVChanInfo(pfPipeVideoChannel* pvchan);
void pfGetPVChanMaxDecScale(const pfPipeVideoChannel* pvchan,
float *xs, float *ys);
void pfGetPVChanMaxIncScale(const pfPipeVideoChannel* pvchan,
float *xs, float *ys);
void pfGetPVChanMaxScale(const pfPipeVideoChannel* pvchan,
float *xs, float *ys);
void pfGetPVChanMinDecScale(const pfPipeVideoChannel* pvchan,
float *xs, float *ys);
Page 2
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
void pfGetPVChanMinDeltas(pfPipeVideoChannel* _pvchan, int *dx,
int *dy);
void pfGetPVChanMinIncScale(const pfPipeVideoChannel* pvchan,
float *xs, float *ys);
void pfGetPVChanMinScale(const pfPipeVideoChannel* pvchan,
float *xs, float *ys);
int pfGetPVChanMode(pfPipeVideoChannel* _pvchan, int _mode);
void pfGetPVChanOrigin(pfPipeVideoChannel* pvchan, int *xo,
int *yo);
void pfGetPVChanOutputOrigin(const pfPipeVideoChannel* pvchan,
int *xo, int *yo);
void pfGetPVChanOutputSize(const pfPipeVideoChannel* pvchan,
int *xs, int *ys);
pfPipe * pfGetPVChanPipe(pfPipeVideoChannel* pvchan);
pfPipeWindow * pfGetPVChanPWin(pfPipeVideoChannel* pvchan);
int pfGetPVChanPWinIndex(pfPipeVideoChannel* pvchan);
void pfGetPVChanScale(const pfPipeVideoChannel* pvchan,
float *xs, float *ys);
void pfGetPVChanSize(pfPipeVideoChannel* pvchan, int *xs,
int *ys);
int pfGetPVChanScreen(const pfPipeVideoChannel* pvchan);
float pfGetPVChanStress(const pfPipeVideoChannel* pvchan);
void pfGetPVChanStressFilter(const pfPipeVideoChannel* pvchan,
float *frac, float *low, float *high,
float *pipeLoadScale, float *stressScale, float *max);
pfWSWindow pfGetPVChanWSWindow(const pfPipeVideoChannel* pvchan);
void pfApplyPVChan(pfPipeVideoChannel* pvchan);
void pfBindPVChan(pfPipeVideoChannel* pvchan);
void pfSelectPVChan(pfPipeVideoChannel* _pvchan);
void pfUnbindPVChan(pfPipeVideoChannel* pvchan);
Page 3
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
int pfIsPVChanBound(const pfPipeVideoChannel* pvchan);
int pfIsPVChanActive(const pfPipeVideoChannel* pvchan);
/* typedef of X-based Performer Types */
typedef XSGIvcChannelInfo *pfWSVideoChannelInfo;
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfPipeVideoChannel is derived from the parent
class pfObject, so each of these member functions of class pfObject are
also directly usable with objects of class pfPipeVideoChannel. Casting
an object of class pfPipeVideoChannel 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 pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfPipeVideoChannel 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);
Page 4
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
PARAMETERS
pvchan identifies a pfPipeVideoChannel
DESCRIPTION
The pfPipeVideoChannel capability is used to direct the output of
pfChannels to different video outputs. A pfPipeVideoChannel is created
from a pfPipe and can only be used to manage video channels on the
graphics pipeline managed by the parent pfPipe. pfPipeVideoChannels are
attached to pfPipeWindows that cover their output area. A
pfPipeVideoChannel belongs to one pfPipeWindow at a time and a
pfPipeWindow may manage multiple pfPipeVideoChannels.
pfPipeVideoChannels are similar to pfVideoChannels but are
tracked/maintained by libpf and are used by libpf to direct final
rendering output of pfChannels within a pfPipeWindow. Because of their
similarity, many of the pfPipeVideoChannel routines are identical to
pfVideoChannel routines accept for the fact that the pfPVChan<*> routines
operate on a pfPipeVideoChannel and the pfVChan<*> routines operate on a
pfVideoChannels. These corresponding routines are listed in the table
below and their functionality is documented in the pfVideoChannels man
page.
Page 5
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
pfPipeVideoChannel routine pfVideoChannels routine
____________________________________________________________
pfPVChanAreaScale pfVChanAreaScale
pfPVChanFullRect pfVChanFullRect
pfPVChanId pfVChanId
pfPVChanMinScale pfVChanMinScale
pfPVChanMaxScale pfVChanMaxScale
pfPVChanOutputOrigin pfVChanOutputOrigin
pfPVChanOutputSize pfVChanOutputSize
pfPVChanScale pfVChanScale
pfPVChanWSWindow pfVChanWSWindow
pfGetPVChanAreaScale pfGetVChanAreaScale
pfGetPVChanId pfGetVChanId
pfGetPVChanMaxScale pfGetVChanMaxScale
pfGetPVChanMinDeltas pfGetVChanMinDeltas
pfGetPVChanMinScale pfGetVChanMinScale
pfGetPVChanMode pfGetVChanMode
pfGetPVChanOrigin pfGetVChanOrigin
pfGetPVChanOutputOrigin pfGetVChanOutputOrigin
pfGetPVChanOutputSize pfGetVChanOutputSize
pfGetPVChanScale pfGetVChanScale
pfGetPVChanSize pfGetVChanSize
pfGetPVChanScreen pfGetVChanScreen
pfGetPVChanScreenOutputOrigin pfGetVChanScreenOutputOrigin
pfGetPVChanInfo pfGetPVChanInfo
pfGetPVChanWSWindow pfGetVChanWSWindow
pfApplyPVChan pfApplyVChan
pfBindPVChan pfBindVChan
pfUnbindPVChan pfUnbindVChan
pfIsPVChanBound pfIsVChanBound
pfIsPVChanActive pfIsVChanActive
pfPVChanMode pfVChanMode
pfSelectPVChan pfSelectVChan
|
pfNewPVChan creates and returns a handle to a pfPipeVideoChannel.
pfPipeVideoChannels are always allocated from shared memory.
pfGetPVChanClassType returns the pfType* for the class
pfPipeVideoChannel. The pfType* returned by pfGetPVChanClassType is the
same as the pfType* returned by invoking pfGetType on any instance of
class pfPipeVideoChannel. 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.
pfPVChanId selects the hardware output video channel for the
pfPipeVideoChannel to use. The output video channel of a
pfPipeVideoChannel can be queried with pfGetPVChanId. Care should be
taken with hard-coding this number because these numbers are not
guaranteed to start at 0 or be sequential and have different meanings on
Page 6
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
different hardware platforms. pfPipeWindows by default will assign their
pfPipeVideoChannels to available hardware video channels. Note that a
video channel Id is relative to a screen and information about a video
channel cannot be known until the screen is known, either by having it
set explicitly on the parent pfPipe with pfPipeScreen or pfPipeWindow
with pfPWinScreen or having the pfPipeWindow opened and thus the screen
being set implicitly.
pfPVChanMode sets a given mode to val where mode may be one of the
following:
PFVCHAN_SYNC
sets the video boundary upon which changes to the video channel
origin and size should take effect: PFVCHAN_SYNC_SWAP for
swapbuffers (the default) and PFVCHAN_SYNC_FIELD for a field,
or vertical retrace, boundary. For resizing for load
management, the default swapbuffers boundary is usually
appropriate. Allowing changes to the origin and size take
effect on the following field boundary allows the panning of
video output from the visible color buffer asynchronous to
drawing and so should be used in conjunction with the
PFVCHAN_AUTO_APPLY mode and doing a pfSelectVChan on the
pfPipeVideoChannel.
PFVCHAN_AUTO_APPLY
accepts a boolean value indicating if changes to pvchan should
be applied automatically, as opposed to waiting for an explicit
call to pfApplyVChan. The changes are not applied by the set
routines because those routines may be called from an
asynchronous process. On InfiniteReality changes to the video
channel must be applied by the draw process so these are
applied automatically by the DRAW process. The pfSelectPVChan
for pvchan is done automatically by its pfPipe. Only one
pfPipeVideoChannel can be actively PFVCHAN_AUTO_APPLY at a time
for a single pfPipe.
pfGetPVChanMode will return the value of the specified mode for pvchan.
pfPVChanDVRMode sets the dynamic video resizing mode to that specified by
mode which may be one of:
PFPVC_DVR_OFF
to disable dynamic video resizing, the default.
PFPVC_DVR_MANUAL
to allow the manual specification of video channel resizing
through routines like pfPVChanOutputSize, pfPVChanAreaScale,
and pfPVChanScale.
PFPVC_DVR_AUTO
allows the automatic dynamic resizing of video channels based
on the current load and stress filter of the
pfPipeVideoChannel. Dynamic resizing of pfPipeVideoChannel
Page 7
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
will only be done when a stress filter has been specified with
pfPVChanStressFilter that includes a non-zero stress scale
value.
pfPVChanMaxDecScale sets the maximum X and Y decrement scaling that can
happen in a single step of automatic dynamic video resizing. A scale
value of (-1) removes the upper bound on decremental scales and is the
default.
pfPVChanMaxIncScale sets the maximum X and Y increment scaling that can
happen in a single step of automatic dynamic video resizing. A scale
value of (-1) removes the upper bound on incremental scales and is the
default.
pfPVChanMinDecScale sets the minimum X and Y decrement scaling that can
happen in a single step of automatic dynamic video resizing. The default
value is 0.0.
pfPVChanMinIncScale sets the minimum X and Y increment scaling that can
happen in a single step of automatic dynamic video resizing. The default
value is 0.0.
pfPVChanStress sets the stress of the pfPipeVideoChannel for the current
frame. This call should be made in the application process after pfSync
and before pfFrame to affect the next immediate draw process frame.
pfPVChanStressFilter sets the parameters for computing stress, when not
explicitly set for the current frame by pfPVChanStress, for pvchan. frac
is the fraction of a frame period pvchan is expected to take to render.
frac should be 1.0 if only a single pfPipeVideoChannel is drawn on a
pfPipe and should be > 0.0 and < 1.0 when using multiple active
pfPipeVideoChannels. frac allows the application to apportion rendering
time amongst multiple video channels so that a channel rendering complex
scenes may be allocated more time than a channel rendering simple ones.
pfGetPVChanStressFilter returns the stress filter parameters for pvchan.
If stressScale is non-zero, stress is computed for the pfPipeVideoChannel
every frame. low and high define a hysteresis band for system load.
When load is >= low and <= high, stress is held constant. When load is <
low or > high, OpenGL Performer will reduce or increase stress
respectively by dynamically resizing the output area of the
pfPipeVideoChannel until load stabilizes within the hysteresis band. low
should be <= high and they both should be positive. If pipeLoadScale is
non-zero, the load of the pfPipe of the pfPipeVideoChannel will be
considered in computing stress. pfPipeVideoChannel stress is computed
using the following algorithm:
pfPipeVideoChannel *pvchan;
......
float vcLoad = pfGetPVChanLoad(pvchan);
float pipeLoad = pfGetPipeLoad(pvchan);
float stressLevel = pfGetPVChanStress(pvchan);
float areaScale;
Page 8
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
/* consider pipe load for stress */
if (pipeLoad > vcLoad)
vcLoad += pipeLoadScale*(pipeLoad - vcLoad);
else if (pipeLoad < vcLoad)
vcLoad -= pipeLoadScale*(vcLoad - pipeLoad);
/* scale by frac of proper draw time relative to 1 sec. */
if (vcLoad > 0.0f)
{
if ((vcLoad <= lowLoad) || (vcLoad >= highLoad))
{
scale = (1.0f / vcLoad);
if ((stressLevel > 0.0f) && (stressLevel != 1.0f))
scale *= (1.0f / (stressLevel * stressLevel));
areaScale = scale * pfGetPVChanAreaScale(pvchan);
}
else
{
stressLevel = 1.0f;
return;
}
}
else
areaScale = 1.0f;
pfPVChanAreaScale(pvchan, areaScale);
The resulting computed scale value is then compared against the limits on
minimum and maximum overall scale values for the pfPipeVideoChannel, as
well as the limits on minimum and maximum incremental and decremental
scaling steps permitted in a single step.
pfGetPVChanLoad will return the last computed load for pvchan. The load
value is defined as time * frameRate / frac, where time is the sum of the
rendering times of the pfChannels drawing to the pfPipeVideoChannel.
pfGetPVChanMaxDecScale returns the X and Y upper bounds on scaling
decrements for pvchan in x and y.
pfGetPVChanMaxIncScale returns the X and Y upper bounds on scaling
increments for pvchan in x and y.
pfGetPVChanMinDecScale returns the X and Y lower bounds on scaling
decrements for pvchan in x and y.
pfGetPVChanMinIncScale returns the X and Y lower bounds on scaling
increments for pvchan in x and y.
pfGetPVChanPipe returns the parent pfPipe of pvchan. pfGetPVChanPWin
returns the pfPipeWindow of pvchan. pfGetPVChanPWinIndex can be used to
Page 9
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
get the position of a channel in its pfPipeWindow list. A return value
of (-1) indicates that the pfPipeVideoChannel is not assigned to a
pfPipeWindow. pfPipeVideoChannels can be added or moved to other
pfPipeWindows via list style API on pfPipeWindows. See the
pfPWinAddPVChan, pfPWinPVChan, and pfPWinRemovePVChan man pages for more
information.
Example 1: How to set up a pfChannel, pfPipeVideoChannel, and
pfPipeWindow
pfPipe *pipe = pfGetPipe(0);
pfChannel *chan = pfNewChan(pipe);
pfPipeWindow *pwin = pfNewPWin(pipe);
pfPipeVideoChannel pvchan = pfNewPVChan(pipe);
int index;
/* select the screen of interest - can be done here or implicitly through
* the pfPipeWindow but no pfPipeVideoChannel queries can be done until the
* screen is known
*/
pfPipeScreen(pipe, 0);
/* select output video channel; default is to find first active */
pfPVChanId(pvchan, 0);
/* assign the pfPipeVideoChannel to the pfPipeWindow */
index = pfPWinAddPVChan(pwin, pvchan);
/* assign the pfChannel to the video channel via its pfPipeWindow */
pfChanPWinPVChanIndex(chan, index);
pfSelectPVChan makes pvchan the current pfPipeVideoChannel in the process
to have PFVCHAN_AUTO_APPLY changes applied in the current process. This
is done automatically in the DRAW process for pfPipeVideoChannels that
have PFVCHAN_AUTO_APPLY enabled. The pfVideoChannel contained withint
the pfPipeVideoChannel will be selected. pfGetCurVChan will return a
pointer to the current pfVideoChannel.
pfApplyPVChan will cause outstanding changes to pvchan to be immediately
applied to the selected hardware video channel. On InfiniteReality,
changes to the video output origin and size should be done in the DRAW
process and so OpenGL Performer automatically does an apply, if
necessary, automatically at the start of the frame. The changes will
then effect the video scan-out of that immediate frame. Changes made in
the APP process between pfSync and pfFrame will affect the next immediate
DRAW process.
pfPVChanCallig let you set the callig to use for calligraphic lights
points. pfGetPVChanCallig returns the pfCalligraphic in use. Please see
the CALLIGRAPHIC section of pfChannel for more information.
Page 10
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NOTES
pfPipeVideoChannel functionality is not currently supported under Linux.
An XSGIvc video channel may only be bound to a single window at a time on
the system. Only a single pfPipeVideoChannel may bind a hardware video
channel.
On InfiniteReality, changes to video channel origin and size require an
active graphics context and so should be made in the DRAW to avoid a
graphics context change which can be expensive.
See the sample program
/usr/share/Performer/src/pguide/libpr/C/queryvchan.c for an example of
how to query general video channel attributes. See the sample program
/usr/share/Performer/src/pguide/libpf/C/pvchan.c for an example of basic
pfPipeVideoChannel setup. See the sample program
/usr/share/Performer/src/pguide/libpr/C/vchan.c for a basic resizing
example using pfVideoChannels.
SEE ALSO
pfDelete, pfGetNumScreenVChans, pfNewChan, pfGetPipe, pfNewPWin,
pfNewVChan, XSGIvc, glXSGIvcQueryChannelInfo, glXBindChannelToWindowSGIX.
Page 11
