pfDecal(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfDecal(3pf)NAME
pfDecal, pfGetDecal, pfApplyDecalPlane, pfGetCurDecalPlane - Set and get
decal mode for drawing coplanar polygons
FUNCTION SPECIFICATION
#include <Performer/pr.h>
void pfDecal(int mode);
int pfGetDecal(void);
void pfApplyDecalPlane(pfPlane *plane);
pfPlane * pfGetCurDecalPlane();
PARAMETERS
mode is a symbolic constant specifying a decaling mode and is one of:
PFDECAL_OFF
Decaling is off
PFDECAL_BASE
Subsequent drawn geometry is considered to be 'base' geometry.
Use the default decaling mechanism.
PFDECAL_LAYER
Subsequent drawn geometry is considered to be 'layered'
geometry. Use the default decaling mechanism.
PFDECAL_BASE_FAST, PFDECAL_LAYER_FAST
Use a decaling mechanism appropriate to the hardware that
produces the fastest, but not necessarily the highest quality,
decaling.
PFDECAL_BASE_HIGH_QUALITY, PFDECAL_LAYER_HIGH_QUALITY
Use a decaling mechanism appropriate to the hardware that
produces the highest quality, but not necessarily the fastest,
decaling.
PFDECAL_BASE_DISPLACE, PFDECAL_LAYER_DISPLACE
Use the polygon displacement technique (glPolygonOffsetEXT in
OpenGL) to slightly displace the depth values of layer
geometry toward the eyepoint.
PFDECAL_BASE_DISPLACE, PFDECAL_LAYER_DISPLACE_AWAY
Use the polygon displacement technique (glPolygonOffsetEXT in
OpenGL) to slightly displace the depth values of layer
geometry away from the eyepoint.
PFDECAL_BASE_STENCIL, PFDECAL_LAYER_STENCIL
Use the stencil buffer technique (glStencilFunc, glStencilOp,
and glEnable(GL_STENCIL_TEST) in OpenGL) to determine visual
Page 1
pfDecal(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfDecal(3pf)
priority.
PFDECAL_PLANE
Use the current decal reference plane to force all decal
geometry to be rendered with the same plane equation.
The constant PFDECAL_PLANE may be specified alone or OR'ed with one of
the above modes to enable the use of reference planes for the base and
layer geometry. When these planes are specified, subsequent geometry is
forced to be truly coplanar with the reference plane. Displace and
stencil operations happen on the planed geometry. Reference planes may
be specified in the global state with pfApplyDecalPlane, in the
pfGeoState with the PFSTATE_DECAL_PLANE attribute, and on the pfGeoSet
itself with pfGeoSet::setDecalPlane. Setting reference planes on
pfGeoSets directly may help improve performance by allowing better re-use
of pfGeoStates but will also slightly slow the handling of the pfGeoSet.
Reference planes are only supported under OpenGL operation and require
the reference_plane SGI extension to the OpenGL. The PFQFTR_DECAL_PLANE
to pfQueryFeature can be used for run-time queries for the support of
decal reference planes.
DESCRIPTION
In some cases, such as when drawing stripes on a runway, it is easier to
draw coplanar polygons than it is to model the geometry without coplanar
faces. However, on Z-buffer based machines, coplanar polygons can cause
unwanted visual artifacts because the visual priorities of the coplanar
polygons are subject to the finite numerical precision of the graphics
pipeline. This results in a "torn" appearance and "twinkling" from frame
to frame.
Decaled geometry can be thought of as a stack where each layer has visual
priority over the geometry beneath it in the stack. An example of a 3
layer stack consists of stripes which are layered over a runway which is
layered over the ground. The bottommost layer is called the "base" while
the other layers are called "decals" or "layers". When using certain
hardware mechanisms (PFDECAL_BASE_STENCIL) to implement pfDecal, the
"base" is special because it defines the depth values which are used to
determine layer visibility with respect to other scene geometry and which
are written to the depth buffer.
Certain decaling mechanisms (currently only DISPLACE) require that each
layer in the layer stack be identified for proper rendering. The
PFDECAL_LAYER_1 through PFDECAL_LAYER_7 tokens are provided for this
purpose and should be logically OR'ed into the layer mode, e.g.,
PFDECAL_LAYER_DISPLACE | PFDECAL_LAYER_2. Note that the layer identifier
is extracted from the mode as follows:
layerId = (mode & PFDECAL_LAYER_MASK) >> PFDECAL_LAYER_SHIFT;
Page 2
pfDecal(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfDecal(3pf)pfDecal is used to draw visually correct coplanar polygons that are
arranged as 'base' and 'layer' polygons as shown here:
/* Prepare to draw base polygons */
pfDecal(PFDECAL_BASE_DISPLACE);
:
/* draw base geometry using OpenGL Performer or graphics library */
:
/* Prepare to draw first layer polygons */
pfDecal(PFDECAL_LAYER_DISPLACE);
:
/* draw layer geometry using OpenGL Performer or graphics library */
:
/* Prepare to draw second layer polygons */
pfDecal(PFDECAL_LAYER_DISPLACE | PFDECAL_LAYER_1);
:
/* draw layer geometry using OpenGL Performer or graphics library */
:
/* exit decal mode */
pfDecal(PFDECAL_OFF);
The different pfDecal modes offer quality-feature tradeoffs listed in the
table below:
DISPLACE STENCIL (DISPLACE | OFFSET)
___________________________________________________________
Quality medium high high
Order not required required not required
Coplanarity not required required not required
Containment not required required not required
|
|
|
The STENCIL mechanism offers the best image quality but at a performance
cost since the base and layer geometry must be rendered in strict order.
When multisampling on RealityEngine, this mechanism also significantly
reduces pixel fill performance. An additional constraint is that
STENCILed layers must be coplanar or decal geometry may incorrectly show
through base geometry. For proper results, each layer in the "stack" must
be completely contained within the boundaries of the base geometry.
The DISPLACE mechanism offers the best performance since layers can be
sorted by graphics state, because the displace call itself is usually
faster than other mode changes, and because there is no pixel fill rate
penalty when it is in use.
The DISPLACE mechanism does not require that geometry within a single
layer be coplanar. The main disadvantage is that decal geometry may
incorrectly poke through other geometry due to the displacement of the
decal geometry.
The performance differences between STENCIL and DISPLACE modes are
hardware-dependent so some experimentation and benchmarking is required
Page 3
pfDecal(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfDecal(3pf)
to determine the most suitable method for your application.
pfDecal is a display-listable command. If a pfDispList has been opened
by pfDispList::open, pfDecal will not have immediate effect but will be
captured by the pfDispList and will only have effect when that pfDispList
is later drawn with pfDispList::draw.
pfGetDecal returns the current decal mode.
The decaling mode state element is identified by the PFSTATE_DECAL token.
Use this token with pfGeoState::setMode to set the decaling mode of a
pfGeoState and with pfOverride to override subsequent decaling mode
changes.
pfApplyDecalPlane will make plane the current decal reference plane and
is a display-listable command. pfGetCurDecalPlane returns the current
decal reference plane.
EXAMPLES
Example 1:
/* Set up 'base' pfGeoState */
gstate->setMode(PFSTATE_DECAL, PFDECAL_BASE);
/* Attach pfGeoState to pfGeoSet */
gset->setGState(gstate);
/* Draw base pfGeoState */
gset->draw();
Example 2:
/* Override decaling mode to PFDECAL_OFF */
pfDecal(PFDECAL_OFF);
pfOverride(PFSTATE_DECAL, PF_ON);
NOTES
PFDECAL_BASE_FAST currently implies displacepolygon on machines that
support this feature. The use of displacements for rendering coplanar
geometry can cause visual artifacts such as decals "Z fighting" or
"flimmering" when viewed perpendicularly and punching through geometry
that should be in front of them when viewed obliquely. In these cases,
use PFDECAL_LAYER_OFFSET, modify the database should by cutting away
overlapping polygons to eliminate the need for coplanar rendering or use
PFDECAL_BASE_HIGH_QUALITY or PFDECAL_BASE_STENCIL.
PFDECAL_BASE_STENCIL is implemented with stencil planes and requires the
Page 4
pfDecal(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfDecal(3pf)
framebuffer to be configured with at least one stencil bit (see
stensize(3g) and mssize(3g)). The first stencil bit should be considered
as reserved for pfDecal.
When using PFDECAL_LAYER_OFFSET, the minimum depth buffer range set with
lsetdepth must be incremented an extra 1024 * max layers so the negative
displacement of the layers does not wrap. pfInitGfx does this
automatically.
The PFDECAL_LAYER_DISPLACE decal mode implements a Z-depth bias that is
influenced by several issues including near clipping plane distance, far
clipping plane distance, the ratio of these values, and the effective
depth precision in the Z-buffer. Clipping plane distances can be inquired
from the pfChannel via channel API and the Z-buffer configuration of the
current pfWindow is available from the pfQueryWin function, using the
PFQWIN_MIN_DEPTH_VAL, PFQWIN_MAX_DEPTH_VAL, and PFQWIN_DEPTH_BITS
arguments.
SEE ALSO
mssize, pfDispList, pfGStateMode, pfGeoState, pfOverride, pfState,
pfInitGfx, pfQueryWin, pfChannel, stencil, stensize
Page 5
