Table 7-2 describes the general routines for 3D databases provided by libpfdu.  

The database loader utility library, libpfdu, provides a convenient function, named pfdLoadFile(), that imports database files stored in any of the supported formats listed in Table 7-6.

Loading database files with pfdLoadFile() is easy. The function prototype is

pfNode *pfdLoadFile(char *fileName);

pfdLoadFile() tests the filename-extension portion of fileName (the substring starting at the last period in fileName, if any) for one of the format-name codes listed in Table 7-6, then calls the appropriate importer.

The file-format selection process is implemented using dynamic loading of DSOs, dynamic shared objects, for IRIX and Linux and DLLs, dynamic link libraries, for Microsoft Windows. This process allows new loaders that are developed as database formats change to be used with OpenGL Performer-based applications without requiring recompilation of the OpenGL Performer application.

---

Note: Subsequent general references in this manual to DSOs also pertain to DLLs unless otherwise noted.

---

If at all possible, pfdInitConverter() should be called before pfConfig() for the potential formats that may be loaded. This will preload the DSO and allow it to initialize any of its own data structures and classes. This is required if the loader DSO extends OpenGL Performer classes or uses any node traversal callbacks so that if multiprocessing these data elements will all have been precreated and be valid in all potential processes. pfdInitConverter() automatically calls pfdLoadNeededDSOs_EXT() to preload additional DSOs needed by the loader if the given loader has defined that routine. These routines take a filename so that the loader has the option to search through the file for possible DSO references in the file.

Details about the database loading process are described further in this section, the pfdLoadFile man page, and the source code which is in /usr/share/Performer/src/lib/libpfdu/pfdLoadFile.c on IRIX and Linux and in %PFROOT%\Src\lib\libpfdu\pfdLoadFile.c on Microsoft Windows.

The routines pfdInitConverter(), pfdLoadFile(), pfdStoreFile(), pfdConvertFrom(), and pfdConvertTo() exist only as a level of indirection to allow you to manipulate all databases regardless of format through a central API. They are in fact merely a mechanism for creating an open environment for data sharing among the multitudes of three-dimensional database formats. Each of these routines determines, using file-type extensions, which database converter to load as a run-time DSO. The routine then calls the appropriate functionality from that converter's DSO. All converters must provide API that is exactly the same as the corresponding libpfdu API with _EXT added to the routine names (for example, for .medit files, the suffix is _medit). Note that multiple physical extensions can be mapped to one converter extension with calls to pfdAddExtAlias(). Several aliases are predefined upon initialization of libpfdu.

It is also important to note that because each of these converters is a unique entity that they each may have state that is important to their proper function. Moreover, their database formats may allow for multiple OpenGL Performer interpretations; so, there exist APIs, shown in Table 7-4, not only to initialize and exit database converters, but also to set and get modes, attributes, and values that might affect the converter's methodology.

Once again each converter provides the equivalent routines with _EXT added to the function name.

For example, the converter for the Open Inventor format would define the function pfdInitConverter_iv() if it needed to be initialized before it was used. Likewise, it would define the function pfdLoadFile_iv() to read an Open Inventor “.iv” file into an OpenGL Performer scene graph.

---

Note: Because each converter is an individual entity (DSO) and deals with a particular type of database, it may be the case that a converter will not provide all of the functionality listed above, but rather only a subset. For instance, most converters that come with OpenGL Performer only implement their version of pfdLoadFile but not pfdStoreFile, pfdConvertFrom, or pfdConvertTo. However, users are free to add this functionality to the converters using compliant APIs and OpenGL Performer's libpfdu will immediately recognize this functionality. Also, libpfdu traps access to nonexistent converter functionality and returns gracefully to the calling code while notifying the user that the functionality could not be found.

---

In order to effectively convert a database into an OpenGL Performer scene graph, it is important to have a substantial understanding of several concepts related to the original database format:

Before trying to convert sophisticated 3D database formats into OpenGL Performer it is important to have a thorough grasp of how every structure in the format needs to affect how OpenGL Performer performs its run-time management of a scene graph. However, although it requires a great deal of understanding to convert complex behaviors of external formats into OpenGL Performer, it is still very straight forward to migrate basic structure, geometry, and graphics state into efficient OpenGL Performer run-time structures using the functionality provided in the OpenGL Performer database builder, pfdBuilder.

Creating an OpenGL Performer scene graph requires a definite knowledge of the following OpenGL Performer libpf node types: pfScene, pfGroup, and pfGeode.

These nodes can be used to define a minimally functional OpenGL Performer scene graph. See “Nodes” in Chapter 3 for more details on libpf and OpenGL Performer scene graphs and node types.

In order to input geometry and graphics into OpenGL Performer, it is important to have an understanding of how OpenGL Performer's low-level rendering objects work in libpr, OpenGL Performer's performance rendering library. The main libpr rendering primitives are a pfGeoSet and a pfGeoState. A pfGeoSet is a collection of like geometric primitives that can all be rendered in exactly the same way in one large continuous chunk. A pfGeoState is a complete definition of graphics mode settings for the rendering hardware and software. It contains many attributes such as texture and material. Given a pfGeoSet and a corresponding pfGeoState, libpr can completely and efficiently render all of the geometry in the pfGeoSet. For a more detailed description of pfGeoSets and pfGeoStates, see “pfGeoSets and pfGeoStates” in Chapter 12, which goes into detail on all libpr primitives and how OpenGL Performer will use them.

However, realizing that OpenGL Performer's structuring of geometry and graphics state is optimized for rendering speed and not for modeling ease or general conceptual partitioning, OpenGL Performer now contains a new mechanism for translating external graphics state and geometry into efficient libpr structures. This new mechanism is the pfdBuilder that exists in libpfdu.

The pfdBuilder allows the immediate mode input of graphics state and primitives through very simple and exposed data structures. After having received all of the relevant information, the pfdBuilder builds efficient and somewhat optimized libpr data structures and returns a low-level libpf node that can be attached to an OpenGL Performer scene graph. The pfdBuilder is the recommended method of importing data from non-OpenGL Performer-based formats into OpenGL Performer.

Creating a new format converter is very simple process. More than thirty database loaders are shipped with OpenGL Performer in source code form to serve as practical examples of this process. The loaders read formats that range from trivial to complex and should serve as an instructive starting point for those developing loaders for other formats. These loaders can be found in the directory /usr/share/Performer/src/lib/libpfdb/libpf* on IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpf* on Microsoft Windows.

This section describes the libpfdu framework for creating a 3D database format converter. Consider writing a converter for a simple ASCII format that is called the Imaginary Immediate Mode format with the file type extension .iim. This format is much like the more elaborate .im format loader used at SGI for the purposes of testing basic OpenGL Performer functionality.

The first thing to do is set up the routine that pfdLoadFile() will call when it attempts to load a file with the extension .iim.

#ifdef WIN32
#define PFDB_DLLEXPORT __declspec(dllexport)
#else
#define PFDB_DLLEXPORT /* no-op */
#endif
extern PFDB_DLLEXPORT pfNode *pfdLoadFile_iim(char *fileName)
{
}

This function needs to perform several basic actions:

Steps 1-8 expand the function outline to the following:

