IRIS Performer 1.2 Release Notes

Silicon Graphics Computer Systems

"The Performer"

This document contains the following chapters:

Introduction
Installation Information
IRIS Performer Source Code
Known Problems and Workarounds
Documentation Errors
Differences Between 1.0/1.1 and 1.2

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.

1.1 Release Identification Information

Following is the release identification information for IRIS Performer:

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 version

Note 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.

1.2 On-Line Release Notes

After you install the on-line documentation for a product (the relnotes subsystem), you can view the release notes on your screen.

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.

1.3 Product Support

Silicon Graphics, Inc., provides a comprehensive product support maintenance program for its products.

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.

2.1 IRIS Performer Subsystems

IRIS Performer includes these subsystems:

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

2.2 IRIS Performer Subsystem Disk Space Requirements

This section lists the subsystems (and their sizes) of the IRIS Performer option.

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

2.3 Installation_Method

All of the IRIS Performer subsystems can be installed using IRIX. You do not need to use the miniroot. Refer to the IRIS Software Installation Guide for complete installation instructions.

2.4 Prerequisites

To run IRIS Performer 1.2, your system must be running IRIX 4.0.5 or later for the IRIX 4.0.5 version and IRIX 5.2 or later for the IRIX 5.2 version.

2.5 Compatibility

IRIS Performer's high-performance rendering library, libpr, is platform-specific. Therefore, when an application built on a machine other than a RealityEngine is run on an RealityEngine not all features are available. A RealityEngine binary may be run on other machine type only under certain later versions of IRIX 4.0.5 whose libgl contain the new routines introduced with RealityEngine.
IRIX 4.0.5F added several new Graphics Library (GL) calls to support RealityEngine features, an application that uses GL routines or tokens found only in 4.0.5F and later, does not run properly under 4.0.5C and earlier releases. In general, an IRIS Performer application compiled and linked under IRIX 4.0.5F or later does not run on earlier releases (4.0.5, 4.0.5B, or 4.0.5C).
A Performer binary compiled and linked under IRIX releases before 4.0.5F, runs under IRIX 4.0.5F and later, but some RealityEngine features are not directly accessible to the application. An application can still use RealityEngine features supported automatically or explicitly through IRIS Performer.
Taking an IRIS Performer application built under IRIX 4.0.5 and running it under IRIX 5.X is not recommended. 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.

Applications created with IRIS Performer 1.2 under IRIX 5.2 run compatibly across all platforms.

2.6 Other_Installation_Information

IRIS Performer installs sample code, binaries, and database files in:

/usr/src/Performer/bin: Compiled versions of the perfly, lod, pickfly, and smallfly sample programs
/usr/src/Performer/lib: Compiled versions of the database loading and utility libraries
/usr/src/Performer/include: Header files for the database loading libraries
/usr/src/Performer/src: Sample programs, database loading and utility library source code
/usr/src/Performer/data: Database files and textures

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.

3.1 IRIS Performer Makefile Conventions

The Makefiles shipped with IRIS Performer source code generally follow certain conventions. The make targets: dbg, opt, and dso will make static debug, static optimized and optimized, dynamic shared object (DSO) versions of libraries or executables. Object files are placed into DBG and OPT directories accordingly and library names indicate their version. For example, libpfutil-g.a, libpfutil.a, and libpfutil.so are the results of the dbg, opt, and dso make targets. Executables are given a single name but are a soft link into either the DBG or OPT directories. For example, perfly may be a link to OPT/perfly.OPT. Makefiles look for libraries first in /usr/src/Performer/lib and then in /usr/lib. In order to link with a custom library built in /usr/src/Performer/lib, the makefiles must be modified.

3.2 Database Loaders

A database loader converts a particular on-disk database format into IRIS Performer run-time data structures. Loaders are provided for some standard Silicon Graphics data formats (.bin, .sgo, .iv) as well as many third party formats such as Coryphaeus' .dwb, Software Systems .flt, Autodesk's .dxf, and Wavefront's .obj.

3.2.1 libpfsgi Database Loaders

libpfsgi consists of loaders for the following database formats:

The SGI .bin, .sgo, .gfo, .poly, and .ptu formats
IRIS Inventor's .iv
Software Systems Version 11 .flt. For source code to loaders for versions greater than 11, contact Software Systems at (408) 247-4326.
Miscellaneous formats (.gfo, .irtp, .stla, .stlb).
The SuperViewer .sv format used in I3DM
Lightscape Graphics Software's .lsa and .lsb formats
Autodesk's AutoCAD .dxf format

The sources for these file loaders are located in /usr/src/Performer/src/lib/libpfsgi. Execute a make in this directory to create the library libpfsgi.a.

3.2.2 Software Systems Flight File Loader

libpfflt.a and libpfflt14.a are loaders for .flt versions up to and including version 13 and 14 respectively. Source code for these loaders is not provided in this release but you may contact Software Systems at (408) 247-4326 to obtain source code. libpfflt.a is the default loader used by the supplied Makefiles so if you wish to use the version 14 loader you must change the Makefile(s) to reference libpfflt14.a instead.

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.

3.2.3 Coryphaeus .dwb Loader

Source code for the .dwb loader is found in /usr/src/Performer/src/lib/libpfdwb. Execute a make in this directory to create the library libpfdwb.a.

3.3 Programmer's Guide Source Code

Programming examples referenced in the IRIS Performer's programming guide may be found in /usr/src/Performer/src/pguide/. Source code is organized first by library, libpr, libpf, libpfutil, and then by example type, either example for code fragments or progs for standalone, runnable programs. This source code is a good place to start when learning IRIS Performer.

3.4 Sample Application Source Code

/usr/src/Performer/src/sample/ contains several sample applications which span a range of complexity and IRIS Performer features. Files shared by multiple applications are found in the common directory. If you wish to modify any of these files, copy them into the particular application directory you are working in. Together, common/main.c and common/generic.c illustrate the main framework of an IRIS Performer application so we encourage you to examine these files.

perfly is a fairly complex program which exercises many IRIS Performer features and is a reasonable starting point for many applications. It provides a graphical user interface for manipulating many viewing parameters and is IRIS Performer's general purpose file viewer.
smallfly is trimmed-down version of perfly
lod is a program which illustrates the level-of-detail feature of IRIS Performer
pickfly extends the feature set of perfly to include picking, highlighting, bounding box visualization, and scene graph browsing.

3.5 Utility Library

The utility library found in /usr/src/Performer/src/lib/libpfutil is a grab bag of features which you may find useful. Brief man pages are provided but be cautioned that the utility library can and will change between IRIS Performer releases.

3.6 Tools

/usr/src/Performer/src/tools/ contains software tools that ease the transition from IRIS Performer version 1.0/1.1 to 1.2.

port1.2 is a script which converts files written for versions 1.0/1.1 into files which will work with version 1.2. The new files are suffixed with pf1.2 and include comments added by port1.2 which direct your attention to portions of code that could not be adequately converted by the script.
freeproc is a script that unisolates and unrestricts all the CPUs on your system. Processors may unknowingly be left in a restricted state if a program which restricted them exits ungracefully.

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.

4.1 libpr

Antialiasing: When it is not multisampling, pfAntialias can significantly degrade performance. Specifically, on non-RealityEngine systems, use pfAntialias only for lines and points.
Z buffer config on 4.0.5 RealityEngine: On some versions of IRIX 4.0.5, mssize(4,24,1) (the default by pfAntiAlias) generates an unusable Z configuration. For these machines, call mssize(4,32,1) followed by gconfig() in your pipe initialization routine and do not attempt to toggle antialiasing.
Coplanar polygons: pfDecal works only on machines that support the stencil or displacepolygon command. The default decaling mode for PFDECAL_BASE now uses displacepolygon instead of stencil. This can significantly improve rendering performance but can result in visual anomalies where layer polygons incorrectly "poke" through other geometry. If you wish the old behavior then specify the PFDECAL_BASE_HIGH_QUALITY token.
Transparency: pfTransparency works only on machines that support either blendfunction or multisample (RealityEngine).
Frame control on low- and mid-range machines: Currently, the video clock (pfInitVClock, pfGetVClock, pfVClockSync) is supported only on systems with VGX, VGXT, RealityEngine, RealityEngine2, Elan, XS, and Extreme graphics hardware. On other systems, pfVClockSync returns immediately. Because libpf normally uses pfVClockSync for frame rate control, frame control is not rigorous on other platforms.
Since having other applications running can impact real-time performance, it's sometimes desirable to minimize the number of daemons and other processes. If you have problems achieving real-time behavior, try the pfuLockCPU in libpfutil. You might also try turning off the desktop support and other daemons that are not crucial to your application, e.g.:
```
              % 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
```

4.2 libpf

Hang on exit: On VGX or VGXT running 5.2, calling pfExit when the phase is PFPHASE_LOCK or PFPHASE_FLOAT can leave an inactive window and DRAW process. Workaround: switch to PFPHASE_FLOAT or PFPHASE_FREE before exiting or kill -9 afterwards.
Cull with overlapped draw latency: When running PFPHASE_LIMIT or PFPHASE_FREE, the draw can start late resulting in higher latency.
Cull with overlapped draw hang: When running PFPHASE_LIMIT or PFPHASE_FREE, with processes locked and non-degrading priorities, it is possible to lock out the X server and hang the system.
Networked graphics: libpf does not support applications that use networked GL, that is DGL. However, applications using libpr can use DGL.
Billboard normals and intersections: During rendering, pfBillboard normals are not affected by the transformation applied to make the geometry follow the eye. Intersection testing of line segments (pfSegsIsectNode) against the pfGeoSet's geometry and bounding box are not yet implemented; only the bounding sphere of the entire pfBillboard is available.
Billboards with multiple pfGeoSets: Using pfBillboards with more than one pfGeoSet sometimes causes a segmentation violation during the first cull traversal. Workaround: use only a single pfGeoSet per pfBillboard at some cost in performance.
Flattening transformation hierarchies: pfFlatten does not work properly on pfGeodes that share pfGeoSets with other pfGeodes.
Gangdraw and cursor loading: Loading the cursor with ganged swapbuffers (external swapready wire) hangs graphics. Workaround: don't load the cursor or run applications which change it.
Transparency sorting: When the PFCULL_SORT mode of pfChanTravMode is set, transparent objects are drawn after all opaque geometry. However, transparent objects are not sorted back to front among themselves, so visual anomalies can result when using blended transparency. Workaround: use multisample transparency (PFTR_MS_ALPHA), if available.
Directional pfLightPoints: Specifying a pfLightPoint node as PFLP_UNIDIRECTIONAL or PFLP_BIDIRECTIONAL can cause a core dump in pfLightPoint::cull. Workaround: set the color of the first light point with pfLPointColor(lp, 0, color) before calling pfLPointShape.
Multipipe pfEarthSky fog: When using multiple pipes which share pfEarthSky fog set by pfESkyFog, the fog may appear to change densities and flash. Workaround: to guarantee that pfClearChan is not called simultaneously by more than one pipe. This may be accomplished with a hardware spin lock (see usnewlock).
Limit phase: The PFPHASE_LIMIT mode of pfPhase only works when the draw stage is configured as a separate process. For example, the PFMP_APP_CULLDRAW mode to pfMultiprocess specifies that the cull and draw stages are combined into a single process and so will not be affected by a LIMIT phase.
Binary compatibility on different machines: In Performer 1.2 for IRIX 4.0.5, libpr is platform- specific with one of two versions installed depending on whether the machines is a RealityEngine or not. Binaries linked on non-RealityEngine machines will run on a RealityEngine, but not all features will be available.
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.
Binary compatibility on different releases: IRIS Performer requires IRIX 4.0.5 or later. Because IRIX 4.0.5F added several new GL calls to support RealityEngine features, an application that uses GL routines or tokens found only in 4.0.5F and later does not run properly under 4.0.5, 4.0.5B, or 4.0.5C. When run on these earlier IRIX releases, an IRIS Performer application making calls to GL functions or using GL tokens that are undefined in the run-time environment cause run-time errors or undefined behavior.
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.
Timing on pre-1992 platforms: Several libpf functions require high-resolution timing information. On most recent machines (Indy, Indigo, Indigo2, 4D/35 and Onyx) and PowerSeries or Crimson machines with IO3 boards, IRIS Performer uses special hardware counters with sub-microsecond resolution. (The IO3 board is standard on Crimson and recent 4D/300 and 4D/400 machines. You can check for it with the hinv(1M) command.)
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.
pfChannel passthrough data: When in PFMP_APPCULL_DRAW multiprocessing mode, pfChannel passthrough data (see pfPassChanData) doesn't always make it to the draw callback (see pfChanDrawFunc), which is passed a NULL pointer. Workaround: call pfPassChanData every frame but to keep passthrough data size small for best performance.
Multipipe workaround for 1.1 dangerous in 1.2: A workaround supplied to customers for a bug in 1.1 will causes a segmentation violation in 1.2. The problem, which occurred in multipipe operation, required the application to execute the following code after creating a new pfChannel called "chan": ((long**)chan)[3] = NULL; This workaround is no longer required.
Phase toggling overlapped cull and draw: When running int the PFMP_CULLoDRAW multiprocessing mode, changing the phase from PFPHASE_LOCK or PFPHASE_FLOAT to PFPHASE_FREE_RUN or PFPHASE_LIMIT can cause the application to deadlock. Workaround: toggle only once every few frames or not at all.
Frame statistics for lightpoints: pfFrameStats for visible uni-directional and bi-directional pfLightPoint nodes and points are incorrect. These statistics are part of the pfFrameStats database statistics (PFFSTATS_DB) and these specific counts are incorrrect. However, the counts for total number of visible pfLightPoint nodes and points are correct, and so are the counts for Omni-directional pfLightPoint nodes and points. However, these numbers are only counted when PFFSTATS_CULL are enabled.
Multi-channel stats warning messages: When a multi- channel libpf application enables libpr pfStats modes (such as graphics statistics -- PFSTATS_GFX) in multiple channels at the same time, warning messages are printed every frame. The calculated statistics will be correct. To stop the stream of warning messages, raise the pfNotifyLevel in the program or set the enviornment variable PFNFYLEVEL to a value smaller than 2.
Video warnings on Indy when multiprocessed: When an application on an Indy is forced to run the APP and DRAW in separate processes, e.g. pfMultiprocess(PFMP_APP_CULLDRAW), pfGetVideoRate warnings are printed when process timing stats are on. To stop the stream of warning messages, raise the pfNotifyLevel in the program or set the enviornment variable PFNFYLEVEL to a value smaller than 2.
Running from a remotely mounted file system: For best performance when multiprocessing, make sure the executable is on a local file system.

4.3 libpfutil

pfuCollide is jerky: The collision model jerks and bounces when you keep hitting something.
pfuSaveImage broken: The image file generated by pfuSaveImage is bogus.
Opening GLX window on 4.0.5 Indigo: This hangs the application. Use a GL window instead.

4.4 libpfsgi

pfLoadDxf: The DXF loader does not fully support the format.
pfLoadIv: The IRIS Inventor loader reads a subset of the IRIS Inventor 1.0 format.

4.5 Sample Programs

Overlay text with GLX on 4.0.5: In the sample programs (e.g. perfly) on some platforms, sometimes drawing messages (pfuDrawMessageCI) to the overlay planes in GLX mode doesn't work under 4.0.5. Workaround: use only in GL mode (e.g. do not use "perfly -x") or upgrade to IRIX 5.2.
Toggling antialiasing with GLX on 4.0.5 RealityEngine: Toggling antialiasing in the sample programs running in GLX mode on a 4.0.5 RealityEngine apparently confuses the graphics pipe and causes wild texturing. Workaround: use only in GL mode (e.g. do not use "perfly -x") or upgrade to IRIX 5.2.
GLX on 4.0.5 Indigo: Sample programs hang on startup. Workaround: start up only in GL mode (e.g. do not use "perfly -x") or upgrade to IRIX 5.2.
Z buffer config on 4.0.5 RealityEngine: On some versions of IRIX 4.0.5, mssize(4,24,1) (the default in perfly) generates an unusable Z configuration. Workaround: for these machines, call mssize(4,32,1) followed by gconfig() in your pipe initialization routine and do not attempt to toggle antialiasing.
Pixel fill statistics under 4.0.5 on RealityEngine: Under 4.0.5, fill statistics do not work when multisampling. Workaround: turn off multisampling.
Phase toggling with overlapped cull and draw: In perfly, rapidly toggling the phase when running with the PFMP_CULLoDRAW multiprocessing model ("perfly -m 65540" or "perfly -m 65542") can cause the application to hang. Workaround: toggle slowly or not at all.
pfDataPool warning on exit: A warning similar to the following sometimes occurs when a sample program exits: "Performer Warning (2): pfReleaseDPool() Could not unlink arena shared memory /usr/tmp/pfUtilDataPool11638.pfdpool." This warning is harmless and can be ignored.
Toggling Antialiasing in GLX: When antialiasing is toggled with the GUI in GLX mode, the GL window changes. As each texture textures first comes into view, it is downloaded to the graphics hardware. Occasional pauses will be seen until all textures are reloaded in the graphics hardware. This can be avoided by redownloading all textures (pfuDownloadTexList).
Hang on exit with VGX/VGXT: On VGX and VGXT running 5.2, when exiting sample programs the draw process sometimes fails to exit when in PFPHASE_LOCK or PFPHASE_FLOAT and leaves behind an inactive window. Workaround: switch to PFPHASE_FLOAT or PFPHASE_FREE before exiting or kill -9 .
pickfly drops core under abuse: When aggressively navigating the hierarchy, the number of pfSCSes in the scene graph can exceed the maximum libpf traversal depth of 64.
detail example broken on 4.0.5: The example program sample/pguide/libpf/progs/detail.c doesn't run properly under 4.0.5. Workaround: upgrade to 5.2.

4.6 Friends of Performer

Belvis makefile requires pmake: The makefile for the belvis demo in the Computer Arts and Development section requires the pmake utility. Workaround: install dev.sw.make.
Toon has bad models and textures: Some of the textures are mixed up in toon town.

4.7 Notes on Shared Memory Configurations

IRIS Performer requires shared memory and uses a memory- mapped file, the location of which depends on the value of the PFTMPDIR environment variable:

If PFTMPDIR is not set, Performer uses /dev/zero as the default. Running an application in this configuration:
- Uses swap space
- Does not require disk space until main memory is exhausted
- Is faster than using a regular memory mapped file via PFTMPDIR
- Causes Performer to limit the size of core dump files to 16 MB under IRIX 4.x because a bug in IRIX dumps all of /dev/zero. If you want to modify core size, use setrlimit() after pfInit and before pfConfig. Under IRIX 5.X no core limit is set by pfInit.
- Causes IRIX to kill the process(es) and log an error to the console if the application runs out of space for shared memory in the swap partition.
If PFTMPDIR is set, Performer creates files in the specified directory. Running an application in this configuration:
- Requires disk space even before main memory is exhausted
- Is slower than /dev/zero because it touches the disk
- Produces appropriately sized core dump files with no limit set by IRIS Performer
- Might cause a core dump from a segmentation violation inside pfMalloc if the application runs out of space for shared memory in the file system containing PFTMPDIR
- PFTMPDIR should be set only to a directory on a local file system.

5. Documentation Errors

This chapter lists the problems with the documentation.

5.1 Reference Pages

pfuGetGLXWin wrong on reference page: The prototype in the man page should read: "extern void pfuGetGLXWin(pfPipe *_pipe, pfuGLXWindow *_glxWin);" pfuGetGLXWin copies the active GLX windows (normal and overlay) for the specified pipe into the provided pfuGLXWindow structure. The active windows change when a different GLX visual is requested.
pfuLockDownApp gives the incorrect location for the procsetup.c example: The correct location for this example is: /usr/src/Performer/src/pguide/libpfutil/progs/procsetup.c Additionally, the reference page should mention the example /usr/src/Performer/src/pguide/libpf/progs/bench.c

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.

6.1 Functional and Programmatic Changes in 1.2

Functional differences are those that are not reflected in the programming interface. An example is pfInitGfx which now enables backface culling but which did not in 1.0 and 1.1. Programmatic differences are changes to routine and token names and changes to routine arguments. Some programmatic changes are purely cosmetic and were made for consistency sake while some are a result of new or modified functionality.

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.

6.2 New Features in 1.2

An overview of the major new features of the IRIS Performer 1.2 release are provided in the following paragraphs. In many cases these are significant new features that will facilitate and enhance your work. The following brief list reviews the major new features, refer to the IRIS Performer Programming Guide and the IRIS Performer Reference Pages for full details.

File loaders for several popular file formats are now provided. The formats supported include: AutoCAD DXF ASCII format, Designer's Workbench DWB format, Lightscape Graphics Software LSA and LSB formats, Wavefront OBJ format, I3DM database modeler SV format, IRIS Inventor IV format, and several SGI formats, such as GFO and POLY.
Window and input management based on X-window system are now supported by the libraries (pfInitGLXGfx() and pfuInitInput()). perfly and several of the other sample programs can run in either GL or X-window mode. The '-x' option to perfly and pickfly specifies that a GLX window should be used and input routed through a separate asyncrhonous process.
pfBillboard nodes now have the ability to rotate about the +X or +Y axis, as well as the fixed +Z axis used before. Also, new billboard rotation modes are provided, including a point-rotate mode that can be used to achieve the effect of a "sprite" or "stamp" -- an object which remains screen-aligned from all view points. Refer to the pfBillboard reference page for detailed information.
Terrain database builder (LoadPTU()) that uses the SGI ImageVision Library to process and resample very large input datasets. This function builds textured multiple level-of-detail hierarchical models automatically.
Dataset importer utility library functions pfuBuilder and pfuBreakup that make creating database loaders much simpler than in previous releases. These and related functions are in the utility library /usr/src/Perfly/src/lib/libpfutil.
Enhanced loaders for Software Systems' FLIGHT files. These new loaders build more efficient databases, especially those with extensive use of material definitions. Both loaders have detailed descriptions in the directory "../../usr/src/Performer/src/lib/libpfflt".
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.
Intersection processing is made more efficient by the new pfPartition node type. The pfPartition node will impose a spatial partitioning on a given subgraph for improved intersection performance.
Statistics gathering support for monitoring IRIS Performer operations and graphics and system utilization, including culling and drawing counts, CPU time usage, and pixel-accurate depth-complexity information.
All IRIS Performer data types are now derived from the base class pfObject. All pfObjects have user-data fields and a unified API for general object operations such as copy, delete, reference, printing, and the getting and setting of a user data field.
Dynamic growable lists. The pfList functions provide general and fast support for list operations. The pfNewList() reference page explains these functions.
Path support for searches and query results. pfLists are used to implement the pfPath data type, which is a dynamically-sized array of pointers to nodes. A pfPath of pfNode pointers can define a specific path or chain of nodes through a scene graph. pfPaths are used by intersections (pfSegsIsectNode()) and picking (pfChanPick()) to show the exact traversal path down to to the object of intersection. Refer the pfNewPath() reference page for more information.
A pfFrustum datatype to specify a general perspective or orthographic viewing volume. Frusta may be non- symmetric for video-wall, offset projection, and other applications. Refer to the pfNewFrust() manual page for information of pfFrustum.
Highlighting utilities for pfGeoSets. IRIS Performer 1.2 provides new drawing methods for highlighting individual objects or parts of the database. See the pfNewHlight() manual page for full information on highlighting.
pfInitGfx initializes pfCullFace(PFCF_BACK) by default. This offers significant performance improvement to those programs that did not enable this feature, but could also cause visibility errors in the scene if database models lack consistent face orientations. The "b" key toggles this mode within perfly.
A new pfLightSource node type that allows you to add gl light sources to your scene graph. The pfLightSource node is derived from the libpr pfLight object and uses pfLight routines to set the light attributes such as color [e.g. pfLightColor(lsource...)]. Further, pfLightSource nodes are leaf nodes and are subject to the current transformation. This means that the position and direction of light sources can be defined and updated using pfSCS and pfDCS nodes.
New PFMP_CULLoDRAW multiprocessing mode which overlaps the cull and draw processes for reduced latency. This mode of operation allows complete cull and draw traversal to occur within a single frame time.
As a new default, when the cull and draw stages are the same process, the internal display list is bypassed for reduced overhead. The new PFMP_CULL_DL_DRAW mode will force the use of libpr display lists even in this "same CPU" case for special applications, such as when using accumulation buffer techniques.
Parallel intersection processing. The PFMP_FORK_ISECT multiprocessing mode will fork a separate, asynchronous process for all intersection processing. This process can be subsequently sproc()'ed as desired to achieve a many-fold increase in intersection performance.

6.3 Details of API changes

What follows is a topical list of changes and new features which distinguish IRIS Performer 1.0 and 1.1 from IRIS Performer 1.2.

6.3.1 New Shared Memory and Temporary Data Directory API

The new function pfSharedArenaSize() can be used to control the amount of memory allocated for the IRIS Performer shared memory arena. There is a default maximum of 256 Megabytes, so most users will not need to specify this. Those whose memory needs exceed the default can use this function to specify the amount of RAM that IRIS Performer will attempt to allocate. This new libpr API consists of:

       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:

Set your PFTMPDIR variable to /usr/tmp, in which case this arena will be allocated on the /usr partition, or
Allocate an addition swap partition or else add a /swap file that is of size 256MB*(Max # of IRIS Performer processes) and then execute:
Allocate a large amount of virtual swap space. Warning: this has the effect of disabling the IRIX 5.x strict memory accounting and so programs may be allowed to run out of swap space and then be terminated. Create a ZERO-LENGTH file /swap and then execute:
Make sure the file is zero length, otherwise the kernel will swap real data to it.

6.3.2 New default pfLayer decaling mechanism

pfLayer nodes use the libpr pfDecal() routine to render coplanar geometry known as "decals" or "subfaces". The default PFDECAL_BASE mode of pfDecal() now uses displacepolygon() (rather than stencil()) as its default mechanism on machines which support this feature. This mechanism can offer substantially higher rendering performance than the old default but can also result in visual anomalies where layer polygons incorrectly "poke" through other geometry. If you have these kinds of problems you can specify the PFDECAL_BASE_HIGH_QUALITY or PFDECAL_BASE_STENCIL token to pfLayerMode to force the pfLayer node to use the higher quality stencil() mechanism.

6.3.3 Control for handling floating-point arithmetic exceptions

This new libpr API consists of:

       pfFPConfig()
       pfGetFPConfig()

6.3.4 pfInitClock API Change

pfInitClock() now takes an initial time argument rather than using an implicit reset value of zero.

       old: void pfInitClock(void);
       new: void pfInitClock(double time);

6.3.5 New pfObject API

The pfObject API may be used on all libpr and libpf objects. These routines handle generic object operations. Reference counting is done on these objects so that they will not be deleted by pfDelete() until their reference counts are zero. This new libpr API consists of:

       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);

6.3.6 Improved Object Printing

All of the pfDebugPrint*() routines have been removed and replaced with a single pfPrint() function. The new libpr API consists of:

       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.

6.3.7 Math API Changes

pfMakePolarSeg() now returns segment with origin as +Y axis. In previous versions it returned a segment relative to +X axis.

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

