A pfVolFog is not part of the scene graph; it is created separately by the application process. Once created, elevation points of a layered fog can be specified by calling pfVolFogAddPoint() or pfVolFogAddColoredPoint() repeatedly. The fog initialization is completed by calling pfApplyVolFog().

pfVolFog *lfog;
lfog = pfNewVolFog(arena);
pfVolFogAddPoint(lfog, elev1, density1);
pfVolFogAddPoint(lfog, elev2, density2);
pfVolFogAddPoint(lfog, elev2, density2);

pfApplyVolFog(lfog); 

The boundary of a patchy fog is specified by pfVolFogAddNode(pfog,node),where node contains the surfaces enclosing the foggy areas. It is possible to define several disjoint areas in the same tree or by adding several different nodes. Note that each area has to be completely enclosed, and the vertices of the surfaces have to be ordered so that the front face of each surface faces outside the foggy area. The node has to be part of the scene graph for the rendering to work properly.

pfVolFog *pfog;
pfNode   *fogNode;
pfog = pfNewVolFog(arena);
fogNode = pfdLoadFile(filename);
pfVolFogAddNode(pfog, fogNode);
pfAddChild(scene, fogNode);
pfApplyVolFog(pfog); 

Patchy and layered fog can be combined but only if layered fog has a uniform color; that is, it is specified using pfVolFogAddPoint() only.

The function pfApplyVolFog() initializes a pfVolFog. If at least two elevation points were defined, it initializes data structures necessary for rendering of a layered fog, including a 3D texture. Any control points defined afterward are ignored. If a node containing patchy fog boundaries has been added prior to calling pfApplyVolFog(), a patchy fog is initialized. Since function pfVolFogAddNode() only marks the parts of the scene graph that specifies the texture, it is possible to add additional patchy fog nodes, even after pfApplyVolFog() has been called.

Table 6-3 summarizes routines for initialization and drawing of a pfVolFog.

The attributes of a pfVolFog are listed in Table 6-4.

The flags of a pfVolFog are listed in Table 6-5.

A pfVolFog needs information about the current eye position and view direction. Since this information is not directly accessible in a draw process, it is necessary to call pfVolFogAddChannel() for each channel at the beginning of the application. Whenever the view changes, the application process has to call pfVolFogUpdateView(). See programs in /usr/share/Performer/src/sample/apps/C/fogfly or /usr/share/Performer/src/sample/apps/C++/volfog for an example. If you do not update the view, the fog will not be rendered.

If the application changes the position of the patchy fog boundaries (for example, by inserting a pfSCS, pfDCS, or pfFCS node above the fog node) or the orientation of the whole scene with respect to the up vector (for example, the use of a trackball in Perfly), the fog may not be drawn correctly.

To draw the scene with a fog, the draw process has to call pfDrawVolFog() instead of pfDraw(). This function takes care of drawing the whole scene graph with the specified fog. Expect the draw time to increase because the scene is drawn twice (three times if both patchy and layered fog are specified). In case of a patchy fog there may also be several full-screen polygons being drawn. You can easily disable the fog by not calling pfDrawVolFog().

Since boundaries of patchy fog are in the scene graph, do not use pfDraw() to draw the scene without fog; instead, use pfDrawBin() with PFSORT_DEFAULT_BIN, PFSORT_OPAQUE_BIN, and PFSORT_TRANSP_BIN.

A patchy fog needs as deep a color buffer as possible (optimally 12 bits per color component) and a stencil buffer. Use at least a 4-bit stencil buffer (1-bit is sufficient only for very simple fog objects). It may be necessary to modify your application so that it asks for such a visual.

A pfVolFog can be deleted using pfDelete(). In case of a layered fog it is necessary to delete the texture handle in a draw process. The texture is returned by pfGetVolFogTexture(). See the example in /usr/share/Performer/src/sample/apps/C/fogfly.

This section describes how to manage the various parameters for both layered and patchy fog.