extern PFDB_DLLEXPORT pfNode *pfdLoadFile_iim(char *fileName)
{
  FILE* iimFile;
  pfdGeom* polygon;
  pfGroup* root;
 
  /* Performer has utility for finding and opening file */
  if ((iimFile = pfdOpenFile(fileName)) == NULL)
  return NULL;
 
  /* Clear builder from previous converter invocations */
  pfdResetBldrGeometry();
  pfdResetBldrState();
 
  /* Call pfdBldrMode for any needed modes here */
 
  /* Create polygon structure */
  /* holds one N-sided polygon where N is < 300 */
  polygon = pfdNewGeom(300);
 
  /* Create pfGroup to hold entire database */
  /* loaded from this file */
  root = pfNewGroup();
 
  /* Specify state for geometry with no graphics state */
  /* As well as default enables, etc. This routine */
  /* should invoke pfdCaptureDefaultBldrState()*/
  SetupDefaultGraphicsStateIfThereIsOne();
 
  /* Do all the real work in parsing the file and */
  /* converting into Performer */
  ParseIIMFile(iimFile, root, polygon);
 
  /* Delete local polygon struct */
  pfdDelGeom(polygon);
 
  /* Close File */
  fclose(iimFile);
 
  /* Optimize OpenGL Performer scene graph */
  /* via use of pfFlatten, pfdCleanTree, etc. */
  OptimizeGraph(root);
 
  return (pfNode*)root;
}

At the heart of the file loader lies the ParseIIMFile() function. The specifics of parsing a file are completely dependent on the format; so, the parsing will be left as an exercise to you. However, the following code fragments should show a framework for what goes into integrating the parser with the pfdBuilder framework for geometry and graphics state data conversion. Note that several possible graphics state inheritance models might be used in external formats and that the pfdBuilder is designed to support all of them:

One of the fundamental structures involved in the above routine outline is the pfdGeom structure which you fill in with information about a single primitive, or a single strip of primitives. The pfdGeom structure is essential in communicating with the pfdBuilder and is defined as follows:

typedef struct _pfdGeom
{
    int         flags;
    int         nbind, cbind, tbind[PF_MAX_TEXTURES];

    int         numVerts;
    short       primtype;
    float       pixelsize;

    /* Non-indexed attributes - do not set if poly is indexed */
    pfVec3      *coords;
    pfVec3      *norms;
    pfVec4      *colors;
    pfVec2      *texCoords[PF_MAX_TEXTURES];

    /* Indexed attributes - do not set if poly is non-indexed */
    pfVec3      *coordList;
    pfVec3      *normList;
    pfVec4      *colorList;
    pfVec2      *texCoordList[PF_MAX_TEXTURES];

    /* Index lists - do not set if poly is non-indexed */
    ushort      *icoords;
    ushort      *inorms;
    ushort      *icolors;
    ushort      *itexCoords[PF_MAX_TEXTURES];

    int         numTextures;

    struct _pfdGeom         *next;

} pfdGeom;

See the pfdGeoBuilder(3pf) man pages for more information on using this structure along with its sister structure, the pfdPrim.

The above should provide a well-defined framework for creating a database converter that can be used with any OpenGL Performer applications using the pfdLoadFile() functionality.

However, it is also important to note that there are a multitude of pfdBuilder modes and attributes that can be used to affect some of the basic methods that the builder actually uses:

Because the pfdBuilder is released as source code, it is easy to add further functionality and more modes and attributes to even further customize this central functionality.

In fact, because the pfdBuilder acts as a “data funnel” in converting data into OpenGL Performer run-time structures, it is easy to control the behavior of many standard conversion tasks through merely globally setting builder modes which will subsequently affect all converters that use the pfdBuilder to process their data.

The pfconv utility converts from any format for which a pfdLoadFile...() function exists into any format for which a pfdStoreFile...() exists. The most common format to convert to is the PFB format. For example, to convert cow.obj into the PFB format, use the following command:

% pfconv cow.obj cow.pfb

By default, pfconv optimizes the scene graph when doing the conversion. The optimizations are controlled with the -o and -O command line options. Builder options are controlled with the -b and -B command line options. Converter modes are controlled with the -m and -M command line options. Refer to the help page for more specific information about the command line options by entering:

% pfconv -h

% pfconv -M pfb, 5, 1 

The pficonv utility converts from IRIS libimage format to PFI format image files. For example, to convert cafe.rgb into the PFI format, use the following command:

% pficonv cafe.rgb cafe.pfi

MIPmaps can be automatically generated and stored in the resulting PFI files by adding -m to the command line.

The AutoDesk 3DS format is used by the 3DStudio program and by a number of 3D file-interchange tools. The OpenGL Performer loader for 3DS files is located in the directory /usr/share/Performer/src/lib/libpfdb/libpf3ds on IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpf3ds on Microsoft Windows. This loader uses an auxiliary library, 3dsftk.a, to parse and interpret the 3ds file.

pfdLoadFile() uses the function pfdLoadFile_3ds() to import data from 3DStudio files into OpenGL Performer run-time data structures.

The SGI BIN format is supported by both Showcase and the powerflip demonstration program. BIN files are in a simple format that specifies only independent quadrilaterals.

The image in Figure 7-1 shows several of the BIN-format objects provided in the OpenGL Performer sample data directory.

Figure 7-1. BIN-Format Data Objects

The source code for the BIN-format importer pfdLoadFile_bin() is provided in the file pfbin.c. This code shows how easy it can be to implement an importer. Since pfdLoadFile_bin() is based on the pfdBuilder() utility function, it will build efficient triangle-strip pfGeoSets from the quadrilaterals of a given BIN file. The BIN format has the following structure:

The BIN format uses these data structures:

typedef struct
{
    float normal[3];
    float coordinate[3];
} Vertex;
 
typedef struct
{
    long magic;
    long vertices;
    long zero;
    Vertex vertex[1];
} BinFile;

pfdLoadFile() uses the function pfdLoadFile_bin() to import data from BIN format files into OpenGL Performer run-time data structures:

The pfdLoadFile_bin() function composes a random color for each file it reads. The chosen color has red, green, and blue components uniformly distributed within the range 0.2 to 0.7 and is fully opaque.

The Side Effects software PRISMS database modeler format supports both ASCII and binary forms of the POLY format. The OpenGL Performer loader for ASCII “.poly” files is located in the directory /usr/share/Performer/src/lib/libpfdb/libpfpoly for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfpoly for Microsoft Windows. The binary format “.bpoly” loader is located in the directory /usr/share/Performer/src/lib/libpfdb/libpfbpoly for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfbpoly for Microsoft Windows. These formats are equivalent in content and differ only in representation.

The POLY format is an easy to understand ASCII data representation with the following structure:

Here is a sample POLY format file for a cube with colors, texture coordinates, and normals specified at each vertex:

POINTS
1: -0.5 -0.5 -0.5 c(0, 0, 0, 1) uv(0, 0) n(0, -1, 0)
2: -0.5 -0.5 0.5 c(0, 0, 1, 1) uv(0, 0) n(0, -1, 0)
3: 0.5 -0.5 0.5 c(1, 0, 1, 1) uv(1, 0) n(0, -1, 0)
4: 0.5 -0.5 -0.5 c(1, 0, 0, 1) uv(1, 0) n(0, -1, 0)
5: -0.5 -0.5 0.5 c(0, 0, 1, 1) uv(0, 0) n(0, 0, 1)
6: -0.5 0.5 0.5 c(0, 1, 1, 1) uv(0, 1) n(0, 0, 1)
7: 0.5 0.5 0.5 c(1, 1, 1, 1) uv(1, 1) n(0, 0, 1)
8: 0.5 -0.5 0.5 c(1, 0, 1, 1) uv(1, 0) n(0, 0, 1)
9: -0.5 0.5 0.5 c(0, 1, 1, 1) uv(0, 1) n(0, 1, 0)
10: -0.5 0.5 -0.5 c(0, 1, 0, 1) uv(0, 1) n(0, 1, 0)
11: 0.5 0.5 -0.5 c(1, 1, 0, 1) uv(1, 1) n(0, 1, 0)
12: 0.5 0.5 0.5 c(1, 1, 1, 1) uv(1, 1) n(0, 1, 0)
13: -0.5 -0.5 -0.5 c(0, 0, 0, 1) uv(0, 0) n(0, 0, -1)
14: 0.5 -0.5 -0.5 c(1, 0, 0, 1) uv(1, 0) n(0, 0, -1)
15: 0.5 0.5 -0.5 c(1, 1, 0, 1) uv(1, 1) n(0, 0, -1)
16: -0.5 0.5 -0.5 c(0, 1, 0, 1) uv(0, 1) n(0, 0, -1)
17: -0.5 -0.5 -0.5 c(0, 0, 0, 1) uv(0, 0) n(-1, 0, 0)
18: -0.5 0.5 -0.5 c(0, 1, 0, 1) uv(0, 1) n(-1, 0, 0)
19: -0.5 0.5 0.5 c(0, 1, 1, 1) uv(0, 1) n(-1, 0, 0)
20: -0.5 -0.5 0.5 c(0, 0, 1, 1) uv(0, 0) n(-1, 0, 0)
21: 0.5 0.5 0.5 c(1, 1, 1, 1) uv(1, 1) n(1, 0, 0)
22: 0.5 0.5 -0.5 c(1, 1, 0, 1) uv(1, 1) n(1, 0, 0)
23: 0.5 -0.5 -0.5 c(1, 0, 0, 1) uv(1, 0) n(1, 0, 0)
24: 0.5 -0.5 0.5 c(1, 0, 1, 1) uv(1, 0) n(1, 0, 0)
POLYS
1: 1 2 3 4 <
2: 5 6 7 8 <
3: 9 10 11 12 <
4: 13 14 15 16 <
5: 17 18 19 20 <
6: 21 22 23 24 <

pfdLoadFile() uses the functions pfdLoadFile_poly() and pfdLoadFile_bpoly() to import data from “.poly” and “.bpoly” format files into OpenGL Performer run-time data structures.

The Brigham Young University “.byu” format is used as an interchange format by some finite element analysis packages. The OpenGL Performer loader for “.byu” files is located in the directory /usr/share/Performer/src/lib/libpfdb/libpfbyu for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfbyu for Microsoft Windows.

The format of a BYU file consists of four parts as defined below:

The following BYU format file defines two adjoining quads:

2 6 2 0
1 1
2 2
0 0 0 10 0 0
10 10 0 0 10 0
10 10 10 0 10 10
1 2 3 -4
4 3 5 -6

pfdLoadFile() uses the function pfdLoadFile_byu() to import data from “.byu” format files into OpenGL Performer run-time data structures.

OpenGL Performer can load native OpenGL Optimizer format files using this loader. OpenGL Optimizer can also load OpenGL Performer's PFB native format files, providing full database interoperability. This allows you to use OpenGL Optimizer database simplification and optimization tools on OpenGL Performer databases.

The OpenGL Performer CT loader allows you to create and configure cliptextures and virtual cliptextures, complete with a scene graph containing simple geometry and callbacks. See the Cliptexture chapter for more details.

The binary DWB format is used for input and output by the Designer's Workbench, EasyT, and EasyScene database modeling tools produced by Coryphaeus Software. DWB is an advanced database format that directly represents many of OpenGL Performer's attribute and hierarchical scene graph concepts.

An importer for this format, named pfdLoadFile_dwb(), has been provided by Coryphaeus Software for your use. The loader code and its associated documentation are in the directory /usr/share/Performer/src/lib/libpfdb/libpfdwb for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfdwb for Microsoft Windows.The image in Figure 7-2 shows a model of the Soma Cube puzzle invented by Piet Hein. The model was created using Designer's Workbench. Each of the pieces is stored as an individual DWB-format file. Do you see how to form the 3 x 3 cube at the lower left from the seven individual pieces?

Figure 7-2. Soma Cube Puzzle in DWB Form

pfdLoadFile() uses the function pfdLoadFile_dwb() to load Designer's Workbench files into OpenGL Performer run-time data structures.

The DXF format originated with Autodesk's AutoCAD database modeling system. The version recognized by the pfdLoadFile_dxf() database importer is a subset of ASCII Drawing Interchange Format (DXF) Release 12. The binary version of the DXF format, also known as DXF, is not supported. Source code for the importer is in the file /usr/share/Performer/src/lib/libpfdb/libpfdxf/pfdxf.c for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfdxf\pfdxf.c for Microsoft Windows. pfdLoadFile_dxf() was derived from the DXF-to-DKB data file converter developed and placed in the public domain by Aaron A. Collins.

The image in Figure 7-3 shows a DXF model of the famous Utah teapot. This model was loaded from DXF format using the pfdLoadFile_dxf() database importer.

Figure 7-3. The Famous Teapot in DXF Form

The DXF format has an unusual though well-documented structure. The general organization of a DXF file is the following:

Within each section are groups of values, where each value is defined by a two-line pair of tokens. The first token is a numeric code indicating how to interpret the information on the next line. For example, the sequence

10
1.000
20
5.000
30
3.000

defines a “start point” at the XYZ location (1, 5, 3). The codes 10, 20, and 30 indicate, respectively, that the primary X, Y, and Z values follow. All data values are retained in a set of numbered registers (10, 20, and 30 in this example), which allows values to be reused. This simple state-machine type of run-length coding makes DXF files space-efficient at the cost of making them harder to interpret.

pfdLoadFile() uses the function pfdLoadFile_dxf() to load DXF format files into OpenGL Performer run-time data structures.

Several widely available technical books provide full details of this format if you need more information. Chief among these are AutoCAD Programming, 2nd Edition, by Dennis N. Jump, Windcrest Books, 1991, and AutoCAD: The Complete Reference, Second Edition, by Nelson Johnson, Osborne McGraw-Hill, 1991.

The OpenFlight format is a binary format used for input and output by the MultiGen and ModelGen database modeling tools produced by MultiGen. It is a comprehensive format that can represent nearly all of OpenGL Performer's advanced concepts, including object hierarchy, instancing, level-of-detail selection, light-point specification, texture mapping, and material property specification.

MultiGen has provided an OpenFlight-format importer, pfdLoadFile_flt(), for your use. The loaders and associated documentation are in the directories /usr/share/Performer/src/lib/libpfdb/libpfflt11 and libpfflt for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfflt11 and libpfllt for Microsoft Windows. Refer to the Readme files in these directories for important information about the loaders and for help in contacting MultiGen for information about pfdLoadFile_flt() or the OpenFlight format.

The image in Figure 7-4 shows a model of a spacecraft created by Viewpoint Animation Engineering using MultiGen. This OpenFlight format model was loaded into OpenGL Performer using pfdLoadFile_flt().

Figure 7-4. Spacecraft Model in OpenFlight Format

pfdLoadFile() uses the function pfdLoadFile_flt() to load OpenFlight format files into OpenGL Performer run-time data structures.

