http://www.sgi.com/tech/Performer/relnotes.html (Silicon Surf Promotional CD, 01/1995)
"The Performer"
This document contains the following chapters:
1. Introduction
IRIS Performer is a toolkit tailored for high-performance
graphics and visual simulation applications on IRIS
workstations. Its core consists of two libraries: libpr.a
and libpf.a. libpr is a low-level library that provides
high-speed rendering functions, state control, and other
machine-oriented functions. libpf is a rapid prototyping
environment that uses libpr functions to create a
multiprocessing, automated database rendering system that
incorporates many features useful to visual simulation
applications.
In addition to libpr.a and libpf.a, IRIS Performer provides a library of utility functions, libpfutil.a and the libpfsgi.a library which contains file loaders for many popular database formats. Source code is provided for both libpfutil.a and libpfsgi.a. For aid in application development IRIS Performer includes sample application source code which ranges from simple programs that illustrate a particular feature to a comprehensive, GUI- driven file viewer called perfly.
And lastly, this distribution includes a wide variety of source code, demos, models, and utilities that have been provided by 3rd party vendors for your use. We call these vendors "friends of Performer" and we encourage you to sample their wares.
Software Option Product IRIS Performer Version 1.2 Product Code SC4-PERF-1.2 System Software Requirements 4D1-4.0.5 for Irix4 version and 4D1-5.2 for Irix5 versionNote that 1.2 is shipped for both 4.0.5 and 5.2 systems. You should only install that version of IRIS Performer that is appropriate for your machine. The IRIS Performer version is indicated by the "Irix4" or "Irix5" string in each product name. Irix4 products should only be installed on 4.0.5 systems and Irix5 products should only be installed on 5.2 systems.
When a choice is possible between IRIX 5.2 and IRIX 4.0.5, IRIX 5.2 is preferable. IRIX 5.2 is the current operating system release and contains many bug fixes and enhancements utilized by IRIX Performer 1.2. IRIS Performer 1.2 for IRIX 4.0.5 is intended only for users who are unable to upgrade to IRIX 5.2.
If you have a graphics system, select ``Release Notes'' from the Tools submenu of the Toolchest. This displays the grelnotes(1) graphical browser for the on-line release notes.
Refer to the grelnotes(1) man page for information on options to this command.
If you are in North America and would like support for your Silicon Graphics-supported products, contact the Technical Assistance Center at 1-800-800-4SGI.
If you are outside North America, contact the Silicon Graphics subsidiary or authorized distributor in your country.
2. Installation Information
This chapter lists information supplemental to the IRIS
Software Installation Guide. The information listed here is
product-specific; use it with the Installation Guide to
install this product.
performer dev.man.performer Man Pages performer_dev.man.relnotes Release Notes performer_dev.src Sample Code performer_dev.src.pguide Programmers Guide Examples performer_dev.src.sample Sample Application performer_dev.sw Development Environment performer_dev.sw.debug Debug Libraries performer_dev.sw.performer Libraries and Headers performer_dev.sw.pfdwb Sample DWB File Conversion Library performer_dev.sw.pfflt Sample Flight File Conversion Library performer_dev.sw.pfsgi Sample SGI File Conversion Library performer_dev.sw.pfutil Utility Library performer_dev.sw.static Non-Shared Libraries performer_eoe.sw.data Demo Databases performer_eoe.sw.demo Demos performer_eoe.sw.performer Dynamic Shared Libraries performer_friends.sw.arpa Friends of IRIS Performer: ARPA World performer_friends.sw.avalon Friends of IRIS Performer: Avalon FTP Site performer_friends.sw.cad Friends of IRIS Performer: Computer Arts & Dev performer_friends.sw.coryphaeus Friends of IRIS Performer: Coryphaeus performer_friends.sw.i3dm Friends of IRIS Performer: Crystal Visions of Reality performer_friends.sw.cvr Friends of IRIS Performer: I3DM Modeler performer_friends.sw.lightscape Friends of IRIS Performer: Lightscape Radiosity performer_friends.sw.models Friends of IRIS Performer: Various Models performer_friends.sw.multigen Friends of IRIS Performer: Multigen Models performer_friends.sw.oort Friends of IRIS Performer: Oort Game performer_friends.sw.paradigm Friends of IRIS Performer: Paradigm Simulation performer_friends.sw.site Friends of IRIS Performer: Building Site performer_friends.sw.town Friends of IRIS Performer: Town Database performer_friends.sw.viewpoint Friends of IRIS Performer: Viewpoint Models performer_friends.sw.wavefront Friends of IRIS Performer: Wavefront Models
If you are installing this option for the first time, the subsystems marked ``default'' are the ones that are installed if you use the ``go'' menu item. To install a different set of subsystems, use the ``install,'' ``remove,'' ``keep,'' and ``step'' commands in inst to customize the list of subsystems to be installed, then select the ``go'' menu item.
Note: The listed subsystem sizes are approximate. Refer to the IRIS Software Installation Guide for information on finding exact sizes.
Subsystem Name Subsystem Size
(512-byte blocks)
IRIX 4/IRIX5
performer_dev.man.performer (default) 2379 / 1679
performer_dev.man.relnotes (default) 179 / 179
performer_dev.src.pguide (default) 591 / 591
performer_dev.src.sample (default) 678 / 666
performer_dev.sw.debug (default) 10830 / 17688
performer_dev.sw.performer (default) 301 / 301
performer_dev.sw.pfdwb (default) 703 / 717
performer_dev.sw.pfflt (default) 654 / 807
performer_dev.sw.pfsgi (default) 4555 / 3492
performer_dev.sw.pfutil (default) 5706 / 4284
performer_dev.sw.static (default) 1757 / 4808
performer_eoe.sw.data (default) 24513 / 24513
performer_eoe.sw.demo (default) 24743 / 24254
performer_eoe.sw.performer (default) 4213 / 4221
performer_friends.sw.arpa 3538 / 3538
performer_friends.sw.avalon 37982 / 37982
performer_friends.sw.cad 7420 / 7420
performer_friends.sw.coryphaeus 44880 / 44880
performer_friends.sw.cvr 21121 / 21121
performer_friends.sw.i3dm 26598 / 26598
performer_friends.sw.lightscape 26598 / 184424
performer_friends.sw.models 80719 / 80719
performer_friends.sw.multigen 119561 / 119561
performer_friends.sw.oort 8544 / 8544
performer_friends.sw.paradigm 81170 / 81170
performer_friends.sw.site 20333 / 20333
performer_friends.sw.town 38019 / 38019
performer_friends.sw.viewpoint 19468 / 19468
performer_friends.sw.wavefront 3222 / 3222
3. IRIS Performer Source Code
IRIS Performer supplies source code that illustrates how to
load some database formats into IRIS Performer run-time data
structures as well as sample source code which ranges from
simple programs to perfly, a general framework for a visual
simulation application. In addition, a utility library,
libpfutil.a, provides both useful features and examples of
programming with IRIS Performer. Scripts are also provided
which convert your old IRIS Performer source code from
1.0/1.1 to 1.2. You are encouraged to understand and modify
this code for your own purposes subject to the terms and
conditions of the Software License Agreement.
The .flt file converter does not support all MultiGen Flight features and attributes. See the README.V13 and README.V14 in the /usr/src/Performer/src/lib/libpfflt directory for details on non-supported features and attributes.
4. Known Problems and Workarounds
This chapter lists the problems with the IRIS Performer
libraries, libpr and libpf, and with the shared memory
configurations.
Note that the IRIS Performer FAQ also contains an up-to-date list of problems and workarounds.
% touch ~/.disableDesktop
or
% mkdir ~/.desktop-
% touch ~/.desktop-/nodesktop
and for total removal do:
% chkconfig desktop off
% chkconfig objectserver off
% chkconfig directoryserver off
% chkconfig fontserver off
Performer 1.2 for IRIX 5.2 contains a single version of libpr for all machines. Applications built with Performer 1.2 for Irix 5.2 are fully compatible across machines and can run on any Irix 5.2 machine without relinking.
An IRIS Performer binary compiled and linked under IRIX releases earlier than 4.0.5F, run under IRIX 4.0.5F and later, but some RealityEngine features are not directly accessible to the application. An application can still access RealityEngine features supported automatically or explicitly through IRIS Performer when linked with IRIS Performer shared libraries.
Running a IRIS Performer application built with IRIX 4.0.5 on IRIX 5.X is not recommended. In particular, multiprocess applications cannot take advantage of all processors. Also, because IRIX 4.0.5's relaxed shared memory accounting was replaced by a despotic and stricter regime under IRIX 5.2, a Performer application built on 4.0.5 will need a much larger amount of swap space to be allocated up front unless PFTMPDIR is used to specify a memory mapped file.
On other platforms, for example, those with IO2 boards, the time-of-day clock is used, which, by default, has a 10 ms resolution. This resolution is inadequate for many libpf functions, including animation sequences (pfSequence), graphics load computation (pfChanStress), and the display of accurate channel statistics (pfDrawChanStats).
To use any of these features on machines without high- resolution hardware timers, enable fast timers. See the man page for ftimer for more information. Frame rate control particularly bad on machines which lack both a fast clock and the video clock used by pfVClockSync.
5. Documentation Errors
This chapter lists the problems with the documentation.
6. Differences Between 1.2 and previous releases
This chapter elucidates the changes and enhancements between
the 1.2 and the previous 1.0 and 1.1 releases of IRIS
Performer. If you are new to IRIS Performer you can skip
this chapter, since the information contained here is
provided to ease porting efforts.
1.0 was the initial release of IRIS Performer and defined a programming interface. With the exception of a few bug fixes, 1.1 was identical to 1.0 except that 1.1 was compiled to run on systems running the 5.0 operating system. However, 1.2 has both functional and programming differences from 1.0 and 1.1 that you should be aware of if you have developed programs for 1.0 and 1.1. In addition, 1.2 has many new features that you may with to take advantage of.
Your most important aid in porting from the 1.0 and 1.1 versions of IRIS Performer to the 1.2 version is the port1.2 script found in /usr/src/Performer/src/tools. This script will change routine and token names to those defined in 1.2. While port1.2 can automatically complete the majority of the 1.2 port, it will highlight code that it cannot adequately convert with the #error directive so that you can easily find which code fragments need fixing by hand. port1.2 will also add comments that highlight important functional changes. These comments are flagged with the "PORT1.2" string. The output of port1.2 is a file whose name is that of the input file's but is suffixed with "pf1.2".
After processing your files you will need to search them for "PORT1.2" tokens which may have been inserted. These identify locations where code could not be automatically converted or where suggestions for better use of IRIS Performer have been inserted as comments. See the comments in the port1.2 shell script for more details.
The FLIGHT v13 loader is described in the file "README.V13" in that directory; the FLIGHT v14 loader in "README.V14". Both loaders have new features and all FLIGHT file users are encouraged to read these documents to understand them.
ulong pfGetSharedArenaSize(void);
void pfSharedArenaSize(ulong size);
void pfTmpDir(char *dirname);
const char * pfGetTmpDir(void);
Also, the accounting mechanisms for tracking memory required
by an application are much stricter in IRIX 5.x than in IRIX
4.x. By default, IRIS Performer allocates a shared memory
arena in the swap partition that may be much larger than
necessary. If allocation of this arena is denied, there are
three immediate possible solutions:
pfFPConfig()
pfGetFPConfig()
old: void pfInitClock(void);
new: void pfInitClock(double time);
long pfUserData(prObject *obj, void *data);
void * pfGetUserData(prObject *obj);
long pfCopy(prObject *dst, prObject *src);
long pfDelete(prObject *obj);
void pfPrint(prObject *obj, ulong which, ulong verbose,
FILE *file);
long pfGetGLHandle(pfObject *obj);
void pfPrint(pfObject *obj, ulong which, ulong verbose,
FILE *file);
pfPrint prints information to a file about the the specified
pfObject obj. The file argument specifies the file. If
file is NULL, the listing is printed to stderr. pfPrint
takes a verbosity indicator, verbose, to select in order of
increasing verbosity are:
PFPRINT_VB_OFF - no printing
PFPRINT_VB_ON - default - minimal printing
PFPRINT_VB_NOTICE - default - minimal printing
PFPRINT_VB_INFO - interesting info about a given object
PFPRINT_VB_DEBUG - prints everything
If obj is a type of pfNode, then which specifies whether the
print traversal should only traverse the current node
(PFTRAV_SELF) or print out the entire scene graph rooted by
node obj by traversing node and its descendents in the graph
(PFTRAV_SELF | PFTRAV_DESCEND). If obj is a pfFrameStats,
then which specifies a bitmask of frame statistics classes
that should be printed. If obj is a pfGeoSet, then which is
ignored and information about that pfGeoSet is printed
according to the verbosity indicator. The output contains
the types, names and bounds of the nodes and pfGeoSets in
the hierarchy. This routine is provided for debugging
purposes only and the content and format may change in
future releases.
pfRotMStack() has a new argument order to match the OpenGL convention:
old: pfRotMStack(pfMatStack* stack,
float x, float y, float z, float degrees);
new: pfPreRotMStack(pfMatStack* stack,
float degrees, float x, float y, float z);
pfScaleMat() has a changed argument list to match both man
page and the function pfScaleMStack:
old: pfScaleMat(pfMatrix dst, float s, const pfMatrix m);
new: pfPreScaleMat(pfMatrix dst, float x, float y, float z,
const pfMatrix m);
pfScaleMStack() has been renamed pfPreScaleMStack()pfTransMStack() has been renamed pfPreTransMStack()
pfMakeRotOntoMat() no longer scales, it only rotates v1 to be proportional to v2
pfGetMatType()
pfPostRotMat()
pfPreRotMat()
pfPostScaleMat()
pfPreScaleMat()
pfPostTransMat()
pfPreTransMat()
pfRotMat()
pfPostRotMStack()
pfPostScaleMStack()
pfPostTransMStack()
pfEqualMat()
pfAlmostEqualVec2()
pfAlmostEqualVec3()
pfAlmostEqualVec4()
pfAlmostEqualMat()
The pfIsect structure has been removed and is replaced by pfHit.
The arguments and functionality of the functions pfSegsIsectNode() and pfSegsIsectGSet() have changed. Routines have been added to libpfutil to be compatible with the previous functionality. These functions are:
pfuSegsIsectNode()
pfuSegTraceSetup()
pfuSegTrace()
These routines are declared in pfutil.h and the source code
for them is provided in
"../../usr/src/Performer/src/lib/libpfutil". For optimal
performance and efficiency, porting to the new intersection
API is recommended.Changed libpr and libpf intersection API:
old: long pfSegsIsectNode(pfNode* node,
pfSeg** segs, long nseg,
long mode, ulong mask, pfCylinder* bcyl,
pfIsect* isects, long (*discFunc)(pfIsect* isect))
new: long pfSegsIsectNode(pfNode *node, pfSegSet *segSet,
pfHit **hits[])
old: long pfSegsIsectGSet(pfGeoSet* gset, pfSeg** segs, long nSeg,
ulong mask, long mode, pfCylinder* bcyl,
pfIsect* isects, long (*discFunc)(pfIsect* isect))
new: long pfSegsIsectGSet(pfGeoSet *gset, pfSegSet *segSet,
pfHit **hits[])
The arguments to pfChanPick() have changed.
old: long pfChanPick(pfChannel* chan,
long mode,
float px,
float py,
float radius,
pfIsect** picklist);
new: long pfChanPick(pfChannel* chan,
long mode,
float px,
float py,
float radius,
pfHit** picklist[]);
Note: picklist must not be NULL and pfQueryHit() or
prMQueryHit() should be used to get back picking
information. Also, if mode includes PFTRAV_IS_PRIM, then
radius must be 0.0f.New libpr Structures:
pfSegSet
pfHit - replaces pfIsect exposed struct
New API:
pfQueryHit()
pfMQueryHit()
pfPartition * pfNewPart(void);
void pfPartAttr(pfPartition* part, long attr, float val);
float pfGetPartAttr(pfPartition *part, long attr);
void pfBuildPart(pfPartition* cset, long type);
void pfUpdatePart(pfPartition* cset);
long pfGetPartType(pfPartition* part);
float pfGetVideoRate(void);
float pfFrameRate(float rate);
float pfGetFrameRate(void);
long pfFieldRate(long fields);
long pfGetFieldRate(void);
Note: pfGetFrameCount now returns frame accurate count
instead of the application process count.
pfInitGLXGfx()
New libpf API for initializing GLX windows. libpfutil
provides additional utilities for setting up a GLX
application with asynchronous X-input handling. Example
programs in the directory
"../../usr/src/Performer/src/pguide/libpf/progs" demonstrate how
to use these utilities.
long pfNodeBSphere(pfNode *node, pfSphere *bsph, long mode);
long pfGetNodeBSphere(pfNode *node, pfSphere *bsph);
void pfPipeSwapFunc(pfPipe *pipe, void (*func)(pfPipe *pipe));
New libpr API: pfIdleTex() signifies that tex is no longer needed in texture memory and may be replaced by new textures.
void pfIdleTex(pfTexture *tex);
pfIsTexLoaded() returns TRUE or FALSE to indicate if a
texture is already loaded in texture memory or not.
long pfIsTexLoaded(pfTexture *tex);
With these two commands (pfIdleTex and pfIsTexLoaded) it is
possible to implement a simple texture paging mechanism for
IRIS Performer.
void pfMtlShininess(pfMaterial *mtl, float shininess);
The default pfMtlColorMode is now PFMTL_CMODE_AD rather than
PFMTL_CMODE_COLOR. This means that pfGeoSet colors will now
change both the diffuse and ambient colors of the current
front material.
void pfMtlColorMode(pfMaterial *mtl, long side, long mode);
old name: pfSelectDList(pfDispList *dlist);
new name: void pfOpenDList(pfDispList *dlist);
old name: void pfEndDList(void);
new name: void pfCloseDList(void);
New libpr API:
void pfResetDList(pfDispList* dl);
pfDispList * pfGetCurDList(void);
long pfGetDListType(pfDispList *dl);
long pfGetDListSize(pfDispList *dl);
Note: The display list size is in words, not in bytes.
void pfApplyCtab(pfColortable *ctab);
void pfEnable(PFEN_COLORTABLE);
old: void pfClear(pfVec4 color, long type);
new: void pfClear(long which, pfVec4 color);
New API:
pfStats* pfNewStats(void* arena);
ulong pfStatsClass(pfStats *stats, ulong enmask, long val);
ulong pfGetStatsClass(pfStats *stats, ulong enmask);
ulong pfStatsClassMode(pfStats *stats, long class, ulong mask,
long val);
ulong pfGetStatsClassMode(pfStats *stats, long class);
ulong pfOpenStats(pfStats *stats, ulong enmask);
ulong pfCloseStats(ulong enmask);
ulong pfGetOpenStats(pfStats *stats, ulong enmask);
pfStats* pfGetCurStats(void);
void pfEnableStatsHw(ulong which);
void pfDisableStatsHw(ulong which);
void pfStatsHwAttr(long attr, float val);
float pfGetStatsHwAttr(long attr);
ulong pfGetEnableStatsHw(ulong which);
void pfCopyStats(pfStats *dst, pfStats *src, ulong which);
void pfResetStats(pfStats *stats);
void pfClearStats(pfStats *stats, ulong which);
void pfStatsCountGSet(pfStats *stats, pfGeoSet *gset);
void pfAccumulateStats(pfStats *dst, pfStats *src, ulong which);
void pfAverageStats(pfStats *dst, pfStats *src, ulong which,
long num);
long pfQueryStats(pfStats *stats, ulong which, float *dst);
long pfMQueryStats(pfStats *stats, ulong *which, float *dst);
pfFrameStats* pfNewFStats(void);
void pfDrawFStats(pfFrameStats* fstats, pfChannel *chan);
ulong pfStatsClass(pfStats *fstats, ulong enmask, long val);
ulong pfGetStatsClass(pfStats *fstats, ulong enmask);
ulong pfStatsClassMode(pfStats *fstats, long class, ulong mask,
long val);
ulong pfGetStatsClassMode(pfStats *fstats, long class);
void pfStatsAttr(pfStats *fstats, long attr, float val);
float pfGetStatsAttr(pfStats *fstats, long attr);
void pfCopyStats(pfStats *dst, pfStats *src, ulong which);
void pfResetStats(pfStats *fstats);
void pfClearStats(pfStats *fstats, ulong which);
void pfStatsCountGSet(pfStats * fstats, pfGeoSet * gset);
void pfAccumulateStats(pfStats* dst, pfStats* src, ulong which);
void pfAverageStats(pfStats* dst, pfStats* src, ulong which,
long num);
long pfQueryStats(pfStats *fstats, ulong which, float *dst);
long pfMQueryStats(pfStats *fstats, ulong *which, float *dst);
void pfStatsCountNode(pfFrameStats *fstats, long class,
ulong mode, pfNode * node);
Display of these statistics can be done as in IRIS Performer
1.0 using pfDrawChanStats(), or can be redirected to a
separate channel with pfDrawFStats().
old: pfNode* pfClone(pfNode *node);
new: pfNode* pfClone(pfNode *node, long mode);
old: long pfFlatten(pfNode *node);
new: long pfFlatten(pfNode *node, long mode);
Note: The mode must be zero in the IRIS Performer 1.2
release.
pfChanViewOffsets have changed to support translational and rotational offsets for the viewpoint. Order of effect is rotation then translation.
old: void pfChanViewOffsets(pfChannel *chan,
float h, float p, float r);
new: void pfChanViewOffsets(pfChannel *chan,
pfVec3 xyz, pfVec3 hpr)
pfGetChanFrust() has been removed The pfChannel object is
derived from pfFrustum so a channel pointer can be passed to
any routine that expects a pointer to a pfFrustum.pfChanFOVZoom() has been removed. Channel FOV must be scaled directly whenever scaling is desired.
old name: pfGetWindowSize();
new name: pfGetPipeSize(pfPipe *pipe, long *xsize, long *ysize);
old name: pfGetWindowOrigin();
new name: pfGetPipeOrigin(pfPipe *pipe, long *xorg, long *yorg);
old name: pfGetScreen();
new name: long pfGetPipeScreen(pfPipe *pipe);
old name: pfSwapFunc();
new name: void pfPipeSwapFunc(pfPipe *pipe,
void (*func)(pfPipe *pipe));
New libpf API:
void pfGetChanOrigin(pfChannel* chan, long *xo, long *yo);
void pfGetChanSize(pfChannel* chan, long *xs, long *ys);
old name: pfDCSMatrix(pfDCS *dcs, pfMatrix m);
new name: void pfDCSMat(pfDCS *dcs, pfMatrix m);
old name: pfGetDCSMatrix(pfDCS *dcs, pfMatrix m);
new name: void pfGetDCSMat(pfDCS *dcs, pfMatrix m);
old name: pfGetSCSMatrix(pfSCS *scs, pfMatrix mat);
new name: void pfGetSCSMat(pfSCS *scs, pfMatrix mat);
old: void pfLPointColor(pfLightPoint* lpoint, pfVec3 clr);
new: void pfLPointColor(pfLightPoint* lpoint, long index, pfVec4 color);
Compiled by: Allan Schaffer