A pfEarthSky is a special set of functions that clears a pfChannel's viewport efficiently and implements various atmospheric effects. A pfEarthSky is attached to a pfChannel with pfChanESky(). Several pfEarthSky definitions can be created, but only one can be in effect for any given channel at a time.

A pfEarthSky can be used to draw a sky and horizon, to draw sky, horizon, and ground, or just to clear the entire screen to a specific color and depth. The colors of the sky, horizon, and ground can be changed in real time to simulate a specific time of day. At the horizon boundary, the ground and sky share a common color, so that there is a smooth transition from sky to horizon color. The width of the horizon band can be defined in degrees.

A pfChannel's earth-sky model is automatically drawn by IRIS Performer before the scene is drawn unless the pfChannel has a draw callback set with pfChanTravFunc(). In this case it is the application's responsibility to clear the viewport. Within the callback pfClearChan() draws the channel's pfEarthSky.

Example 8-1 shows how to set up an pfEarthSky().

pfEarthSky  *esky;
pfChannel *chan;

sky = pfNewESky();
pfESkyMode(esky, PFES_BUFFER_CLEAR, PFES_SKY_GRND);
pfESkyAttr(esky, PFES_GRND_HT, -1.0f);
pfESkyColor(esky, PFES_GRND_FAR, 0.3f, 0.1f, 0.0f, 1.0f);
pfESkyColor(esky, PFES_GRND_NEAR, 0.5f, 0.3f, 0.1f,1.0f);
pfChanESky(chan, esky);

The complexities of atmospheric effects on visibility are approximated within IRIS Performer using a multiple-layer sky model, set up as part of the pfEarthSky function. In this design, individual layers are used to represent the effects of ground fog, clear sky, and clouds. Figure 8-1 shows the identity and arrangement of these layers.

Figure 8-1. Layered Atmosphere Model

The lowest layer consists of ground fog, extending from the ground up to a user-selected altitude. The fog thins out with increasing altitude, disappearing entirely at the bottom of the general visibility layer. This layer extends from the top of the ground fog layer to the bottom of the cloud layer's lower transition zone, if such a zone exists. The transition zone provides a smooth transition between general visibility and the cloud layer. (If there is no cloud layer, then general visibility extends upward forever.) The cloud layer is defined as an opaque region of near-zero visibility; you can set its upper and lower boundaries. You can also place another transition zone above the cloud layer to make the clouds gradually thin out into clear air.

Set up the atmospheric simulation with the commands listed in Table 8-1

You can set any pfEarthSky attribute, mode, or color in real time. Selecting the active pfFog definition can also be done in real time. However, changing the parameters of a pfFog once they are set isn't advised when in multiprocessing mode.

The default characteristics of a pfEarthSky are listed in Table 8-2.

By default, an earth-sky model isn't drawn. Instead, the channel is simply cleared to black and the Z-buffer is set to its maximum value. This default action also disables all other atmospheric attributes. To enable atmospheric effects, select PFES_SKY, PFES_SKY_GRND, or PFES_SKY_CLEAR when turning on the earth-sky model.

Clouds are disabled when the cloud top is less than or equal to the cloud bottom. Cloud transition zones are disabled when clouds are disabled.

Fog is enabled when either the general or ground fog is set to a valid pfFog. If ground fog isn't enabled, no ground fog layer will be present and fog will be used to support general visibility. Setting a fog attribute to NULL disables it. See “Fog” for further information on fog parameters and operation.

The earth-sky model is an attribute of the channel and thus accesses information about the viewer's position, current field of view, and other pertinent information directly from pfChannel. To set the pfEarthSky in a channel, use pfChanESky().

A pfLightSource node's primary purpose is to represent a graphics library light source (pfLight) in a scene graph. The position and orientation of the light source is affected by transformations inherited through the scene graph providing a simple means of moving lights about. In conjunction with an object's material properties (pfMaterial) and the global lighting model (pfLightModel), illumination is computed at geometry vertices by the Geometry Pipeline.

While this kind of “bread-and-butter” lighting is very efficient it does not adequately simulate certain important lighting effects. In particular, per-pixel spotlights and shadows are not supported by the default lighting mechanism. On graphics library implementations which support texture mapping, the pfLightSource node supports per-pixel spotlights and opera lighting through a technique called projective texturing and also support shadows if shadow map hardware is available. In practice, default lighting is used in conjunction with projected texturing since the latter does not consider geometry normals but the former does.

Both projected texturing and shadows require a pfFrustum which defines the “viewing volume” of the light source. The frustum's eye point is located at the pfLightSource position and the frustum's view direction is aligned along the pfLightSource's +Y axis. You can think of the frustum as a slide projector whose eyepoint is the projector's bulb and whose view plane is the slide holder and the projected texture map is the slide. A pfLightSource's frustum is set with pfLSourceAttr() with the PFLS_PROJ_FRUSTUM identifying token.