Files in the OpenFlight format are structured as a linear sequence of records. The first few bytes of each record are a header containing an op-code, the length of the record, and possibly an ASCII name for the record. The first record in the file is a special “database header” record whose op-code, stored as a 2-byte short integer, has the value 1. This op-code header can be used to identify OpenFlight-format files. By convention, these files have a “.flt” filename extension.

pfdLoadFile_flt() makes use of several environment variables when locating data and texture files. These variables and several additional functions, including pfdConverterMode_flt(), pfdGetConverterMode_flt(), and pfdConverterAttr_flt() assist in OpenFlight file processing.  

The “.gds” format (also known as the “Things” format) is used in at least one CAD system, and a minimal loader for this format has been developed for OpenGL Performer users. The OpenGL Performer loader for “.gds” files is located in the directory /usr/share/Performer/src/lib/libpfdb/libpfgds for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfgds for Microsoft Windows.

The GDS format subset accepted by the pfdLoadFile_gds() function is easy to describe. It consists of the following five sequential sections in an ASCII file:

pfdLoadFile() uses the function pfdLoadFile_gds() to load “.gds” format files into IRIS Performer.

The GFO format is the simple ASCII format of the barcelona database that is provided in the OpenGL Performer sample database directory. This database represents the famous German Pavilion at the Barcelona Exhibition of 1929, which was designed by Ludwig Mies van der Rohe and is shown in Figure 7-5.

Figure 7-5. GFO Database of Mies van der Rohe's German Pavilion

The source code for the GFO-format loader is provided in the file /usr/share/Performer/src/lib/libpfdb/libpfgfo/pfgfo.c for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfgfo\pfgfo.c for Microsoft Windows.

pfdLoadFile() uses the function pfdLoadFile_gfo() to load GFO format files into OpenGL Performer run-time data-structures.

When working with GFO files, remember that hardware lighting is not used since all illumination effects have already been accounted for with the ambient color at each vertex.

The GFO format defines polygons with a color at every vertex. It is the output format of an early radiosity system. Files in this format have a simple ASCII structure, as indicated by the following abbreviated GFO file:

scope {
v3f {42.9632 8.7500 0.9374}
cpack {0x8785a9}
v3f {42.9632 8.0000 0.9374}
cpack {0x8785a9}
...
v3f {-1.0000 -6.5858 10.0000}
cpack {0xffffff}
polygon {cpack[0] v3f[0] cpack[1] v3f[1] cpack[2] v3f[2] cpack[3] v3f[3] }
polygon {cpack[4] v3f[4] cpack[5] v3f[5] cpack[6] v3f[6] cpack[7] v3f[7] }
...
polygon {cpack[7330] v3f[7330] cpack[7331] v3f[7331] cpack[7332] v3f[7332] cpack[7333] v3f[7333] }
instance {
polygon[0]
polygon[1]
...
polygon[2675]
}
}

This example is taken from the file barcelona-l.gfo, one of only two known databases in the GFO format. The importer uses functions from the libpfdu library ( such as those from the pfdBuilder) to generate efficient shared triangle strips. This increases the speed with which GFO databases can be drawn and reduces the size and complexity of the loader, since the builder's functions hide the details of the pfGeoSet construction process.

The “.im” format is a simple format developed for test purposes by the OpenGL Performer engineering team. As new features are added to OpenGL Performer, the “.im” loader is extended to allow experimentation and testing. A recent example of this is support for pfText, pfString, and pfFont objects which can be seen by running Perfly on the sample data file fontsample.im. The OpenGL Performer “.im” loader is in the directory /usr/share/Performer/src/lib/libpfdb/libpfim for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfim for Microsoft Windows.

Here is an example IM format file that creates an extruded 3D text string. Copy this to a file ending in the extension “.im” and load it into Perfly. For a complete example of how text is handled in OpenGL Performer, use Perfly to examine the file /usr/share/Performer/data/fontsample2.im on IRIX and Linux and in %PFROOT%\Data\fontsample2.im on Microsoft Windows.

breakup 0 0.0 0 0
new root top
end_root
 
new font mistr-extruded Mistr 3
end_font
 
new str_text textnode mistr-extruded 1
Hello World||
end_text
 
attach top textnode

pfdLoadFile() uses the function pfdLoadFile_im() to load “.im” format files into OpenGL Performer run-time data structures:

pfdLoadFile_im() searches the current OpenGL Performer file path for the named file and returns a pointer to the pfNode parenting the imported scene graph, or NULL if the file is not readable or does not contain a valid database.

The AAI/Graphicon “.irtp” format is used by the TopGen database modeling system and by the Graphicon-2000 image generator. The name IRTP is an acronym for Interactive Real-Time PHIGS. The OpenGL Performer “.irtp” loader is in the directory /usr/share/Performer/src/lib/libpfdb/libpfirtp for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfirtp for Microsoft Windows. Though loader does not support the more arcane IRTP features, such as binary separating planes or a global matrix table, it has served as a basis for porting applications to OpenGL Performer and the RealityEngine.

pfdLoadFile() uses the function pfdLoadFile_irtp() to load IRTP format files into OpenGL Performer run-time data structures.

The Open Inventor object-oriented 3D-graphics toolkit defines a persistent data format that is also a superset of the VRML networked graphics data format. The image in Figure 7-6 shows a sample Open Inventor data file.

Figure 7-6. Aircar Database in IRIS Inventor Format

The model in Figure 7-6 represents one design for the perennial “personal aircar of the future” concept. It was created, using Imagine, by Mike Halvorson of Impulse, and was modeled after the Moller 400 as described in Popular Mechanics.

The Open Inventor data-file loader provided with OpenGL Performer reads both binary and ASCII format Open Inventor data files. Open Inventor scene graph description files in both formats have the suffix “.iv” appended to their file names.

Here is a simple Open Inventor file that defines a cone:

#Inventor V2.1 ascii
 
Separator {
 Cone {
 }
}

The source code for the Open Inventor format importer is provided in the libpfdb/libpfiv source directory.

pfdLoadFile() uses the function pfdLoadFile_iv() to load Open Inventor format files into OpenGL Performer run-time data-structures. OpenGL Performer also comes with an Inventor loader that works with Open Inventor 2.0, if Open Inventor 2.1 is not installed.

The Lightscape Visualization system is a product of Lightscape Technologies, Inc., and is designed to compute accurate simulations of global illumination within complex 3D environments. The output files created with Lightscape Visualization can be read into OpenGL Performer for real-time visual exploration.

Lightscape Technologies provides importers for two of their database formats, the simple ASCII LSA format and the comprehensive binary LSB format. These loaders are in the files pflsa.c and pflsb.c in the directories /usr/share/Performer/src/lib/libpfdb/libpflsa and libpflsb for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpflsa and libpflsb for Microsoft Windows. Files in the LSA format are in ASCII and have the following components:

There are four types of geometric definitions in LSA files. The formats of these definitions are as shown in Table 7-7.

The Cn values in Table 7-7 refer to colors in the format accepted by the OpenGL function glColor(); these colors should be provided in decimal form. The X, Y, and Z values are vertex coordinates. Polygon vertex ordering in LSA files is consistently counterclockwise, and polygon normals are not specified. The first few lines of the LSA sample file chamber.0.lsa provide an example of the format:

 0.486911  0.03228900  0.979046  0.9596590
