pfFog(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFog(3pf)NAME
pfNewFog, pfGetFogClassType, pfFogType, pfGetFogType, pfFogColor,
pfGetFogColor, pfFogRange, pfGetFogRange, pfFogOffsets, pfGetFogOffsets,
pfFogRamp, pfGetFogRamp, pfGetFogDensity, pfApplyFog, pfGetCurFog -
Create, modify and query fog definition
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfFog * pfNewFog(void *arena);
pfType * pfGetFogClassType(void);
void pfFogType(pfFog *fog, int type);
int pfGetFogType(const pfFog *fog);
void pfFogColor(pfFog *fog, float r, float g, float b);
void pfGetFogColor(const pfFog *fog, float *r, float *g, float *b);
void pfFogRange(pfFog *fog, float onset, float opaque);
void pfGetFogRange(const pfFog *fog, float *onset, float *opaque);
void pfFogOffsets(pfFog *fog, float onset, float opaque);
void pfGetFogOffsets(const pfFog *fog, float *onset,
float *opaque);
void pfFogRamp(pfFog *fog, int points, float *range,
float *density, float bias);
void pfGetFogRamp(const pfFog *fog, int *points, float *range,
float *density, float *bias);
float pfGetFogDensity(const pfFog *fog, float range);
void pfApplyFog(pfFog *fog);
pfFog * pfGetCurFog(void);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfFog is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfFog. Casting an object of class
pfFog 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.
Page 1
pfFog(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFog(3pf)
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 pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfFog 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);
DESCRIPTION
pfFog is used to simulate atmospheric phenomena such as fog and haze and
for depthcueing. The fog color is blended with the color that is
computed for rendered geometry based on the geometry's range from the
eyepoint. Fog effects may be computed at geometric vertices and then
interpolated or computed precisely at each individual pixel.
pfNewFog creates and returns a handle to a new pfFog. arena specifies a
malloc arena out of which the pfFog is allocated or NULL for allocation
from the calling process' heap. pfFogs can be deleted with pfDelete.
pfGetFogClassType returns the pfType* for the class pfFog. The pfType*
returned by pfGetFogClassType is the same as the pfType* returned by
invoking pfGetType on any instance of class pfFog. When decisions are
made based on the type of an object, it is usually better to use
pfIsOfTypeto test if an object is of a type derived from a Performer type
rather than to test for strict equality of the pfType*'s.
pfFogType sets the fog type to be used when this pfFog is applied. type
Page 2
pfFog(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFog(3pf)
must be one of:
PFFOG_VTX_LIN
PFFOG_VTX_EXP
PFFOG_VTX_EXP2
PFFOG_PIX_LIN
PFFOG_PIX_EXP
PFFOG_PIX_EXP2
PFFOG_PIX_SPLINE
Detailed descriptions of these fog types are in the OpenGL glFog(3G) man
pages, with the exception of PFFOG_PIX_SPLINE. This is an advanced fog
type that allows the user to define fog densities as a PFFOG_MAXPOINTS
point spline curve as described in pfFogRamp. When fog type
PFFOG_PIX_SPLINE is specified the internal fog ramp table will be
recomputed using the current values of fog range, fog offsets, and fog
ramp. The default fog type is PFFOG_PIX_EXP2. pfGetFogType returns the
fog type as its value.
pfFogColor specifies the color to be used as the fog blend color. The
default fog color is white, whose RGB value is [1.0, 1.0, 1.0].
pfGetFogColor returns the fog color in the variables specified.
pfFogRange sets the onset and opaque ranges in world coordinate
distances. The onset is the range at which fog blending first occurs.
The opaque range is the distance at which scene elements are completely
opaque and appear as the fog color. For the fog types PFFOG_VTX_EXP,
PFFOG_VTX_EXP2, PFFOG_PIX_EXP, PFFOG_PIX_EXP2 only the opaque range is
significant; the onset range is always 0.0 in world coordinates. If the
fog type is PFFOG_PIX_SPLINE then the internal fog ramp table will be
recomputed whenever the ranges are specified. pfGetFogRange returns the
current fog range values.
pfFogOffsets sets the individual onset and opaque range offsets used to
modify the fog range. These offsets are added to the fog range values
when the pfFog is applied. Calling this function with offsets of zero
causes the ranges defined by pfFogRange to be used directly. If the fog
type is PFFOG_PIX_SPLINE then the internal fog ramp table will be
recomputed whenever the offsets are specified. pfGetFogOffsets returns
the current fog offset values.
pfFogRamp defines the fog density curve using a table rather than as an
algebraic function of range. The fog ramp table is only used with the
PFFOG_PIX_SPLINE fog type. From four to PFFOG_MAXPOINTS control points
are used to describe this curve. If fewer than four control points are
given, the last point will be replicated to create four points. Each
point consists of a range and fog density pair. These are given in
ascending order in the arrays range and density. The range value is
specified in a normalized form in the numeric range [0..1], with 0.0
corresponding to the fog onset range (plus offset) and 1.0 the fog opaque
range (plus offset). This allows the ranges to be changed while
maintaining the same fog density curve. The fog density at each range
point must also be in the [0..1] range, where 1.0 represents no fog and
Page 3
pfFog(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFog(3pf)
0.0 means opaque fog, using the OpenGL- style interpretation. A Catmull-
Rom spline interpolation is used to create hardware fog tables from this
fog ramp table. If the fog type is PFFOG_PIX_SPLINE then the internal
fog ramp table will be recomputed whenever the fog ramp, fog range, or
fog offsets are specified. The default fog ramp table defines a linear
interpolation between the onset and opaque ranges. Currently, the bias
value must be set to zero. pfGetFogRamp returns the number of points,
range and density arrays, and bias in the variables specified.
pfGetFogDensity returns the density, ranging from 0 to 1 of fog at range
range.
pfApplyFog configures the graphics hardware with the fog parameters
encapsulated by fog. Only the most recently applied pfFog is active
although any number of pfFog definitions may be created. Fogging must
also be enabled (pfEnable(PFEN_FOG)) for fog to take effect.
Modifications made to this pfFog do not have effect until pfApplyFog is
called. If a pfDispList has been opened by pfOpenDList, pfApplyFog will
be captured by the pfDispList and will only have effect when that
pfDispList is later drawn with pfDrawDList.
The fog state element is identified by the PFSTATE_FOG token. Use this
token with pfGStateAttr to set the fog mode of a pfGeoState and with
pfOverride to override subsequent fog changes:
Example 1:
/* Set up 'fogged' pfGeoState */
pfGStateMode(gstate, PFSTATE_ENFOG, PFFOG_ON);
pfGStateAttr(gstate, PFSTATE_FOG, fog);
/* Attach gstate to gset */
pfGSetGState(gset, gstate);
/* Draw fogged gset */
pfDrawGSet(gset);
Example 2:
/* Override so that all geometry is fogged with 'fog' */
pfEnable(PFEN_FOG);
pfApplyFog(fog);
pfOverride(PFSTATE_FOG | PFSTATE_ENFOG, PF_ON);
pfGetCurFog returns the currently active pfFog.
Page 4
pfFog(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFog(3pf)NOTES
PFFOG_PIX_SPLINE and PFFOG_PTX* fog modes are not currently supported
under Linux.
PFFOG_PIX_SPLINE is only effective on InfiniteReality and RealityEngine
graphics systems. The visual quality of per-pixel fogging is influenced
by the ratio of the distances from the eye to the far and the eye to the
near clipping planes. This ratio should be minimized for best results.
BUGS
pfGetFogDensity does not properly evaluate PFFOG_PIX_SPLINE; instead it
linearly interpolates the spline points.
SEE ALSO
pfDispList, pfEnable, pfGeoState, pfObject, pfOverride, fogvertex,
lsetdepth, perspective, glFog
Page 5