Layered Fog

As mentioned earlier, a layered fog of a uniform color is specified by function pfVolFogAddPoint(), which sets the fog density at a given elevation. The density is scaled so that if the fog has a density of 1, the nearest object inside the fog that has full fog color is at a distance equal to 1/10 of the diagonal of the scene bounding box. The layered fog color is set by function pfVolFogSetColor() or by calling pfVolFogSetAttr() with parameter PFVFOG_COLOR and a pointer to an array of three floats.

A layered fog of nonuniform color is specified by function pfVolFogAddColoredPoint(), which sets the fog density and the fog color at a given elevation. The color set by pfVolFogSetColor() is then ignored.

The layered fog mode is set by function pfVolFogSetVal() with parameter PFVFOG_LAYERED_MODE and one of PFVFOG_LINEAR, PFVFOG_EXP, or PFVFOG_EXP2.

It is also possible to set the mode both for a layered and patchy fog at once by using parameter PFVFOG_MODE. The default mode is PFVFOG_LINEAR. The function of the mode parameter is equivalent to the function of the fog mode parameter of the OpenGL function glFog().

The size of a 3D texture used by a layered fog can be modified by calling pfVolFogSetAttr() with parameter PFVFOG_3D_TEX_SIZE and an array of three integer values. The default texture size is 64x64x64, but reasonable results can be achieved with even smaller sizes. The sizes are automatically rounded up to the closest power of 2. The second value should be equal to or greater than the third value. If 3D textures are not supported, a set of 2D textures is used instead of a 3D texture (the number of 2D textures is equal to the third dimension of the 3D texture). Every time the r coordinate changes more than 0.1, a new texture is computed by interpolating between two neighboring slices, and the texture is reloaded. The use of 2D textures can be forced by calling: pfVolFogSetFlags() with flag PFVFOG_FLAG_FORCE_2D_TEXTURE set to 1.

---

Note: Once a layered fog is initialized by calling the pfApplyVolFog(), changing any of the parameters described here will not affect rendering of the layered fog.

---

Patchy Fog

The density of a patchy fog is controlled by function pfVolFogSetDensity() or by using pfVolFogSetVal() with parameter PFVFOG_FOG_DENSITY. As in the case of a layered fog, the density of a patchy fog is scaled by 1/10 of the diagonal of the scene bounding box.

You can specify an additional density value that is added to every pixel inside or behind a patchy fog boundary using the function pfVolFogSetVal() with parameter PFVFOG_FOG_DENSITY_BIAS. This value makes a patchy fog appear denser but it may create unrealistically sharp boundaries.

The patchy fog color is set by function pfVolFogSetColor() or by calling pfVolFogSetAttr() with parameter PFVFOG_COLOR and a pointer to an array of three floats. If the blend_color extension is not available, patchy fog will be white.

The patchy fog mode is set by function pfVolFogSetVal() with parameter PFVFOG_PATCHY_MODE and one of PFVFOG_LINEAR, PFVFOG_EXP, or PFVFOG_EXP2.

It is also possible to set the mode both for a patchy and layered fog at once by using parameter PFVFOG_MODE. The default mode is PFVFOG_LINEAR.

---

Note: The parameters of a patchy fog can be modified at any time and they will affect the rendering of the subsequent frame.

---

This section describes the following topics:

The example in /usr/share/Performer/src/sample/C++/volfog illustrates the use of all these advanced features.

The quality and speed of patchy fog rendering can be controlled by calling pfVolFogSetVal() with the parameter PFVFOG_RESOLUTION. The resolution is a value between 0 and 1. Higher values will reduce banding and speed up the drawing. On the other hand, high values may cause corruption in areas of many overlapping fog surfaces. The default value is 0.2, but you may use values higher than that if your fog boundaries do not overlap much.

The following are other performance considerations:

OpenGL Performer has the following limitations in regards to fog management:

Layered fog

