You can control transparency using pfTransparency(). Possible transparency modes are listed in the following table.

In addition, the flag PFTR_NO_OCCLUDE may be logically ORed into the transparency mode in which case geometry will not write depth values into the frame buffer. This will prevent it from occluding subsequently rendered geometry. Enabling this flag improves the appearance of unordered, blended transparent surfaces.

There are two basic transparency mechanisms: screen-door transparency, which requires hardware multisampling, and blending. Blending offers very high-quality transparency but for proper results requires that transparent surfaces be rendered in back-to-front order after all opaque geometry has been drawn. When using transparent texture maps to “etch” geometry or if the surface has constant transparency, screen-door transparency is usually good enough. Blended transparency is usually required to avoid “banding” on surfaces with low transparency gradients like clouds and smoke.

You can select either flat shading or Gouraud (smooth) shading. pfShadeModel() takes one of two tokens: PFSM_FLAT or PFSM_GOURAUD. One some graphics hardware flat shading can offer a significant performance advantage.

The pfAlphaFunc() function is an extension of the glAlphaFunc() function; it allows OpenGL Performer to keep track of the hardware mode. The alpha function is a pixel test that compares the incoming alpha to a reference value and uses the result to determine whether or not the pixel is rendered. The reference value must be specified in the range [0, 1]. For example, a pixel whose alpha value is 0 is not rendered if the alpha function is PFAF_GREATER and the alpha reference value is also 0. Note that rejecting pixels-based alpha can be faster than using transparency alone. A common technique for improving the performance of filling polygons is to set an alpha function that will reject pixels of low (possibly nonzero) contribution. The alpha function is typically used for see-through textures like trees.

On Z-buffer-based graphics hardware, coplanar geometry can cause unwanted artifacts due to the finite numerical precision of the hardware which cannot accurately resolve which surface has visual priority. This can result in flimmering, a visual “tearing” or “twinkling” of the surfaces. pfDecal() is used to accurately draw coplanar geometry on SGI graphics platforms and it supports two basic implementation methods : stencil decaling and displace decaling.

The stencil decaling method uses a hardware resource known as a stencil buffer and requires that a single stencil plane (see the man page for glStencilOp()) be available for OpenGL Performer. This method offers the highest image quality but requires that geometry be coplanar and rendered in a specific order which reduces opportunities for the performance advantage of sorting by graphics mode.

A potentially faster method is the displace decaling method. In this case, each layer is displaced towards the eye so it hovers slightly above the preceding layer. Displaced decals need not be coplanar, and can be drawn in any orde, but the displacement may cause geometry to incorrectly poke through other geometry.

The specificaton of a decal plane can improve the displace decaling method. The object geometry will be projected onto the specified plane and if the same plane is specified for base and layer geometry, the base and layer polygons will be generated with identical depth values. If the objects are drawn in priority order, no further operation is necessary. Otherwise, displace can be applied to the planed geometry for a superior result. Decal planes can be specified on pfGeoSets with pfGSetDecalPlane(), on a pfGeoState with the PFSTATE_DECALPLANE attribute to pfGStateAttr(), or globally with pfApplyDecalPlane().

Decals consist of base geometry and layer geometry. The base defines the depth values of the decal while layer geometry is simply inlaid on top of the base. Multiple layers are supported but limited to eight when using displaced decals. Realize that these layers imply superposition; there is no limit to the number of polygons in a layer, only to the number of distinct layers.

The decal mode indicates whether the subsequent geometry is base or layer and the decal method to use. For example, a mode of PFDECAL_BASE_STENCIL means that subsequent geometry is to be considered as base geometry and drawn using the stencil method. All combinations of base/layer and displace/stencil modes are supported but you should make sure to use the same method for a given base-layer pair.

Example 12-1 illustrates the use of pfDecal().

Example 12-1. Using pfDecal() to a Draw Road with Stripes

pfDecal(PFDECAL_BASE_STENCIL); /* ... draw underlying geometry (roadway) here ...*/ pfDecal(PFDECAL_LAYER_STENCIL); /* ... draw coplanar layer geometry (stripes) here ... */ pfDecal(PFDECAL_OFF);

---

Note: libpf applications can use the pfLayer node to include decals within a scene graph.

---

