pfShadow(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfShadow(3pf)NAMEpfShadow - Controls rendering of shadows under selected objects.
FUNCTION SPECIFICATION
#include <Performer/pf/pfShadow.h>
void pfShadow::setNumCasters(int index);
int pfShadow::getNumCasters(void);
void pfShadow::setShadowCaster(int index, pfNode *caster,
pfMatrix &mat);
void pfShadow::adjustCasterCenter(int index, pfVec3 *trans);
pfNode * pfShadow::getShadowCaster(int index);
pfMatrix * pfShadow::getShadowCasterMatrix(int index);
void pfShadow::setNumSources(int num);
int pfShadow::getNumSources(void);
void pfShadow::setSourcePos(int index, float x, float y,
float z, float w);
void pfShadow::getSourcePos(int index, float *x, float *y,
float *z, float *w);
void pfShadow::setLight(int index, pfLight *light);
pfLight * pfShadow::getLight(int index);
void pfShadow::setAmbientFactor(int light, float factor);
float pfShadow::getAmbientFactor(int light);
void pfShadow::setTextureBlendFunc(_pfBlendFunc blendFunc);
void pfShadow::addChannel(pfChannel *channel);
void pfShadow::updateView(void);
void pfShadow::updateCaster(int index, pfMatrix &mat);
void pfShadow::apply(void);
void pfShadow::draw(pfChannel *chan);
void pfShadow::setFlags(int which, int value);
Page 1
pfShadow(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfShadow(3pf)
int pfShadow::getFlags(int which);
void pfShadow::setVal(int caster, int light, int which,
float val);
float pfShadow::getVal(int caster, int light, int which);
pfDirData * pfShadow::getDirData(int caster, int light);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfShadow is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfShadow. This is also true for
ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfShadow can also be used with these functions
designed for objects of class pfMemory.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
Page 2
pfShadow(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfShadow(3pf)DESCRIPTION
A pfShadow is used to control rendering of shadows under selected
objects. The user can specify a set of objects and a set of light
sources. The class takes over the drawing and renders shadows for each
combination of a shadow caster and a light source. Shadows are rendered
by projecting the objects as seen from the light source into a texture
and projecting the texture onto a scene. To avoid computing the texture
for each frame, a set of textures is precomputed at the first frame, then
for each frame the best representative is chosen and warped to
approximate the correct shadow.
A pfShadow is not part of the scene graph, it is created separately by
the application process. Once created the user can specify the number of
shadow casters by calling pfShadow::setNumCasters and then set each
caster using pfShadow::setShadowCasters. 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 pfShadow::setNumSources. A light
source is defined by its position or direction, set by
pfShadow::setSourcePos or pfShadow::setLight. The class initialization
is completed by calling pfShadow::apply.
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 pfShadow::addChannel for each channel (at
the beginning of the application). Whenever the view changes the
application process has to call pfShadow::updateView. Even if the view
does not change, this function has to be called at least once in a single
process mode or as many times as the number of buffers in a pfFlux in MP
mode. Without updating the view the shadow is not rendered correctly.
Example:
pfShadow *shd = new pfShadow;
shd->setNumCasters(2);
shd->setShadowCaster(0, node1, matrix1);
shd->setShadowCaster(1, node2, matrix2);
shd->setNumSources(1);
shd->setSourcePos(0, x1, y1, z1, w1);
shd->addChannel(channel);
shd->apply();
See a sample implementation of shadows in
perf/samples/pguide/libpf/C++/shadowsNew.
Page 3
pfShadow(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfShadow(3pf)
ADDITIONAL PARAMETERS
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 slightly different direction its 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 case of some
long protruding parts) and function pfShadow::adjustCasterCenter can be
used to shift the bounding box center towards the object center.
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 pfShadow::setAmbientFactor. The default value is 0.6
For each combination shadow caster-light source it is possible to specify
how many shadow textures are used, what their sizes are, and the set of
directions, for which the textures are precomputed. The number of
textures and their size can be set by pfShadow::setVal, where the first
parameter is PFSHD_PARAM_TEXTURE_SIZE or PFSHD_PARAM_NUM_TEXTURES. The
set of directions can be controlled by getting the pointer to the
corresponding pfDirData (a class that stores data associated with a set
of directions), using pfShadow::getDirData. Then you can either select
the default mode (see below) or specify the directions directly. See
class pfDirData for more details. By default there is one texture of
size 512x512 and the direction corresponds to the light direction (or a
vector from a point light source to the object center). If there are more
textures, the original light direction is rotated around a horizontal
direction, assuming that the object will mostly keep its horizontal
position (for example a helicopter or a plane).
RENDERING
The user has to call the draw function provided by the class
pfShadow::draw otherwise shadows are not rendered. 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.
Make sure that the window is not obscured, otherwise the textures would
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,
a flag PFSHD_BLEND_TEXTURES can be set using pfShadow::setFlags. In this
case two closest textures are selected and blended together, resulting in
smoother transitions. Also, instead of a linear blend between the
textures, the user can define a blend function, mapping values 0-1 to
interval 0-1. The blend function can be set using
pfShadow::setTextureBlendFunc.
Every time the caster changes its position or orientation with respect to
the light source, it is necessary to update its matrix using
Page 4
pfShadow(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages pfShadow(3pf)
pfShadow::updateCaster (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 one
or two closest representatives.
A visual with an alpha channel has to be selected for the rendering to
work. See sample code in perf/samples/pguide/libpf/C++/shadowsNew.C for
an example of how to get a visual with an alpha channel.
LIMITATIONS
Since pfShadow is using its own draw function you cannot use it together
with pfVolFog.
pfShadow is using cull programs to cull out geometry that is not affected
by the shadow to make the multi-pass drawing more efficient. At present,
though, the cull program used by pfShadow class overwrites any other cull
program specified by the user. Note: make sure that you do not overwrite
TravMode in your application by setting it to PFCULL_ALL, the mode is set
by pfShadow when pfShadow::apply is called.
When projecting a caster into a shadow texture, pfSwitch children are
selected according to switch value. In case of pfLOD the finest level is
chosen. Also, pfSequences are ignored, which can be useful in case of
helicopter rotors, for example.
SEE ALSO
pfObject, pfDirData, pfTexture, pfCullProgram
Page 5
