This document (dated 1/19/96) hails from http://www.sgi.com/Technology/Performer/relnotes.html
-- always reference the above link, for the most current, up-to-date version of this page.

IRIS Performer 2.0 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 2.0 and previous releases

1. Introduction

Welcome to the IRIS Performer application development environment.

IRIS Performer provides a powerful and extensible programming interface (with ANSI C and C++ bindings) for creating real-time visual simulation and other interactive graphics applications. IRIS Performer 2.0 supports both the IRIS Graphics Library (IRIS GL) and the industry standard OpenGL graphics library; these libraries combine with the IRIX operating system and REACT extensions to form the foundation of a powerful suite of tools and features for creating real-time visual simulation applications on Silicon Graphics systems.

IRIS Performer is an integral part of the Onyx/RealityEngine and Indigo2/Impact graphics systems and provides interfaces to advanced features of RealityEngine-class graphics. IRIS Performer is compatible with uniprocessor and multiprocessor SGI graphics platforms and attains maximum performance on all. IRIS Performer provides an extensible basis for creating real-time 3D graphics applications in the fields of visual simulation, entertainment, virtual reality, broadcast video, and computer aided design. IRIS Performer is the flexible, intuitive, toolkit-based solution for developers who want to optimize performance on Silicon Graphics systems.

IRIS Performer consists of two main libraries, libpf and libpr, and four associated libraries, libpfdu, libpfdb, libpfui, and libpfutil.

The basis of IRIS Performer is the performance rendering library libpr, a low level library providing high speed rendering functions based on pfGeoSets, efficient graphics state control using pfGeoStates, and other application-neutral functions.

Layered above libpr is libpf, a real-time visual simulation environment providing a high-performance multi-processing database rendering system that takes best advantage of IRIS symmetric multiprocessing CPU hardware.

The database utility library libpfdu provides powerful functions for defining both geometric and appearance attributes of three dimensional objects, encourages sharing of state and materials and generates efficient triangle strips from independent polygonal input.

The database library libpfdb uses the facilities of libpfdu, libpf, and libpr to import database files in many popular industry standard database formats. These loaders also serve as a guide to developers creating new database importers.

libpfui contains user interface building blocks for creating manipulators common to many interactive applications. This library has both a C and C++ API and is GL independent.

Completing the suite of libraries is libpfutil, the IRIS Performer utility library. It provides a collection of important convenience routines implementing such diverse tasks as smoke effects, MultiChannel Option support, graphical user interface tools, X and IRS GL event collection and management, and traversal functions.

For aid in application development, IRIS Performer includes sample application source code ranging from simple programs to illustrate particular features to the comprehensive, GUI-driven file viewer perfly.

In addition to these SGI-developed tools, IRIS Performer also includes a very large repository of sample code, databases, games, and movies contributed by the Friends of Performer: companies and individuals with services of general interest to the IRIS Performer community. 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                        2.0
       Product Code                   SC4-PERF-2.0
       System Software Requirements   4D1-5.3 R3000/R4000
                                      4D1-6.1 R8000

Note that the IRIS Performer 2.0 release contains libraries and executables intended for both IRIX 5.3 and IRIX 6.2 (or later) systems. The 32-bit MIPS I IRIX 5.3 libraries and executables work well on IRIX 6.1 and IRIX 6.2 systems, but the converse is not true; the 64-bit MIPS III libraries and executables are not compatible with IRIX 5.3 or IRIX 6.1 systems; neither are the 32-bit MIPS III (N32) libraries. For development of 64-bit or N32 OpenGL applications, the use of IRIX 6.2 is required.

In order to install the MIPS III versions (N32 and N64) on IRIX 5.3 systems (for cross-development or shared file server situations), set the RULESOVERRIDE option of swmgr or inst to ON and then the installation will be allowed.

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

Many subsystems comprise the IRIS Performer 2.0 distribution. These subsystems are not all required for a proper installation. In fact, it is doubtful that any one developer would find more than a few of the subsystems useful on any particular project.

There are OpenGL and IRIS GL versions of the GL-specific Performer libraries -- these are the two GL-types supported by this release. There are also dynamic shared object (DSOs or ".so" files) and static linking (archive or ".a" files) versions of the Performer libraries. In addition, this release supports both optimized (compiled "-O2" for performance) and debug (compiled "-g" for full symbol table and stack trace support) versions of each library. Finally, since this release spans two machine architecture levels -- the 32-bit MIPS I/II instruction set and the 64-bit MIPS III/IV instruction set -- along with two versions of 32-bit support -- the old caller-save register management protocol known as Old-32 (O32 is used by all current IRIX 5 programs) and the newer callee-save register management protocol termed New-32 (N32) -- there are actually three versions of each library: O32, N32, and N64. The O32 versions is MIPS I and can be used with MIPS I/II executables on IRIX 5.3 or IRIX 6.1 (or later). The N32 and N64 versions are MIPS III and can be used with MIPS III/IV executables on IRIX 6.2 (or later).

This multidimensional complexity is hidden within IRIS Performer since the APIs are unchanged between the versions. The complexity only surfaces when installing software or constructing Makefiles since consistent choices must be made throughout.

Despite these issues, the subsystem naming conventions are designed to be simple and regular:

Old-32 32-bit libraries are the default and are in ".sw" subsystems. These are standard IRIX 5.3 libraries and are marked for default installation.
New-32 32-bit libraries are in ".sw32" subsystems. These are only useful on IRIX 6.2 and later operating system releases and are not enabled for installation on IRIX 5.3.
New-64 64-bit libraries are in ".sw64" subsystems. These are only useful on IRIX 6.2 and later operating system releases and are not enabled for installation on IRIX 5.3.
IRIS GL libraries have ".igl" subsubsystem name components. For best performance, use IRIS GL on RealityEngine and all previous graphics systems.
OpenGL libraries have ".ogl" subsubsystem name components. For best performance, use OpenGL on Impact and all subsequent graphics systems.
Optimized libraries are the default and have no special name. For best performance, always use the optimized Performer libraries.
Debug libraries have "debug" subsubsystem name components. You may want to use these during program development with CASE tools that work best when provided full symbol table information. Once the development stage is complete, use of the optimized libraries is strongly recommended for full performance.
Dynamic shared objects are the default and have no special name.
Static (".a") libraries have "static" subsubsystem name components. Static libraries are more amenable to performance fine tuning using tools like pixie and coord and may be desired for these reasons.

A few simple examples should make this clear:

performer_eoe.sw.igl_performer: O32, IRIS GL, Optimized, DSO
performer_dev.sw32.ogl_debug_performer: N32, OpenGL, Debug, DSO
performer_dev.sw64.debugstatic_performer: N64, OpenGL, Debug, Static (Note that this example illustrates a subtlety not mentioned in the rules above -- since only OpenGL is supported in 64-bit modes, all GL-specific 64-bit subsystems are inherently OpenGL in nature.)

IRIS Performer includes these subsystems whose names were composed following the conventions outlined above:

performer_dev.books.Perf_PG: IRIS Performer Programming Guide in IRIS InSight online documentation (book) viewer form. Use insight to read, search, or print the Programming Guide.
performer_dev.man.c: C Language Man Pages for developers. See xman Performer or man Performer for an introduction and complete C language API overview.
performer_dev.man.c++: C++ Language Man Pages for developers. See xman Performer or man Performer for an introduction and complete C++ language API overview.
performer_dev.man.common: Language-independent Man Pages for developers.
performer_dev.man.relnotes: The release notes that you are reading now.
performer_dev.src.loader: Database loader source code for the 36 different file formats directly supported by IRIS Performer.
performer_dev.src.sample: Sample applications and feature demonstrations.
performer_dev.sw.common_debug_performer: GL-independent Debug DSOs
performer_dev.sw.common_debugstatic_performer: GL-independent Debug Static Libraries
performer_dev.sw.common_static_performer: GL-independent Static Libraries
performer_dev.sw.hdr: Headers
performer_dev.sw.igl_debug_performer: IRIS GL Debug DSOs
performer_dev.sw.igl_debugstatic_performer: IRIS GL Debug Static Libraries
performer_dev.sw.igl_static_performer: IRIS GL Static Libraries
performer_dev.sw.ogl_debug_performer: OpenGL Debug DSOs
performer_dev.sw.ogl_debugstatic_performer: OpenGL Debug Static Libraries
performer_dev.sw.ogl_static_performer: OpenGL Static Libraries
performer_dev.sw32.common_debug_performer: GL-independent Debug DSOs (n32)
performer_dev.sw32.common_debugstatic_performer: GL-independent Debug Static Libraries (n32)
performer_dev.sw32.common_static_performer: GL-independent Static Libraries (n32)
performer_dev.sw32.igl_debug_performer: IRIS GL Debug DSOs (n32)
performer_dev.sw32.igl_debugstatic_performer: IRIS GL Debug Static Libraries (n32)
performer_dev.sw32.igl_static_performer: IRIS GL Static Libraries (n32)
performer_dev.sw32.ogl_debug_performer: OpenGL Debug DSOs (n32)
performer_dev.sw32.ogl_debugstatic_performer: OpenGL Debug Static Libraries (n32)
performer_dev.sw32.ogl_static_performer: OpenGL Static Libraries (n32)
performer_dev.sw64.debug_performer: Debug DSOs (n64)
performer_dev.sw64.debugstatic_performer: Debug Static Libraries (n64)
performer_dev.sw64.static_performer: Static Libraries (n64)
performer_eoe.sw.common_performer: GL-independent DSOs
performer_eoe.sw.data: Sample Data and Fonts
performer_eoe.sw.demo: Demos
performer_eoe.sw.igl_performer: IRIS GL DSOs
performer_eoe.sw.ogl_performer: OpenGL DSOs
performer_eoe.sw.performer1_2: Performer 1.2 Compatibility DSOs
performer_eoe.sw32.common_performer: GL-independent DSOs (n32)
performer_eoe.sw32.igl_performer: IRIS GL DSOs (n32)
performer_eoe.sw32.ogl_performer: OpenGL DSOs (n32)
performer_eoe.sw64.performer: DSOs (n64)
performer_friends.sw.arpa: Earth model and texture image from United States Advanced Research Projects Agency
performer_friends.sw.avalon: Avalon FTP Site
performer_friends.sw.coryphaeus: Coryphaeus database modeling tools and sample databases
performer_friends.sw.cvr: Crystal Visions of Reality architectural and site plan visualization examples
performer_friends.sw.devices: Input Devices (e.g. flybox)
performer_friends.sw.inventor: Open Inventor File Translators
performer_friends.sw.lightscape: Lightscape radiosity solution databases and images
performer_friends.sw.medit: Medit Productions modeling tools and databases
performer_friends.sw.models: Various models in many popular formats
performer_friends.sw.multigen: Multigen database modeling tools and sample databases
performer_friends.sw.paradigm: Paradigm Simulation contributed databases
performer_friends.sw.radiance: Radiance Software modeling tools and sample databases
performer_friends.sw.site: The Silicon Graphics Building #20 database
performer_friends.sw.town: The Performer Town database: models and textures
performer_friends.sw.viewpoint: Viewpoint 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 swmgr or inst to customize the list of subsystems to be installed, then select the ``go'' action.

Note: The listed subsystem sizes are approximate. Refer to the IRIS Software Installation Guide for information on finding exact sizes.

       Subsystem Name                                      Subsystem Size
                                                           (1k-byte blocks)


       performer_dev.books.Perf_PG (default)                      5947
       performer_dev.man.c (default)                              1383
       performer_dev.man.c++ (default)                            1448
       performer_dev.man.common (default)                          324
       performer_dev.man.relnotes (default)                        115
       performer_dev.src.loader                                   2197
       performer_dev.src.sample (default)                         2443
       performer_dev.sw.common_debug_performer (default)           996
       performer_dev.sw.common_debugstatic_performer              1100
       performer_dev.sw.common_static_performer                    378
       performer_dev.sw.hdr (default)                              871
       performer_dev.sw.igl_debug_performer (default)            20860
       performer_dev.sw.igl_debugstatic_performer                25528
       performer_dev.sw.igl_static_performer                      7477
       performer_dev.sw.ogl_debug_performer (default)            20866
       performer_dev.sw.ogl_debugstatic_performer                25609
       performer_dev.sw.ogl_static_performer                      7486
       performer_dev.sw32.common_debug_performer                  1631
       performer_dev.sw32.common_debugstatic_performer            1891
       performer_dev.sw32.common_static_performer                  615
       performer_dev.sw32.igl_debug_performer                    22474
       performer_dev.sw32.igl_debugstatic_performer              25689
       performer_dev.sw32.igl_static_performer                    9403
       performer_dev.sw32.ogl_debug_performer                    22589
       performer_dev.sw32.ogl_debugstatic_performer              25804
       performer_dev.sw32.ogl_static_performer                    9423
       performer_dev.sw64.debug_performer                        29629
       performer_dev.sw64.debugstatic_performer                  35539
       performer_dev.sw64.static_performer                       13246
       performer_eoe.sw.common_performer (default)                 339
       performer_eoe.sw.data (default)                           15179
       performer_eoe.sw.demo (default)                            9555
       performer_eoe.sw.igl_performer (default)                   7139
       performer_eoe.sw.ogl_performer (default)                   7149
       performer_eoe.sw.performer1_2                              2114
       performer_eoe.sw32.common_performer                         411
       performer_eoe.sw32.igl_performer                           6945
       performer_eoe.sw32.ogl_performer                           6962
       performer_eoe.sw64.performer                               8934
       performer_friends.sw.arpa                                  1770
       performer_friends.sw.avalon                               18991
       performer_friends.sw.coryphaeus                           44534
       performer_friends.sw.cvr                                  66719
       performer_friends.sw.devices                               1324
       performer_friends.sw.inventor                             10848
       performer_friends.sw.lightscape                          145486
       performer_friends.sw.medit                                37541
       performer_friends.sw.models                              106836
       performer_friends.sw.multigen                             64059
       performer_friends.sw.paradigm                             41040
       performer_friends.sw.radiance                             11688
       performer_friends.sw.site                                 10167
       performer_friends.sw.town                                 17919
       performer_friends.sw.viewpoint                            27420

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. Detailed information about both the swmgr and inst installation management tools is available through the man and xman commands.

2.4 Prerequisites

To use IRIS Performer 2.0, your system must be running IRIX 5.3 or later. To use the 64-bit MIPS III/IV extensions, you must use IRIX 6.2 or a later operating system release. In order to develop MIPS-III/IV applications you must also install the appropriate selection of N32 and N64 subsystems as listed above. Use of IRIX 6.2 is highly recommended for 64-bit OpenGL application development. IRIS Performer developers will also need a C or C++ compiler, the loader, and associated software development tools.

2.5 Compatibility

Compatibility issues with IRIX 5.3:

Applications compiled with IRIS Performer 2.0 using IRIX 5.3 will run unmodified across all SGI platforms. For best performance, use IRIS GL with RealityEngine and other pre-Impact systems and use OpenGL for Impact and post-Impact graphics hardware. OpenGL-oriented systems provide the IGLOO (Iris GL on OpenGL) portability layer to execute IRIS GL applications, but it is not the maximum performance route. Performance oriented developers are advised to generate both IRIS GL and OpenGL executables, by linking with the API-compatible IRIS Performer 2.0 IRIS GL and OpenGL libraries. In this way, you can assure optimum performance across present and future graphics systems. For OpenGL development on RealityEngine with IRIX 5.3, patch 154 (or a superseding patch) is recommended for performance and features.
Applications created with IRIS Performer 2.0 using IRIX 5.3 also run under IRIX 6.1 and later IRIX releases in 32-bit mode. The 32-bit applications created using IRIX 5.3 will not make use of 64-bit address space and other MIPS III/IV features provided by the IRIS Performer N32 and N64 development environment under IRIX 6.2 and later operating system releases.