The  pfCullFace() function controls which side of a polygon (if any) is discarded in the Geometry Pipeline. Polygons are either front-facing or back-facing. A front-facing polygon is described by a counterclockwise order of vertices in screen coordinates, and a back-facing one has a clockwise order. pfCullFace() has four possible arguments:

In particular, back-face culling is highly recommended since it offers a significant performance advantage for databases where polygons are never be seen from both sides (databases of “solid” objects or with constrained eyepoints).

The pfAntialias() function is used to turn the antialiasing mode of the hardware on or off. Currently, antialiasing is implemented differently by each different graphics system. Antialiasing can produce artifacts as a result of the way OpenGL Performer and the active hardware platform implement the feature. See the man page for pfAntialias() for implementation details.

OpenGL Performer supports texturing through pfTextures and pfTexEnvs, which provide encapsulated suppport for graphics library textures (see glTexImage2D() ) and texture environments (see glTexEnv()). A pfTexture defines a texture image, format, and filtering. A pfTexEnv specifies how the texture should interact with the colors of the geometry where it is applied. You need both to display textured data, but you do not need to specify them both at the same time. For example, you could have pfGeoStates each of which had a different texture specified as an attribute and still use an overall texture environment specified with pfApplyTEnv().

A pfTexture is created by calling pfNewTex(). If the desired texture image exists as a disk file in IRIS RGB image format (the file often has a “.rgb” suffix ) or in the OpenGL Performer fast-loading image format (a “.pfi” suffix), you can call pfLoadTexFile() to load the image into CPU memory and completely configure the pfTexture, as shown in the following:

pfTexture *tex = pfLoadTexFile(“brick.rgba”);

Otherwise, pfTexImage() lets you directly provide a GL-ready image array in the same external format as specified on the pfTexture and as expected by glTexImage2D(), as shown in the following:

void pfTexImage(pfTexture* tex, uint* image, 
int comp, int sx, int sy, int sz);

OpenGL expects packed texture data with each row beginning on a long word boundary. However, OpenGL expects the individual components of a texel to be packed in opposite order. For example, OpenGL expects the texels to be packed as RGBA. If you provide your own image array in a multiprocessing environment, it should be allocated from shared memory (along with your pfTexture) to allow different processes to access it. A basic example demonstrating loading a image file and placing the resulting pfTexture on scene graph geometry is at /usr/share/Performer/src/pguide/libpf/C/texture.c on IRIX and Linux and %PFROOT%\Src\pguide\libpf\C\texture.c on Microsoft Windows.

---

Note: The size of your texture must be an integral power of two on each side. OpenGL refuses to accept badly sized textures. You can rescale your texture images with the izoom or imgworks programs (shipped with IRIX 5.3 in the eoe2.sw.imagetools and imgtools.sw.tools subsystems; and with IRIX 6.2 in the eoe.sw.imagetools and imgworks.sw.tools subsystems).

---

Your texture source does not have to be a static image. pfTexLoadMode() can be used to set one of the sources listed in Table 12-6 with  PFTEX_LOAD_SOURCE. Note that sources other than CPU memory may not be supported on all graphics platforms, or may have some special restrictions. There are several sample programs that demonstrate paging sequences of texture from different texture sources. For paging from host memory there are the following:

These examples demonstrate the use of different texture sources for paging textures, and libpufitl utilties for managing texture resources. One thing these examples do is use pfTexLoadImage() to update the pointer to the image data to avoid the expensive reformating the texture. This requires that the provided image data be the same size as the original image data, as well as same number of components and same formats.

The source of texture image data can be live video input. OpenGL Performer supports the video input mechanisms of Sirius Video on RealityEngine and InfiniteReality, DIVO on InfiniteReality, and Silicon Graphics O2 and Octane video input. OpenGL Performer includes a sample program that features video texturing:

/usr/share/Performer/src/pguide/libpf/movietex.c (IRIX and Linux) %PFROOT%\Src\pguide\libpf\movietex.c (Microsoft Windows)

This example demonstrates that all video initialization, including the creation of video library resources, is done in the draw process, as required by the video library. Part of that initialization includes setting the proper number of components on the pfTexture and choosing a texture filter and potentially internal format. Those basic operations are discussed further in this section.

OpenGL Performer will automatically download the frame of video when the texture object is applied through the referencing pfGeoState. Alternatively, you may want to schedule this download to happen at the beginning or end of the rendering frame; you can force it with pfLoadTex().

Textures must be created with sizes that are powers of 2; the input video frame is usually not in powers of 2. The [0,1] texture coordinate range can be scaled into the valid part of the pfTexture with a texture matrix. This matrix can be applied directly to the global state with pfApplyTMat() to affect all pfGeoSets, or can be set on a pfGeoState with the PFSTATE_TEXMAT attribute to pfGStateAttr().

Texture storage is limited only by virtual memory, but for real-time applications you must consider the amount of texture storage the graphics hardware supports. Textures that do not fit in the graphics subsystem are paged as needed when pfApplyTex() is called. The libpr library provides routines for managing hardware texture memory so that a real-time application does not have to get a surprise texture load. pfIsTexLoaded(), called from the drawing process, tells you if the pfTexture is currently properly loaded in texture memory. The initially required textures of an application, or all of the textures if they fit, can be preloaded into texture memory as part of application initialization. pfuMakeSceneTexList() makes a list of all textures referenced by a scene graph and pfuDownloadTexList() loads a list of textures into hardware texture memory (and must be called in the draw process). The Perfly sample program does this as part of its initialization and displays the textures as it preloads them.

There are additional routines to assist with the progressive loading and unloading of pfTextures. pfIdleTex() can be used to free the hardware texture memory owned by a pfTexture. GL host and hardware texture memory resources can be freed with pfDeleteGLHandle() from the drawing process. OpenGL Performer will automatically re-allocate those resources if the pfTexture is used again. For an example of management of texture resources, see the example program /usr/share/Performer/src/pguide/libpfutil/texmem.c for IRIX and Linux or %PFROOT%\Src\pguide\libpfutil\texmem.c for Microsoft Windows. The program uses the pfuTextureManager from libpfutil for basic texture paging support.

The pfLoadTex() function, called from the drawing process, can be used to explicitly load a texture into graphics hardware texture memory (which includes doing any necessary formatting of the texture image). By default, pfLoadTex() loads the entire texture image, including any required minification or magnification levels, into texture memory. pfSubloadTex() and pfSubloadTexLevel() can also be used in the drawing process to do an immediate load of texture memory managed by the given pfTexture and these routines allow you to specify all loading parameters (source, origin, size, etc.). This is useful for loading different images for the same pfTexture in different graphics pipelines. pfSubloadTex() allows you to load a subsection of the texture tile by tile.

A special pfTexFormat() formatting mode, PFTEX_SUBLOAD_FORMAT, allows part or all of the image in texture memory owned by the pfTexture to be replaced using pfApplyTex(), pfLoadTex(), or pfSubloadTex(), without having to go through the expensive reformatting phase. This allows you to quickly update the image of a pfTexture in texture memory. The PFTEX_SUBLOAD_FORMAT used with an appropriate pfTexLoadSize() and pfTexLoadOrigin() allows you to control what part of the texture will be loaded by subsequent calls to pfLoadTex() or pfApplyTex(). There are also different loading modes that cause pfApplyTex() to automatically reload or subload a texture from a specified source. If you want the image of a pfTexture to be updated upon every call to pfApplyTex(), you can set the loading mode of the pfTexture with pfTexLoadMode() to be  PFTEX_BASE_AUTO_REPLACE. pfTexLoadImage() allows you to continuously update the memory location of an IMAGE source texture without triggering any reformatting of the texture.

There are texture formatting modes that can improve texture performance and these are the modes that are used by default by OpenGL Performer. Of most importance is the 16-bit texel internal formats. These formats cause the resulting texels to have 16 bits of resolution instead of the standard 32. These formats can have dramatically faster texture-fill performance and cause the texture to take up half the hardware texture memory. Therefore, they are strongly recommended and are used by default. There are different formats for each possible number of components to give a choice of how the compression is to be done. These formats are described in the pfTexFormat(3pf) man page.

There may also be formatting modes for internal or external image formats for which OpenGL Performer does not have a token. However, the GL value can be specified. Specifying GL values will make your application GL-specific and may also cause future porting problems; so, it should only be done if absolutely necessary.

The pfTexture class also allows you to define a set of textures that are mutually exclusive; they should always be applied to the same set of geometry; and, thus, they can share the same location in hardware texture memory. With pfTexList(tex, list) you can specify a list of textures to be in a texture set managed by the base texture, tex. The base texture is what gets applied with pfApplyTex(), or assigned to geometry through pfGeoStates. With pfTexFrame(), you can select a given texture from the list (–1 selects the base texture and is the default). This allows you to define a texture movie where each image is the frame of the movie. You can have an image on the base texture to display when the movie is not playing. There are additional loading modes for pfTexLoadMode() described in Table 12-7 to control how the textures in the texture list share memory with the base texture.

Texture list textures can share the exact graphics texture memory as the base texture but this has the restriction that the textures must all be the exact same size and format as the base texture. Texture list textures can also indicate that they are mutually exclusive, which will cause the texture memory of previous textures to be freed before applying the new texture. This method has no restrictions on the texture list, but is less efficient than the previous method. Finally, texture list textures can be treated as completely independent textures that should all be kept resident in memory for rapid access upon their application.

The pfTexFilter() function sets a desired filter to a specified filtering method on a pfTexture. The minification and magnification texture filters are described with bitmask tokens. If filters are partially specified, OpenGL Performer fills the rest with machine-dependent fast defaults. The PFTEX_FAST token can be included in the bitmask to allow OpenGL Performer to make machine dependent substitutions where there are large performance differences.

There are a variety of texture filter functions that can improve the look of textures when they are minified and magnified. By default, textures use MIPmapping when minified (though this costs an extra 1/3 in storage space to store the minification levels). Each level of minification or magnification of a texture is twice the size of the previous level. Minification levels are indicated with positive numbers and magnification levels are indicated with nonpositive numbers. The default magnification filter for textures is bilinear interpolation. The use of detail textures and sharpening filters can improve the look of magnified textures. Detailing actually uses an extra detail texture that you provide that is based on a specified level of magnification from the corresponding base texture. The detail texture can be specified with the pfTexDetail() function. By default, MIPmap levels are generated for the texture automatically. OpenGL operation allows for the specification of custom MIPmap levels. Both MIPmap levels and detail levels can be specified with pfTexLevel(). The level number should be a positive number for a minification level and a nonpositive number for a magnification (detail) level. If you are providing your own minification levels, you must provide all log₂(MAX(texSizeX, texSizeY)) minification levels. There is only one detail texture for a pfTexture.

Standard MIPmap filtering can induce blurring on a texture if the texture is applied to a polygon which is angled away from the viewer. To reduce this blurring, an anisotropic filter can be used to improve visual quality. pfTexAnisotropy() sets the degree of anisotropy to be used by the specified pfTexture. The default degree of anisotropy is 1, which is the same as the standard isotropic filter. A value of 2 will apply a 2:1 anisotropic filter. The maximum degree of anisotropy can be queried with pfQuerySys(). Anisotropic filtering is supported on OpenGL implementations that support the GL_EXT_texture_filter_anisotropic extension. pfQueryFeature() can be used to determine if anisotropic filtering is supported on the current platform. If the environment variable PF_MAX_ANISOTROPY is set, then an anisotropic filter of the value specified by PF_MAX_ANISOTROPY will be applied to pfTextures that do not set the degree of anisotropy.

The magnification filters use spline functions to control their rate of application as a function of magnification and specified level of magnification for detail textures. These splines can be specified with pfTexSpline(). The specification of the spline is a set of control points that are pairs of nondecreasing magnification levels (specified with nonpositive numbers) and corresponding scaling factors. Magnification filters can be applied to all components of a texture, only the RGB components of a texture, or to just the alpha components. OpenGL does not allow different magnification filters (between detail and sharpen) for RGB and alpha channels.

---

Note: The specification of detail textures may have GL dependencies and magnifications filters may not be available on all hardware configurations. The pfTexture man page describes these details.

---

The format in which an image is stored in texture memory is defined with pfTexFormat():

void pfTexFormat(pfTexture *tex, int format, int type)

The format variable specifies which format to set. Valid formats and their basic types include the following:

In the case of cube maps, where there are six images, the images are specified using the function pfTexMultiImage(). The parameter imageIndex with value 0–5 specifies the cube face in the following order:

min_x, max_x, min_y, max_y, min_z, max_z

For the order of faces and how the vector from the cube center to each texel is computed, see the sample program in following file:

/usr/share/Performer/src/pguide/libpf/C++/cubeMap.C
(IRIX and Linux)
%PFROOT%\Src\pguide\libpf\C++\cubeMap.C
(Microsoft Windows)

All six images have to be specified, they must have the same size, and the value ns has to be equal to nt.

The following are other variants of functions that are used by the cube maps:

Other than having six images, the cube maps are used as any other pfTexture. The exception is that subloads from other sources than user specified memory are not supported.

In general, you will just need to specify the number of components in pfTexImage(). You
may want to specify a fast-loading hardware-ready external format, such as PFTEX_UNSIGNED_SHORT_5_5_5_1, in which case OpenGL Performer automatically
chooses a matching internal format. See the pfTexFormat(3pf) man page for more informaton on texture configuration details.

You can control the levels of detail (LODs) of a texture that are accessed and used with pfTexLOD to force higher or lower MIPmap levels to be used when minifying. You can use this to give the graphics hardware a hint about what levels can be accessed (Impact hardware takes great advantage of such a hint) and you can use this to have multiple textures sharing a single MIPmap pyramid in texture memory. For example, a distant object and a close one may use different LODs of the same pfTexture texture. The pfGeoStates of those pfGeoSets would have different pfTexLOD objects that referenced the proper texture LODs. pfTexLevel() would be used to specify and update the proper image for each LOD in the pfTexture. You can use LODs to specify to yourself and the GL which LODs of texture should be loaded from disk into main memory. For example, if the viewer is in one LOD, most of the tex ture in that LOD can often be viewed and, consequently, should be paged into texture memory. You can set LOD parameters on a pfTexture directly or use pfTexLOD.

To use a pfTexLOD object, you do the following:

See the following sample program for an example of using a pfTexLOD:

/usr/share/Performer/src/pguide/libpr/C/texlod.c (IRIX and Linux) %PFROOT%\Src\pguide\libpr\C\texlod.con (Microsoft Windows)

The environment specifies how the colors of the geometry, potentially lit, and the texture image interact. This is described with a pfTexEnv object. The mode of interaction is set with pfTEnvMode() and valid modes include the following:

Automatic texture coordinate generation is provided with the pfTexGen state attribute. pfTexGen closely corresponds to OpenGL's glTexGen() function. When texture coordinate generation is enabled, a pfTexGen applied with pfApplyTGen() automatically generates texture coordinates for all rendered geometry. Texture coordinates are generated from geometry vertices according to the texture generation mode set with pfTGenMode(). Available modes and their function are listed in Table 12-8.

Some modes refer to a plane which is set with pfTGenPlane() and to a line that is specified as a point and direction with pfTGenPoint(). The default texture generation mode for all texture coordinates is PFTG_OFF. The function pfGetTGenMode() returns the mode of the pfTexGen.

See the man page for the OpenGL function glTexGen() for the specific mathematics of the generation modes for texture coordinates.

OpenGL Performer lighting is an extension of graphics library lighting (see glLight() and related functions in OpenGL). The light embodies the color, position, and type (for example, infinite or spot) of the light. The light model specifies the environment for infinite (the default) or local viewing, and two-sided illumination.

The lighting model describes the type of lighting operations to be considered, including local lighting, two-sided lighting, and light attenuation. The fastest light model is infinite, single-sided lighting. A pfLightModel state attribute object is created with pfNewLModel(). A light model also allows you to specify ambient light for the scene, such as might come from the sun with pfLModelAmbient().

The pfLights are created by calling pfNewLight(). A light has color and position. The light colors are specified with pfLightColor() as follows:

void pfLightColor(pfLightSource* lsource, int which, float r, 
   float g, float b);

which specifies one of three light colors as follows:

You to position the light source using pfLightPos():

void pfLightPos(pfLight* light, float x, float y, 
    float z, float w);

The variable w is the distance between the location in the scene defined by (x, y, z) and the light source lsource. If w equals 0, lsource is infinitely far away and (x, y, z) defines a vector pointing from the origin in the direction of lsource; if w equals 1, lsource is located at the position (x, y, z). The default position is (0, 0, 1, 0), directly overhead and infinitely far away.

The pfLights are attached to a pfGeoState through the PFSTATE_LIGHTS attribute.

The transformation matrix that is on the matrix stack at the time the light is applied controls the interpretation of the light source direction:

The number of lights you can have turned on at any one time is limited by PF_MAX_LIGHTS, just as is true with the graphics libraries.

---

Note: In previous versions, attenuation was also part of the light model definition. In OpenGL, attenuation is defined per light . The libpr API for setting it is pfLightAtten().

---

---

Note: libpf applications can include light sources in a scene graph with the pfLightSource node.

---

OpenGL Performer materials are an extension of graphics library material (see glMaterial()). pfMaterials encapsulate the ambient, diffuse, specular, and emissive colors of an object as well as its shininess and transparency. A pfMaterial is created by calling pfNewMtl(). As with any of the other attributes, a pfMaterial can be referenced in a pfGeoState, captured by a display list, or invoked as an immediate mode command.

The pfMaterials, by default, allow object colors to set the ambient and diffuse colors. This allows the same pfMaterial to be used for objects of different colors, removing the need for material changes and thus improving performance. This mode can be changed with pfMtlColorMode(mtl, side, PFMTL_CMODE_*). OpenGL allows front or back materials to track the current color. If the same material is used for both front and back materials, there is no difference in functionality.

With the function pfMtlSide() you can specify whether to apply the the material on the side facing the viewer (PFMTL_FRONT), the side not facing the viewer (PFMTL_BACK), or both (PFMTL_BOTH). Back-sided lighting will only take affect if there is a two-sided lighting model active. Two-sided lighting typically has some significant performance cost.

Object materials only have an effect when lighting is active.

A pfColortable substitutes its own color array for the normal color attribute array ( PFGS_COLOR4) of a pfGeoSet. This allows the same geometry to appear differently in different views simply by applying a different pfColortable for each view. By leaving the selection of color tables to the global state, you can use a single call to switch color tables for an entire scene. In this way, color tables can simulate time-of-day changes, infrared imaging, psychedelia, and other effects.

The  pfNewCtab() function creates and returns a handle to a pfColortable. As with other attributes, you can specify which color table to use in a pfGeoState or you can use pfApplyCtab() to set the global color table, either in immediate mode or in a display list. For an applied color table to have effect, color table mode must also be enabled.

A pfFog is created by calling pfNewFog(). As with any of the other attributes, a pfFog can be referenced in a pfGeoState, captured by a display list, or invoked as an immediate mode command. Fog is the atmospheric effect of aerosol water particles that occlude vision over distance. SGI graphics hardware can simulate this phenomenon in several different fashions. A fog color is blended with the resultant pixel color based on the range from the viewpoint and the fog function. pfFog supports several different fogging methods. Table 12-9 lists the pfFog tokens and their corresponding actions.

The pfFogType() function uses these tokens to set the type of fog. A detailed explanation of fog types is given in the man pages pfFog(3pf) and glFog(3g).

You can set the near and far edges of the fog with pfFogRange(). For exponential fog functions, the near edge of fog is always zero in eye coordinates. The near edge is where the onset of fog blending occurs, and the far edge is where all pixels are 100% fog color.

The token PFFOG_PIX_SPLINE selects a spline function to be applied when generating the hardware fog tables. This is further described in the pfFog(3pf) man page. Spline fog allows you to define an arbitrary fog ramp that can more closely simulate real-world phenomena like horizon haze.

For best fogging effects, the ratio of the far to the near clipping planes should be minimized. In general, it is more effective to add a small amount to the near plane than to reduce the far plane.

OpenGL Performer provides a mechanism for highlighting geometry with alternative rendering styles, useful for debugging and interactivity. A pfHighlight, created with pfNewHlight(), encapsulates the state elements and modes for these rendering styles. A pfHighlight can be applied to an individual pfGeoSet with pfGSetHlight() or can be applied to multiple pfGeoStates through a pfGeoState or pfApplyHlight(). The highlighting effects are added to the normal rendering phase of the geometry. pfHighlights make use of special outlining and fill modes and have a concept of a foreground color and a background color that can both be set with pfHlightColor(). The available rendering styles can be combined by ORing together tokens for pfHlightMode() and are described in Table 12-10.

For a demonstration of the highlighting styles, see the sample program /usr/share/Performer/pguide/src/libpr/C/hlcube.c on IRIX and Linux and %PFROOT%\Src\pguide\libpr\C\hlcube.c on Microsoft Windows.

The contents of one pfDispList may be appended to a second pfDispList by using the function, pfAppendDList(). All pfDispList elements in src are appended to the pfDispList dlist.

Alternately, you can append the contents of one pfDispList to a second pfDispList by using the function pfDispList::append(). All pfDispList elements in src are appended to the pfDispList on which the append method is invoked.

The pfPushState() function pushes the state stack of the currently active pfState, duplicating the top state. Subsequent modifications of the state through libpr routines are recorded in the top of the stack. Consequently, a call to pfPopState() restores the state elements that were modified after pfPushState().

The code fragment in Example 12-2 illustrates how to push and pop state.

/* set state to transparency=off and texture=brickTex */
pfTransparency(PFTR_OFF);
pfApplyTex(brickTex);
 
/* ... draw geometry here using original state ... */
 
/* save old state. establish new state */
pfPushState();
pfTransparency(PFTR_ON);
pfApplyTex(woodTex);
 
/* ... draw geometry here using new state ...*/
 
/* restore state to transparency=off and texture=brickTex */
pfPopState();

There are two levels of rendering state: local and global. A record of both is kept in the current pfState. The local state is that defined by the settings of the current pfGeoState. The rendering state and attributes of a pfGeoState can be either locally set or globally inherited. If all state elements are set locally, a pfGeoState becomes a full graphics context—that is, all state is then defined at the pfGeoState level. Global state elements are set with libpr immediate-mode routines like pfEnable(), pfApplyTex(), pfDecal(), or pfTransparency() or by drawing a pfDispList containing these commands with pfDrawDList(). Local state elements for subsequent pfGeoSets are set by applying a pfGeoState with pfApplyGState() (note that pfDrawGSet() automatically calls pfApplyGState() if the pfGeoSet has an attached pfGeoState). The state elements applied by a pfGeoState are those modes, enables, and attributes that are explicitly set on the pfGeoState. Those settings revert back to the pfState settings for the next call to pfApplyGState(). A pfGeoState can be explicitly loaded into a pfState to affect future pfGeoStates with pfLoadGState().

---

Note: By default, all state elements are inherited from the global state. Inherited state elements are evaluated faster than values that have been explicitly set.

---

While it can be useful to have all state defined at the pfGeoState level, it usually makes sense to inherit most state from global default values and then explicitly set only those state elements that are expected to change often.

Examples of useful global defaults are lighting model, lights, texture environment, and fog. Highly variable state is likely to be limited to a small set such as textures, materials, and transparency. For example, if the majority of your database is lighted, simply configure and enable lighting at the beginning of your application. All pfGeoStates will be lighted, except the ones for which you explicitly disable lighting. Then, attach different pfMaterials and pfTextures to pfGeoStates to define specific state combinations.

---

Note: Use caution when enabling modes in the global state. These modes may have cost even when they have no visible effect. Therefore, geometry that cannot use these modes should have a pfGeoState that explicitly disables the mode. Modes that require special care include the texturing enable and transparency.

---

You specify that a pfGeoState should inherit state elements from the global default with pfGStateInherit(gstate, mask). mask is a bitmask of tokens that indicates which state elements to inherit. These tokens are listed in the “Rendering Modes”, “Rendering Values”, and “Rendering Attributes” sections of this chapter. For example, PFSTATE_ENLIGHTING | PFSTATE_ENTEXTURE makes gstate inherit the enable modes for lighting and texturing.

A state element ceases to be inherited when it is set in a pfGeoState. Rendering modes, values, and attributes are set with pfGStateMode(), pfGStateVal(), and pfGStateAttr(), respectively. For example, to specify that gstate is transparent and textured with treeTex, use the following:

pfGStateMode(gstate, PFSTATE_TRANSPARENCY, PFTR_ON);
pfGStateAttr(gstate, PFSTATE_TEXTURE, treeTex);

Use pfApplyGState() to apply the state encapsulated by a pfGeoState to the Geometry Pipeline. The effect of applying a pfGeoState is similar to applying each state element individually. For example, if you set a pfTexture and enable a decal mode on a pfGeoState, applying it essentially calls pfApplyTex() and pfDecal(). If in display-list mode, pfApplyGState() is captured by the current display list.