-1.665110  0.00944197  0.286293  0.2806240
 0.000000  1.92730000 -0.017805 -0.0174524
 0.240398 -5.54670000 13.021200 13.4945000
 
1782 4751 0 0
 
t 4.35 -7.3677 2.57 6188666 6.5 -9.3 2.57 5663353 4.35 -9.3 2.57 5728890
t 6.5 -9.3 2.57 5663353 4.35 -7.3677 2.57 6188666 6.5 -8.2463 2.57 6057596

The count line indicates that the file contains 1782 independent triangles and 4751 independent quadrilaterals, which together represent 11,284 triangles. The image in Figure 7-7 shows this database, the New Jerusalem City Hall. This was produced by A.J. Diamond of Donald Schmitt and Company, Toronto, Canada, using the Lightscape Visualization system.

Figure 7-7. LSA-Format City Hall Database

pfdLoadFile() uses the function pfdLoadFile_lsa() to load LSA format files into OpenGL Performer run-time data structures.

Files in the LSB binary format have a very different structure from LSA files. Representing not just polygon data, they contain much of the structural information present in the “.ls” files used by the Lightscape Visualization system, including material, layer, and texture definitions as well as a hierarchical mesh definition for geometry. This information is structured as a series of data sections, which include the following:

The format of the geometric clusters is somewhat complicated. A cluster is a group of coplanar surfaces called patches that share a common material, layer, and normal. Each patch shares at least one edge with another patch in the cluster. Each patch defines either a convex quadrilateral or a triangle, and patches represent quad-trees called nodes. Each node points to its corner vertices and its children. The leaf nodes point to their corner vertices and the child pointers can optionally point to the vertices that split an edge of the node. Only the locations of vertices that are corners of the patches are stored in the file; other vertices are created by subdividing nodes of the quad-tree as the LSB file is loaded. The color information for each vertex is unique and is specified in the file.

The image in Figure 7-8 shows an LSB-format database developed during the design of a hospital operating room. This database was produced by the DeWolff Partnership of Rochester, New York, using the Lightscape Visualization system.

Figure 7-8. LSB-Format Operating Room Database

pfdLoadFile() uses the function pfdLoadFile_lsb() to load LSB format files into OpenGL Performer run-time data structures.

When working with Lightscape Technologies files, remember that hardware lighting is not needed because all illumination effects have already been accounted for with the ambient color at each vertex.

The “.medit” format is used by the Medit database modeling system produced by Medit Productions. The OpenGL Performer “.medit” loader is in the directory /usr/share/Performer/src/lib/libpfdb/libpfmedit for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfmedit for Microsoft Windows.

pfdLoadFile() uses the function pfdLoadFile_medit() to load MEDIT format files into OpenGL Performer run-time data structures.

The “.nff” format was developed by Eric Haines as a way to provide standard procedural databases for evaluating ray tracing software. OpenGL Performer includes an extended NFF loader with superquadric torus support, a named build keyword, and numerous small bug fixes. The “.nff” loader is located in the directory /usr/share/Performer/src/lib/libpfdb/libpfnff for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfnff for Microsoft Windows.

The file /usr/share/Performer/data/sampler.nff on IRIX and Linux and %PFROOT%\Data\sampler.nff on Microsoft Windows uses each of the NFF data types. It is an excellent way to explore the “Show Tree”, “Draw Style”, and “Highlight Mode” features of Perfly. It is included here:

#-- torus
f .75 .00 .25 .6 .8 20 0
t 5 5 0 0 0 1 2 1
build torus
 
#-- cylinder
f .00 .75 .25 .6 .8 20 0
c
15 5 -3 2
15 5 3 2
#-- put a disc on the top and bottom of the cylinder
d 15 5 -3 0 0 -1 0 2
d 15 5 3 0 0 1 0 2
build cylinder
 
#-- cone
f .00 .25 .75 .6 .8 20 0
c
25 5 -3 3
25 5 3 0
#-- put a disc on the bottom of the cone
d 25 5 -3 0 0 -1 0 3
build cone
 
#-- sphere
f .75 .00 .75 .6 .8 20 0
s 5 15 0 3
build sphere
 
#-- hexahedron
f .25 .25 .50 .6 .8 20 0
h 13 13 -2 17 17 2
build hexahedron
 
#-- superquadric sphere
f .80 .10 .30 .6 .8 20 0
ss 25 15 0 2 2 2 .1 .4
build superquadric_sphere
 
#-- disc (washer shape)
f .20 .20 .90 .6 .8 20 0
d 5 25 0 0 0 1 1 2.5
build disc
 
#-- grid (height field)
f .80 .80 .10 .6 .8 20 0
g 4 4 12 18 22 28 0 4
0 0 0 0
0 1 0 0
0 0 -1 0
0 0 0 0
build grid
 
#-- superquadric torid
f .40 .20 .60 .6 .8 20 0
st 25 25 0 0.5 0.5 0.5 .33 .33 3
build superquadric_torid
 
#-- polygon with no normals
f .20 .20 .20 .6 .8 20 0
p 4
-5 -5 -10
35 -5 -10
35 35 -10
-5 35 -10
build polygon

pfdLoadFile() uses the function pfdLoadFile_nff() to load NFF format files into OpenGL Performer run-time data structures.

The OBJ format is an ASCII data representation read and written by the Wavefront Technology Model program. A number of database models in this format have been placed in the public domain, making this a useful format to have available. OpenGL Performer provides the function pfdLoadFile_obj() to import OBJ files. The source code for pfdLoadFile_obj() is in the file pfobj.c in the loader source directory /usr/share/Performer/src/lib/libpfdb/libpfobj for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfobj for Microsoft Windows.

The OBJ-format database shown in Figure 7-9 models an office building that is part of the SGI corporate campus in Mountain View, California.

Figure 7-9. SGI Office Building as OBJ Database

Files in the OBJ format have a flexible all-ASCII structure, with simple keywords to direct the parsing of the data. This format is best illustrated with a short example that defines a texture-mapped square:

#-- `v' defines a vertex; here are four vertices
v -5.000000  5.000000 0.000000
v -5.000000 -5.000000 0.000000
v  5.000000 -5.000000 0.000000
v  5.000000  5.000000 0.000000
 
#-- `vt' defines a vertex texture coordinate; four are given
vt 0.000000 1.000000 0.000000
vt 0.000000 0.000000 0.000000
vt 1.000000 0.000000 0.000000
vt 1.000000 1.000000 0.000000
 
#-- `usemtl' means select the material definition defined
#-- by the name MaterialName
usemtl MaterialName
 
#-- `usemap' means select the texturing definition defined
#-- by the name TextureName
usemap TextureName
 
#-- `f' defines a face. This face has four vertices ordered
#-- counterclockwise from the upper left in both geometric
#-- and texture coordinates. Each pair of numbers separated
#-- by a slash indicates vertex and texture indices,
#-- respectively, for a polygon vertex.
f 1/1 2/2 3/3 4/4

pfdLoadFile() uses the function pfdLoadFile_obj() to load Wavefront OBJ files into OpenGL Performer run-time data structures.

---

Note: The PFB format is undocumented and is subject to change.

---

Although OpenGL Performer has no true native database format, the PFB format is designed to exactly replicate the OpenGL Performer scene graph; this design increases loading speed. A file in the PFB format has the following advantages:

You can think of the PFB format as being a cache. You can convert your files into PFB for fast and efficient loading or paging, but you should always keep your original files in case you wish to modify them.

The PFI image file format is designed for fast loading of images into pfTextures. pfLoadTexFile() can load PFI files as the image of a pfTexture. Since the format of the image in a PFI file matches that of a pfTexture, data is not reformatted at load time. Eliminating the reformatting often cuts the load time of textures to half of the load time of the same image in the IRIS RGB image format.

PFI files can contain the mipmaps of the image. This feature saves significant time in the OpenGL Performer DRAW process since it does not have to generate the mipmaps.

The PHD format was created to describe the geometric polyhedron definitions derived mathematically by Andrew Hume and by the Kaleido program of Zvi Har'El. This format describes only the geometric shape of polyhedra; it provides no specification for color, texture, or appearance attributes such as specularity.

The OpenGL Performer sample data directories contain numerous polyhedra in the PHD format. The image in Figure 7-10 shows many of the polyhedron definitions laboriously computed by Andrew Hume.

Figure 7-10. Plethora of Polyhedra in PHD Format

The source code for the PHD-format importer is in the file /usr/share/Performer/src/lib/libpfdb/libpfpoly/pfphd.c on IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfpoly\pfdhd.c on Microsoft Windows.

PHD format files have a line-structured ASCII form; an initial keyword defines the contents of each line of data. The file format consists of a filename definition (introduced by the keyword file) followed by one or more object definitions.

Object definitions are bracketed by the keywords object.begin and object.end and contain one or more polygon definitions. Objects can have a name in quotes following the object.begin keyword; such a name is used by the loader for the name of the corresponding OpenGL Performer node.

Polygon definitions are bracketed by the keywords polygon.begin and polygon.end and contain three or more vertex definitions.

Vertex definitions are introduced by the vertex keyword and define the X, Y, and Z coordinates of a single vertex.

The following is a PHD-format definition of a unit-radius tetrahedron centered at the origin of the coordinate axes. It is derived from the database developed by Andrew Hume but has since been translated, scaled, and reformatted.

file 000.phd
object.begin "tetrahedron"
polygon.begin
vertex -0.090722 -0.366647  0.925925
vertex  0.544331 -0.628540 -0.555555
vertex  0.453608  0.890430  0.037037
polygon.end
polygon.begin
vertex -0.907218  0.104757 -0.407407
vertex -0.090722 -0.366647  0.925925
vertex  0.453608  0.890430  0.037037
polygon.end
polygon.begin
vertex -0.090722 -0.366647  0.925925
vertex -0.907218  0.104757 -0.407407
vertex  0.544331 -0.628540 -0.555555
polygon.end
polygon.begin
vertex  0.453608  0.890430  0.037037
vertex  0.544331 -0.628540 -0.555555
vertex -0.907218  0.104757 -0.407407
polygon.end
object.end

pfdLoadFile() uses the function pfdLoadFile_phd() to load PHD format files into OpenGL Performer run-time data structures.

The pfdLoadFile_phd() function composes a color with red, green, and blue components uniformly distributed within the range 0.2 to 0.7 that is consistent for each polygon with the same number of vertices within a single polyhedron.

The PTU format is named for the OpenGL Performer Terrain Utilities, of which the pfdLoadFile_ptu() function is the sole example at the present time. This function accepts as input the name of a control file (the file with the “.ptu” filename extension) that defines the desired terrain parameters and references additional data files.

The database shown in Figure 7-11 represents a portion of the Yellowstone National Park. This terrain database was generated completely by the OpenGL Performer Terrain Utility data generator from digital terrain elevation data and satellite photographic images. Image manipulation is performed using the SGI ImageVision Library functions.

Figure 7-11. Terrain Database Generated by PTU Tools

The PTU control file has a fixed format that does not use keywords. The contents of this file are simply ASCII values representing the following data items:

The source code for the PTU-format importer is provided in the file /usr/share/Performer/src/lib/libpfdb/libpfptu/pfptu.c on IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfptu\pfptu.c on Microsoft Windows.

pfdLoadFile() uses the function pfdLoadFile_ptu() to load PTU format files into OpenGL Performer run-time data structures.

ArchVision provides the rich photorealistic content (RPC) loader. The RPC loader loads in images from an ArchVision RPC file. The images represent views of an object from a set of directions around the object. If you provide an existing pfIBRnode, the images are loaded into a pfIBRtexture of the node. Otherwise, the function creates a new pfIBRnode with a single pfGeoSet and a pfIBRtexture containing the images. In the case of new content with meshes, the pfGeoSet contains the mesh, which becomes the proxy in the pfIBRnode.

The following functions allow you to access and alter the modes, values, and attributes of the RPC loader:

You control the RPC converter modes with the token PFRPC_USE_USER_IBRNODE. By default, the loader creates a pfIBRnode with a single pfGeoSet and a pfIBRtexture that contains the loaded images. If this mode is set to PF_ON and you supply a pfIBRnode using pfdConverterAttr_rpc(), the images are loaded into the pfIBRtexture of that node.

Table 7-8 describes the RPC converter values.

Table 7-9 describes the converter attributes.

---

Note: The loader is using a relatively slow, third-party routine for decompressing images. For a faster load time, you may want to convert your RPC files into PFB files using pfconv.

---

Two sample RPC files can be found in directory /usr/share/Performer/data/ibr/rpc for IRIX and Linux and in %PFROOT%\Data\ibr\rpc for MicroSoft Windows. You can download other files from the ArchVision webpage at www.archvision.com.

The SGF format is used at the United States Naval Academy as a standard graphics format for geometric data. The loader was developed based on the description of the standard graphics format as described by David F. Rogers and J. Alan Adams in the book Mathematical Elements for Computer Graphics. The OpenGL Performer “.sgf” format loader is located in the directory /usr/share/Performer/src/lib/libpfdb/libpfsgf for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfsgf for Microsoft Windows

Here is the vector definition for four stacked squares in SGF form:

0, 0, 0
1, 0, 0
1, 1, 0
0, 1, 0
0, 0, 0
1.0e37, 1.0e37, 1.0e37
0, 0, 1
1, 0, 1
1, 1, 1
0, 1, 1
0, 0, 1
1.0e37, 1.0e37, 1.0e37
0, 0, 2
1, 0, 2
1, 1, 2
0, 1, 2
0, 0, 2
1.0e37, 1.0e37, 1.0e37
0, 0, 3
1, 0, 3
1, 1, 3
0, 1, 3
0, 0, 3
1.0e37, 1.0e37, 1.0e37

pfdLoadFile() uses the function pfdLoadFile_sgf() to load SGF format files into OpenGL Performer run-time data-structures.

The SGI Object format is used by several utility programs and was one of the first database formats supported by OpenGL Performer. The image in Figure 7-12 shows a model generated by Paul Haeberli and loaded into Perfly by the pfdLoadFile_sgo() database importer.

Figure 7-12. Model in SGO Format

Objects in the SGO format have per-vertex color specification and multiple data formats. Objects contained in SGO files are constructed from three data types:

Objects of different types can be included as data within one SGO file.

The SGO format has the following structure:

The layout of an SGO file is the following:

<SGO-file magic number>
<data-type token for object #1>
<data for object #1>
<data-type token for object #2>
<data for object #2>
...
<data-type token for object #n>
<data for object #n>
<end-of-data token>

Each of the identifying tokens is 4 bytes long. Table 7-10 lists the symbol, value, and meaning for each token.

The next word following any of the three object types is the number of 4-byte words of data for that object. The format of this data varies depending on the object type.

For quadrilateral list (OBJ_QUADLIST) and triangle list (OBJ_TRILIST) objects, there are nine words of floating-point data for each vertex, as follows:

In quadrilateral lists, vertices are in groups of four; so, there are 4 × 9 = 36 words of data for each quadrilateral. In triangle lists, vertices are in groups of three, for 3 x 9 = 27 words per triangle.

The triangle mesh, OBJ_TRIMESH, is the most complicated of the three object data types. Triangle mesh data consists of a set of vertices followed by a set of mesh-control commands. Triangle mesh data has the following format:

The triangle mesh controls, each of which is one word in length, are listed in Table 7-11.

The triangle-mesh controls are interpreted sequentially. The first control must always be OP_BGNTMESH, which initiates the mesh-decoding logic. After each mesh control is a word (of type long integer) that indicates how many vertex indices follow. The vertex indices are in byte offsets, so to access vertex n, you must use the byte offset n x 9 x 4.

pfdLoadFile() uses the function pfdLoadFile_sgo() to load SGO format files into OpenGL Performer run-time data structures.

You can find the source code for the SGO-format importer in the file pfsgo.c. This importer does not attempt to decode any triangle meshes present in input files; instead, it terminates the file conversion process as soon as an OBJ_TRIMESH data-type token is encountered. If you use SGO-format files containing triangle meshes you will need to extend the conversion support to include the triangle mesh data type.

The “.spf” format is used at the United States Naval Academy as a simple polygon file format for geometric data. The loader was developed based on the description in the book Mathematical Elements for Computer Graphics. The OpenGL Performer “.spf” loader is in the directory /usr/share/Performer/src/lib/libpfdb/libpfspf on IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfspf on Microsoft Windows.

The following “.spf” format file is defined in that book.

polygon with a hole
14,2
4,4
4,26
20,26
28,18
28,4
21,4
21,8
10,8
10,4
10,12
10,20
17,20
21,16
21,12
9,1,2,3,4,5,6,7,8,9
5,10,11,12,13,14

If you look at this file in Perfly, you will see that the hole is not cut out of the letter “A” as might be desired. Such computational geometry computations are not considered the province of simple database loaders.

pfdLoadFile() uses the function pfdLoadFile_spf() to load SPF format files into OpenGL Performer run-time data structures.

The Sierpinski Sponge (also known as Menger Sponge) loader is not based on a data format but rather is a procedural data generator. The loader interprets the portion of the user-provided filename before the period and extension as an integer which specifies the number of recursive subdivisions desired in data generation. For example, providing the pseudo filename “3.sponge” to Perfly will result in the Sponge loader being invoked and generating a sponge object using three levels of recursion, resulting in a 35712 polygon database object. The OpenGL Performer “.sponge” loader can be found in the directory /usr/share/Performer/src/lib/libpfdb/libpfsponge on IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfsponge on Microsoft Windows.

pfdLoadFile() uses the function pfdLoadFile_sponge() to load Sponge format files into OpenGL Performer run-time data structures.

The “.star” format is a distillation of astronomical data from the Yale Compact Star Chart (YCSC). The sample data file /usr/share/Performer/data/3010.star for IRIX and Linux and %PFROOT%\Data\3010.star for Microsoft Windows contains data from the YCSC that has been reduced to a list of the 3010 brightest stars as seen from Earth and positioned as 3010 points of light on a unit-radius sphere. The OpenGL Performer “.star” loader can read this data and is provided as a convenience for making dusk, dawn, and night-time scenes. The loader is in the directory /usr/share/Performer/src/lib/libpfdb/libpfstar on IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfstar on Microsoft Windows.

Data in a “.star” file is simply a series of ASCII lines with the “s” (for star) keyword followed by X, Y, and Z coordinates, brightness, and an optional name. Here are the 10 brightest stars (excluding Sol) in the “.star” format:

s -0.18746032  0.93921369 -0.28763914 1.00 Sirius
s -0.06323564  0.60291260 -0.79529721 1.00 Canopus
s -0.78377002 -0.52700269  0.32859191 1.00 Arcturus
s  0.18718566  0.73014212  0.65715599 1.00 Capella
s  0.12507832 -0.76942003  0.62637711 0.99 Vega
s  0.13051330  0.68228769  0.71933979 0.99 Capella
s  0.19507207  0.97036278 -0.14262892 0.98 Rigel
s -0.37387931 -0.31261155 -0.87320572 0.94 Rigil Kentaurus
s -0.41809806  0.90381104  0.09121194 0.94 Procyon
s  0.49255905  0.22369388 -0.84103900 0.92 Achernar

pfdLoadFile() uses the function pfdLoadFile_star() to load Star format files into OpenGL Performer run-time data structures.

The STL format is used to define 3D solids to be imaged by 3D lithography systems. STL defines objects as collections of triangular facets, each with an associated face normal. The ASCII version of this format is known as STLA and has a very simple structure.

The image in Figure 7-13 shows a typical STLA mechanical CAD database. This model is defined in the bendix.stla sample data file.

Figure 7-13. Sample STLA Database

The source code for the STLA-format loader is in the files /usr/share/Performer/src/lib/libpfdb/libpfstla/pfstla.c on IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfstla\pfstla.c on Microsoft Windows.

STLA-format files have a line-structured ASCII form; an initial keyword defines the contents of each line of data. An STLA file consists of one or more facet definitions, each of which contains the following:

Here is an excerpt from nut.stla, one of the STLA files provided in the OpenGL Performer sample data directories. These are the first two polygons of a 524-triangle hex-nut object:

facet normal 0 -1 0
 outer loop
  vertex 0.180666 -7.62 2.70757
  vertex -4.78652 -7.62 1.76185
  vertex -4.436 -7.62 0
 endloop
endfacet
facet normal -0.381579 -0.921214 -0.075915
 outer loop
  vertex -4.48833 -7.59833 0
  vertex -4.436 -7.62 0
  vertex -4.78652 -7.62 1.76185
 endloop
endfacet

Use this function to import data from STLA-format files into OpenGL Performer run-time data structures:

pfNode *pfdLoadFile_stla(char *fileName);

pfdLoadFile_stla() searches the current OpenGL Performer file path for the file named by the fileName argument and returns a pointer to the pfNode that parents the imported scene graph, or NULL if the file is not readable or does not contain recognizable STLA format data.

The SuperViewer (SV) format is one of the several database formats that the I3DM database modeling tool can read and write. The I3DM modeler was developed by John Kichury of SGI and is provided with OpenGL Performer. The source code for the SV format importer is in the file pfsv.c.

The passenger vehicle database shown in Figure 7-14 was modeled using I3DM and is stored in the SV database format.

Figure 7-14. Early Automobile in SuperViewer SV Format

Within SV files, object geometry and attributes are described between text lines that contain the keywords model and endmodel. For example:

model wing
geometry and attributes
endmodel

Any number of models can appear within a SuperViewer file. The geometry and attribute data mentioned above each consist of one of the following types:

In actual use the SV format is somewhat self-documenting. Here is part of the SV file apple.sv from the directory /usr/share/Performer/data on IRIX and Linux and in %PFROOT%\Data on Microsoft Windows:

material 20 0.0 0.0 0 0.400000 0.000000 0 0.333333 0.000000 0.0 10.0000 0 0 0
material 42 0.2 0.2 0 0.666667 0.666667 0 0.800000 0.800000 0.8 94.1606 0 0 0
material 44 0.0 0.2 0 0.000000 0.200000 0 0.000000 0.266667 0.0  5.0000 0 0 0
 
texture 4 prchmnt.rgb
texture 6 wood.rgb
 
model LEAF
material 44
texture 4
backface on
poly3dn 4 textured
 1.35265 1.35761 13.8338 0.0686595 -0.234553 -0.969676 0 1
 0.88243 0.96366 14.0329 0.0502096 -0.376701 -0.924973 0 0.75
-4.44467 1.24026 13.5669 0.0363863 -0.337291 -0.940697 0.0909091 0.75
-2.37938 2.17479 13.3626 0.0363863 -0.337291 -0.940697 0.0909091 1
poly3dn 4 textured
-2.37938 2.17479 13.3626 0.0363863 -0.337291 -0.940697 0.0909091 1
-4.44467 1.24026 13.5669 0.0363863 -0.337291 -0.940697 0.0909091 0.75
-9.23775 2.34664 13.1475 0.0344832 -0.284369 -0.958095 0.181818 0.75
-6.69592 3.94535 12.6716 0.0344832 -0.284369 -0.958095 0.181818 1

This excerpt specifies material properties and references texture images stored in the files prchmnt.rgb and wood.rgb, and then defines two polygons.

pfdLoadFile() uses the function pfdLoadFile_sv() to load SuperViewer files into OpenGL Performer run-time data structures.

The “.tri” format is used at the University of Minnesota's Geometry Center as a simple geometric data representation. The loader was developed by inspection of a few sample files. The OpenGL Performer “.tri” loader is in the directory /usr/share/Performer/src/lib/libpfdb/libpftri on IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpftri on Microsoft Windows.

These files have a very simple format: a line per vertex with position and normal given on each line as 6 ASCII numeric values. The file is simply a series of these triangle definitions. Here are the first two triangles from the data file /usr/share/Performer/data/mobrect.tri on IRIX and Linux and in %PFROOT%\Data\mobrect.tri on Microsoft Windows:

1.788180  1.000870 0.135214 0.076169 -0.085488 0.993423
1.574000  0.925908 0.146652 0.089015 -0.086072 0.992304
1.793360  0.634711 0.099409 0.076402 -0.111845 0.990784
0.836848 -0.595230 0.197960 0.156677  0.044503 0.986647
0.709638 -0.345676 0.210010 0.157642  0.021968 0.987252
0.581200 -0.535321 0.234807 0.145068  0.030985 0.988936

pfdLoadFile() uses the function pfdLoadFile_tri() to load “.tri” format files into OpenGL Performer run-time data structures.

The “.unc” format was once used at the University of North Carolina as a format for geometric data in an architectural walkthrough application. The loader was developed based on inspection of a few sample files. The OpenGL Performer “.unc” loader is in the directory /usr/share/Performer/src/lib/libpfdb/libpfunc for IRIX and Linux and in %PFROOT%\Src\lib\libpfdb\libpfunc for Microsoft Windows.

pfdLoadFile() uses the function pfdLoadFile_unc() to load UNC format files into OpenGL Performer run-time data structures.

The VRML 2.0 format for OpenGL Performer, wrl, is made by DRaW Computing Associates. It accepts geometry and texture only. Basic geometry nodes like Sphere, Cone, Cylinder, Box and related nodes like Shape, Material, Appearance, TextureTransform, ImageTexture, and ElevationGrid are supported. Also, complex geometries can be obtained using the IndexedFaceSet node. You can do geometric manipulations to nodes using Group nodes and Transform nodes. You can also make very complex structures using PROTOs, where you group many geometry nodes.

The Maya exporter should be installed for you automatically as part of the OpenGL Performer installation process. You must have a licensed copy of Maya 4.5 or later installed on every machine that runs the exporter because it is a Maya plug-in and can only run within the Maya environment. This differs from previous OpenGL Performer file loaders that run within the OpenGL Performer environment. The Maya exporter is available for both IRIX and Windows, but not for Linux.

The .pfa and .pfb files produced by the Maya exporter can be viewed on any machine with OpenGL Performer 3.1 or later installed. These files are not compatible with previous versions of OpenGL Performer. Maya has capabilities like subdivision surfaces and non-uniform rational B-splines (NURBS) that require the OpenGL Performer 3.1 or later run-time environment. The exporter can optimize geometry to take advantage of the new OpenGL extensions available on Onyx4 systems. These extensions also need OpenGL Performer 3.1 or later support.

If you launch Maya and it cannot find the plug-in, you can troubleshoot by checking the MAYA_PLUG_IN_PATH and MAYA_SCRIPT_PATH environment variables. Both variables should be defined at installation to reference the OpenGL Performer directory containing the Maya extensions.

Table 7-13 shows the default path for IRIX and Microsoft Windows.

Any Maya scene can be exported to OpenGL Performer format. Unsupported features will be flagged in the export log file and may result in objects missing from the scene when viewed with OpenGL Performer. To run the plug-in from the Maya graphical user interface, use the Export All or Export Selection items from the File menu. As shown in Figure 7-15, you should be able to select PFBexport as one of the file types. The only supported extensions are .pfb and .pfa.

Figure 7-15. Maya Export Screen

There are a number of parameters that control how Maya content is translated to OpenGL Performer format. You can produce exported files that take advantage of OpenGL extensions for multitexturing and vertex buffer objects but you must be running Maya on a platform which has these features. In general, OpenGL Performer .pfa and .pfb files are cross-platform and can be successfully imported on machines that are less-capable than where they originated with some loss of fidelity. For example, displaying a multitextured object on an Octane will drop all textures but the first.

As shown in Figure 7-16, you can optimize for earlier versions of SGI hardware by choosing Optimize for OpenGL 1.0. If you have have an Onyx 4 system, do not check this option or you will not get the best graphics performance. If your graphics hardware does not have multitexturing capabilities, do check this option.

Figure 7-16. Maya Export Options

Table 7-14 describes the export options.

If you are familiar with MEL, the Maya scripting language, you can invoke the OpenGL Performer export plug-in from within a script. This allows you to do batch translation of Maya files to OpenGL Performer. The following sample MEL script converts all of the Maya binary (.mb) files in a given directory to OpenGL Performer binary (.pfb) format:

global proc int ExportAsPFB(string $indir, string $opts)
{
    string $infile;
    string $outfile;
    string $files[];
    string $s;
    int $succeed = 1;

    if ($opts == "")
        $opts = "textures=1;width=256;height=256;indexed=1;tristrip=1;"
                "gl1=1;preview=0;";
    if ($indir == "")
        $indir = "./";
    setProject $indir;
    $files=`getFileList -folder $indir -filespec "*.mb"`;

    for ($infile in $files)
    {
        $outfile = $indir + substring($infile, 1, size($infile) - 3) +
                   ".pfb";
        $infile = $indir + $infile;
        file -open -force $infile;
        $s = `file -exportAll -type "PFBexport" -options $opts -force
             $outfile`;
        $succeed = `file -query -exists $s`;
        if (!$succeed)
            $s = "ERROR: failed to export " + $outfile + "\n";
        else
            $s = "exported " + $s + "\n";
        print $s;
    }
    return $succeed;
}

This section describes the translation of Maya scenes to OpenGL Performer using the following topics: