winters 1% man performer Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) NAME Performer - Overview of IRIS Performer and summary of the C++ Language Bindings: libpr, libpf, libpfdu, libpfdb, libpfui, and libpfutil. DESCRIPTION Welcome to the IRIS Performer application development environment. IRIS Performer provides a comprehensive programming interface (with ANSI C and C++ bindings) for creating real-time visual simulation and other interactive graphics applications. IRIS Performer 2.2 supports the industry standard OpenGL graphics library; and the IRIS Graphics Library (IRIS GL); 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 Performer2.2 supports all Silicon Graphics running IRIX 6.2 or later. IRIS Performer is an integral part of the InfiniteReality, RealityEngine Octane and Indigo2/Impact, and O2 visual simulation systems and provides interfaces to the advanced features of InfiniteReality class graphics. IRIS Performer is compatible with all SGI graphics platforms and attains maximum performance on each. 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. Take a Test Drive If you are new to IRIS Performer, the best way to start learning about it is to go for a test drive. The Performer-based sample application perfly is installed in the /usr/sbin directory. To start perfly, all that you need to do is type perfly esprit.flt Type "man pfiXformer" for details on how to drive, fly, or tumble; and rerun perfly with the command line option "-help" for a full list of features. Type "?" while running perfly to print a list of keyboard command sequences to the shell window. The source code for this program is in /usr/share/Performer/src/sample/C/perfly. Handy Environment Variables to Remember There are a few IRIS Performer environment variables that can make your life easier. Page 1 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) PFPATH A colon separated list of directoris in which to find Performer data files: PFLD_LIBRARY_PATH and PFLD_LIBRARY{N32,64}_PATH A colon separated list of additional directories in which to find database loaders. These directories are searched before LD_LIBRARY_PATH. PFNFYLEVEL The maximum allowed of IRIS Performer print message. 1-FATAL, 2-WARN, 3-NOTICE, 4-INFO, 5-DEBUG, 6-FP_DEBUG, 7- INTERNAL_DEBUG. PFSHAREDSIZE The size (in bytes) of the shared memory arena to create. PFSHAREDBASE The address at which to place the shared memory arena. PF_LPOINT_BOARD Pretend there is a calligraphic light point board for calligraphic debugging. PFXDEBUG Turns on X Syncrhonization for debugging. Very slow, but helpful if you are exiting with X Errors. Setenv PFXDEBUG 1, dbx the program, breakpoint in exit, run, look at stack trace when stop. PFMACHTYPE Force the gfx machine type to be the give token for debugging. Uses the values from /usr/incude/sys/invent.h. PFASDLODSIZE Set the number of LODs to be constructed in pfASD using routines in pfdBuildASD.c. In general, a value less than 8 runs a lot faster and uses much less space than any value beyond 8. PFTMPDIR sets the tmp directory location. PFMEMDEBUG This variable sets up the trace on pfMemory usage. PFCULLSPINCOUNT If DRAW has finished previous frame, wait for DRAW to grab most recent buffer before updating it. This avoids hairy edge problems when the CULL is short and the DRAW wakes up just after the CULL has finished a new buffer. Page 2 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) IRIS Performer Overview 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 the user interface, and input management facilities common to many interactive applications. 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, input event collection and handling, and various traversal functions. In addition to these SGI-developed tools, IRIS Performer also includes 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. Program Structure Most IRIS Performer application programs have a common general structure. The following steps are typically involved in preparing for a real-time simulation: 1. Initialize IRIS Performer with pfInit. 2. Specify number of graphics pipelines with pfMultipipe, choose the multiprocessing configuration by calling pfMultiprocess, and specify the hardware mode with pfHyperpipe if needed. 3. Initiate the chosen multiprocessing mode by calling pfConfig. 4. Initialize the frame rate with pfFrameRate and set the frame- extend policy with pfPhase. 5. Create, configure, and open windows with new pfPipeWindow, pfPipeWindow::setFBConfigAttrs, and pfPipeWindow::open, as required. Page 3 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) 6. Create and configure display channels with new pfChannel, pfChannel::setTravFunc, pfChannel::setFOV, and pfChannel::setScene as required. Once the application has created a graphical rendering environment as shown above, the remaining task is to iterate through a main simulation loop once per frame. 7. Compute dynamics, update model matrices, etc. 8. Delay until the next frame time: pfSync 9. Perform latency critical viewpoint updates. 10. Draw a frame by calling pfFrame. In many applications the viewpoint will be set in step 7 and both step 8 and step 9 are not required. The more general case is shown since it is typical in head-tracked and other cases where low-latency applications with last-minute position input must be used. The libpr Performance Rendering Library Libpr consists of many low-level hardware oriented facilities generally required for real-time and other performance-oriented graphics applications. These features include High-speed rendering functions using the innovative pfGeoSet. Efficient graphics state management and mode control based on the pfGeoState. Display lists suitable for rendering between multiple processes. An extensive collection of fast linear algebra and math routines. Intersection computation and detection services. A colortable mechanism for rapid switching of database appearance. Asynchronous file I/O system for real-time file operations. Memory allocation oriented to shared memory and mutual exclusion. High speed clock functions that hide the complexities of hardware clocks. GeoSets are collections of drawable geometry which group same-type graphics primitives (e.g. triangles or quads) into one data object. The GeoSet contains no geometry itself, only pointers to data arrays and Page 4 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) index arrays. Geometry arrays may be indexed or non-indexed (i.e. stored in order) depending upon application requirements. Because all the primitives in a GeoSet are of the same type and have the same attributes, rendering of most databases is performed at maximum hardware speed. There are many GeoSet rendering methods, one for each combination of geometry and attribute specification. However, in IRIS Performer, all GeoSet rendering is performed through a single render dispatching routine, pfGeoSet::draw. GeoStates provide graphics state definitions (e.g. texture or material) for GeoSets. When used in conjunction with Performer state management functions, GeoSets can be rendered in a prescribed way without concern for the inherited modes of the graphics pipeline. GeoSets may share GeoStates. Less-used machine modes are not supported. State Management and Mode Control. IRIS Performer provides functions that bundle together graphics library state control functions such as lighting, materials, texture, and transparency. They have two purposes: to track state and to allow the creation of display lists that can be rendered later. The application program can set states in three ways: globally, locally (via GeoState), and directly. State changes made using direct graphics library calls are not "known" to the IRIS Performer state tracking mechanisms, and thus defeat IRIS Performer state management. However, functions exist to push state, pop state, and get the current state so proper intermixing of direct graphics library and IRIS Performer functions can be achieved. Display Lists are supported in IRIS Performer. These are not typical graphics library display lists, but rather simple token and data mechanisms that do not cache geometry or state data and are designed to allow efficient multiprocessing. These display lists use IRIS Performer state and rendering commands. They also support function callbacks to allow application programs to perform any required special processing during display list rendering. Windows for IRIS GL, IRIS GL mixed model (GLX), and OpenGL applications can be configured, created and managed with the pfWindow routines. Math Support is provided by an extensive set of point, segment, vector, plane, matrix, cylinder, sphere and frustum functions. Intersection and collision detection functions are provided to test for the intersection of line segments with cylinders, spheres, boxes, planes, and geometry. Intersection functions for spheres, cylinders, and frusta are also provided. ColorTables are supported by allowing GeoSet color indexes to refer to common tables of RGBA color information. Color tables are global and may be of any size. Any number of color tables may exist at one time and they can be activated at any time. The active color table may be switched in real-time without performance impact. Page 5 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) Asynchronous File I/O is provided by a simple non-blocking file access method. This is provided to allow applications to retrieve file data during real-time operation. Memory Allocation is supported with routines to allocate memory from process heap storage, shared memory arenas, and datapool memory. Shared arenas must be used when multiple processes need to access data. The arena is created by the application program. Datapools allow applications to create shared arenas visible to any process where allocations can be locked for easy mutual exclusion on a per allocation basis. High Speed Clock support is based on a high speed clock access routine that reports elapsed time in seconds as a double precision floating point number to highest machine resolution. Statistics are maintained by IRIS Performer on the geometry that is drawn, state changes, transformations, and most internal operations. These statistics can used for application tuning and form the basis for IRIS Performer's automatic system load management. The libpf Visual Simulation Library libpf is a high level library built on libpr that is architected and implemented to meet the specific needs of real-time graphics software. Applications developed with libpf are able to provide smooth motion through elaborate scenes at programmable frame rates, all with very little code development. libpf provides Hierarchical scene graph processing and operators. Transparent multiprocessing for parallel simulation, culling and drawing. Graphics load measurement and frame rate management. Level of detail selection with smooth fade and rotational invariance. Rapid culling to the viewing frustum through hierarchical bounding volumes. Multiprocessed intersection detection and reporting. Dynamic coordinate systems for highly interactive graphics. Multibuffering of changes to the scene graph for simple multiprocessing. Multiprocessing Page 6 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) libpf provides a pipelined multiprocessing model for implementing visual simulation applications. The application, visibility culling and drawing tasks can all run in separate processes. The simulation process updates the scene, the cull process traverses the scene checking for visibility and generates display lists which are then rendered by the drawing process. libpf multibuffering capabilities allow each process to have copies of the scene graph and the user data appropriate to its target frame time. The simulation, culling, and drawing for a graphics pipeline may be combined into one, two or three processes to allow an application to be tailored to different hardware and expected CPU demand in each process. For example, culling and drawing are normally done by separate processes in order to obtain maximum graphics performance, but if an application is simulation bound, it may wish to combine both cull and draw into a single process. Statistics are maintained for each IRIS Performer process - application, cull and draw. These statistics can be displayed in a channel, printed, and queried using the pfFrameStats routines. Graphics Pipes, Windows, and Channels In addition to the functionality it derives from libpr, libpf supports multiple channels per window, multiple windows per graphics pipe, grouping of channels to form video walls, and frame synchronization between multiple graphics pipes. libpf maintains a graphics stress value for each channel and uses it to attempt to maintain a fixed frame rate by manipulating levels-of-detail (LODs). Like many graphics libraries, libpf assumes a coordinate system with +Z up, +X to the right and +Y into the screen. Database libpf supports a general database hierarchy which consists of the following node types: pfNode General node (base class) pfScene Top level node. pfGroup Node with multiple children. pfSCS Static coordinate system. pfDCS Dynamic coordinate system. pfLayer Layer or decal node. pfLOD Level of detail node. pfSwitch Switch node. pfSequence Sequential animation node. pfGeode Fundamental geometry node. pfBillboard Special tracking leaf node. pfLightPoint One or more emissive light points. pfLightSource Definition of a graphics hardware light. pfPartition Special culling acceleration node. Page 7 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) pfText 2D and 3D text geometry. pfMorph Geometry morphing node. Each of these is derived from pfNode and any function which requires a pfNode* as an argument can accept any of the above types. Similarly pfSCS, pfDCS, pfLOD, pfSequence and pfSwitch are derived from pfGroup and can be used in any function which takes a pfGroup* as an argument. Nodes can be assembled into a directed graph to represent a scene with its modeling hierarchy. Geometry and graphics state information is contained in pfGeoStates and pfGeoSets which are attached to pfGeodes. Intersection inquiries are made via groups of line segments which can be tested against a subgraph of the scene. Masks and callbacks can be specified to allow evaluation of line-of-sight visibility, collisions, and terrain intersections. libpf also provides earth-sky and weather functions for modeling fog, haze and other atmospheric effects. The libpfdu Database Utility Library libpfdu provides helpful functions for constructing optimized IRIS Performer data structures and scene graphs. It is used by most of the database loaders in libpfdb to take external file formats containing 3D geometry and graphics state and load them into IRIS Performer optimized run-time data structures. Such utilities often prove very useful; most modeling tools and file formats represent their data in structures that correspond to the way users model data, but such data structures are often mutually exclusive with effective and efficient IRIS Performer run-time structures. libpfdu contains many utilities, including DSO support for database loaders and their modes, file path support, and so on, but the heart of libpfdu is the IRIS Performer database builder and geometry builder. The builders are tools that allow users to input or output a collection of geometry and graphics state in immediate mode. Users send geometric primitives one at a time, each with its corresponding graphics state, to the builder. When the builder has received all the data, the user simply requests optimized IRIS Performer data structures which can then be used as a part of a scene graph. The builder hashes 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, and so on) and shares state elements whenever possible. Finally, the builder creates pfGeoSets that contain triangle meshes created by running the original geometry through the libpfdu triangle-meshing utility. To go along with each pfGeoSet, the builder creates a pfGeoState (IRIS Performer's encapsulated state primitive). The builder generates pfGeoStates that share as many attributes as possible with other pfGeoStates in the scene graph. Page 8 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) Having created these primitives (pfGeoSets and pfGeoStates) the builder will place them in a leaf node (pfGeode), and optionally create a spatial hierarchy by running the new database through a spatial breakup utility function which is also contained in libpfdu. Note that the builder also allows the user to extend the notion of a graphics state by registering callback functionality through builder API and then treating this state or functionality like any other IRIS Performer state or mode (although such uses of the builder are slightly more complicated). In short, libpfdu is a collection of utilities that effectively act as a data funnel where users enter flattened 3D graphics information and are given in return fully functional and optimized IRIS Performer run-time structures. The libpfui User Interface Library The libpfui library provides building blocks for writing manipulation components for user interfaces. This library provides both C and C++ interfaces. Provided are separate components for motion control (- pfiInputCoordXform), collision detection between the viewer and objects in the scene (pfiCollide), and picking of objects in the scene based on current mouse coordinates (pfiPick). The pfiInputCoordXform utilities update transformation matrices that can be used to drive motion in an application. The actual mapping of user events is orthogonal to these motion models and can be done using the input collection utilities in libpfutil, or directly with custom application code. The pfiXformer is a re-implementation of the old pfuXformer based on these components and combines several different kinds of motion control in one complex component. The pfiXformer also provides mapping of user input events, such as mouse and keyboard, to motion controls which is described in the pfiXformer reference page. Examples of how to use these utilities can be found in /usr/share/Performer/src/pguide/libpfui The libpfutil Utility Library The libpfutil library contains a large number of miscellaneous functions that provide support for the following important tasks. Processor control enables the user to specify which CPU a particular Performer process runs on and to devote a particular processor to a given process. Multiprocess rendezvous lets master and slave processes synchronize in a multiprocessing environment. GLX mixed model routines are provided for compatibility with previous versions of IRIS Performer. Current development should be based on the pfWindow and pfPipeWindow routines that provide a single API for managing IRIS GL, IRIS GL mixed model, and OpenGL windows. Page 9 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) GL and X input handling is handled by an exhaustive set of commands that operate on compressed, space-efficient queues of events. Cursor control is provided to easily manipulate the cursors associated with each window managed by IRIS Performer. X fonts are supported so that they can be used to draw text in IRIS Performer windows. The main task of these functions is to simplify the use of X fonts and present a high-level interface to the user. Graphical User Interfaces (GUIs) are made easily accessible to the user through a set of functions that provide simple means to create a GUI, set up widgets, manipulate them, set user-defined functions to control their behavior and do other common tasks. Scene graph traversal routines provide for different, highly-customizable traversal mechanisms for the IRIS Performer scene graph. MultiChannel Option (MCO) is supported on RealityEngine graphics systems by a set of functions that generically initialize channels for using MCO. These same routines support the two and eight video output (DG-2 and DG- 8) versions of the InfiniteReality display generator board as well. Path following mechanisms allow the user to follow a pre-defined path in a walkthrough application. Functions to create paths are also provided. Various draw styles like haloed lines and wireframe images are supported as a demonstration of the uses of multi-pass rendering. Other utilities supported are for timer control to track time in real- time independently of the frame-rate, managing hash tables, a simple geometric simplification scheme for generating very simple level-of- detail representations of the scene graph, texture loading and texture animation, random number generation, flybox control, smoke and fire simulation and converting light point states into textures. The libpfdb Database Library 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 loaders in libpfdb have been developed by Silicon Graphics, by modeling tool vendors, and by Performer customers. Many are provided in source form as part of this IRIS Performer distribution. Use these loaders as templates to write custom loaders for whatever formats you require in your applications. The different kinds of file formats supported by IRIS Performer are listed below Page 10 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) 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 csb OpenGL Optimizer native csb format 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 / Silicon Studio Keystone lsa Lightscape Technologies radiosity (ASCII) lsb Lightscape Technologies radiosity (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 phd Minor SGI format (polyhedra) pfa IRIS Performer ASCII database format pfb IRIS Performer BINARY database format poly Side Effects Software PRISMS ASCII data pts University of Washington point data ptu Minor SGI format (IRIS Performer example) 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 wrl OpenWorlds VRML 2.0 loader from DRaW Computing Source code for many of these loaders is provided with IRIS Performer. Loader source code is located in and below the directory /usr/share/Performer/src/lib/libpfdb While most loaders do in fact "load" data from files, scene graphs can also be generated procedurally. The sponge loader is an example of such automatic generation; it builds a model of the Menger (Sierpinski) sponge, without requiring an input file. To see the sponge run perfly specify the number of recursions (0, 1, 2, ...) as the filename. For example Page 11 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) perfly 2.sponge Learning More Once you've seen IRIS Performer in action, you will want to learn more about it. The IRIS Performer Programming Guide and the IRIS Performer Release Notes are the primary sources of information, but the following overview will give you a head start in your learning process. IRIS Performer Sample Code The IRIS Performer sample code can be found in /usr/share/Performer/src/pguide - small examples and /usr/share/Performer/src/sample - sample applications and its subdirectories. The "apps" subdirectory contains the various flying demos like perfly and the Performer town demo. The "pguide" subdirectory has further subdirectories for each IRIS Performer library. Each of these directories has example and sample programs that highlight the features of the corresponding library. IRIS Performer Documentation In addition to the reference pages on IRIS Performer, an on-line Programming Guide is also provided. To read this, run Insight and click on the Performer Programming Guide button. IRIS Performer World Wide Web Home Page Silicon Surf, the Silicon Graphics World Wide Web Home Page, contains an archive of IRIS Performer-related technical and promotional material in the Extreme Tech section. The information from the IRIS Performer FTP site and mailing list is also accessible via the WWW. Explore Silicon Surf using the URL http://www.sgi.com/ or go directly to the IRIS Performer information with the URL http://www.sgi.com/Technology/Performer Page 12 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) IRIS Performer INTERNET FTP Site An archive of IRIS Performer-related material is available via anonymous FTP from Silicon Graphics. The FTP address is ftp://sgigate.sgi.com/pub/Performer Current contents of the IRIS Performer FTP site include README Overview file FAQ The IRIS Performer FAQ INFO-PERFORMER Information about the IRIS Performer mailing list src/ Sample source code and miscellaneous patches docs/ IRIS Performer documents including SIGGRAPH '94 paper selected-topics/ Directory of info, Q&A, etc. from mailing list monthly-archives/ Raw monthly archives of the mailing list CortaillodCentre/ Goodies from SGI's Cortaillod Office RealityCentre/ Goodies from SGI's RealityCentre in the UK IRIS Performer Electronic Mailing List The IRIS Performer mailing list is a resource for developers who are using IRIS Performer to maximize the performance of their graphics applications on Silicon Graphics hardware. The info-performer list is intended to be an unmoderated, free-form discussion of IRIS Performer with issues both technical and non-technical; and to provide feedback to Silicon Graphics about the product. Much like the comp.sys.sgi.* newsgroups, it is not an official support channel but is monitored by the IRIS Performer development team, so it's an excellent source of early information about upcoming events and product features, as well as a venue for asking questions and having them answered. To subscribe to the info-performer mailing list, send email to info-performer-request@sgi.com Once your request is processed you will receive submission and posting instructions, some guidelines, and a current copy of the Performer Page 13 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) Frequently-Asked-Questions (FAQ) list. The mailing list has become rather large and carries several hundred messages per month. Mailing list archives are available in the Performer FTP area (see above) in ftp://sgigate.sgi.com/pub/Performer/monthly-archives/ IRIS Performer Frequently Asked Questions Silicon Graphics maintains a publicly accessible directory of questions that developers often ask about IRIS Performer, along with answers to those questions. Each question-and-answer pair is provided in a file of its own, named by topic. To obtain any of these files, use anonymous FTP to connect to sgigate.sgi.com; then cd to the directory /pub/Performer/selected-topics and use ls to see a list of available topics. Alternatively, use a World Wide Web browser to look at ftp://sgigate.sgi.com/pub/Performer/selected-topics The Friends of Performer A number of leading companies in the visual simulation, database modeling, game authoring, and, virtual reality marketplaces produce tools and products that are based on and work with IRIS Performer. Several of these companies have provided samples of their work for your use and enjoyment. These software gifts are in the Friends CD of the IRIS Performer distribution, and can be installed in the directory /usr/share/Performer/friends Check out the gifts and the products that these companies offer. IRIS Performer Application Programming Interface The IRIS Performer application programming interface (API) has been designed by following a consistent set of naming principles that are outlined below. Following that review is a complete listing of the API grouped by topic for your use as both a quick reference and as an API Page 14 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) directory. Each of the libpf, libpr, libpfdu, libpfdb, libpfui, and libpfutil functions also has a complete reference page description available via the IRIX man and xman commands. Refer to these reference pages for a thorough discussion of the functions and data types, features and limitations, performance and resource implications, and sample code showing how these functions are used in practice. IRIS Performer Software Conventions All the IRIS Performer commands have intuitive names that describe what they do. These mnemonic names make it easy for you to learn and remember the commands. The names may look a little strange to you if you're unfamiliar with this type of convention because they use a mixture of upper and lowercase letters. Naming conventions provide for consistency and uniqueness, both for routines and for symbolic tokens. Following consistent naming practices in the software that you develop will make it easier for you and others on your team to understand and debug your code. Naming conventions for IRIS Performer are as follows: All class, command and token names, associated with libpf or libpr are preceded by the letters pf, denoting the IRIS Performer library. Member functions do not have the pf prefix since the class name provides sufficient scope resolution. Functions from the other libraries also affix an identifying letter suffix (d, i, or u) to the pf prefix for scope resolution purposes. Library | Prefix | Example ___________|________|________________________ libpf | pf | pfMultiprocess libpr | pf | pfGetCurDList libpfdu | pfd | pfdNewGeom libpfdb | pfd | pfdLoadFile_medit libpfui | pfi | pfiResetXformerPosition libpfutil | pfu | pfuDownloadTexList Command and type names are mixed-case, while token names are uppercase. For example, pfTexture is a type name and PFTEX_SHARPEN is a token name. Underscores are not used in function names except in the libpfdb libraries, where the underscore serves to separate the common loader name (pfdLoad) from the file type extension (medit in the example above). In type names, the part following the pf is usually spelled out in full, as is the case with pfTexture, but in some cases a shortened form of the word is used. For example, pfDispList is the name of the display-list type. Much of IRIS Performer's interface involves setting parameters and retrieving parameter values. For the sake of brevity, the word Set is omitted from function names, so that instead of pfSetMtlColor, pfMtlColor Page 15 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) is the name of the routine used for setting the color of a pfMaterial. Get, however, is not omitted from the names of routines that get information, such as pfGetMtlColor. C++ member function names do include both "get" and "set". Routine names are constructed by appending a type name to an operation name. The operation name always precedes the type name. In this case, the operation name is unabbreviated and the type name is abbreviated. For example, the name of the routine that applies a pfTexture is pfApplyTex. Compound type names are abbreviated by the first initial of the first word and the entire second word. For example, to draw a display list, which is type pfDispList, use pfDrawDList. Symbolic token names incorporate another abbreviation, usually shorter, of the type name. For example pfTexture tokens begin with PFTEX_. pfDispList tokens begin with PFDL_. This convention ensures that tokens for a particular type have their own name space. Other tokens and identifiers follow the conventions of ANSI C and C++ wherein a valid identifier consists of upper and lower-case alphabetic characters, digits, and underscores, and the first character is not a digit. LIBPF Initialization pfInit initializes all internal IRIS Performer data structures while pfExit cleans up before returning control to the application. The other functions provide support for multiprocessed execution. This involves configuring IRIS Performer for multiple processes and threads and multiple and multiplexed (hyper) pipes. int pfInit(void); int pfIsInited(void); void pfExit(void); int pfMultipipe(int numPipes); int pfGetMultipipe(void); int pfHyperpipe(int numHyperPipes); int pfGetHyperpipe(pfPipe *pipe); int pfMultiprocess(int mpMode); int pfGetMultiprocess(void); int pfGetMPBitmask(void); int pfMultithread(int pipe, uint stage, int nprocs); Page 16 Performer(3pf) IRIS Performer 2.1 C++ Reference Page Overview Performer(3pf) int pfGetMultithread(int pipe, uint stage); int pfConfig(void); int pfIsConfiged(void); pid_t pfGetPID(int pipe, uint stage); uint pfGetStage(pid_t pid, int *pipe); void pfStageConfigFunc(int pipe, uint stage, pfStageFuncType configFunc); pfStageFuncType pfGetStageConfigFunc(int pipe, uint stage); int pfConfigStage(int pipe, uint stage); const char * pfGetStageName(int pipe, uint stage); const char * pfGetPIDName(pid_t pid); void pfCreateProcessFunc(pfCreateProcessFuncType func); pfCreateProcessFuncType pfGetCreateProcessFunc(void); void pfProcessMiscCPU(int cpu); int pfGetProcessMiscCPU(void); void pfPrintProcessState(FILE *fp); Frame Control IRIS Performer is designed to run at a fixed frame rate. pfFrame, pfSync and associated functions set a frame rate the application should run at, initiate each new frame of IRIS Performer processing and synchronize the application process with the specified frame rate. pfApp, pfCull, pfDraw and pfDBase trigger the default IRIS Performer processing for each stage of the graphics pipeline. User-defined callbacks can be specified for each of these stages using the pf*Func functions. Data can be allocated for each stage and also passed down the different stages of the pipeline. [snip! The rest of the man page is a detailed descripion of the lib functions]