Compatibility issues with IRIX 6.1:

Applications created with IRIS Performer 2.0 under IRIX 6.1 can be compiled and linked for 32-bit IRIX 5.3-style execution (known as Old 32-bit mode, or O32) only. IRIS Performer programs built for the two new executable types (N32 and N64) are not operable on pre-6.2 systems -- specifically, they will not run on IRIX 5.3 or 6.1 systems.
O32 IRIS Performer programs will run on IRIX 6.1. However, the OpenGL development environment of IRIX 6.1 is not as full featured as the 32-bit OpenGL of IRIX 5.3 or IRIX 6.2. This can cause both low-performance and lack-of-feature problems for developers creating OpenGL applications. For this reason, developers are advised to build only IRIS GL applications on IRIX 6.1 systems or to upgrade to IRIX 6.2 for access to its enhanced 32-bit and 64-bit OpenGL development environment.
Note that applications built on an IRIX 6.1 or 6.2 systems are not guaranteed to run properly on 5.3 systems, due to changes in structures used by system libraries. (This is true even for applications that do not use IRIS Performer-- applications built on later versions of IRIX may not run on earlier ones). Therefore to produce an O32 executable that will run on all SGI systems 5.3 and later, the compiling must be done on an IRIX 5.3 system.

Compatibility issues with IRIX 6.2:

IRIS Performer 2.0 is compatible with IRIX 6.2, and applications can be developed for all three execution modes: O32, N32, and N64. The IRIX 6.2 32-bit and 64-bit OpenGL implementations have the RealityEngine feature extensions and performance enhancements found in IRIX 5.3. For this reason, developers are urged to use IRIX 6.2 or later rather than IRIX 6.1 for OpenGL development. As mentioned above, IRIS Performer applications built in either N32 or N64 mode will not run on IRIX 5.3 or 6.1 systems, and, in general, applications should not be run on earlier versions of IRIX than the machine on which they are compiled.

2.6 Other Installation Information

IRIS Performer installs sample code, binaries, and database files in and below the following locations:

/usr/sbin: Compiled versions of perfly the sample database viewer. Both IRIS GL (perfly_igl) and OpenGL (perfly_ogl) versions are installed, and a soft link (named perfly) is made to the preferred version based on system graphics hardware type. Type "perfly -h" for help with perfly.
/usr/lib: Compiled versions of the database loading and utility libraries. It is these libraries that are dynamically loaded and which must be accessible for Performer 2.0 applications to successfully execute.
/usr/include/Performer: Header files for software developers.
/usr/share/Performer/src: Sample programs, automatic porting scripts for 1.2 to 2.0 conversion, database import/export tools, and utility library source code.
/usr/share/Performer/data: Database files and textures
/usr/share/Performer/friends: Friends of Performer sample databases and applications from many developers and tool providers.

3. IRIS Performer Source Code

IRIS Performer 2.0 includes a considerable archive of source code -- 246 files containing 125730 lines -- more than 3 megabytes in total. Shipped examples include file loaders for 36 different file formats, demonstration programs from which Programming Guide examples have been extracted, and the complete source for perfly, the general framework from which many IRIS Performer visual simulation applications have been built. Included in the distribution are several important Performer libraries that are provided in source code to encourage changes and enhancement:

libpfdu - The database utility library with support for easy dynamic loading of DSOs, triangle meshing, attribute sharing, concave polygon decomposition, scene graph optimization, and other geometric and file-processing tasks.
libpfui - The user interface library which provides an extensible framework for 3D manipulator specification, and provides the trackball, drive, and fly models used in the perfly program.
libpfutil - The general utility library provides both useful features and examples of programming with IRIS Performer.

Porting and conversion tools are also provided to ease the effort of moving existing IRIS Performer 1.2 source code to the extended API of the Performer 2.0 release.

You are encouraged to understand and modify this code for your own purposes subject to the terms and conditions of the Software License Agreement and the Copyright notices included in each file.

3.1 IRIS Performer Makefile Conventions

The Makefiles shipped with IRIS Performer source code follow certain general conventions. The symbol PFGLTYPE can be defined on the make command line to have values "IRISGL" or "OPENGL" to specify IRIS GL and OpenGL compilation respectively. The symbol PFSTYLE can be defined with one of the three values "32", "N32", or "64" to select one of the three (O32, N32, N64) architecture and calling convention choices described in Chapter 2 of these release notes. The make targets for the different versions of the libraries or executables include:

dso: optimized dynamic shared object
ddso: debug dynamic shared object
opt: optimized static
dbg: debug static

Object files are placed into directories with names constructed from DBG/OPT, O32/N32/O64, and IGL/OGL according to compile mode and library names indicate their static/dynamic nature. For example, libpfutil_igl-g.a, libpfutil_igl.a, libpfutil_igl.so, and libpfutil_igl-g.so are the results of the dbg, opt, dso, and ddso make targets for PFGLTYPE=IRISGL. Executables are given a single name but are a soft link into the appropriate DBG/OPT, O32/N32/O64, and IGL/OGL directory name. For example, perfly may be a link to OPT.O32.OPENGL. Makefiles look for libraries first in /usr/share/Performer/lib and then in /usr/lib/performer. In order to link with a custom library built in /usr/share/Performer/lib, the makefiles must be modified.

3.2 Database Loaders

A database loader can either load a particular on-disk database format into IRIS Performer run-time data structures, write Performer data structures out in a particular format, perform a memory-to-memory translation of formatted databases, or provide a combination of these capabilities. Loaders are provided for several Silicon Graphics data formats (bin, gfo, im, iv, phd, ptu, and sgo) as well as many popular formats including Autodesk's dxf and 3ds, Coryphaeus' dwb, Medit's medit, Software Systems flt, and Wavefront's obj.

3.2.1 libpfdb Database Loaders

libpfdb is a collection of independent libraries (one for each supported file format) that read or write a particular scene description file format. These loaders are implemented using the IRIX Dynamic Shared Object facility and are demand loaded as needed. The file loaders provided with IRIS Performer 2.0 include:

3ds: AutoDesk 3DStudio binary data
bin: Minor SGI format used by powerflip
bpoly: Side Effects Software PRISMS binary
byu: Brigham Young University CAD/FEA data
dwb: Coryphaeus Software Designer's Workbench
dxf: AutoDesk AutoCAD ASCII format
flt11: MultiGen public domain Flight v11 format
flt14: MultiGen OpenFlight v14 format
gds: McDonnell-Douglas GDS things data
gfo: Minor SGI format (radiosity output)
im: Minor SGI format (IRIS Performer example)
irtp: AAI/Graphicon Interactive Real-Time PHIGS
iv: SGI OpenInventor / VRML 1.0
lsa: Lightscape radiosity solutions (ASCII)
lsb: Lightscape radiosity solutions (binary)
m: University of Washington mesh data
medit: Medit Productions medit modeling tool
nff: Eric Haines' ray tracing test data format
obj: Wavefront Technologies data format
post: Minor SGI format (example gridded terrain loader)
phd: Minor SGI format (polyhedra)
poly: Side Effects Software PRISMS ASCII data
pts: University of Washington point data
ptu: Minor SGI format (IRIS Performer example)
s1k: US ARMY SIMNET databases (Texas Instruments)
sgf: US NAVY standard graphics format
sgo: Minor SGI format
spf: US NAVY simple polygon format
sponge: Sierpinski sponge 3D fractal generator
star: Yale University compact star chart data
stla: 3D Structures Stereolithography (ASCII)
stlb: 3D Structures Stereolithography (binary)
sv: Format of John Kichury's i3dm modeler
tri: University of Minnesota Geometry Center data
unc: University of North Carolina data

Source code for many of these loaders is provided in the directory /usr/share/Performer/src/libpfdb.

3.3 Programming Guide Source Code

