pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAME
pfCalligraphic, pfSelectCallig, pfGetCurCallig - Calligraphic Lights
Points optional extension to OpenGL Performer
FUNCTION SPECIFICATION
#include <Performer/pr/pfCalligraphic.h>
pfCalligraphic::pfCalligraphic();
static pfType * pfCalligraphic::getClassType(void);
static int pfCalligraphic::initBoard(int board);
static int pfCalligraphic::isBoardInited(int board);
static int pfCalligraphic::getBoardMemSize(int board);
static LPB_info * pfCalligraphic::getInfo(int board);
static int pfCalligraphic::getDeviceId(int board);
static int pfCalligraphic::closeBoard(int board);
static unsigned int pfCalligraphic::queryBoard(int board);
static int pfCalligraphic::partition(int board,
size_t * allocate, int n);
static int pfCalligraphic::waitForVME(int board);
static int pfCalligraphic::waitForVISI(int board);
static void pfCalligraphic::swapVME(int board);
int pfCalligraphic::setChannel(int board, int channel);
int pfCalligraphic::getChannel(int board, int channel);
int pfCalligraphic::isInited(void);
void pfCalligraphic::setZFootPrintSize(float size);
float pfCalligraphic::getZFootPrintSize(void);
void pfCalligraphic::setDrawTime(float time);
float pfCalligraphic::getDrawTime(void);
void pfCalligraphic::setExposureRatio(float ratio);
Page 1
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
float pfCalligraphic::getExposureRatio(void);
void pfCalligraphic::setFilterSize(unsigned int sizeX,
unsigned int sizeY);
void pfCalligraphic::getFilterSize(unsigned int * sizeX,
unsigned int * sizeY);
void pfCalligraphic::setDefocus(float defocus);
float pfCalligraphic::getDefocus(void);
void pfCalligraphic::setRasterDefocus(float defocus);
float pfCalligraphic::getRasterDefocus(void);
void pfCalligraphic::setStress(float stress);
float pfCalligraphic::getStress(void);
int -
pfCalligraphic::downLoadSlewTable(pfCalligSlewTableEnum offset,
pfCalligSlewTable Slew);
int -
pfCalligraphic::upLoadSlewTable(pfCalligSlewTableEnum offset,
pfCalligSlewTable Slew);
int -
pfCalligraphic::downLoadGammaTable(pfCalligGammaTableEnum offset,
pfCalligGammaTable Gamma);
int -
pfCalligraphic::upLoadGammaTable(pfCalligGammaTableEnum offset,
pfCalligGammaTable Gamma);
void pfCalligraphic::setWin(unsigned int xmin,
float ymin, float width, float height);
void pfCalligraphic::getWin(unsigned int * xmin,
float * ymin, float * width, float *height);
void pfCalligraphic::setXYSwap(int flag);
int pfCalligraphic::getXYSwap(void);
void pfCalligraphic::setMultisample(int n);
int pfCalligraphic::getMultisample(void);
Page 2
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfCalligraphic::setProjMat(pfMatrix *projMat);
void pfCalligraphic::getProjMat(pfMatrix *projMat);
void pfSelectCallig(pfCalligraphic *calligraphic);
pfCalligraphic * pfGetCurCallig(void);
typedef enum {
pfXSlewQuality0 = 0,
pfXSlewQuality1 = 1,
pfXSlewQuality2 = 2,
pfYSlewQuality0 = 3,
pfYSlewQuality1 = 4,
pfYSlewQuality2 = 5,
pfDefocusQuality0 = 6,
pfDefocusQuality1 = 7
} pfCalligSlewTableEnum;
typedef float pfCalligSlewTable[256][256];
typedef enum {
pfRedGammaTable = 0,
pfGreenGammaTable = 1,
pfBlueGammaTable = 2
} pfCalligGammaTableEnum;
typedef float pfCalligGammaTable[1024];
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfCalligraphic is derived from the parent
class pfObject, so each of these member functions of class pfObject are
also directly usable with objects of class pfCalligraphic. This is also
true for ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
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 pfCalligraphic can also be used with these
functions designed for objects of class pfMemory.
Page 3
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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();
int pfMemory::getSize();
PARAMETERS
calligraphic identifies a pfCalligraphic.
Slew identifies a pfCalligraphicSlewTable
Gamma identifies a pfCalligraphicGammaTable
DESCRIPTION
The pfCalligraphic object is a libpr data structure that is used, in
conjunction with a pfLPointState, to control the calligraphic light point
features in OpenGL Performer. Calligraphic light points require a
calligraphic light point board (LPB) with it's low-level device driver, a
calligraphic display system, and special cables between the
InifiniteReality raster manager boards and the LPB. If you do not have
this specific optional hardware, you are limited to raster light points,
as supported by the pfLPointState extension to the pfGeoState.
The main difference between the usual raster display and a calligraphic
display is that the number of lights that can be displayed is
proportional to the time preallocated for the calligraphic display in the
video format. No more points can be displayed once the Vsync point is
reached so the LPB must stop its drawing, returning control back to the
raster display no matter how many points were still waiting for
calligraphic display.
An other main difference is that an error in a program or an invalid
parameter specified in a pfCalligraphic object may have a destructive
effect on the (often very expensive) calligraphic projector or the light
point board.
pfCalligraphic support provides advanced functions to manage calligraphic
Page 4
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
light points such as using raster lights instead of calligraphic lights
based on user-specified significance, allowing delayed computation in a
hybrid video format and returning detailed information of the previous
frame for a good feedback loop.
The light point computation, and especially the calligraphic light point
computation, is a sensitive (sometimes proprietary) part of a simulator.
The design of pfCalligraphic and pfLPointState processing allows the user
to implement their own algorithms using a pre or post processing
callback.
LPB Hardware Configuration
LPB are fully supported only on InfiniteReality systems. The LPB is a 9U
VME board that is connected to a IR pipe through the following links:
o The VME bus is used to transfer all the lights points to the LPB,
including the color, focus, exposure time, quality and position
of each light point.
o The VISI bus is used to transfer the Z-buffer comparison result
from the graphic pipe to the LPB. Each Light Point have a
unique Id sent to the pipe which is transferred back to the LPB
with the number of visible samples. The VISI bus is a connector
on each RM board, the LPB must be connected to all RMs board
(1,2 or 4).
o The video, including vertical and horizontal synchronization signals.
The LPB uses these signals to trigger the display of
calligraphics.
o The Swap Ready signal. This signal is used to tell the LPB that the
raster display has swapped, so it should also swap it's
internal buffers. If the LPB does not get a Swap Ready
acknowledgement, the LPB will redisplay the same calligraphic
light points at each Vsync (since the raster frame is being
repeated, so must the calligraphic lights be unchanged).
Only one light point board is supported per pipe. The LPB is connected to
all the Video Channels produced by a single pipe.
The board may be used in a system without a VISI bus (systems prior to
IR), in which case no Z-buffer information will be given to the board, so
all points will be 100% visible.
Calligraphic computation is a very CPU consuming process, and does a lot
of Kernel calls through the LPB VME driver. It is recommanded that at
least one CPU is dedicated on a system per LPB. The process creation and
synchronization is automatically handled in libpf when giving
PFMP_FORK_LPOINT to pfMultiprocess before calling pfConfig. It is based
Page 5
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
on the display list preprocessing capacity introduced in OpenGL Performer
2.2.
A special environment variable PF_LPOINT_BOARD may be used when one wants
to try pfCalligraphics without a light point board. In this mode all the
computations will be performed, and raster light points will be displayed
with the following limitations:
o focus as no effect on simulated display
o every light point have the same size, defined by the Z-footprint
LPB Initialization
Each LPB must be initialized before any fork() or sproc() call. This
means they must be initialized before calling pfConfig() when using
libpf. Each board is initialized by pfCalligraphic::initBoard with board
the number of the board. As there is one board per pipe, the board number
is also the pipe number.
This call will open the LPB device "/dev/lpb%" (% is the board #) and get
the current configuration. The configuration of the board is not
available through libpr, and all Calligraphic channels have to be enabled
before using the LPB utilities.
This function returns TRUE in case of success, FALSE otherwise.
pfCalligraphic::isBoardInited can be used to check if the board has been
initialized.
pfCalligraphic::getInfo returns a pointer to the info structure
maintained by the LPB driver. LPB_info is defined as an unknown structure
in 'pr.h'. In order to use the correct definition of this structure, one
must include the driver 'lpb.h' file before any OpenGL Performer includes
files. This file is not distributed with OpenGL Performer, it is part of
the LPB driver distribution.
pfCalligraphic::getDeviceId returns the device Id returned by the open()
call done by libpr.
pfCalligraphic::closeBoard close the driver and the initBoard function
has to be called again in order to use calligraphic light points again.
This function can be used in a test routine that just look if a board is
there by using initBoard and then closeBoard.
pfCalligraphic::queryBoard returns a bit mask indicating which channels
are enabled on a board. A return of 0 is returned if there is no board,
or if no channel is enabled, in either case no calligraphic light points
can be used on this pipe. If the board is not opened, the this function
will open and then close the board, so it can be used anytime, like other
pfQuery functions.
Once a board is initialized, it has to be partitioned. Each enabled
Page 6
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
channel on the LPB are given an equal amount of Light Point Memory at
initialization. LcpfCalligPartitionpfCalligraphic::partition can be used
to set up an other partition. This function accepts an array of type int
specifying how many bytes of memory should be allocated for each channel.
The size of the LPB memory is given by pfGetCalligBoardMemSize and is
reported in bytes.
LPB Synchronization
As described above, the LPB is connected to the VME bus and the VISI bus.
Both buses contain information for the light points that are buffered in
the LPB. The SwapReady connection to the graphic pipe tells the board
when the transfer on the VISI bus is finished, and that we should display
the next Frame at the next VSync. pfCalligraphic::swapVME does the same
for the VME bus.
In a calligraphic-only video mode, the VME bus swap command should be
issued before the graphic pipe swapbuffer command because the LPB starts
displaying the lights as soon as the next Vsync. But in hybrid mode, this
allow the LPB to use some of the raster display time to catch up with
delayed VME transfers.
If the VME bus swap is too late, the LPB will not wait for the command
and raise a TOO_LATE error exception. pfCalligraphic handle that problem
and ensure that the LPB buffers always contain valid data even if such an
event occurs.
The LPB needs some time before being able to accept new information on
the VME and the VISI bus after receiving the corresponding swap command.
pfCalligraphic::waitForVME and
LcpfCalligWaitForVISIpfCalligraphic::waitForVISI are used to wait for the
board to be ready before sending new information to the board.
All of this synchronization mechanism is handled automatically in libpf.
Note that if you use calligraphics, and you do also use directly
pfSwapPWinBuffers, then you will have to do a VME swap to keep the board
in sync, or issue 2 VME swap after a series of WIN swap to resynchronize
the LPB.
Initializing a Calligraphic Channel
If the LPB can be initialized in libpr, and some channels have been
enabled when its video format has been programmed, a pfCalligraphic
object can be created pfCalligraphic::pfCalligraphic, and mapped to on
channel on one LPB using pfCalligraphic::setChannel. This function
returns TRUE in case of success, FALSE otherwise.
pfCalligraphic::getChanel or pfCalligraphic::isInited can be used to
check if the pfCalligraphic is well initialized. More than one
pfCalligraphic can be mapped to the same LPB video channel, but they
cannot be processed in parallel. Once mapped, any changed made to a
pfCalligraphic is immediately transmitted to the driver.
Page 7
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
fCalligraphic::setMultisample is used to tell the pfCalligraphic how many
multisample are used in the corresponding video channel.
pfCalligraphic::getMultisample returns the current setting. This call is
automatically done by libpf to tell the current pfCalligraphic how many
multisample are used in the current window, only direct libpr users have
to use that function.
fCalligraphic::setProjMat is used by libpf to give a projection matrix to
use when sending the calligraphic footprint to the pipe when this matrix
should not be identity. It is the case when DVR is in use.
fCalligraphic::getProjMat copy the current projMatrix at the address
specicied as an argument.
pfCalligraphic::downLoadSlewTable and pfCalligraphic::downLoadGammaTable
respectively loads a slew table and a gamma table in the LPB. There are
pfSlewTableEnum (8) slew tables and pfGammaTableEnum (3) Gamma table per
channel.
Some projectors do not need Slew Tables and/or Gamma Tables. A default
gamma and Slew table are loaded in the LPB by the driver at the
initialisation of the system. The tables stay loaded until a new call to
pfCalligraphic::downLoadXX is done, but they will not survive a power off
of the system.
pfCalligraphic::upLoadSlewTable gives back the slew table for the offset.
A slew value is given in nanoseconds, and converted to the LPB internal
representation. A gamma value is a normalize floating point number
[0,1]. Be aware that not all values may have a meaning for the
LPB/Projector component. Refers to the LPB and projector documentation.
A default generic (slow) Slew Table is loaded in the LPB when
initializing the board. A linear ramp is preprogrammed as a GammaTable
(gamma = 1).
pfCalligraphic::setZFootPrintSize gives the diameter in pixels of the
footprint sent to the graphic pipe for the Z buffer test. It is required
that the foot print covers at least 4 multisamples. The default value is
4 pixels, giving for a 8 multisample configuration a total of
(PI*4*4/4*8) 100 multisamples for a 100% visible point.
A light point that covers less than 4 multisamples is considered not
visible at all. A light point cannot cover more than 255 multisamples, as
the light point board register is 8 bits. Anyway, the coverage should be
limited to 100 multisamples as after this size, OpenGL uses an
approximation of a point using a triangle fan, that does not provide a
perfect circle and may result in slight blinking effects.
pfCalligraphic::getZFootPrintSize gives back the current setting.
pfCalligraphic::setWin set the pfCalligraphic range for the 2D coordinate
system accepted by the projector and the LPB. Default values are for an
EIS projector, please refers to the projector documentation if you are
Page 8
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
using a different projector. You can also use the Win to draw in a
smaller area than the full screen in case you whant to have multiple
calligraphic channel on the same projector. Negative numbers can be used
if the axis are reversed on the projector, and the projector do not have
a INVERT option.
pfCalligraphic::getWin gives back the current setting.
pfCalligraphic::setXYSwap let you exchange the X and Y axis if it is
needed for your projector. pfCalligraphic::getXYSwap returns the current
setting.
The formulas used to compute the projector coordinates from the 2D
coordinates are: Xp = ax * X + bx; Yp = ay * Y + by;
with: ax = (-width)/2.; bx = (xmin+width/2.); ay = (height/2.); by =
(ymin+height/2.);
Calligraphic parameters
pfCalligraphic::setDrawTime set the draw time of the calligraphic lights
points. Changing this value result in a global change in the intensity,
but also in the number of Calligraphic Light Points drawable in a video
field, as each point takes more time to draw.
pfCalligraphic::getDrawTime returns the current setting.
Draw times are given in nano seconds, and are scaled to the projector
values dividing by the exposureRatio. The by default value is for a EIS
projector, please refers to the projector documentation if you want to
change the ratio using pfCalligraphic::setExposureRatio.
pfCalligraphic::getExposureRatio returns the current settings.
pfCalligraphic::setFilterSize set the Calligraphic debunching filter.
pfCalligraphic::getFilterSize returns the current values.
sizeX and sizeY gives the size of the filter in the 2D coordinate system
defined by the pfCalligraphic viewport. If two consecutive Light Points
are separate by less than the filter size, the one that have the lowest
intensity is removed. Filter is not active is both sizes are less or
equal to 1. Filter is always done after the callbacks (see the
pfLPointState extension below)
pfCalligraphic::setDefocus set the requested defocus value for the light
points. (see the pfLPointState extension below)
pfCalligraphic::getDefocus returns the current setting.
pfCalligraphic::setRasterDefocus set the defocus for the Raster part of
the Hybrid projector. pfCalligraphic::getRasterDefocus returns the
current value.
The defocus result is very dependent of the LPB/projector system used.
Page 9
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
No rule can be givent here for the setting of this value, refers to the
LPB and projector documentation.
pfCalligraphic::setStress sets the current Calligraphic Stress. If a
Calligraphic light point does not pass the stress test, it will be
drawned as a Raster light point. (see the plLPointState extension below)
pfCalligraphic::getStress returns the current setting.
When using libpf, the calls to change the Calligraphic parameters can be
done in the LPoint process callback function with
pfChannel::setTravFunc(PFTRAV_LPOINT, LpointFunc)
Preprocessing a DL in a Process
Calligraphic light points require a fair amount of CPU. To add
calligraphic light points to an application, OpenGL Performer uses the
Display List preprocessing capacity is a separate process that runs in
parallel with the Draw Process.
Use pfSelectCallig to select on which channel of which LPB the
calligraphic light points have to be sent. See pfDispList man pages for a
complete description of Display List preprocessing.
pfGetCurCallig returns the current selected calligraphic.
Extension to pfLPointState
Calligraphic lights points is an extension to the pfLPointState. Every
field in a pfLPointState should be correctly filled before adding the
Calligraphic capability. So a pfLPointState that have a Calligraphic
capability can be rendered either in Raster or Calligraphic mode.
Extensions to the pfLPointState Mode:
PFLPS_DRAW_MODE /* Enable calligraphic drawing */
PFLPS_DRAW_MODE_RASTER - Default value: raster only
PFLPS_DRAW_MODE_CALLIGRAPHIC - Draw in Calligraphic mode
PFLPS_QUALITY_MODE /* Set the quality of draw */
PFLPS_QUALITY_MODE_HIGH - Use High Quality Slew Tables
PFLPS_QUALITY_MODE_MEDIUM - Use Medium Quality Slew Tables
PFLPS_QUALITY_MODE_LOW - Use Low Quality Slew Tables
PFLPS_DEBUNCHING_MODE /* Enable calligraphic debunching */
PFLPS_DEBUNCHING_MODE_ON - Turn on the debunching (see FilterSize)
PFLPS_DEBUNCHING_MODE_OFF - Turn off debunching
Page 10
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
Extensions to the pfLPointState Vals:
PFLPS_SIGNIFICANCE give the significance of the light points. This
value is compared to the pfCalligraphic stress value, and if the
significance value is higher than the stress value, then the light
goes calligraphic. If not, it will be drawned as regular raster
lights.
PFLPS_MIN_DEFOCUS set the min defocus value for the light points.
PFLPS_MAX_DEFOCUS set the max defocus value for the light points.
The pfCalligraphic defocus value is clamped against those min and
max defocus values.
When using libpf and in order to optimize the drawing time of the
calligraphic light points, it is recommended to set the draw order
of each GeoSet attached to a pfLPointState. The lpoint process
creates the PFSORT_LPSTATE_BIN that have the PFSORT_DRAW_ORDER sort
that use directly the draw order set in the pfGeoSet. See pfGeoSet
and pfChannel man pages.
Callbacks
The Calligraphic callback function is set through the pfLPointState.
As for the pfLPointState callbacks, pfCalligraphic callbacks can be done
before or after the standard computation by choosing the
PFLPS_CALLBACK_MODE_PRE or PFLPS_CALLBACK_MODE_POST mode.
The callback function receive many arguments (as defined in pr.h):
typedef struct {
pfLPointState *lpstate; /* Read Only LPState */
pfGeoSet *geoset; /* Read Only GeoSet */
void *userData; /* Provided when setting the callback */
unsigned short *index; /* Read Write - index of visible lpoints */
int *n; /* Read Write - number of visible lpoints */
pfVec3 *coords2D; /* Read Write - screen space X,Y,Z */
float *intensity;/* Write Only - resulting intensity */
float **focus; /* Write Only - optional per lpoint (de)focus */
float **drawTime;/* Write Only - optional per lpoint drawTime */
} pfCalligData;
lpstate, geoset, userData are defined just like in the raster callback
(see man pfLPointState).
But in the case of pfCalligraphic, a 2D projection and clipping to the
Page 11
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
calligraphic viewport is always done. So the callback has also access to:
o coords2D the screen space (X,Y,Z) coordinate of the vertices after the
OpenGL transformations, including the projection matrix.
o index the indirection vector, that give the list of non clipped points. The
order of points in the indirection vector may be changed, so the
user callback can do a screen sort.
o n the number of elements to that indirection vector, that write-able,
so the callback can eliminate some lpoints. One can use it to do
it's own debunching and disable the one done by Performer.
Some post processing is also always done. The filter is called, it
can be disabled by setting the filter sized to 1.
Then the computed lpoints have to be sent to the LPB and to the
graphic pipe if a VISI bus is available. Two more options are given
to the Callback:
o returning a non null pointer to an array of focus values allow each
individual lights in the pfGeoSet to have a different defocus value
instead of using the standard min and max clamping. For drawing
performance materm it is not recommanded to set a different value to
each point, but this can be used for special effects such as local
windscreen wipers.
o returning a non null pointer to an array of drawTime values allow
each individual lights in the pfGeoSet to have a different drawTime
value instead of the fixed value given in the pfCalligraphic. This
may be necessary for some very fine tuning, such as required but the
FAA regulation.
The focus and drawTime arrays are not allocated by OpenGL Performer.
It is safe not to allocate them from the Shared Memory, but not from
the stack of the Callback function. To return defocus values, simply
change the focus pointer to where the defocus values are.
NOTES
pfCalligraphic functionality is not supported under Linux.
EIS is short for Electronic Image Systems, Inc. 600 Bellbrook Avenue,
Xenia, OH 45385 USA. Returning a negative alpha cause Performer to use
the BackColor in the pfLPointState and -alpha as the alpha value.
The filtering algorithm is active within a pfGeoSet, not filtering occurs
between points that are not in the same geoset.
The GeoSet used for calligraphics has to have a color setting, otherwise
this will result in a core dump of the lpoint process.
Page 12
pfCalligraphic(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
SEE ALSO
pfChannel, pfConfig, pfDispList, pfGeoSet, pfGeoState, pfLPointState,
pfMultiprocess, pfState
Page 13