Patchy fog

A pfShadow is not part of the scene graph; it is created separately by the application process. Once the pfShadow is created, you can specify the number of shadow casters by calling function pfShadowNumCasters() and then set each caster using the function pfShadowShadowCasters(). Each shadow caster is specified by a scene graph node and a matrix that contains the transformation of the node with respect to the scene graph root. Shadow casters are indexed from 0 to the number of casters minus 1.

Similarly, the number of light sources is set by function pfShadowNumSources(). A light source is defined by its position or direction, set by pfShadowSourcePos() or pfShadowLight().

A pfShadow needs information about the current eye position and view direction. Since this information is not directly accessible in a draw process, it is necessary to call pfShadowAddChannel() for each channel at the beginning of the application. Whenever the view changes, the application process has to call pfShadowUpdateView(). Even if the view does not change, this function must be called at least once in single-process mode or as many times as the number of buffers in a pfFlux in multiprocess mode. Without updating the view, the shadow is not rendered correctly.

The class initialization is completed by calling the function pfShadowApply() as shown in the following creation example:

pfShadow *shd = pfNewShadow();

pfShadowNumCasters(shd, 2);
pfShadowShadowCaster(shd, 0, node1, matrix1);
pfShadowShadowCaster(shd, 1, node2, matrix2);

pfShadowNumSources(shd, 1);
pfShadowSourcePos(shd, 0, x1, y1, z1, w1);

pfShadowAddChannel(channel);

pfShadowApply(shd);

Table 6-6 summarizes the functions for the initialization and drawing of a pfShadow.

The attributes of a pfShadow are listed in Table 6-7.

There is only one pfShadow flag, PFSHD_BLEND_TEXTURES. This blend-textures flag has a default of 0.

To draw a scene with real-time shadows, the draw process has to call the draw function provided by the pfShadow class: pfShadowDraw(). Before the first frame is rendered, all required shadow textures are precomputed. A warning is printed if the window size is smaller than the texture dimensions. Ensure that the window is not obscured; otherwise, the textures will not be correct.

By default, only the closest shadow texture is selected for any direction and it is skewed so that it approximates the correct shadow. Optionally, the flag PFSHD_BLEND_TEXTURES can be set using the function pfShadowFlags(). In this case, the two closest textures are selected and blended together, resulting in smoother transitions. Also, instead of a linear blend between the textures, you can define a blend function, mapping values 0–1 to the interval 0–1. The blend function can be set using the function pfShadowTextureBlendFunc().

Every time the caster changes its position or orientation with respect to the light source, it is necessary to update its matrix using pfShadowUpdateCaster() (the caster is identified by its index). When the caster's matrix changes, the shadow of the caster changes as well. In this case, the set of precomputed shadow textures is searched to find the one or two closest representatives.

The shadow texture is used to darken the scene pixels when the texture texel is set to 1. The amount by which the scene pixel is darkened can be set by the function pfShadowAmbientFactor(). The default value is 0.6

As the caster is projected into a shadow texture, the center of the projection corresponds with the center of the bounding box of the caster's node. When the shadow texture is skewed to approximate shadows from a slightly different direction, it is best if the center of the projection corresponds with the center of the object. The bounding box center may not coincide with the center of the object (in the case of some long protruding parts) and you can use the function pfShadowAdjustCasterCenter() to shift the bounding box center toward the center of the object.

For each combination of a shadow caster and a light source, it is possible to specify the number of shadow textures used, their sizes, and a set of directions for which the textures are precomputed. The number of textures and their sizes can be set by the function pfShadowVal(), where the first parameter is PFSHD_PARAM_TEXTURE_SIZE or PFSHD_PARAM_NUM_TEXTURES.

The set of directions can be controlled by using the function pfGetShadowDirData() to get the pointer to the corresponding pfDirData, a class that stores data associated with a set of directions. Then you can either select the default mode or specify the directions directly. See following section “Assigning Data with Directions” for more details. By default, there is one texture of size 512 x 512 and the direction corresponds to the light direction (or a vector from a point light source to the object's center). If there are more textures, the original light direction is rotated around a horizontal direction, assuming that the object will primarily keep its horizontal position (for example, a helicopter or a plane).

A sample implementation of shadows is in the file perf/samples/pguide/libpf/C++/shadowsNew.

The pfDirData class is used to store directional data—that is, data that depend on direction. A pfDirData stores an array of directions and an array of (void *) pointers representing the data associated with each direction.

The directions and data can be set using the function pfDirDataData(). Optionally, you can set only the directions using the function pfDirDataDirections() in the case that the associated data are defined later or generated internally by another OpenGL Performer class (such as pfShadow).

You can also generate directions automatically using the function pfDirDataGenerateDirections(). The first parameter defines one of the default sets of directions and the second parameter is used to specify additional values. At present only type PFDD_2D_ROTATE_AROUND_UP is supported, in which case the second parameter points to a 3D vector that is rotated around the up vector, creating a number of directions.

The data can be queried using the pfDirDataFindData() or pfDirDataFindData2() function. In the first case, the function finds the closest direction to the direction specified as the first parameter, copies it to the second parameter, and returns the pointer to the data associated with it. The input direction has to be normalized. The second function finds the two closest directions to the specified direction. It copies the two directions to the second parameter (which should point to an array of two vectors). The two pointers to the data associated with the two directions are copied to the array of two (void *) pointers specified as the third parameter. In addition, two weights associated with each direction are copied to the array of two floats. These weights are determined based on the distance of the end point of the input direction and each of the two closest directions.

The following are limitations of real-time shadows in OpenGL Performer:

A pfIBRnode is a child class of pfBillboard. You create a pfIRRnode in a fashion similar to that of a pfBillboard. Compared to a pfBillboard, a pfIBRnode has two additional parameters: a pfIBRtexture and an array of angles defining the initial rotation of the objects.

Each pfIBRnode has associated with it a single pfIBRtexture, which stores a set of images of the complex object as viewed from different directions. Each pfGeoSet is then rendered with a texture representing the view of the object from the given direction. A pfIBRtexture is specified using the function pfIBRnodeIBRtexture().

Using the function pfIBRnodeAngles(), you control the initial orientation of the complex object by specifying the rotation from the horizontal and vertical planes for each pfGeoSet. These angles are very useful in case of trees, for example, because you can use a different vertical angle for each instance of the tree. The trees then appear different, although they all use the same pfIBRtexture. The first value is ignored in the case that only one ring of views around the object is used.

You must set up a pfIBRnode so that the pfIBRtexture applied to it can modify properly the image at each frame. You do so in the following manner:

See the file sample/pguide/C++/IBRnode.C for an example.

A pfIBRtexture stores a set of images of a complex object as viewed from different directions. The images are loaded using the function pfIBRtextureLoadIBRtexture(). The first parameter specifies the path in which the images are stored as well as how they are indexed—for example, images/view%03d.rgb. The other two parameters specify the number of images and the increment between two loaded images. The increment specification is useful when the texture memory is limited; for instance, specifying step=2 causes every second image to be skipped. Optionally, you can specify the views using the function pfIBRtextureIBRtextures(). The parameters are an array of pointers to the textures containing the views and the number of the textures in this array.

There are two ways to organize the views. By default, the textures represent views around the object, all perpendicular to the vertical axis. In this case, specified textures form a single ring of views that are evenly spaced. If the flag PFIBR_3D_VIEWS is specified by the function pfIBRtextureFlags(), the textures form a set of rings. Each ring contains an array of evenly spaced views that have the same angle from the horizontal plane.

If the flag PFIBR_3D_VIEWS is not set, both functions pfIBRtextureLoadIBRtexture() and pfIBRtextureIBRtextures() will set one ring with the specified number of textures and a horizontal angle of 0. If the flag PFIBR_3D_VIEWS is set, the class checks whether a file info is present in the image directory. If it is, the information about rings is loaded from that file. The file contains two values on each line: the horizontal angle and the number of textures at each ring. If the file is not present in the image directory, you must specify the rings before the images are loaded by calling the functions pfIBRtextureNumRings() and pfIBRtextureRing(). Rings are indexed from 0 and should be ordered by the horizontal angle, with the lowest angle at index 0. Each ring can have a different number of textures associated with it.

When 3D views are used, the image files read by function pfIBRtextureLoadIBRtexture() should be indexed by the ring index and the index of the image in a given ring. Specify the format string in the manner shown in the following example:

images/view%02d_%03d.rgb

If you specify the textures using the function pfIBRtextureIBRtextures(), the texture pointers are all stored in a single array, starting with textures of the first ring, followed by textures of the second ring, and so on.

It is assumed that the views in each ring are uniformly spaced and they are ordered clockwise with respect to the vertical axis. If the views are ordered in the opposite direction, use the function pfIBRtextureDirection() to set the direction to –1.

See the pfIBRnode man page and the program sample/pguide/C++/IBRnode for more details about associating a pfIBRtexture with a pfIBRnode.

At present, the pfIBRtexture class is used only by the pfIBRnode class. The pfIBRtexture class provides a draw function for pfGeoSets that belong to the pfIBRnode, but the draw process is transparent to you. You can control the drawing by setting flags using the function pfIBRtextureFlags(). If the flag PFIBR_NEAREST is set, the closest view from the closest ring is selected and applied as a texture of the pfGeoSet. This approach is fast on all platforms, but it results in visible jumps when the texture is changed. Thus, by default, the flag PFIBR_NEAREST is not set and the two or, in case of 3D views, four closest views are blended together. If the graphics hardware supports register combiners, flags PFIBR_USE_REG_COMBINERS and PFIBR_USE_2D_TEXTURES are automatically set by the class constructor and blending of textures can be done in one pass.

By default on IRIX, the flag PFIBR_USE_2D_TEXTURES is not set and a 3D texture is used for fast blending between the two closest views. This may result in flickering when the object is viewed from a distance due to the lack of mipmapping. Thus, set the flag PFIBR_USE_2D_TEXTURES to avoid this problem, although this causes each pfGeoSet to be rendered multiple times.

The following are current limitations of image-based rendering in OpenGL Performer:

You can use the program makeIBRimages from the directory /usr/share/Performer/src/conv/ to create images (views) of a specified object from a set of directions. The input is a file that can be read by OpenGL Performer and the output is a set of images of that object that can be directly used as an input for a pfIBRtexture. The images are stored in a directory specified using the option -f.

If a text file info is present in the output directory, a set of 3D views is rendered. The file has the same syntax as described in section “Creating a pfIBRtexture”. Each line of the file info contains two values: the angle from the horizontal plane and how many views are created for that angle. The images are then indexed by two integer values that are appended to the name specified by the option -f. The first value is the ring index of the views and the second one indexes the views within the ring.

If the file info is not present, a set of N views (set by the option -n) is computed around the object using the horizontal angle of 0. In this case, only one index is appended to the image name.

If you specify the option -pfb, the program outputs a pfb file in the specified directory. The file contains a single pfIBRnode that uses the created images.

---

Note: Before loading perfly, ensure that PFPATH is set to the directory that contains the images. If your machine does not support a single-buffered visual with at least 8 bits per red, green, blue, and alpha component, the images may be missing the alpha channel. Note the number of alpha bits printed when makeIBRimages begins. When using pfIBRnodes and pfIBRtextures in perfly, you also need an alpha buffer. If the pfIBRnode is rendered as a full rectangle, try the command-line parameter –9, in which case perfly requests a visual with alpha.

---

To obtain the full set of command-line options, run the program makeIBRimages without any parameters.