The complete text of the programming examples referenced in the IRIS Performer Programming Guide is located in the directory /usr/share/Performer/src/pguide/. Source code is organized first by library, libpr, libpf, libpfui, libpfutil, then by language, either C or C++, 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/share/Performer/src/sample/ contains the perfly sample application in the perfly directory as well as a number of files that are common between perfly-like applications 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, the files common/main.c and common/generic.c (or common/main.C and common/generic.C in the C++ version) illustrate the main framework of an IRIS Performer application so we encourage you to examine these files.

perfly is a fairly complex program that exercises many IRIS Performer features and so 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.

3.5 Utility Library

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

3.6 Tools

/usr/share/Performer/src/tools/ contains software tools that ease the transition of applications from IRIS Performer 1.2 to the 2.0 release as well as tools of general utility.

port2.0 is a script that converts files written for version 1.2 into files that will work with version 2.0. The new files are suffixed with pf2.0 and include comments added by port2.0 that direct your attention to portions of code that could not be automatically 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.

4.1 General Issues

When building static OpenGL executables in IRIX 5.3 installed it may be necessary to specify the "-ignore_unresolved" option to ld since not all OpenGL extensions used in Performer are available on all platforms and OS versions. You may see warnings for the unresolved symbols of OpenGL extensions that are not present on the current system, but the executable will still successfully link.
When building executables on IRIX 6.2 and linking directly using ld rather than implicitly via CC, an alarming number of warnings about tables that are defined in multiple .so's may be printed. These are harmless but the appropriate compiler option to disable the warning has not yet been identified. The problem does not occur when linking with CC, which is identical in function and serves as an effective workaround.
When moving a window on Extreme graphics under IRIX 5.3 in some clear modes the Z-buffer may not be updated properly until a full czclear() operation is performed.
When more than 512 textures are used in either IRIS GL or OpenGL the hardware and or host-side software may become confused and in some cases, may falter completely and terminate the application. This is a graphics library limitation.
IRIS GL based Performer 2.0 executables may encounter difficulties when executing multipipe on dual-head Indigo systems. This problem is not present in OpenGL applications. Check with SGI Customer Support for the latest advice if you encounter this problem and need to use IRIS GL rather than OpenGL.
The video rate used by IRIS Performer for frame rate control is computed at application startup on some machines and is not always exactly correct. If this is a problem, the video rate can be set with pfVideoRate.
Dynamic resizing of pfPipeWindows when multi-processed and using X windows (IRIS GLX or OpenGL/X) when an alternate framebuffer configuration window is selected (such as the fill statistics window in OpenGL/X perfly) can cause channel viewports to be confused when the alternate framebuffer configuration window is de-selected (such as disabling the fill statistics in perfly when running with X windows).
pfApplyFrust() does not properly apply a frustum which has been transformed with pfOrthoXformFrust(). Instead, the canonical frustum whose eye is at the origin and is looking down the +Y axis, is applied.
pfFlatten() is broken for pfGeoSets with pfCycleBuffer attribute arrays. A core dump is likely.
The PFSTATE_LIGHTS sorting key for the PFSORT_BY_STATE mode of pfChanBinSort() is not yet implemented.
Although Performer supports it, OpenGL does not support different material color modes for front and back materials. When Performer encounters this case, it disables the material color mode for the back material.

4.2 IRIX6 and 64Bit

Statistics: The PFSTATSHW_CPU pfStats statistics class for accumulation of statistics on CPU usage are not yet implemented for IRIX6 operation (64bit or 32bit).
pfdLoadFile_flt: The FLT loader under 64bit operation may core dump.
hello sample program: The src/pguide/libpf/C/hello sample program may core dump under 64bit operation.
Forked X input handling: On beta versions of 6.2 some problems were experienced with handling X input in an additional forked process. For this reason, the perfly sample application has a conditional compilation construct to use the non-forked X input handling option of the libpfutil X input handling utilities when compiled under IRIX6. You may find this to not be necessary.

4.3 libpr

Antialiasing: When it is not multisampling, pfAntialias can significantly degrade performance. Specifically, on non-RealityEngine systems, use pfAntialias only for lines and points.
Coplanar polygons: pfDecal works only on machines that support the stencil or displacepolygon command. The default decaling mode for PFDECAL_BASE 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 to use stencil then specify the PFDECAL_BASE_HIGH_QUALITY token.
Stencil: stencil is used for PFDECAL_BASE_HIGH_QUALITY and for pfStats mode PFSTATSHW_GFXPIPE_FILL. Stencil is not supported on all graphics platforms. Indy graphics platforms under IRIS GL operation do not support stencil. The Extreme graphics platforms support stencil with reduced depth buffer resolution so IRIS Performer will not allocate stencil bits in the default framebuffer configuration. While allocated by default, the allocation of extra stencil bits can also affect your depth resolution and number of samples for multisample on RealityEngine graphics platforms.
Transparency: pfTransparency works only on machines that support either blendfunction or multisample (RealityEngine).
pfLPointState: pfLPointStates offer advanced features for the sophisticated light point primitive for visual simulation applications. Some of the texturing modes may not be supported or currently working on mid-range or low-end graphics platforms.
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, Extreme, and Impact 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.
pfInitClock() on 250MHz IMPACT: The clock period determined by pfInitClock() on 250MHz IMPACT systems is apparently inconsistent with the true clock period. It seems that the actual clock period is that of a 200MHz system. Consequently, pfGetTime() will return a time that is .8 (200/250) that of the true time. As a workaround, you can specify an alternate clock period with the PFCLOCKPERIOD environment variable. If set, PFCLOCKPERIOD specifies the clock period, in picoseconds, to be used by pfInitClock(). For proper behavior on 250MHz IMPACT systems, use 40000 for the period.
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 utility code 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-<machinename>
% touch ~/.desktop-<machinename>/nodesktop
and for total removal do:
% chkconfig desktop off
% chkconfig objectserver off
% chkconfig directoryserver off
% chkconfig fontserver off

4.4 libpf

Intersection testing of line segments (pfNodeIsectSegs) against geometry in pfBillboard nodes is not yet implemented; only the bounding sphere of the entire pfBillboard is available.
Channel fade LOD attributes and mixed graphics configurations: Channel fade LOD attributes are set in the application process. The existence of multisample,required for fade LOD, is tested at the time that the attributes are set with pfChanLODAttr. This test for multisample uses the application process window system connection (pfOpenWSConnection) or else the DISPLAY environment variable to select a screen for determining graphics configuration, instead of testing the current window of the pfChannel. In a multipipe environment where one graphics pipeline has multisample and one does not, the application process needs to have a window system connection or DISPLAY that points to the pipeline with multisample, in which case the non-multisample pfChannels will try to use fade LOD. In a multi-window environment, windows without multisample on a system with multisample will try to use fade LOD.
Gangdraw and cursor loading: Loading the cursor with ganged swapbuffers (external swapready wire) hangs graphics. Workaround: don't load the cursor and use a full screen window when using ganged swapbuffers.
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 was standard on Crimson and later 4D/300 and 4D/400 machines. You can check for it with the hinv(1M) command.)
On older 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). On these machines, you may want to enable fast timers using systune(1M) to set the fasthz variable. See the man page for timers for more information. Frame rate control is poor on machines that lack both a fast clock and the video clock used by pfVClockSync.

4.5 libpfutil

No known problems.

4.6 libpfui

Libpfui has both a C API and a C++ API. The C API is actually wrappers around the C++ API and is not complete.

4.7 libpfdb

pfdLoadFile_dxf: The DXF loader does not fully support the format.
pfdLoadFile_sgo: The SGO loader does not support triangle strips.

4.8 Sample Programs

perfly on Indy under IRIS GL: the background of the GUI panel is influenced by the loaded database. Additionally, fill statistics are not supported on Indy under IRIS GL and will cause flashing and error messages to stderr.
pguide/libpf/C/pipewin: The overlay text is only drawn in IRIS GL and does not get properly redrawn wih the window size is changed.
pguide/libpf/C/lpsatate: The lpstate.c example for demonstrating pfLPointStates uses sophisticated texturing capabilities that may not yet work on the IMPACT, Extreme, or Indy graphics platforms.

4.9 Friends of Performer

No known problems.

4.10 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 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 known problems with the documentation.

5.1 IRIS Performer Release Notes

There may be minor differences between the inst-image sizes listed in Chapter 2 and those reported by swmgr or inst.

5.2 IRIS Performer C Language Reference Pages

No known errors.

5.3 IRIS Performer C++ Language Reference Pages

No known errors.

5.4 IRIS Performer Programming Guide

Figure 2-2 incorrectly indicates the names of several database loaders, showing a dash where an underscore should be used. For example, "pfdLoadFile_medit()" appears as "pfdLoadFile-medit()" in the drawing.
Several of the color images in the Programming Guide are displayed poorly from within the IRIS Insight on-line documentation (book) viewer. The images can be saved and viewed using standard image tools to appreciate their proper color and shading if desired.

6. Differences Between 2.0 and previous releases

This chapter elucidates the changes and enhancements between IRIS Performer 2.0 and the previous 1.2 release. If you are new to IRIS Performer you can skip this chapter, since the information contained here is provided to ease porting efforts, and the new features are described in the the IRIS Performer Programming Guide.

6.1 New Features

6.1.1 Support for OpenGL

Performer 2.0 includes separate sets of libraries for supporting IRIS GL or OpenGL interfaces. These libraries have GL-dependent suffixes to indicate their type: IRIS GL=_igl and OpenGL=_ogl

: IRIS GL: libpf_igl.so; OpenGL: libpf_ogl.so

Porting an IRIS Performer application from IRIS GL to OpenGL should require very little work. There are a couple of isolated routine changes (see API changes below). The main work will be in porting an application IRIS GL code in user draw callbacks and in porting the windowing and event handling to X. For porting windowing code, pfWindows and pfPipeWindows (libpr and libpf, respectively) provide a GL independent windowing environment. Libpfutil provides GL- input handling utilities for libpf applications using pfPipeWindows (pfuInitInput()). The sample programs installed in

: /usr/share/Performer/src/pguide/{libpr,libpf}/progs

also demonstrate comparative X vs GL input handling.

When compiling for IRIS GL, use '-DIRISGL' on the command line to include the IRIS GL versions of the Performer header files.

6.1.2 64-bit address space support

6.1.3 Performer Environment Variables and DSOs

Performer now robustly supports the notion of separate run-time file loaders as DSO's (Dynamic Shared Objects). Thus, the generic utility method for opening a file now differs considerably - the extension of the filename is used to determine the name of shared object to load as well as the function within that shared library to call. Two new environment variables exist to help locate these dynamic shared object libraries at run-time:

PFLD_LIBRARY_PATH Specifies a colon separated list of directories where Performer should look for dynamic objects...
PFHOME Specifies the root Performer directory (the root used to install Performer). This is used such that various code in the libraries can look relative to this top level such as $PFHOME/usr/lib/libpfdb might be a location where dso's would live. In this way a consistent tree structure might be maintained regardless of Performers PFHOME directory. (This is useful when using Performer installed on another automounted machine for instance - setenv PFHOME /hosts/remote_machine/)

6.1.4 C++ API

When compiling programs using Performer's C++ API, you need to directly include the class header files from

: /usr/include/Performer/pr; and; /usr/include/Performer/pf.

6.1.5 Compiling Performer 1.2 C++ applications with Performer 2.0

With Performer 2.0, compiling a Performer application with the C++ compiler enables the use of C++ classes for Performer types. Some of these Performer types (pfMatrix, pfVec2, pfVec3, pfVec4, pfQuat) are typedefed arrays when compiling with C and classes when compiling with C++. Because typedefed arrays and classes differ in their usage, Performer applications written C++ using Performer 1.2's C API may not compile under C++ unless Performer is told to revert to C types when compiling under C++.

If you wish to compile existing C++ code using Performer C types add the line

: '#define PF_CPLUSPLUS_API 0'

before including any Performer header files. Note that the use of C types precludes the use of Performer's C++ API.

6.1.6 Mixing C++ API and C API in a Single Application

Normally, when compiling under C++, the C API routines corresponding to member functions on a class are not exposed in the header files. Applications wishing to taste the combined smorgasboard of both APIs should add the line

: '#define PF_C_API 1

before including any Performer header files.

6.2 LIBPR Enhancements

6.2.1 pfGeoSet

PFGS_POLYS for N-sided, convex polygons. Specify the number of sides of each polygon with pfGSetPrimLengths().

pfGSetPassFilter() sets a filter which allows only specific pfGeoSets to be drawn, e.g., a

: PFGS_NONTEX_GSET | PFGS_EMISSIVE_GSET

filter will draw only non-textured, emissive pfGeoSets.

pfGetGSetAttrRange() returns the number of attributes (e.g., coordinates) accessed by non-indexed a pfGeoSet and the maximum range of indexes if the pfGeoSet is indexed.

pfGeoSets can now index their pfGeoStates through a global table set by pfApplyGStateTable(). pfGSetGStateIndex() sets the value which is used to index the global table. Indexed pfGeoStates in conjunction with different pfGeoState tables allow drastically different appearances of a single database without duplicating geometry or the scene graph. For example, a visual and infrared version of a database is easily supported with 2 different pfGeoState tables.

pfGeoSets now accept pfCycleBuffer* as attribute lists to support dynamic attribute changes in a pipelined, multiprocessing environment. pfCycleBuffers automatically manage multiple data buffers to avoid data collisions and ensure frame-accurate behavior of attribute changes. This greatly simplifies modification of coordinates for sophisticated facial and skeletal animation, geometrically morphed level-of-detail, and special effects such as explosions.

6.2.2 pfGeoState

pfGStateFuncs() allow pre and post callbacks on a per- pfGeoState basis. The pre callback is invoked after the GL has been configured with the pfGeoState's state and the post callback is lazily invoked by the next pfGeoState application so the pre/post callbacks nicely bracket pfDrawGSet().

pfGStateVal() is added for floating point values and now accepts PFSTATE_ALPHAREF.

pfGeoSets can now index pfGeoStates (pfGSetGStateIndex()) through pfGeoState global tables (pfApplyGStateTable()) or pfGeoState tables assigned to a pfChannel (pfChanGStateTable()) .

6.2.3 pfFog

pfGetFogDensity returns the density of a pfFog at a given range.

6.2.4 pfLPointState

A new PFSTATE attribute, pfLPointState causes pfGeoSets of type PFGS_POINTS to be rendered as "light points", e.g., runway lights, stars. Light points have perspective size based on range and many other features. This is a major enhancement and is discussed in great detail in the pfLPointState man page.

6.2.5 pfSprite

A new kind of transform, pfSprite automatically rotates pfGeoSets and plain GL geometry to face the viewer. Different rotational constraints are possible including: rotate about an axis, rotate about a point.

6.2.6 pfTexGen

A new PFSTATE attribute, pfTexGen encapsulates the GL's texgen() feature which automatically generates texture coordinates. The Wavefront OBJ file loader in libpfdb provides an example of the use of this new capability. Refer to that source code for usage examples.

6.2.7 pfTransparency

pfTransparency now supports PFTR_MS_ALPHA_MASK which enables multisample transparency but also writes the true alpha value into the frame buffer instead of fully opaque alpha values as PFTR_MS_ALPHA does.

6.2.8 pfDecal

When using DISPLACE type decals, LAYERS are no longer required to be rendered immediately after their BASES - they can be drawn in any order. This introduces new LAYER- specific tokens: PFDECAL_LAYER_FAST, PFDECAL_LAYER_DISPLACE and requires specific identification of all layers after the first since each layer must be displaced slightly more than its predecessor. The tokens PFDECAL_LAYER_1 -> PFDECAL_LAYER_7 are provided for layer identification.

6.2.9 pfCycleBuffer/pfCycleMemory

A new kind of pfMemory, pfCycleBuffer supports changing data in a pipelined, multiprocessing environment while maintaining data exclusion and frame-accurate behavior. A pfCycleBuffer manages a set of buffers called pfCycleMemorys and "rotates" them each frame, advancing the data modifications cleanly down the processing pipeline. libpf transparently handles the buffer rotations.

6.2.10 pfPolytope

A pfPolytope is a set of N half spaces whose intersection defines a possibly semi-infinite, convex volume which is useful for culling and intersection testing where a tighter bound than a pfSphere, pfBox, pfCylinder, pfFrustum is of benefit.

6.2.11 pfGLOverride

Adds the ability to force the use of a particular GL mechanism to implement a libpr feature.

6.2.12 pfNotify

pfNotify has been enhanced with new formatting and modes (PFNFY_MORE). Refer to the pfNotify man page for full details.

6.2.13 pfGetTime

New functions. Refer to the reference pages for further information.

: pfWrapClock; pfClockName; pfClockMode

6.2.14 Window System Routines

New window-system interface functions provide a single API for creating and managing windows that works across the IRIS GL, IRIS GLX Mixed Mode, and OpenGL-X environments. Window system independent types have been provided to match the X Window System types to provide complete portability between the IRIS GL and OpenGL-X windowing environments.

6.2.15 pfQueryFeature/pfQuerySys

New QueryFeature routines determine the presence, absence, or limitations of features in the underlying graphics implementation, like the availability of attenuation in the lighting model or the availability of multiple graphics pipes.

The QuerySys routines determine the capacity and limitations of the underlying graphics implementation, like the size of texture memory or the number of stencil planes available.

6.2.16 pfTexture extensions

6.2.17 Integrated Text Support

Two and Three dimensional font rendering is supported by the new pfFont (libpr), pfString (libpr), and pfText (libpf) primitives.

The pfFont facility provides the capability to load fonts for 3-D rendering with the string drawing routines from pfString and pfText. IRIS Performer uses this facility to provide flat, extruded, and textured-quad fonts in three dimensions.

pfString provides a pfGeoSet like facility for encapsulating geometry to display a string in 3-D with attributes such as color, arbitrary transformation matrix, and font (see pfFont).

A pfText node is a list of pfStrings much as a pfGeode is a list of pfGeoSets. The two APIs are also similar - a new pfText node can be created and the list of pfStrings attached to it can be manipulated by addition, insertion, removal or replacement.

The best examples of these new font tools at present are hello.c and helloC.C, both provided in the IRIS Performer source directory.

6.2.18 pfQuat

A full set of quaternion utilities is defined in prmath.h and is documented in the pfQuat man page.

6.3 LIBPF Enhancements

6.3.1 Multiple Windows on a single pfPipe

Multiple windows can now be rendered from a single pfPipe. This allows a single drawing process to render to multiple windows on a single screen. Libpf now requires use of the pfPipeWindow primitive for opening windows for pfPipes. See the pfWindow and pfPipeWindow (pfConfigPWin()) reference pages for details.

6.3.2 pfMorph

pfMorph is a new group node intended for automatic morphing of pfGeoSet attributes: colors, normals, coordinates, and texture coordinates but which can morph any floating point values. pfMorph is triggered during the new APP traversal and linearly combines N source arrays into a single destination which is typically a pfCycleBuffer used as a pfGeoSet attribute array. By modifying the source weights each frame, the application can produce sophisticated, frame-accurate effects such as facial and skeletal animation and morphed, geometric level-of-detail.

6.3.3 pfDBase

The DBASE process is a new addition to the IRIS Performer multiprocessing family. It is similar to the ISECT process in that it can run asynchronously with respect to the main processing pipeline (APP->CULL->DRAW). Callback and trigger functions, pfDBaseFunc() and pfDBase() respectively, allow explicit control and customization of the DBASE function. The DBASE is intended for asynchronous database processing, particularly paging to and from disk when using large databases. Note that IRIS Performer does not provide a paging facility directly - rather it provides the tools which the application can use to implement database paging. Database deletions are carried out in pfDBase() and do not slow down the synchronous pipeline if DBASE is configured as a separate process.

6.3.4 pfBuffer

pfBuffer is the primary tool for asynchronous database manipulations. A pfBuffer isolates database changes to a given process, avoiding dangerous data collisions with other processes when multiprocessing. Scene graphs built in an asynchronous process, such as the DBASE, do not affect the synchronous, real-time APP->CULL->DRAW pipeline and are quickly and safely merged into the main processing stream with pfMergeBuffer().

6.3.5 pfMultithread

pfMultithread adds a new multiprocessing dimension by multithreading a given IRIS Performer processing stage. Currently, only the CULL stage may be multithreaded such that thread culls a pfChannel. This is expected to be very useful for MCO applications where many pfChannels per pipe cause the CULL stage to become a bottleneck.

6.3.6 PFTRAV_APP

PFTRAV_APP is a new automated IRIS Performer traversal intended for behavior computation, event distribution and other application level functions. It is carried out in the APP process and is initiated directly by pfAppFrame() or automatically by pfSync(). A wrapper callback and callback data (pfAppFunc(), pfPassAppData()) and node callbacks and data (pfNodeTravFuncs(), pfNodeTravData()) provide application extensibility similar to that offered for the CULL, DRAW, and ISECT traversals.

6.3.7 pfChanData

pfChannel passthrough data may be supplied by the application with pfChanData() rather than allocated by the pfChannel with pfAllocChanData(). This allows pfChannels to share a single passthrough data block.

6.3.8 pfChanCullPtope

pfChanCullPtope() specifies that a pfChannel use a pfPolytope, rather than its viewing pfFrustum, for culling. This allows highly customized culling for specific environments where visibility can be predetermined to some extent, e.g., when in a room and looking through a door the cull volume can be shrunk to the door opening.

6.3.9 pfChanNodeIsectSegs

pfChanNodeIsectSegs() is identical to pfNodeIsectSegs() but includes a pfChannel to evaluate pfLODs during the intersection traversal. Thus, pfChanNodeIsectSegs() computes intersections with the same level-of-detail as is selected for rendering. This greatly simplifies operations such as terrain following on terrain which is modeled as levels-of-detail.

6.3.10 pfChanGStateTable

pfChannels can provide a pfGeoState table which is accessed by indexed pfGeoSets. This simplifies the management of multiple views of a single database, such as infrared vs. out-the-window.

6.3.11 pfVideoRate

In release 1.2, IRIS Performer internally computed the rate of the video clock. In 2.0, IRIS Performer now queries the video microcode for the video retrace rate or accepts the rate set by the application with pfVideoRate().

6.3.12 pfConfigStage

pfStageConfigFunc() allows the specification of an initialization callback for each IRIS Performer processing stage. pfConfigStage() invokes specified initialization callbacks in the appropriate processes at the next pfFrame(). Initialization callbacks typically establish the inital conditions of a process. Examples include setting non-degrading priorities and locking processes to CPUs for real-time applications and downloading textures in the DRAW stage.

6.3.13 pfLookupNode

pfLookupNode() extends pfFindNode by searching for a path- named node of a particular type, beginning at a specific node. This greatly simplifies finding named parts of a pfCloned subgraph.

6.3.14 pfSceneGState

pfScenes can now reference a pfGeoState that defines the "global state" which may be inherited by other pfGeoStates within the scene.

6.3.15 pfGetSCSMatPtr and pfGetDCSMatPtr

pfGetDCSMatPtr() returns a pointer to the pfDCS matrix for fast access. Likewise, pfGetSCSMatPtr() returns a pointer to the pfSCS matrix.

6.3.16 New GL-independent Windowing Utilities

IRIS Performer now provides utilities for opening, closing, and managing windows. The same routines will manage pure IRIS GL windows, IRIS GL-X Mixed-Mode, and OpenGL-X windows. Libpf application will now use the new pfPipeWindow for opening IRIS Performer windows. See the pfWindow (libpr) and pfPipeWindow (libpf) (pfConfigPWin()) reference pages for details.

6.3.17 API Changes

pfSelectCtab() is now pfApplyCtab()
pfGetMallocSize() is now pfGetSize()
pfGetHyperId() is now pfGetPipeHyperId()

6.3.18 Reference Counting

All pfObjects, including pfNodes now have a reference count. A pfGroup increments the reference count of all its children.

6.3.19 Mode Query Semantics

pfGetGStateAttr/Mode do not return the global values of inherited state elements. Instead NULL and -1 are returned. Use pfGetCurGStateAttr/Mode for 1.2 behavior.

6.3.20 Video Clock

pfInitVClock() no longer starts and stops the video clock. Instead, use pfStart/StopVClock() to start and stop video interrupts. pfStart/StopVClock are only necessary for VGX/VGXT graphics and are ignored on other graphics.

6.3.21 pfPipeScreen

Proper multipipe operation now requires that pipes be assigned a screen (pfPipeScreen) before the first pfFrame(). Otherwise, pipes will be automatically assigned a screen.

6.3.22 pfEvaluateLOD

pfEvaluateLOD() returns a floating point number indicating which child is selected by a given pfChannel. The fractional portion of the number is used for fading transitions.

6.3.23 pfLODState

pfLODStates are used to specify how individual LOD's or groups of LODs will respond to stress and range. pfLODStates can either be explicitly set per LOD or set as an index into a list of pfLODStates provided to a pfChannel. Thus pfLODStates can make the same pfLOD behave differently in different channels as well as differently under different stress conditions. pfLODStates ultimately modify the range and fade transition calculations made by performer when culling. See pfLODState, pfLOD, and pfChannel.

6.3.24 pfLOD enhancements

pfLODs now support per-pair transition zones for fade LOD See the pfLODTransition reference page.

pfLODs now respond to stress by scaling LOD ranges and transition zones and take a pfLODState structure to describe the desired stress behavior of a pfLOD. See the pfLODState reference page.

LOD Priority Classes can be formed by the sharing of pfLODState structures across a set of LODs.

Per-Channel LOD Priority Classes can be formed by assigning pfChannels with tables of pfLODStates and assigning pfLODs an index into these tables. See the pfChanLODAttr and pfLODLODStateIndex reference pages.

6.4 libpfdu Enhancements

6.4.1 Optimizing Scene Builder for use in File Loaders

Performer 2.0 contains a new layer of support for easily converting databases from external formats into performer runtime structures. This new layer is called libpfdu which stands for library of performer database utilities. The pfdBuilder contains mechanisms for completely converting external database formats and data into efficient IRIS performer structures. The builder will take care of state sharing and sort your geometry by state. Collections of graphics state and geometry are given to the pfdBuilder as a database is read in. At the end of reading a database file, a pfNode containing an efficient Performer representation of the database can be obtained. This new API supersedes the previous pfuBuilder which was a simple interface for encapsulating geometric data into performer structures in an intuitive way. This new layer of support is built on top of and is a superset of the previous pfuBuilder (which has now become the pfdGeoBuilder) that was released with Performer1.2. Check out

/usr/include/Performer/pfdu.h

for mode settings and api for the new extended builder.

libpfdu is the Performer library of database utilities. Its purpose is to provide helpful functions for constructing optimized Performer data structures and scene graphs. It is used mainly by database loaders which take an external file format containing 3d geometry and graphics state and load them into Performer optimized run-time only structures. Note that these utilities often prove very useful as most modeling tools and file formats represent their data in structures that correspond to the way users model data and these data structures are often necessarily mutually exclusive with effective and efficient Performer run-time structures. libpfdu contains many utilities including dso support for database loaders and their modes, file path support, etc, but the heart of libpfdu is the notion of the Performer database 'builder' - pfdBuilder.

The builder is a tool to allow users to input/output a collection of geometry and graphics state in immediate mode fashion (similar to Open/Iris GL). Data is inputed to the builder one geometric primitive at a time along with its corresponding graphics state. When all of the data has been inputed, the user simply requests optimized Performer data structures which can then be used as a part of a Performer Scene Graph. The builder hashs geometry into different 'bins' based on the geometry's attribute binding types and associated graphics state. It also keeps track of graphics state elements (textures,materials,light models, fog,etc) and shares state elements whenever possible. In the end, the builder will create Performer 'pfGeoSets' that contain triangle meshes created by running the original geometry through the libpfdu tmeshing utility. To go along with each pfGeoSet, the builder builds up a Performer pfGeoState (Performer's encapsulated state primitive) which has been optimized to share as many attributes as possible with other pfGeoStates being build (and possibly even with a more global pfChannelGState). Having created all of these Performer primitives (pfGeoSets and pfGeoStates) the builder will place them in a Performer leaf node (pfGeode), and possibly even artificially create a spatial hierarchy by running the new database through a spatial breakup utility function which is also contained in libpfdu. Note that this builder should also allow the user to extend the notion of a 'graphics state' by registering callback functionality through builder api and then treating this state/functionality like any other Performer state/mode (although such uses of the builder are of course at least slightly more complicated).

In short libpfdu is a collection of utilities that effectively act as a data funnel where users input flattened 3d graphics information and are given in return fully functional and hopefully well optimized Performer run-time structures.

6.5 libpfdb Enhancements

6.5.1 New File Formats

OpenInventor 2.0 file support. This is a completely new loader that uses OpenInventor traversal of the input scene graph to create the Performer scene graph, allowing robust conversion of all geometry.
AutoDesk 3DStudio file support using the 3dsftk.
Side Effects Software Prisms (.poly and .bpoly) file support.
Medit Productions Medit (.medit) file support
S1000 file support, based on code from Texas Instruments.
Several other formats. Look in libpfdb for the complete list.

6.6 Structural Changes

6.6.1 Class structure

One of the major differences from 1.2 is that libpr is now written in C++ and the class tree has changed. 1.2 had both a prObject and pfObject - now there is a single pfObject which is derived from IRIS Performer's base class, pfMemory. There are no more pr-prefixed routines which were used for libpr->libpf inheritance, e.g, pfLight -> pfLightSource.

6.6.2 pfType

IRIS Performer has changed its type system to support new, application-derived types. pfGetType() now returns a pfType* instead of a bitmask. Each IRIS Performer data type which has an explicit allocator (usually pfNew*()) has an associated pfType which is created at initialization time by pfInit(). The pfType corresponding to a particular class is returned by pfGet<*>ClassType(), e.g.,

pfGetGroupClassType(). The primary difference in 2.0 is the fact that types are no longer represented with bitmasks where the inheritance chain of a particular type is encoded in the bitmask, e.g., PFTYPE_SCS == (100 | PFCLASS_SCS | PFCLASS_GROUP | PFCLASS_NODE), indicating that SCS is derived from pfGroup and pfNode. pfType is an opaque data structure whose inheritance chain must be queried through pfIsOfType().

Here are the old and new methods for testing an object for exact type equality. The 1.2 method:

: if (pfGetType(node) == PFTYPE_SCS)

and the 2.0 methods, which are equivalent

: if (pfGetType(node) == pfGetSCSClassType()); if (pfIsExactType(node, pfGetSCSClassType()))

Here are the old and new methods for testing an object for derivation from a give type. The 1.2 method:

: if (pfGetType(node) & PFCLASS_GROUP)

and the 2.0 method

: if (pfIsOfType(node, pfGetGroupClassType()))

Special care should be taken when porting to the new type API.

6.7 Changes in libpr

6.7.1 Default Enables

PFEN_TEXTURE, PFEN_LIGHTING, PFEN_FOG are no longer enabled by default. Databases created with loaders that assumed specific global defaults, e.g., pfEnable(PFEN_TEXTURE) will be rendered improperly. All IRIS Performer loaders shipped with 2.0 create pfGeoStates that assume the global default is the same as that set by pfBasicState(), i.e., everything is OFF.

6.7.2 Line Width and Point Size

pfGeoSets with linewidth/pointsize of <= 0 will not set linewidth or pointsize but will inherit it through the GL.

6.7.3 Alpha Reference Value

The PFSTATE_ALPHAREF state element has changed from an integer in the range 0-255 to a float in the range 0-1 and is now set on pfGeoStates with the new routine, pfGStateVal. A warning will be generated if set through pfGStateMode.

6.7.4 Decal Implementation

pfDecal no longer sets zwritemask to 0 when drawing displaced layers. This allows layers to be drawn separately from their bases, enabling improved sorting by graphics mode.

6.7.5 Math Functions

pfXformPt3/Vec3 previously considered the last column of the matrix and divided by the homogeneous coordinate, w. The new pfXformPt3/Vec3 are much faster and treats the pfMatrix as a 4x3 matrix. The old behavior is now accessed through the new pfFullXformPt3/Vec3 routines.

pfInvertMat is now named pfInvertFullMat but a #define ensures 1.2 compatibility.

pfMakeRotOntoMat is obsoleted in favor of the much faster pfMakeVecRotVecMat which assumes normalized input vectors.

6.7.6 Frustum Specification

pfFrustAspect is no longer persistent. In 1.2, automatic frustum calculation (e.g. PFFRUST_CALC_HORIZ) was always in effect once set. In 2.0, pfFrustAspect recomputes the frustum only at time of invocation.

6.8 Changes in libpf

6.8.1 Default Enables

PFEN_TEXTURE, PFEN_LIGHTING, PFEN_FOG are no longer enabled by default. Databases created with loaders that assumed specific global defaults, e.g., pfEnable(PFEN_TEXTURE) will be rendered improperly. All IRIS Performer loaders shipped with 2.0 create pfGeoStates which assume the global default is the same as that set by pfBasicState(), i.e., everything is OFF. To achieve 1.2 behavior with 1.2 loaders, call the following in the DRAW process after the window is opened:

: pfEnable(PFEN_LIGHTING);; /* Only on RealityEngine/VGX/VGXT */; pfEnable(PFEN_TEXTURE);; pfEnable(PFEN_FOG);

6.8.2 Multi-channel fog and lighting consistency

pfChannels now encode rotational offsets (pfChanViewOffsets) in the ModelView instead of the Projection matrix. Consequently, fog always matches across adjacent pfChannels but for proper lighting, a local viewer lighting model is required (pfLModelLocal).

6.8.3 Type inheritance

Multiple inheritance through the C API is gone. Previously, pfChannels could use pfFrustum API, e.g., pfMakePerspFrust(chan,...) pfFrameStats could use pfStats API, and pfLightSources could use pfLight API, e.g., pfLightPos(lsource...). Additional routines are now provided to maintain the same functionality without the complexities of multiple inheritance. The new routines name are simply the old routines where the "base" class name is replaced with the "derived" class name. For example, pfMakePerspFrust becomes pfMakePerspChan and pfLightPos becomes pfLSourcePos. Comprehensive tables illustrating the correspondence between routine names are found in pfChannel, pfFrameStats, and pfLightSource man pages.

6.8.4 Frustum Specification

Customizing a viewing frustum with pfMakePerspChan or pfMakeOrthoChan now disables the automatic viewport aspect ratio matching feature of pfChannel (pfChanAutoAspect).

6.8.5 API Changes

pfChanCullFunc and pfChanDrawFunc are now subsumed by pfChanTravFunc.

pfStageConfigFunc() and pfConfigStage() replace the now obsolete pfInitPipe().

6.8.6 Bug fix

PFPHASE_FLOAT and PFPHASE_LOCK now work in single process mode.

6.8.7 pfSwitch semantics

pfSwitchVal() used to determine the validity of the switch value which was problematic if no children had been added to the pfSwitch yet. The validity check is now deferred to individual traversal routines.

6.8.8 pfDataPools

When Performer shared memory has been created, pfDataPools are now positioned in the virtual address space so that conflicts are less likely to arise. Such conflicts were a frequent cause of failures of pfAttachDPool. Deleting a data pool now detaches it from the address space.

6.8.9 pfPartitions

Allow better specification of the spacing and positioning of the spatial partition to reduce construction time. They also work now.

6.8.10 Other Changes

6.8.11 Elimination of multiple inheritance

The CAPI inheritance of pfChannel from pfFrustum, pfLightSource from pfLight and pfFrameStats from pfStats has been removed. API has been added on the formerly derived to duplicate the functionality of the former base class, e.g. pfApplyFrust(chan) -> pfApplyChan(chan).

6.8.12 Light Model Attenuation vs Light Attenuation

IRIS GL: Light Attenuation is on the pfLightModel

: void pfLModelAtten(pfLightModel* _lm, float _a0, float _a1, float _a2);; void pfGetLModelAtten(pfLightModel* _lm, float* _a0, float* _a1, float* _a2);

OpenGL: Light Attenuation is on the pfLight

: void pfLightAtten(pfLight* _lt, float _a0, float _a1, float _a2);; void pfGetLightAtten(pfLight* _lt, float* _a0, float* _a1, float* _a2);

6.8.13 pfAlphaFunc now takes a float for ref

: was: void pfAlphaFunc(int ref, int func);; new: void pfAlphaFunc(float ref, int func);

6.8.14 pfGetAlphaFunc now returns a float for ref

: was: void pfGetAlphaFunc(int *ref, int *func);; new: void pfGetAlphaFunc(float *ref, int *func);

6.8.15 pfGStateMode and pfGetGStateMode

pf{Get}GStateMode can no longer accept the PFSTATE_ALPHAREF token. Use

: pfGStateVal(gstate, PFSTATE_ALPHAREF, val);

6.8.16 pfLightColor and pfGetLightColor

pfLightColor and pfGetLightColor now take arguments to specify which color.

: was: pfLightAmbient and pfGetLightAmbient are obsolete.; new: void pfLightColor(pfLight* _lt, int which, float _r, float _g, float _b);; new: void pfGetLightColor(pfLight* _lt, int which, float* _r, float* _g, float* _b);

6.8.17 pfInitGfx

pfInitGfx() has changed API, location and behavior:

: was: void pfInitGfx(pfPipe *p);; new: pfInitGfx(void);

pfInitGfx() should now be used to initialize all pfWindows and pfPipeWindows.

6.8.18 pfInitGLXGfx

pfInitGLXGfx(pfPipe *) has been removed. Use the pfPipeWindow utilities.

6.8.19 pfGetPipeWin and pfGetPipeGLXWins

pfGetPipeWin and pfGetPipeGLXWins have been removed. There is now pfGetPipePWin() to support this functionality.

6.8.20 pfInitPipe

pfInitPipe() is obsoleted in favor of pfStageConfigFunc() and pfConfigStage(). pfInitPipe() no longer is used to create windows. Use pfConfigPWin for a window initialization callback. Use pfConfigStage for initializing (or later re-configuring) the CULL or DRAW processes (stages) for a given pipe.

6.8.21 pfGetPipeOrigin

pfGetPipeOrigin() has been removed. Use pfGetWinOrigin() or pfGetPWinOrigin() to get the size of a pfWindow or pfPipeWindow respectively.

6.8.22 pfGetPipeSize

pfGetPipeSize() now returns the screen size of a pfPipe. Use pfGetWinSize() or pfGetPWinSize() to get the size of a pfWindow or pfPipeWindow respectively.

6.8.23 pfuWidgetFunc renamed

pfuWidgetFunc() is now pfuWidgetActionFunc().

6.8.24 pfuEnablePanel

pfuEnablePanel() no longer takes an enable argument. Instead, pfuPanels are enabled/disabled with pfuEnablePanel() and pfuDisablePanel() respectively.

6.8.25 pfuGetPanelSize

pfuGetPanelSize now follows standard convention of (xo, yo, xs, ys) parameter ordering.

: was: pfuGetPanelSize(pfuPane *p, int *xo, int *xs, int *yo, int *ys);; new: pfuGetPanelOrgSize(pfuPane *p, int *xo, int *yo, int *xs, int *ys);

6.8.26 pfInitPWin

pfInitPWin is now pfConfigPWin