pfEarthSky(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NAME
pfNewESky, pfGetESkyClassType, pfESkyMode, pfGetESkyMode, pfESkyAttr,
pfGetESkyAttr, pfESkyColor, pfGetESkyColor, pfESkyFog, pfGetESkyFog,
pfESkyFogDensities, pfGetESkyFogDensities, pfESkyFogTextureElevations,
pfGetESkyFogTextureElevations, pfESkyFogTexture, pfGetESkyFogTexture,
pfESkyFogTextureColorTable, pfGetESkyFogTextureColorTable,
pfESkyLoadFogTextureColorTable, pfESkyMakeFogTexture - Create and control
weather, Earth-Sky model, and screen clearing.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfEarthSky * pfNewESky(void);
pfType * pfGetESkyClassType(void);
void pfESkyMode(pfEarthSky *esky, int mode, int val);
int pfGetESkyMode(pfEarthSky *esky, int mode);
void pfESkyAttr(pfEarthSky *esky, int attr, float val);
float pfGetESkyAttr(pfEarthSky *esky, int mode);
void pfESkyColor(pfEarthSky *esky, int which, float r, float g,
float b, float a);
void pfGetESkyColor(pfEarthSky *esky, int which, float *r,
float *g, float *b, float *a);
void pfESkyFog(pfEarthSky *esky, int which, pfFog *fog);
pfFog * pfGetESkyFog(pfEarthSky *esky, int which);
void pfESkyFogDensities(pfEarthSky* _esky, int numpt,
float *elevations, float *densities);
void pfGetESkyFogDensities(pfEarthSky* _esky, int *numpt,
float **elevations, float **densities);
void pfESkyFogTextureElevations(pfEarthSky* _esky, int n,
float *elev);
void pfGetESkyFogTextureElevations(pfEarthSky* _esky, int *n,
float **elev);
void pfESkyFogTexture(pfEarthSky* _esky, pfTexture *tex);
pfTexture* pfGetESkyFogTexture(pfEarthSky* _esky);
Page 1
pfEarthSky(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
void pfESkyFogTextureColorTable(pfEarthSky* _esky, int n,
unsigned char *table);
void pfGetESkyFogTextureColorTable(pfEarthSky* _esky, int *n,
unsigned char **table);
void pfESkyLoadFogTextureColorTable(pfEarthSky* _esky);
void pfESkyMakeFogTexture(pfEarthSky* _esky);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfEarthSky is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfEarthSky. Casting an object of
class pfEarthSky to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfEarthSky can also be used with these
functions designed for objects of class pfMemory.
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
Page 2
pfEarthSky(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
PARAMETERS
esky identifies a pfEarthSky.
DESCRIPTION
These functions provide a means to clear the frame and Z-buffer, draw a
sky, horizon and ground plane, and to implement various weather effects.
Once the earth-sky is set in a channel, it should be the first thing
drawn when a scene is rendered.
pfNewESky creates and returns a handle to a pfEarthSky. Like other
pfNodes, pfEarthSky nodes are always allocated from shared memory and can
be deleted using pfDelete.
pfNewESky creates a pfEarthSky and sets up reasonable defaults. To
render the earth and sky model, it must be added to a pfChannel. By
default, the mode is to render a full screen clear unless either the sky
or ground is turned on. pfEarthSky is called automatically in the draw
process, unless a draw callback is present, in which case, it must be
explicitly called using pfClearChan.
pfGetESkyClassType returns the pfType* for the class pfEarthSky. The
pfType* returned by pfGetESkyClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfEarthSky.
Because OpenGL Performer allows subclassing of built-in types, when
decisions are made based on the type of an object, it is usually better
to use pfIsOfType to test if an object is of a type derived from a
Performer type rather than to test for strict equality of the pfType*'s.
pfESkyMode is used to set the earth-sky rendering mode. pfGetESkyMode is
used to obtain the earth-sky rendering mode. These functions currently
accept the two mode arguments PFES_BUFFER_CLEAR, and PFES_CLOUDS.
PFES_BUFFER_CLEAR may have the following values:
PFES_FAST
The default mode. This simply clears the color and Z
buffers. The clear color can be set using pfESkyColor.
Dithering is turned off during the clear.
PFES_TAG Initializes the framebuffer to a known state very
rapidly. Has an effect only when multisampling. Often,
this mode is used as an optimization before rendering a
background that covers the entire screen. See pfClear for
the details and restrictions of the mode PFCL_MSDEPTH.
PFES_SKY
Causes a sky and horizon backdrop to be drawn. These are
drawn using large polygons that are recalculated each
frame, using information about the clipping planes, field
of view, and eyepoint vertical position for the selected
channel. They are drawn instead of a screen clear,
forcing the Z buffer to a known state. If the viewpoint
goes below the ground plane, the area below the horizon
Page 3
pfEarthSky(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
will not be cleared. In the case of PFES_SKY, the screen
is never cleared below the lower edge of the horizon.
PFES_SKY_GRND
Add a ground plane to the sky and horizon model drawn by
PFES_SKY.
PFES_SKY_CLEAR
Draw the sky and horizon, and clear the screen below the
edge of the horizon.
PFES_CLOUDS is used to set the type of cloud layer. Currently, the
only value supported is:
PFES_OVERCAST
This cloud type is a non-textured, opaque region that has
a color and both top and bottom dimensions. This, being
the only choice at present, is the default type.
pfESkyColor is used to set the colors referenced by the earth-sky
rendering routines. pfGetESkyColor returns the indicated color component
of the earth-sky mode. The components are:
PFES_SKY_TOP The color of the sky directly above the
viewpoint.
PFES_SKY_BOT The color of the sky where it joins the horizon.
PFES_HORIZ The color of the bottom edge of the horizon.
PFES_GRND_FAR The color of the ground plane where it meets the
horizon.
PFES_GRND_NEAR The color of the ground plane directly below the
viewer.
PFES_CLOUD_BOT The color of the bottom of the opaque cloud
layer.
PFES_CLOUD_TOP The color of the top of the opaque cloud layer.
PFES_CLEAR The color for simple screen clearing.
The fog color is set as explained in the pfFog man page.
pfESkyAttr is used to set a number of attributes. The companion function
pfGetESkyAttr is used to return these same attribute values. The tokens
and their meanings are listed below:
PFES_GRND_HT Set the ground height for the ground plane that is
used when PFES_SKY_GRND is enabled and defines the bottom edge
of the horizon which is used in all of the modes that draw a
Page 4
pfEarthSky(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
sky. The ground plane extends from the eyepoint to the horizon
with a width greater than the field of view. Note that objects
placed on the ground with the same height may not Z buffer
correctly. Also, as objects move into the distance, the Z
buffer resolution for those pixels will decrease, making proper
priority resolution of small distances between the ground plane
and objects less likely.
PFES_HORIZ_ANGLE Set the vertical displacement of the horizon band
in degrees. The horizon band is blended into the sky bottom
color so it may appear to be less than this angle. This angle
remains constant for any heading. To simulate directional
horizon glow, the angle and color can be changed each frame to
achieve the correct appearance.
PFES_CLOUD_TOP Set the cloud layer upper position. The cloud layer
is enabled when the cloud base is less than the cloud top. By
default, it is disabled (base > top). Each token is followed
by a height value. The cloud layer is opaque. The cloud layer
thickness is simply (top - bottom).
PFES_CLOUD_BOT Set the cloud layer lower position. The cloud layer
is enabled when the cloud base is less than the cloud top. By
default, it is disabled (base > top). Each token is followed
by a height value. The cloud layer is opaque. The cloud layer
thickness is simply (top - bottom).
PFES_TZONE_TOP Set the transition zone for exiting a cloud layer.
Provided to allow a smooth transition out of clouds. This
transition is enabled by making the transition height greater
than the cloud top. It is disabled by doing the opposite or by
disabling the cloud layer. By default, the transition zone is
disabled.
PFES_TZONE_BOT Set the transition zone for entering a cloud layer.
Provided to allow a smooth transition into clouds. This
transition is enabled by making the transition height less than
the cloud bottom. It is disabled by doing the opposite or by
disabling the cloud layer. By default, the transition zone is
disabled.
PFES_GRND_FOG_TOP Set the height of the ground fog layer. Ground
fog is enabled when a valid pfFog is set. By default ground
fog is disabled.
PFES_TENT_DISTANCE_FACTOR sets a factor for pulling the pfEarthSky
geometry towards the camera and away from the far clipping
plane. When using pfChannel offsets, the pfEarthSky geometry
may be clipped against the far clipping plane. In order to
avoid this artifact, the application may request to draw the
pfEarthSky geometry closer to the camera. A value of 1.0 means
drawing the geometry at the far clipping plane. a value of 0.0
Page 5
pfEarthSky(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
means drawing the geometry at the near plane. The default value
is 1.0.
pfESkyFog sets which type of fog to use when in ground fog or general
visibility. The token may be one of the following values:
PFES_GRND
PFES_GENERAL
pfGetESkyFog returns the indicated fog selection.
Several different fog functions may be defined at initialization, then
just switched in using this routine. Distant haze and different curves
would be done this way. If ground fog is enabled, and the viewer is
transitioning out of the ground fog layer, the fog will be blended into
clear visibility or PFES_GENERAL fog.
Due to the design of the graphics library, fog would be discontinuous in
adjacent channels which use rotational viewing offsets (See
pfChanViewOffsets). However, when attached to a pfChannel (see
pfChanESky) that has a rotational viewing offset, a pfEarthSky will
automatically adjust the ranges of the pfFog set by pfESkyFog to account
for any rotational offsets so that fog is continuous across adjacent
channels.
NOTES
pfEarthSky does not work properly for off-axis viewing frusta.
Because PFES_TAG only has effect when multisampling, care must be taken
for cross-platform portability. Background renderings that rely on the
depth buffer having been reset (e.g. backgrounds that do not disable z
buffering with glDepthFunc(GL_ALWAYS) in OpenGL) may need to request a
normal depth buffer clear when not multisampling.
When multisampling, PFES_SKY_GND and PFES_SKY are significantly faster
than PFES_SKY_CLEAR.
Layered Fog Support
pfEarthSky provides basic support for creating a layered fog model based
on the defined elevations and densities of the different atomospheric
layers. The resulting model is stored in a 3D texture where each slice
of the 3D texture represents summed fog densities for an eye at a given
elevation and points at d,h where d is a horizontal distance from the
eye and h is the height of the given point along a defined "up" vector. A
texture lookup table (texture color table) is then use to exponentiate
this value to turn the fog density into a fog blending factor. pfTexGen
functions are used to do the proper indexing into the fog model when
rendering. This 3D texture can be used to apply a layered fog model as a
second pass after first rendering an unfogged scene.
pfESkyMakeFogTexture will create the fog texture and create it just based
on the normal pfEarthSky definition, or use additional information, such
as your own provided layers and densities for finer resolution. The
following routines allow you to set and get the different parts of the
Page 6
pfEarthSky(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
elements used to create the model:
pfESkyFogDensities
pfGetESkyFogDensities
pfESkyFogTextureElevations
pfGetESkyFogTextureElevations
pfESkyFogTexture
pfGetESkyFogTexture
pfESkyFogTextureColorTable
pfGetESkyFogTextureColorTable
pfESkyLoadFogTextureColorTable
/usr/share/Performer/src/sample/C/fogfly/
For an example of layerd fog look at the
demonstration program.
BUGS
The layered fog model on pfEarthSky doesn't work with the pfEarthSky
geometry. Instead, you should define your own enviornmental geometry.
SEE ALSO
pfChanViewOffsets, pfClear, pfFog, pfNewChan, zfunction, glDepthFunc,
pfDelete
Page 7