6.3.8 Math API Additions

       pfGetMatType()

       pfPostRotMat()
       pfPreRotMat()

       pfPostScaleMat()
       pfPreScaleMat()

       pfPostTransMat()
       pfPreTransMat()

       pfRotMat()

       pfPostRotMStack()
       pfPostScaleMStack()
       pfPostTransMStack()

       pfEqualMat()

       pfAlmostEqualVec2()
       pfAlmostEqualVec3()
       pfAlmostEqualVec4()
       pfAlmostEqualMat()

6.3.9 Intersection API Changes and Additions

Intersection API and some functionality has been changed and enhanced.

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()

6.3.10 pfPartition node type

A pfPartition is a type of pfGroup which organizes the scene graphs of its children into a static data structure which can be more efficient for culling and intersections. The new libpf API consists of:

       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);

6.3.11 Video Refresh Rate Specification

       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.

6.3.12 X-window system interface

New libpf API:

       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.

6.3.13 Enhanced bounding volumes

You can now get and set bounding spheres as well as bounding boxes for libpf objects.

       long pfNodeBSphere(pfNode *node, pfSphere *bsph, long mode);
       long pfGetNodeBSphere(pfNode *node, pfSphere *bsph);

6.3.14 User control of gl swapbuffers() function

Normally a pfPipe swaps the image buffers at the end of each frame. However, if user control of buffer swapping is desired, pfPipeSwapFunc will register a function as the buffer swapping function for pipe. Instead of swapping buffers directly, the user's function will be called and will be expected to swap the buffers as desired. New libpf API:

       void pfPipeSwapFunc(pfPipe *pipe, void (*func)(pfPipe *pipe));

6.3.15 New texture processing options

New libpf API: pfGetTexFile() has been removed and has been replaced with pfGetTexName(). Textures can now be named with pfTexName().

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.

6.3.16 Material API and Functionality Changes

pfMtlShininess now takes float rather than long.

       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);

6.3.17 Enhanced display list features

Changed libpr API:

       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.

6.3.18 Changed Color Table API

pfGSetCtabMode() has been replaced by:

       void    pfApplyCtab(pfColortable *ctab);
       void    pfEnable(PFEN_COLORTABLE);

6.3.19 pfClear API Change

The argument order has been changed:

       old: void pfClear(pfVec4 color, long type);
       new: void pfClear(long which, pfVec4 color);

6.3.20 Enhanced Channel Statistics Collection and Display

The statistics maintained by IRIS Performer have been greatly enhanced. There are functions to collect, manipulate, print, and query statistics on state operations, geometry, and graphics and system operations. The routines, structures, and constants are declared in "prStats.h". Refer to the following manual pages for information on these utilities:

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().

6.3.21 Changes to Flatten and Clone API

pfFlatten() and pfClone() now take an additional mode argument. This will be used to specify additional details of the clone and flatten operations.

       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.

6.3.22 New View-point and Viewing Projection API

IRIS Performer 1.2 has a new view specification method to support the definition of orthographic and asymmetric perspective viewing volumes. Refer to the pfNewFrust() manual page for more details on pfFrustum.

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.

6.3.23 pfPipe API changes

Changed libpf API:

       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);

6.3.24 pfDCS API changes

Changed libpf API:

       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);

6.3.25 pfLPoint API changes

The arguments to pfLPointColor() have changed so that now you can set the color of an arbitrary light point in a pfLightPoint group.

       old: void pfLPointColor(pfLightPoint* lpoint, pfVec3 clr);
       new: void pfLPointColor(pfLightPoint* lpoint, long index, pfVec4 color);

6.3.26 New pfPhase mode - PFPHASE_LIMIT

PFPHASE_LIMIT behaves similarly to PFPHASE_FREE_RUN except that PFPHASE_LIMIT will limit the application frame rate to that specified by pfFrameRate.

6.3.27 Changed pfConfig behavior when running as root

Previously, root privilege caused pfConfig() to assign non- degrading priorities to Performer processes. Due to deadlock and "good neighbor" issues we have removed this function from pfConfig(). Instead, use the utility function, pfuPrioritizeProcs(TRUE), to assign non-degrading priorities to Performer processes or call schedctl() in conjunction with pfGetPID() to customize process priorities.

Compiled by: Allan Schaffer