In addition to a frustum, projected texturing requires a texture map supplied with pfLSourceAttr() with PFLS_PROJ_TEX identifying token. This texture map can be anything but is usually a texture with identical intensity and alpha components which represent the soft-edged circle of a spotlight. Colored spotlights are simulated by coloring the pfLightSource with pfLSourceColor() rather than coloring the texture map. Opera lighting, where an actual color slide is projected onto the set, is simulated with a texture map consisting of red, green, blue, and alpha components (this is supported only if the pfLightSource is the only one that is projecting a texture).

Shadows do not require the application to supply a texture map; rather, one is automatically created by IRIS Performer. However, the size of the shadow map has an important effect on the quality of the shadows and may be set with the PFLS_SHADOW_SIZE token to pfLSourceVal(). For high quality shadows, the pfLightSource's frustum must encompass the entire scene that is to be shadowed as tightly as possible. If the frustum's field-of-view or far to near clipping plane ratio becomes too large, the shadows will become blocky and incorrect. One way to improve shadow quality is to increase the size of the shadow map but this will decrease performance.

Projected textures and shadows both use texture mapping so if your scene is texture mapped, multiple rendering passes are required to combine the projected texture with the normal scene textures. In pfDraw(), pfChannels assume the scene is textured and automatically render the scene multiple times. However, if your scene is not textured you can avoid a complete rendering pass by setting the PFMPASS_NONTEX_SCENE bit in the PFTRAV_MULTIPASS mode given to pfChanTravMode().

Example 8-3 is a code snippet which shows how to set up both projected texture and shadowing pfLightSources.

pfFrustum *shadFrust;
pfLightSource *shad, *proj;
pfDCS *shadDCS, *projDCS;
pfTexture *tex;

// Create and configure shadow frustum
shadFrust = pfNewFrust(arena);
pfMakeSimpleFrust(shadFrust, 60.0f);
pfFrustNearFar(shadFrust, 1.0f, 100.0f);

/* Create and configure red shadow casting light source */
shad = pfNewLSource();
pfLSourceMode(shad, PFLS_SHADOW_ENABLE, 1);
pfLSourceAttr(shad, PFLS_PROJ_FRUST, shadFrust);
pfLSourceColor(shad, PFLT_DIFFUSE, 1.0f, 0.0f, 0.0f);
pfLSourceVal(shad, PFLS_INTENSITY, .5f);
pfLSourcePos(shad, 0.0f, 0.0f, 0.0f, 1.0f); /* make local */

/* Create and configure blue spotlight */
proj = pfNewLSource();
tex = pfNewTex(arena);
pfLoadTexFile(tex, “spotlight.inta”);
pfLSourceMode(proj, PFLS_PROJTEX_ENABLE, 1);
pfLSourceAttr(proj, PFLS_PROJ_FRUST, shadFrust);
pfLSourceAttr(proj, PFLS_PROJ_TEX, tex);
pfLSourceColor(proj, PFLT_DIFFUSE, 0.0f, 0.0f, 1.0f);
pfLSourceVal(proj, PFLS_INTENSITY, .5f);
pfLSourcePos(proj, 0.0f, 0.0f, 0.0f, 1.0f); /* make local */

/* Add to DCSes so we can move lights around */
shadDCS = pfNewDCS();
pfAddChild(shadDCS, shad);
pfAddChild(scene, shadDCS);

projDCS = pfNewDCS();
pfAddChild(projDCS, proj);
pfAddChild(scene, projDCS);

For scenes with multiple pfLightSources you can scale the contribution from each source with the PFLS_INTENSITY value so that the total illumination from all sources does not exceed one. Otherwise lighted geometry may become saturated and not look real.

pfLightSources which are located near the eyepoint and which project a texture to simulate spotlights can attenuate the spotlight based on range by using a pfFog to define the falloff ramp. The pfFog is set with the PFLS_PROJ_FOG token to pfLSourceAttr() and should have the same color as the lighting ambient.

Morphing is the smooth transition from one particular appearance to another. Morphing can refer to images or geometry colors, texture coordinate or coordinates. For example, you could “morph” the following:

pfMorph is a group node that supports the morphing of lists of numbers. These numbers could be colors, coordinates, or pixels -- it is up to you to decide what to morph.

Conceptually, pfMorph combines multiple input lists of numbers into a single output list. This output may be used arbitrarily but is most often used as a pfGeoSet attribute array, be it colors, normals, texture coordinates, or coordinates. The combination is linear, that is, the input lists are scaled by a value (which has no restricted range) and then summed together to produce the output. One example of geometric morphing is in facial animation where multiple input faces with canonical expressions: smiley, frowny, surprised, are combined to produce a face with a mixture of expressions.

pfMorphs can handle multiple sets of input->output lists so a single pfMorph could, for example, morph the normals and coordinates of an animated figure. An input->output set is called a morph attribute since a set typically corresponds to a pfGeoSet attribute. Morph attributes are specified with pfMorphAttr(). Example 8-4 is a snippet of the morph.c test program in /usr/share/Performer/src/pguide/libpf/C/ shows how to configure a pfMorph node that morphs the normals and coordinates of a pfGeoSet.

/* Sinusoidally modify morph weights to oscillate between
* cube and sphere.
*/
static void
breatheMorph(pfMorph *morph, double t)
{
 float     s = (sinf(t) + 1.0f) / 2.0f;
 float     weights[2];

 weights[0] = s;
 weights[1] = 1.0f - s;

 pfMorphWeights(morph, 0, weights); /* coordinate weights*/
 pfMorphWeights(morph, 1, weights); /* normal weights */
}


static pfMorph*
initMorph(void)
{
 pfGeoSet     *gset;
 pfGeode     *geode;
 pfGeoState     *gstate;
 pfMaterial     *mtl;
 pfMorph     *morph;
 ushort     *icoords, *inorms;
 pfVec3     *coords, *ncoords, *norms, *nnorms;
 float     *srcs[2];
 int          i, nSph;
 void     *arena = pfGetSharedArena();

 morph = pfNewMorph();
 geode = pfNewGeode();
 gset = pfdNewSphere(400, arena);
 gstate = pfNewGState(arena);

 mtl = pfNewMtl(arena);
 pfMtlColor(mtl, PFMTL_DIFFUSE, 1.0f, 0.0f, 0.0f); 
 pfMtlColor(mtl, PFMTL_SPECULAR, 1.0f, 1.0f, 1.0f); 
 pfMtlColorMode(mtl, PFMTL_BOTH, PFMTL_CMODE_OFF);
 pfMtlShininess(mtl, 32);

 pfGStateAttr(gstate, PFSTATE_FRONTMTL, mtl);
 pfGStateMode(gstate, PFSTATE_ENLIGHTING, 1);
 pfGSetGState(gset, gstate);

 pfAddGSet(geode, gset);
 pfAddChild(morph, geode);

 /*
 * NULL forces recomputation of bound. Force it to be static 
 * to avoid expensive recomputation. Static bound should
 * encompass the extent of all morph possibilities. 
 */
 pfGSetBBox(gset, NULL, PFBOUND_STATIC);
 pfNodeBSphere(geode, NULL, PFBOUND_STATIC);

 pfGetGSetAttrLists(gset, PFGS_COORD3, (void**)&coords, &icoords);
 pfGetGSetAttrLists(gset, PFGS_NORMAL3, (void**)&norms, &inorms);
 nSph = pfGetSize(coords) / sizeof(pfVec3);

 ncoords = pfMalloc(pfGetSize(coords), arena);
 nnorms = pfMalloc(pfGetSize(norms), arena);

 for (i=0; i<nSph; i++)
 {
     int     max;
     float     t;

     /* Find which face of the cube this vertex maps to */
     if (PF_ABS(coords[i][PF_X]) > PF_ABS(coords[i][PF_Y]))
     {
      if (PF_ABS(coords[i][PF_X]) > PF_ABS(coords[i][PF_Z]))
          max = PF_X;
      else
          max = PF_Z;
     }
     else 
     {
      if (PF_ABS(coords[i][PF_Y]) > PF_ABS(coords[i][PF_Z]))
          max = PF_Y;
      else
          max = PF_Z;
     }

     /* Compute cube normals and coordinates */
     pfSetVec3(nnorms[i], 0.0f, 0.0f, 0.0f); 
     if (coords[i][max] < 0.0f)
     {
      t = -1.0f / coords[i][max];
      pfScaleVec3(ncoords[i], t, coords[i]);
      nnorms[i][max] = -1.0f;
     }
     else
     {
      t = 1.0f / coords[i][max];
      pfScaleVec3(ncoords[i], t, coords[i]);
      nnorms[i][max] = 1.0f;
     }
 }

 /* Morph attribute 0 is coordinates */
 srcs[0] = (float*)coords; 
 srcs[1] = (float*)ncoords;
 pfMorphAttr(morph, 0, 3, nSph, NULL, 2, srcs, NULL, NULL);

 pfGSetAttr(gset, PFGS_COORD3, PFGS_PER_VERTEX, 
      (void*)pfGetMorphDst(morph, 0), icoords);

 /* Morph attribute 1 is normals */
 srcs[0] = (float*)norms;
 srcs[1] = (float*)nnorms;
 pfMorphAttr(morph, 1, 3, nSph, NULL, 2, srcs, NULL, NULL);

 pfGSetAttr(gset, PFGS_NORMAL3, PFGS_PER_VERTEX, 
      (void*)pfGetMorphDst(morph, 1), inorms);

 return morph;
}