State is (logically) pushed before and popped after pfGeoStates are applied so that pfGeoStates do not inherit state from each other. This is a very powerful and convenient characteristic since, as a result, pfGeoStates are order-independent, and you do not have to worry about one pfGeoState corrupting another. The code fragment in Example 12-4 illustrates how pfGeoStates inherit state.

/* gstateA should be textured */
pfGStateMode(gstateA, PFSTATE_ENTEXTURE, PF_ON);
 
/* gstateB inherits the global texture enable mode */
pfGStateInherit(gstateB, PFSTATE_ENTEXTURE);
 
/* Texturing is disabled as the global default */
pfDisable(PFEN_TEXTURE);
 
/* Texturing is enabled when gstateA is applied */
pfApplyGState(gstateA);
/* Draw geometry that will be textured */
 
/* The global texture enable mode of OFF is restored 
so that gstateB is NOT textured. */
pfApplyGState(gstateB);
/* Draw geometry that will not be textured */

The actual pfGeoState pop is a "lazy" pop that does not happen unless a subsequent pfGeoState requires the global state to be restored. This means that the actual state between pfGeoStates is not necessarily the global state. If a return to global state is required, call pfFlushState() to restore the global state. Any modification to the global state made using libpr functions—pfTransparency(), pfDecal(), and so on—becomes the default global state.

For best performance, set as little local pfGeoState state as possible. You can accomplish this by setting global defaults that satisfy the majority of the requirements of the pfGeoStates being drawn. By default, all pfGeoState state is inherited from the global default.

There is a special relationship between pfGeoSets and pfGeoStates. Together they completely define both geometry and graphics state. You can attach a pfGeoState to a pfGeoSet with pfGSetGState() to specify the appearance of geometry. Whenever the pfGeoSet is drawn with pfDrawGSet(), the attached pfGeoState is first applied using pfApplyGState(). If a pfGeoSet does not have a pfGeoState, its state description is considered undefined. To inherit all values from the global pfState, a pfGeoSet should have a pfGeoState with all values set to inherit, which is the default.

This combination of routines allows the application to combine geometry and state in high-performance units that are unaffected by rendering order. To further increase performance, sharing pfGeoStates among pfGeoSets is encouraged.

Table 12-13 lists and describes the pfGeoState routines.

Figure 12-1 diagrams the conceptual structure of a pfGeoState.

Figure 12-1. pfGeoState Structure

Some graphic hardware supports the use of multiple texture maps on a single polygon. These multiple texture maps are blended together according to a collection of texture environments. Figure 12-2 demonstrates the OpenGL definition for generating the color of a multitextured pixel. The figure assumes that the hardware has four texture units and so each pixel can receive contribution from four texture maps.

Figure 12-2. Generating the Color of a Multitextured Pixel

In the figure, the shaded and un-textured color of a pixel enters the first texture blending unit together with the texture color computed by the first texture unit. The texture environment marked TexEnv 0 determines the math operation between the two. The output color of this operation feeds the second texture blending unit together with the texture color computed by the second texture unit. This process continues four times until the final color of the pixel is generated.

The pfGeoState class allows specifying multiple texture maps on a single pfGeoSet. All these texture maps will be applied when the pfGeoSet is applied (providing that the graphic hardware has enough texture mapping units). pfGeoState also allows specifying multiple pfTexEnv, pfTexGen, pfTexMat, and pfTexLOD objects—one for each pfTexture.

The following code fragment shows how to add multiple textures to a pfGeoState:

{
    pfGeoState *gstate;
    pfTexture  *tex;
    pfTexEnv   *tev;
    gstate = pfNewGState (pfGetSharedArena());
    for (i = 0 ; i < PF_MAX_TEXTURES ; i ++)
    {
            /* Load texture # i from a file */
            tex = pfNewTex (pfGetSharedArena());
            pfLoadTexFile (tex, texture_file_name[i]);

            tev = pfNewTEnv (pfGetSharedArena());

            /* Enable texture unit # i on the pfGeoState. */
            pfGStateMultiMode (gstate, PFSTATE_ENTEXTURE, i, 1);

            /* Attach texture for texture unit # i */
            pfGStateMultiAttr (gstate, PFSTATE_TEXTURE, i, tex);

            /* Attach texture environment for texture unit # i */
            pfGStateMultiAttr (gstate, PFSTATE_TEXENV, i, tev);
    }
}

Notes: