EXT_stencil_clear_tag
GL_EXT_stencil_clear_tag
Mark J. Kilgard, NVIDIA Corporation (mjk 'at' nvidia.com)
Copyright NVIDIA Corporation, 2004.
Implemented, September 2004
Advertised and hardware-supported on NVIDIA GeForce 6 TurboCache
GPUs.
Last Modified: 10/15/2004
NVIDIA Revision: 4
XXX
Written based on the wording of the OpenGL 1.5 specification.
Stencil-only framebuffer clears are increasingly common as 3D
applications are now using rendering algorithms such as stenciled
shadow volume rendering for multiple light sources in a single frame,
recent "soft" stenciled shadow volume techniques, and stencil-based
constructive solid geometry techniques. In such algorithms there
are multiple stencil buffer clears for each depth buffer clear.
Additionally in most cases, these algorithms do not require all
of the 8 typical stencil bitplanes for their stencil requirements.
In such cases, there is the potential for unused stencil bitplanes
to encode a "stencil clear tag" in such a way to reduce the number
of actual stencil clears. The idea is that switching to an unused
stencil clear tag logically corresponds to when an application would
otherwise perform a framebuffer-wide stencil clear.
This extension exposes an inexpensive hardware mechanism for
amortizing the cost of multiple stencil-only clears by using a
client-specified number of upper bits of the stencil buffer to
maintain a per-pixel stencil tag.
The upper bits of each stencil value is treated as a tag that
indicates the state of the upper bits of the "stencil clear tag" state
when the stencil value was last written. If a stencil value is read
and its upper bits containing its tag do NOT match the current upper
bits of the stencil clear tag state, the stencil value is substituted
with the lower bits of the stencil clear tag (the reset value).
Either way, the upper tag bits of the stencil value are ignored by
subsequent stencil function and operation processing of the stencil
value.
When a stencil value is written to the stencil buffer, its upper bits
are overridden with the upper bits of the current stencil clear tag
state so subsequent reads, prior to any subsequent stencil clear
tag state change, properly return the updated lower bits.
In this way, the stencil clear tag functionality provides a way to
replace multiple bandwidth-intensive stencil clears with very
inexpensive update of the stencil clear tag state.
If used as expected with the client specifying 3 bits for the stencil
tag, every 7 of 8 stencil-only clears of the entire stencil buffer can
be substituted for an update of the current stencil clear tag rather
than an actual update of all the framebuffer's stencil values. Still,
every 8th clear must be an actual stencil clear. The net effect is
that the aggregate cost of stencil clears is reduced by a factor of
1/(2^n) where n is the number of bits devoted to the stencil tag.
The application specifies two new pieces of state: 1) the number of
upper stencil bits, n, assigned to maintain the tag bits for each
stencil value within the stencil buffer, and 2) a stencil clear tag
value that packs the current tag and a reset value into a single
integer values. The upper n bits of the stencil clear tag value
specify the current tag while the lower s-min(n,s) bits specify
the current reset value, where s is the number of bitplanes in the
stencil buffer and n is the current number of stencil tag bits.
If zero stencil clear tag bits are assigned to the stencil tag
encoding, then the stencil buffer operates in the conventional
manner.
1) Can the stencil clear tag state be switched at anytime?
RESOLUTION: Yes. The state controls the interpretation of
the stencil values without actually change the values within
the stencil buffer. So, for example, it is possible to render
to the stencil buffer with 3 tag bits and then switch to 4 tag
bits and a different reset value.
The effect of changing stencil clear tag state is well-defined
though perhaps not useful.
The motivation for this decision is to make the underlying
hardware implementation simple and not encumber operations such
as stencil readback with extra expense to re-interpret stencil
values.
2) Can two distinct OpenGL rendering contexts render to the same
framebuffer but with different stencil clear tag state?
RESOLUTION: Yes. The stencil buffer contains raw stencil values
whose interpretation and update may be different for the two
contexts, but the values themselves are the same.
The motivation for this is that it avoids trying to coordinate
two different contexts into maintaining the same interpretation
of the stencil buffer. Different contexts can each view the
stencil buffer values differently based on their own stencil
clear tag state.
3) For the purposes of the stencil comparison and stencil operations,
how are upper bits of the read stencil value treated?
RESOLUTION: The upper n bits where n is the current value of
stencil tag bits (GL_STENCIL_TAG_BITS_EXT) are masked to zero
when n is greater than zero.
For example, if a raw stencil value is 0xFA and the current
stencil tag bits state is 3 with a stencil clear tag value of
0x82, the effective read stencil value is 0x02 because the upper
3 bits of 0xFA do not match the upper 3 bits of 0x82 and so the
effective read stencil value is replaced with the lower 5 bits
of 0x82 which is 0x02 while masking to zero the upper 3 bits.
If instead, the stencil clear tag value was 0xEB, then the
effective read stencil value is 0x1A because the upper 3 bits
of 0xEB match the upper 3 bits of 0xFF so the effective read
stencil value is 0xFA with the upper 3 bits masked to zero.
4) How does the GL_INCR operation work when the stencil tag bits
value is greater than zero?
RESOLUTION: GL_INCR saturates to the value 2^(s-min(n,s))-1
where s is the number of stencil bits in the stencil buffer and n
is the current value of stencil tag bits, rather than saturating
to 2^s-1 or wrapping.
The motivation for this is to ensure that the stencil clear tag
mechanism can fully emulate stencil buffers with fewer than s
bits.
5) What is the initial number of stencil tag bits?
RESOLUTION: Zero. This is consistent with the conventional
operation of the stencil buffer. The stencil clear tag value
state is ignored when the stencil tag bits value is zero.
6) Should glClear involving GL_STENCIL_BUFFER_BIT be subject to the
stencil clear tag or tag bits state?
RESOLUTION: No. An actual clear to the stencil buffer needs to
reset the bitplanes allocated to the upper stencil tag bits as
well as the lower bitplanes. So the stencil mask applies, but
the stencil clear tag and tag bits state is ignored by glClear.
7) Should glDrawPixels operations be subject to the stencil
clear tag functionality?
RESOLUTION: Yes. glDrawPixels to stencil already abides by
the stencil write mask. Conceptually, think of glDrawPixels to
stencil as being the GL_REPLACE operation where the value to be
written comes from the glDrawPixels image rectangle rather than
the stencil reference value.
The motivation is to allow the stencil clear tag mechanism to
fully simulate a stencil buffer with fewer stencil bits.
If you want to write the entire stencil value, including upper
bits that are allocated to encode the stencil tag, simply set
the stencil tag bits state to zero for the duration of the
glDrawPixels command.
8) Should glReadPixels operations of type GL_STENCIL_INDEX be
subject to the stencil clear tag state?
RESOLUTION: Yes. So if you read stencil values from the
stencil buffer, the n upper bits of each stencil value is
compared to the n upper bits of the stencil clear tag value
and if they mismatch, the lower s-min(n,s) bits of the stencil
clear tag value (the reset value) are returned instead, where s
is the number of stencil bitplanes and n is the current stencil
tag bits value. In any case, the upper n bits of the stencil
value are zeroed.
The motivation is to allow the stencil clear tag mechanism to
fully simulate a stencil buffer with fewer stencil bits.
If you want to read the entire stencil value, including upper
bits that are allocated to encode the stencil tag, then set
the stencil tag bits state to zero for the duration of the
glReadPixels command.
9) Should glCopyPixels operations of type GL_STENCIL_INDEX be
subject to the stencil clear tag state?
RESOLUTION: Yes, because glReadPixels and glDrawPixels are both
affected and glCopyPixels is defined in terms of glReadPixels
and glDrawPixels.
10) Should the current tag and reset value in the current stencil
clear tag be packed into a single value where the stencil tag
bits value divides the upper tag value bits from the lower reset
value bits?
RESOLUTION: Yes. This makes a lot of sense because there are
always s bits required where n bits are for the current tag value
and s-min(n,s) bits are for the reset value, where s is the number
of stencil bitplanes and n is the number of stencil tag bits.
This packing also makes the explanation of how bit comparisons
and the required masking operations operate in the specification
language. It also naturally corresponds to how a hardware
implementation would maintain the state.
11) Clears can be scissored to only update a subrectangle of the
entire framebuffer. Can the stencil clear tag facility accelerate
scissored clears that do not clear the entire framebuffer?
RESOLUTION: No. The stencil clear tag state is a single
per-context state value that applies to the entire framebuffer.
For scissored clears to sufficiently small enough subrectangles
of the screen, it may be more advantageous to perform an actual
scissored clear if changing the current stencil clear tag value
would be better used to save an subsequent actual stencil clear
of the entire (or nearly the entire) framebuffer.
Doom 3 uses scissored clears when performing per-light stencil
clears for its stenciled shadow volumes where the scissor is a
2D bound for the light's illumination.
12) How does this extension interact with EXT_stencil_two_side or
other two-sided stencil testing functionality such as that
provided by OpenGL 2.0?
RESOLUTION: The stencil clear tag state is not two-sided because
it reflects the manner that stencil values in the stencil buffer
are read to and written from the buffer rather than anything to
do with the facingness of primitives.
13) How does the GL_KEEP operation operate when the value of
GL_STENCIL_TAG_BITS_EXT is greater than zero?
RESOLUTION: GL_KEEP means no stencil write is performed so the
pixel's stencil value is completely unchanged. This means the
pixel's stencil value will still have the old stencil tag.
The rationale for this is that GL_KEEP will always avoid memory
writes to the stencil buffer, even when the current stencil tag
state does not match the tag of pixel's stencil value.
All other stencil operations must actually write the stencil
tag bits into the upper bits of the pixel's stencil value
if the old value's tag does not match the current stencil tag
state. For example, if the value of GL_STENCIL_TAG_BITS_EXT is 3,
the value of GL_STENCIL_CLEAR_TAG_EXT is 0x80, the stencil write
mask is 0xFF, and a pixel's stencil value is 0x00, the result
of a GL_ZERO stencil operation for this pixel is to write 0x80.
into the stencil buffer.
14) How does a stencil write mask of zero operate when the value of
GL_STENCIL_GENERATION_BITS_EXT is greater than zero?
RESOLUTION: A stencil write mask of zero means no stencil write
is performed so the pixel's stencil value is completely unchanged.
This means the pixel's stencil value will still have the old
stencil tag bits.
The rationale for this is essentially the same for GL_KEEP's
behavior in the previous issue.
15) Conceptually, how does the stencil clear tag functionality
augment the existing stencil processing pipeline?
RESOLUTION: Unextended OpenGL stencil processing (ignoring the
depth test interactions) says:
read stencil value
|
v
evaluate stencil function
|
v
apply appropriate stencil operation
|
v
if operation is non-GL_KEEP, write stencil value
The EXT_stencil_clear_tag functionality augments this pipeline
with two new stages:
read stencil value
|
v
perform stencil clear tag "read merge"
|
v
evaluate stencil function
|
v
apply appropriate stencil operation
|
v
perform stencil clear tag "write merge"
|
v
if a non-KEEP operation, write stencil value
The new stencil clear tag merge stages are pass-through operations
if the value of GL_STENCIL_TAG_BITS_EXT is zero (the initial
state).
16) Can you provide an example of how this stencil clear tag mechanism
could be used to eliminate stencil clears for a stenciled shadow
volume application with multiple light sources per frame.
First assume the application's shadow complexity is such that
scenes never exceed a shadow complexity of 31 (or 63 or 127)
at any pixel, meaning a 5 (or 6 or 7) bit stencil buffer is
sufficient to avoid artifacts.
The code assumes "Z fail" shadow volume rendering with two-sided
stencil testing and an 8-bit stencil buffer.
So initialize the stencil-related state as follows:
const GLint stencilTagBits = 3; // or 2 or 1
const int hasStencilClearTagExtension =
queryExtension("GL_EXT_stencil_clear_tag");
GLint stencilBits;
GLuint maxStencilValue;
GLint tagInit;
GLint tagDecrement;
GLint stencilClearTag;
if (hasStencilClearTagExtension) {
glGetIntegerv(GL_STENCIL_BITS, &stencilBits);
maxStencilValue = (1U<<stencilBits)-1;
assert(stencilBits > stencilTagBits);
tagDecrement = 1<<(stencilBits - stencilTagBits);
tagInit = ~(tagDecrement-1) & maxStencilValue;
glStencilClearTagEXT(stencilTagBits, tagInit);
glStencilClear(tagInit);
} else {
glStencilClear(0);
}
glEnable(GL_STENCIL_TWO_SIDE_EXT);
glActiveStencilFaceEXT(GL_BACK);
glStencilMask(~0);
glActiveStencilFaceEXT(GL_FRONT);
glStencilMask(~0);
Then rendering one frame of a shadowed scene looks like:
int i;
glDepthMask(1);
glColorMask(1,1,1,1);
if (hasStencilClearTagExtension) {
stencilClearTag = tagInit;
glStencilClearTagEXT(stencilTagBits, stencilClearTag);
}
glClear(GL_STENCIL_BUFFER_BIT |
GL_DEPTH_BUFFER_BIT |
GL_COLOR_BUFFER_BIT);
glDisable(GL_BLEND);
glDisable(GL_STENCIL_TEST);
glDepthFunc(GL_LESS);
glEnable(GL_DEPTH_TEST);
renderDepthAndAmbient();
glEnable(GL_BLEND);
glBlendFunc(GL_ONE, GL_ONE);
glEnable(GL_STENCIL_TEST);
glDepthMask(0);
glDepthFunc(GL_EQUAL);
for (i=0; i<numberOfLights; i++) {
if (i == 0) {
// First light can hitches ride on frame's initial gang clear
} else {
// Subsequent lights must effect a clear
if (hasStencilClearTagExtension) {
// Did start on a new set of tags?
if (stencilClearTag == tagInit) {
// If so, do real stencil clear and reset stencilClearTag.
glClear(GL_STENCIL_BUFFER_BIT);
// Decrement to next tag.
stencilClearTag -= tagDecrement;
}
// Are we out of tags?
else if (stencilClearTag == 0) {
// Reset to the initial tag.
stencilClearTag = tagInit;
} else {
// Decrement to next tag.
stencilClearTag -= tagDecrement;
}
glStencilClearTagEXT(stencilTagBits, stencilClearTag);
} else {
// Actual per-light clear needed
glClear(GL_STENCIL_BUFFER_BIT);
}
}
glActiveStencilFaceEXT(GL_BACK);
glStencilFunc(GL_ALWAYS, 0, ~0);
glStencilOp(GL_KEEP, GL_INCR_WRAP, GL_KEEP);
glActiveStencilFaceEXT(GL_FRONT);
glStencilFunc(GL_ALWAYS, 0, ~0);
glStencilOp(GL_KEEP, GL_DECR_WRAP, GL_KEEP);
glColorMask(0,0,0,0);
renderShadowVolumesForLight(i);
glActiveStencilFaceEXT(GL_BACK);
glStencilFunc(GL_EQUAL, 0, ~0);
glStencilOp(GL_KEEP, GL_KEEP, GL_KEEP);
glActiveStencilFaceEXT(GL_FRONT);
glStencilFunc(GL_EQUAL, 0, ~0);
glStencilOp(GL_KEEP, GL_KEEP, GL_KEEP);
glColorMask(1,1,1,1);
renderLightingContributionForLight(i);
}
A smarter implementation could include computation of the scissor
(and depth bounds) for each light source. If the number of
lights exceeds the number of available stencil tags, the lights
with the smallest scissor area could be performed as actual
scissored clears so the clears to the largest regions could be
done as stencil clear tag state updates.
stencilTagBits can be adjusted based on the number of active
lights. For example, if there are only 4 lights active,
stencilTagBits could be 2 instead of 3 and thereby recover a
bit of stencil precision for the shadow volume count.
17) Why "s-min(n,s)" instead of simply "s-n" where s is the number
of stencil bits and n is the number of stencil tag bits?
RESOLVED: This makes sure if a context migrates to a
drawable with fewer stencil bits than a drawable had when
glStencilClearTagEXT was last called, the effect should be
well-defined.
For example, if glStencilClearTagEXT(3,0) is called with an
8-bit stencil buffer and then that context is bound to a drawable
with no stencil buffer (effectively, 0 bits), s-min(n,s) is zero
rather than s-n being -3.
18) Should the stencil reference value be ANDed with
2^(s-min(n,s))-1?
RESOLOVED: Yes. this way the reference value and the compared
stencil value compare a matching number of bits.
   New Procedures and Functions |
StencilClearTagEXT(sizei stencilTagBits,
uint stencilClearTag)
Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
GetFloatv, and GetDoublev:
STENCIL_TAG_BITS_EXT 0x88F2
STENCIL_CLEAR_TAG_VALUE_EXT 0x88F3
| Additions to Chapter 2 of the GL Specification (OpenGL Operation) |
None
| Additions to Chapter 3 of the GL Specification (Rasterization) |
None
| Additions to Chapter 4 of the GL Specification (Per-Fragment Operations and the Framebuffer) |
Section 4.1.5 "Stencil Test" (page 174), add after the 1st paragraph:
"The command
void StencilClearTagEXT(sizei stencilTagBits,
uint stencilClearTag);
controls the stencil clear tag state. stencilTagBits is a count of
the number of most-significant stencil buffer bits involved in the
stencil clear tag update. The error INVALID_VALUE is generated if
stencilTagBits is negative or greater or equal to s."
Add after the 2nd sentence in the 2nd paragraph:
"The effective reference value used for the stencil comparison is
ref ANDed with 2^(s-min(n,s))-1, where n is equal to stencilTagBits."
Addd after the 2nd paragraph:
"The stored stencil value used for the stencil comparison and
subsequent stencil operations is obtained by reading the pixel's
corresponding stencil value from the stencil buffer and possibly
modifying that value based on the stencil clear tag state.
The stored stencil value is modified prior to the stencil comparison
if n (again where n is equal to stencilTagBits) is greater than zero;
otherwise if zero, the stored stencil value remains unmodified.
If n is greater than zero and the n most-significant bits of
the stored stencil value all match the corresponding bits of
the stencilClearTag, then the stored stencil value is ANDed with
2^(s-min(n,s))-1. If n is greater than zero and the n most-significant
bits of the stored stencil value do NOT match all the corresponding
bits of the stencilClearTag, then the stored stencil value becomes
stencilClearTag ANDed with 2^(s-min(n,s))-1. "
Change the KEEP operation description in the 4th sentence to indicate
that KEEP does not perform the stencil clear tag write merge:
"keeping the current value without writing the stencil buffer,"
Change the second sentence of the fourth paragraph to read:
"Incrementing or decrementing with saturation clamps the stencil
value at 0 and 2^(s-min(n,s))-1 so when stencilTagBits is zero the
maximum saturation value is the maximum representable stencil value."
Section 4.2.5 "Fine Control of Buffer Updates" (page 185), prior to
the paragraph describing the StencilMask command, add:
"Writes to the stencil buffer are controlled through a combination
of stencil mask and stencil clear tag state."
Then add after the paragraph describing the StencilMask command:
"If the stencil mask ANDed with s^2(s-min(n,s))-1 is zero, no write
occurs. Otherwise, the pixel's stencil value is written with the
value determined by the following C-style bit-wise expression:
( stencilClearTag & ~tagMask ) |
( newValue & mask & tagMask ) |
( storedValue & ~mask & tagMask )
where tagMask is 2^(s-min(n,s))-1, n is the value of the
stencil tag bits state, newValue is the stencil value to
be written (after the stored value's potential modification due to
stencil clear tag state AND after the effect of applying a stencil
operation to the value), and storedValue is the pixel's stored
stencil value after to its potential modification due to stencil
clear tag state BUT BEFORE to any stencil operation that may have
been performed (as discussed in section 4.1.5). When n is zero,
this is equivalent to
( newValue & mask ) |
( storedValue & ~mask )
"
Section 4.2.3 "Clearing the Buffers", change the ClearStencil sentence
to read:
"Similarly,
void ClearStencil(int s);
takes a single integer argument that is the value to which to clear
the stencil buffer. s is masked to the number of bitplanes in the
stencil buffer. Clearing stencil ignores the stencil clear tag
state."
Section 4.3.1 "Writing to the Stencil Buffer", change the last
sentence to say:
"Finally, each stencil index is written to its indicated location
in the framebuffer, subject to the current setting of StencilMask
and StencilClearTagEXT (see section 4.2.5). This means the
most-significant n stencil bitplanes cannot be written by DrawPixels
where n is the current number of stencil tag bits."
Section 4.3.2 "Reading Pixels - Obtaining Pixels from the
Framebuffer", change third paragraph to read:
"If the format is STENCIL_INDEX, then values are taken from the
stencil buffer; again, if there is no stencil buffer, the error
INVALID_OPERATION occurs. If the current stencil tag bits state is
zero (see section 4.2.5), the read stencil value is unmodified when
read. If the current stencil tag bits state is greater than zero,
then the upper most-significant n bits of the read stencil value are
compared to the corresponding n bits of the stencil clear tag value,
where n is the current number of stencil tag bits. If these upper
bits mismatch, the read stencil value is replaced with the lower
s-min(n,s) bits of the stencil clear tag state (zeroing the upper
n bits), where s is the number of stencil bitplanes. If the upper
bits match, the upper n bits of the read stencil value are zeroed."
| Additions to Chapter 6 of the GL Specification (State and State Requests) |
None
| Additions to the GLX Specification |
None
A new GL rendering command is added. The following command is sent
to the server as part of a glXRender request:
StencilClearTagEXT
2 12 rendering command length
2 4223 rendering command opcode
4 INT32 stencilTagBits
4 CARD32 stencilClearTag
INVALID_VALUE is generated by StencilClearTagEXT if stencilTagBits
is negative or greater or equal to s where s is the number of bits
in the stencil buffer.
(table 6.19, page 245)
Get Value Type Get Command Initial Value Sec Attribute
------------------------ ---- ------------ ------------- ----- ---------
STENCIL_TAG_BITS_EXT Z+ GetIntegerv 0 4.1.5 stencil-buffer
STENCIL_CLEAR_TAG_EXT Z+ GetIntegerv 0 4.1.5 stencil-buffer
| New Implementation Dependent State |
None
None
 |  | Last update: November 14, 2006.
Cette page doit être lue avec un navigateur récent respectant le standard XHTML 1.1.
|
