pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
NAMEpfPipeVideoChannel - Multiprocessed video channel hookup for pfPipes,
pfWindows, and pfChannels
FUNCTION SPECIFICATION
#include <Performer/pf/pfPipeVideoChannel.h>
pfPipeVideoChannel::pfPipeVideoChannel(pfPipe *pipe);
pfType * pfPipeVideoChannel::getClassType(void);
void pfPipeVideoChannel::setAreaScale(float s);
void pfPipeVideoChannel::setCallig(pfCalligraphic* callig);
void pfPipeVideoChannel::setDVRMode(int index);
void pfPipeVideoChannel::setFullRect(void);
void pfPipeVideoChannel::setId(int index);
void pfPipeVideoChannel::setMode(int mode, int val);
void pfPipeVideoChannel::setOutputOrigin(int xo, int yo);
void pfPipeVideoChannel::setOutputSize(int xs, int ys);
void pfPipeVideoChannel::setScale(float xs, float ys);
void pfPipeVideoChannel::setStress(float s);
void pfPipeVideoChannel::setStressFilter(float *frameFrac,
float *lowLoad, float *highLoad, float *pipeLoadScale,
float *stressScale, float *maxStress);
void pfPipeVideoChannel::setWSWindow(pfWSWindow wsWin);
float pfPipeVideoChannel::getAreaScale(void);
pfCalligraphic*
pfPipeVideoChannel::getCallig(void);
int pfPipeVideoChannel::getDVRMode(void);
int pfPipeVideoChannel::getId(void);
float pfPipeVideoChannel::getLoad(void);
void pfPipeVideoChannel::getMinDecScale(float *xs, float *ys);
Page 1
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
void pfPipeVideoChannel::getMinDeltas(int *_dx, int *_dy);
void pfPipeVideoChannel::getMinIncScale(float *xs, float *ys);
void pfPipeVideoChannel::getMinScale(float *xs, float *ys);
void pfPipeVideoChannel::getMaxDecScale(float *xs, float *ys);
void pfPipeVideoChannel::getMaxIncScale(float *xs, float *ys);
void pfPipeVideoChannel::getMaxScale(float *xs, float *ys);
int pfPipeVideoChannel::getMode(int _mode);
void pfPipeVideoChannel::getOutputOrigin(int *xo, int *yo);
void pfPipeVideoChannel::getOutputSize(int *xs, int *ys);
pfPipe * pfPipeVideoChannel::getPipe(void);
pfPipeWindow * pfPipeVideoChannel::getPWin(void);
int pfPipeVideoChannel::getPWinIndex(void);
void pfPipeVideoChannel::getScale(float *xs, float *ys);
float pfPipeVideoChannel::getStress(void);
void pfPipeVideoChannel::getStressFilter(float *frameFrac,
float *lowLoad, float *highLoad, float *pipeLoadScale,
float *stressScale, float *maxStress);
void pfPipeVideoChannel::getSize(int *xs, int *ys);
int pfPipeVideoChannel::getScreen(void);
void pfPipeVideoChannel::getScreenOutputOrigin(int *xo,
int *yo);
pfWSVideoChannelInfo
pfPipeVideoChannel::getPVChanInfo(void);
pfWSWindow pfPipeVideoChannel::getWSWindow(void);
void pfPipeVideoChannel::apply(void);
void pfPipeVideoChannel::bind(void);
void pfPipeVideoChannel::unbind(void);
Page 2
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
void pfPipeVideoChannel::select(void);
int pfPipeVideoChannel::isBound(void);
int pfPipeVideoChannel::isActive(void);
/* 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. This is
also true for ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
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 pfPipeVideoChannel 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();
Page 3
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
int pfMemory::getSize();
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 4
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
|
new pfPipeVideoChannel creates and returns a handle to a
pfPipeVideoChannel. pfPipeVideoChannels are always allocated from shared
memory and cannot be created statically, on the stack or in arrays.
pfPipeVideoChannel::getClassType returns the pfType* for the class
pfPipeVideoChannel. The pfType* returned by
pfPipeVideoChannel::getClassType is the same as the pfType* returned by
invoking the virtual function getType 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 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.
pfPipeVideoChannel::setId selects the hardware output video channel for
the pfPipeVideoChannel to use. The output video channel of a
pfPipeVideoChannel can be queried with pfPipeVideoChannel::getId. Care
Page 5
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
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 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 pfPipe::setScreen or
pfPipeWindow with pfPipeWindow::setScreen or having the pfPipeWindow
opened and thus the screen being set implicitly.
pfPipeVideoChannel::setMode 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 select 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 apply. 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
pfPipeVideoChannel::select for pvchan is done automatically by
its pfPipe. Only one pfPipeVideoChannel can be actively
PFVCHAN_AUTO_APPLY at a time for a single pfPipe.
pfPipeVideoChannel::getMode will return the value of the specified mode
for pvchan.
pfPipeVideoChannel::setDVRMode 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 pfPipeVideoChannel::setOutputSize,
pfPipeVideoChannel::setAreaScale, and
pfPipeVideoChannel::setScale.
Page 6
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
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
will only be done when a stress filter has been specified with
pfPipeVideoChannel::setStressFilter that includes a non-zero
stress scale value.
pfPipeVideoChannel::setMaxDecScale 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.
pfPipeVideoChannel::setMaxIncScale 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.
pfPipeVideoChannel::setMinDecScale 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.
pfPipeVideoChannel::setMinIncScale 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.
pfPipeVideoChannel::setStress 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.
pfPipeVideoChannel::setStressFilter sets the parameters for computing
stress, when not explicitly set for the current frame by
pfPipeVideoChannel::setStress, for the pfPipeVideoChannel. frac is the
fraction of a frame period the pfPipeVideoChannel 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.
pfPipeVideoChannel::getStressFilter returns the stress filter parameters
for the pfPipeVideoChannel. 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:
Page 7
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
pfPipeVideoChannel *pvchan;
......
float vcLoad = pfGetPVChanLoad(pvchan);
float pipeLoad = pfGetPipeLoad(pvchan);
float stressLevel = pfGetPVChanStress(pvchan);
float areaScale;
/* 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.
pfPipeVideoChannel::getLoad will return the last computed load for the
pfPipeVideoChannel. 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.
pfPipeVideoChannel::getMaxDecScale returns the X and Y upper bounds on
scaling decrements for the pfPipeVideoChannel in x and y.
pfPipeVideoChannel::getMaxIncScale returns the X and Y upper bounds on
scaling increments for the pfPipeVideoChannel in x and y.
Page 8
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
pfPipeVideoChannel::getMinDecScale returns the X and Y lower bounds on
scaling decrements for the pfPipeVideoChannel in x and y.
pfPipeVideoChannel::getMinIncScale returns the X and Y lower bounds on
scaling increments for the pfPipeVideoChannel in x and y.
pfPipeVideoChannel::getPipe returns the parent pfPipe of the
pfPipeVideoChannel. pfPipeVideoChannel::getPWin returns the pfPipeWindow
of the pfPipeVideoChannel. pfChannel::getPWinIndex can be used to 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 pfPipeWindow
man page 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);
pfPipeVideoChannel::select 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.
pfPipeVideoChannel::apply 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
Page 9
pfPipeVideoChannel(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
the next immediate DRAW process.
pfPipeVideoChannel::setCallig let you set the callig to use for
calligraphic lights points. pfPipeVideoChannel::getCallig returns the
pfCalligraphic in use. Please see the CALLIGRAPHIC section of pfChannel
for more information.
NOTESpfPipeVideoChannel 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, pfChannel, pfPipe, pfPipeWindow,
pfVideoChannel, XSGIvc, glXSGIvcQueryChannelInfo,
glXBindChannelToWindowSGIX.
Page 10
