| Name |
| |
| EXT_stencil_two_side |
| |
| Name Strings |
| |
| GL_EXT_stencil_two_side |
| |
| Contact |
| |
| Mark J. Kilgard, NVIDIA Corporation (mjk 'at' nvidia.com) |
| |
| Notice |
| |
| Copyright NVIDIA Corporation, 2001-2002. |
| |
| Status |
| |
| Implemented in CineFX (NV30) Emulation driver, August 2002. |
| Shipping in Release 40 NVIDIA driver for CineFX hardware, January 2003. |
| |
| Version |
| |
| Last Modified Date: 09/15/2005 |
| Revision: 2 |
| |
| Number |
| |
| 268 |
| |
| Dependencies |
| |
| Written based on the OpenGL 1.3 specification. |
| |
| NV_packed_depth_stencil affects the definition of this extension. |
| |
| OpenGL 2.0 affects the definition of this extension. |
| |
| Overview |
| |
| This extension provides two-sided stencil testing where the |
| stencil-related state (stencil operations, reference value, compare |
| mask, and write mask) may be different for front- and back-facing |
| polygons. Two-sided stencil testing may improve the performance |
| of stenciled shadow volume and Constructive Solid Geometry (CSG) |
| rendering algorithms. |
| |
| Issues |
| |
| Is this sufficient for shadow volume stencil update in a single pass? |
| |
| RESOLUTION: Yes. |
| |
| An application that wishes to increment the stencil value for |
| rasterized depth-test passing fragments of front-facing polygons and |
| decrement the stencil value for rasterized fragments of depth-test |
| passing back-facing polygons in a single pass can use the following |
| configuration: |
| |
| glDepthMask(0); |
| glColorMask(0,0,0,0); |
| glDisable(GL_CULL_FACE); |
| glEnable(GL_STENCIL_TEST); |
| glEnable(GL_STENCIL_TEST_TWO_SIDE_EXT); |
| |
| glActiveStencilFaceEXT(GL_BACK); |
| glStencilOp(GL_KEEP, // stencil test fail |
| GL_KEEP, // depth test fail |
| GL_DECR_WRAP_EXT); // depth test pass |
| glStencilMask(~0); |
| glStencilFunc(GL_ALWAYS, 0, ~0); |
| |
| glActiveStencilFaceEXT(GL_FRONT); |
| glStencilOp(GL_KEEP, // stencil test fail |
| GL_KEEP, // depth test fail |
| GL_INCR_WRAP_EXT); // depth test pass |
| glStencilMask(~0); |
| glStencilFunc(GL_ALWAYS, 0, ~0); |
| |
| renderShadowVolumePolygons(); |
| |
| Notice the use of EXT_stencil_wrap to avoid saturating decrements |
| losing the shadow volume count. An alternative, using the |
| conventional GL_INCR and GL_DECR operations, is to clear the stencil |
| buffer to one half the stencil buffer value range, say 128 for an |
| 8-bit stencil buffer. In the case, a pixel is "in shadow" if the |
| final stencil value is greater than 128 and "out of shadow" if the |
| final stencil value is 128. This does still create a potential |
| for stencil value overflow if the stencil value saturates due |
| to an increment or decrement. However saturation is less likely |
| with two-sided stencil testing than the conventional two-pass |
| approach because front- and back-facing polygons are mixed together, |
| rather than processing batches of front-facing then back-facing |
| polygons. |
| |
| Contrast the two-sided stencil testing approach with the more |
| or less equivalent approach using facingness-independent stencil |
| testing: |
| |
| glDepthMask(0); |
| glColorMask(0,0,0,0); |
| glEnable(GL_CULL_FACE); |
| glEnable(GL_STENCIL_TEST); |
| |
| glStencilMask(~0); |
| glStencilFunc(GL_ALWAYS, 0, ~0); |
| |
| // Increment for front faces |
| glCullFace(GL_BACK); |
| glStencilOp(GL_KEEP, // stencil test fail |
| GL_KEEP, // depth test fail |
| GL_INCR); // depth test pass |
| |
| renderShadowVolumePolygons(); |
| |
| // Decrement for back faces |
| glCullFace(GL_FRONT); |
| glStencilOp(GL_KEEP, // stencil test fail |
| GL_KEEP, // depth test fail |
| GL_DECR); // depth test pass |
| |
| renderShadowVolumePolygons(); |
| |
| Notice that all the render work implicit |
| in renderShadowVolumePolygons is performed twice with the |
| conventional approach, but only once with the two-sided stencil |
| testing approach. |
| |
| Should there be just front and back stencil test state, or should |
| the stencil write mask also have a front and back state? |
| |
| RESOLUTION: Both the stencil test and stencil write mask state |
| should have front and back versions. |
| |
| The shadow volume application for two-sided stencil testing does |
| not require differing front and back versions of the stencil write |
| mask, but we anticipate other applications where front and back |
| write masks may be useful. |
| |
| For example, it may be useful to draw a convex polyhedra such that |
| (assuming the stencil bufer is cleared to the binary value 1010): |
| |
| 1) front-facing polygons that pass the depth test set stencil bit 0 |
| |
| 2) front-facing polygons that fail the depth test zero stencil bit 1 |
| |
| 3) back-facing polygons that pass the depth test set stencil bit 2 |
| |
| 4) back-facing polygons that fail the depth test zero stencil bit 3 |
| |
| This could be accomplished in a single rendering pass using: |
| |
| glStencilMask(~0); |
| glStencilClear(0xA); |
| glClear(GL_STENCIL_BUFFER_BIT); |
| |
| glDepthMask(0); |
| glColorMask(0,0,0,0); |
| glDisable(GL_CULL_FACE); |
| glEnable(GL_STENCIL_TEST); |
| glEnable(GL_STENCIL_TEST_TWO_SIDE_EXT); |
| |
| glActiveStencilFaceEXT(GL_BACK); |
| glStencilOp(GL_KEEP, // stencil test fail |
| GL_ZERO, // depth test fail |
| GL_REPLACE); // depth test pass |
| glStencilMask(0xC); |
| glStencilFunc(GL_ALWAYS, 0x4, ~0); |
| |
| glActiveStencilFaceEXT(GL_FRONT); |
| glStencilOp(GL_KEEP, // stencil test fail |
| GL_ZERO, // depth test fail |
| GL_REPLACE); // depth test pass |
| glStencilMask(0x3); |
| glStencilFunc(GL_ALWAYS, 0x1, ~0); |
| |
| renderConvexPolyhedra(); |
| |
| Is there a performance advantage to using two-sided stencil testing? |
| |
| RESOLUTION: It depends. |
| |
| In a fill-rate limited situation, rendering front-facing primitives, |
| then back-facing primitives in two passes will generate the same |
| number of rasterized fragments as rendering front- and back-facing |
| primitives in a single pass. |
| |
| However, in other situations that are CPU-limited, |
| transform-limited, or setup-limited, two-sided stencil testing can |
| be faster than the conventional two-pass face culling rendering |
| approaches. For example, if a lengthy vertex program is executed |
| for every shadow volume vertex, rendering the shadow volume with |
| a single two-sided stencil testing pass is advantageous. |
| |
| Often applications using stencil shadow volume techniques require |
| substantial CPU resources to determine potential silhouette |
| boundaries to project shadow volumes from. If the shadow volume |
| geometry generated by the CPU is only required to be sent to the GL |
| once per-frame (rather than twice with the conventional technique), |
| that can ease the CPU burden required to implement stenciled shadow |
| volumes. |
| |
| Should GL_FRONT_AND_BACK be accepted by glActiveStencilFaceEXT? |
| |
| RESOLUTION: No. |
| |
| GL_FRONT_AND_BACK is useful when materials are being updated for |
| two-sided lighting because the front and back material are often |
| identical and may change frequently (glMaterial calls are allowed |
| within glBegin/glEnd pairs). |
| |
| Two-sided stencil has no similiar performance justification. |
| |
| It is also likely that forcing implementations to support this mode |
| would increase the amount of overhead required to set stencil |
| state, even for applications that don't use two-sided stencil. |
| |
| How should the two-sided stencil enable operate? |
| |
| RESOLUTION: It should be modeled after the way two-sided lighting |
| works. There is a GL_LIGHTING enable and then an additional |
| two-sided lighting mode. Unlike two-sided lighting which is a |
| light model boolean, the two-sided stencil testing is a standard |
| enable named GL_STENCIL_TEST_TWO_SIDE_EXT. |
| |
| Here is the pseudo-code for the stencil testing enables: |
| |
| if (glIsEnabled(GL_STENCIL_TEST)) { |
| if (glIsEnabled(GL_STENCIL_TEST_TWO_SIDE_EXT) && primitiveType == polygon) { |
| use two-sided stencil testing |
| } else { |
| use conventional stencil testing |
| } |
| } else { |
| no stencil testing |
| } |
| |
| How should the two-sided stencil interact with glPolygonMode? |
| |
| RESOLUTION: Primitive type is determined by the begin mode |
| so GL_TRIANGLES, GL_TRIANGLE_STRIP, GL_QUAD_STRIP, GL_QUADS, |
| GL_TRIANGLE_FAN, and GL_POLYGON generate polygon primitives. If the |
| polygon mode is set such that lines or points are rasterized, |
| two-sided stencil testing still operates based on the original |
| polygon facingness if stencil testing and two-sided stencil testing |
| are enabled. |
| |
| This is consistent with how two-sided lighting and face culling |
| interact with glPolygonMode. |
| |
| New Procedures and Functions |
| |
| void ActiveStencilFaceEXT(enum face); |
| |
| New Tokens |
| |
| Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, |
| and by the <pname> parameter of GetBooleanv, GetIntegerv, |
| GetFloatv, and GetDoublev: |
| |
| STENCIL_TEST_TWO_SIDE_EXT 0x8910 |
| |
| Accepted by the <face> parameter of ActiveStencilFaceEXT: |
| |
| FRONT |
| BACK |
| |
| Accepted by the <pname> parameters of GetBooleanv, GetIntegerv, |
| GetFloatv, and GetDoublev: |
| |
| ACTIVE_STENCIL_FACE_EXT 0x8911 |
| |
| 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" |
| |
| Replace the first paragraph in the section with: |
| |
| "The stencil test conditionally discards a fragment based on the |
| outcome of a comparison between the value in the stencil buffer at |
| location (xw,yw) and a reference value. |
| |
| The test is enabled or disabled with the Enable and Disable commands, |
| using the symbolic constant STENCIL_TEST. When disabled, the stencil |
| test and associated modifications are not made, and the fragment is |
| always passed. |
| |
| Stencil testing may operate in a two-sided mode. Two-sided stencil |
| testing is enabled or disabled with the Enable and Disable commands, |
| using the symbolic constant STENCIL_TEST_TWO_SIDE_EXT. When stencil |
| testing is disabled, the state of two-sided stencil testing does |
| not affect fragment processing. |
| |
| There are two sets of stencil-related state, the front stencil |
| state set and the back stencil state set. When two-sided stencil |
| testing is enabled, stencil tests and writes use the front set of |
| stencil state when processing fragments rasterized from non-polygon |
| primitives (points, lines, bitmaps, image rectangles) and front-facing |
| polygon primitives while the back set of stencil state is used when |
| processing fragments rasterized from back-facing polygon primitives. |
| For the purposes of two-sided stencil testing, a primitive is still |
| considered a polygon even if the polygon is to be rasterized as |
| points or lines due to the current polygon mode. Whether a polygon |
| is front- or back-facing is determined in the same manner used for |
| two-sided lighting and face culling (see sections 2.13.1 and 3.5.1). |
| When two-sided stencil testing is disabled, the front set of stencil |
| state is always used when stencil testing fragments. |
| |
| The active stencil face determines whether stencil-related commands |
| update the front or back stencil state. The active stencil face is |
| set with: |
| |
| void ActiveStencilFace(enum face); |
| |
| where face is either FRONT or BACK. Stencil commands (StencilFunc, |
| StencilOp, and StencilMask) that update the stencil state update the |
| front stencil state if the active stencil face is FRONT and the back |
| stencil state if the active stencil face is BACK. Additionally, |
| queries of stencil state return the front or back stencil state |
| depending on the current active stencil face. |
| |
| The stencil test state is controlled with |
| |
| void StencilFunc(enum func, int ref, uint mask); |
| void StencilOp(enum sfail, enum dpfail, enum dppass);" |
| |
| Replace the third and second to the last sentence in the last |
| paragraph in section 4.1.5 with: |
| |
| "In the initial state, stencil testing and two-sided stencil testing |
| are both disabled, the front and back stencil reference values are |
| both zero, the front and back stencil comparison functions are ALWAYS, |
| and the front and back stencil mask are both all ones. Initially, |
| both the three front and the three back stencil operations are KEEP." |
| |
| -- Section 4.2.2 "Fine Control of Buffer Updates" |
| |
| Replace the last sentence of the third paragraph with: |
| |
| "The initial state is for both the front and back stencil plane mask |
| to be all ones. The clear operation always uses the front stencil |
| write mask when clearing the stencil buffer." |
| |
| -- Section 4.3.1 "Writing to the Stencil Buffer or to the Depth and |
| Stencil Buffers" |
| |
| Replace the final sentence in the first paragraph with: |
| |
| "Finally, each stencil index is written to its indicated location |
| in the framebuffer, subject to the current front stencil mask state |
| (set with StencilMask), and if a depth component is present, if the |
| setting of DepthMask is not FALSE, it is also written to the |
| framebuffer; the setting of DepthTest is ignored." |
| |
| Additions to Chapter 5 of the GL Specification (Special Functions) |
| |
| None |
| |
| Additions to Chapter 6 of the GL Specification (State and State Requests) |
| |
| None |
| |
| Additions to the GLX, WGL, and AGL Specification |
| |
| None |
| |
| GLX Protocol |
| |
| A new GL rendering command is added. The following command is sent to the |
| server as part of a glXRender request: |
| |
| ActiveStencilFaceEXT |
| 2 8 rendering command length |
| 2 4220 rendering command opcode |
| 4 ENUM face |
| |
| Interactions with OpenGL 2.0 |
| |
| OpenGL 2.0 provides similar "separate stencil" functionality with an API |
| based on the ATI_separate_stencil extension. In the OpenGL 2.0 API, there |
| is no enable; instead, new functions are provided that set both front and |
| back state simultaneously. Non-separate stencil functions (e.g., |
| StencilFunc, StencilOp) set *both* back and front state. In this |
| extension, they set either front or back state depending on the active |
| stencil face. |
| |
| Implementations supporting both this extension and OpenGL 2.0 will need to |
| support both styles of two-sided stencil usage without API modification, |
| which is ugly since the OpenGL 2.0 API does not have an enable for |
| two-sided functionality -- it's always on. To achieve this, we provide |
| three different sets of stencil state: |
| |
| - front state |
| - "OpenGL 2.0" back state |
| - "EXT_stencil_two_side" back state |
| |
| OpenGL 2.0 separate stencil functions set the front and "OpenGL 2.0" back |
| state. Non-separate stencil functions use the stencil face selector to |
| determine what to set: FRONT (the default) sets both front and "OpenGL |
| 2.0" back state; BACK sets "EXT_stencil_two_side" back state. |
| |
| If the two-sided stencil enable in this extension is set, implying |
| EXT_stencil_two_side usage, we choose between the front state and the |
| EXT_stencil_two_side back state. Those two sets of state are set |
| appropriately when using the active stencil face selector provided by this |
| extension. |
| |
| If the two-sided stencil enable in this extension is not set, implying |
| either OpenGL 2.0 or "one-sided" EXT_stencil_two_side usage, we choose |
| between the front state and the OpenGL 2.0 back state. In OpenGL 2.0 |
| usage, the separate stencil functions set either of these two pieces of |
| state appropriately, and the non-separate stencil functions set both. In |
| "one-sided" EXT_stencil_two_side usage, the separate stencil functions |
| from OpenGL 2.0 will not be used. Any time the non-separate functions set |
| the front state (active face == FRONT), they also set the OpenGL 2.0 back |
| state, so the front and back state used will always be identical in this |
| case. |
| |
| The relevant spec language changes in the OpenGL 2.0 specification are: |
| |
| (modify 2nd paragraph, p. 202) There are three sets of stencil-related |
| state, the front stencil state set, the OpenGL 2.0 back stencil state set, |
| and the EXT_stencil_two_side back stencil state set. Stencil tests and |
| writes use the front set of stencil state when processing fragments |
| rasterized from non-polygon primitives (points, lines, bitmaps, image |
| rectangles) and front-facing polygon primitives. When processing |
| fragments rasterized from back-facing polygon primitives, stencil tests |
| and writes use the OpenGL 2.0 back stencil state set when |
| STENCIL_TEST_TWO_SIDE_EXT is disabled and the EXT_stencil_two_side back |
| stencil state set otherwise. ... |
| |
| (modify 3rd paragraph, p. 202) StencilFuncSeparate and StencilOpSeparate |
| take a face argument which can be FRONT, BACK, or FRONT_AND_BACK and |
| indicates which set of state is affected. If <face> is BACK or |
| FRONT_AND_BACK, the OpenGL 2.0 back stencil state is modified, but the |
| EXT_stencil_two_side state is not. StencilFunc and StencilOp set state |
| based on the active stencil face. If the active stencil face is FRONT, |
| the corresponding front and OpenGL 2.0 back stencil state are set to |
| identical values. If the active stencil face is BACK, the corresponding |
| EXT_stencil_two_side back state is set. |
| |
| Errors |
| |
| None |
| |
| New State |
| |
| (table 6.15, page 205) amend the following entries: |
| |
| Get Value Type Get Command Initial Value Description Sec Attribute |
| ------------------------- ---- ----------- ------------- ------------------- ----- -------------- |
| STENCIL_FUNC 2xZ8 GetIntegerv ALWAYS Stencil function 4.1.4 stencil-buffer |
| STENCIL_VALUE_MASK 2xZ+ GetIntegerv 1's Stencil mask 4.1.4 stencil-buffer |
| STENCIL_REF 2xZ+ GetIntegerv 0 Stencil reference 4.1.4 stencil-buffer |
| value |
| STENCIL_FAIL 2xZ6 GetIntegerv KEEP Stencil fail action 4.1.4 stencil-buffer |
| STENCIL_PASS_DEPTH_FAIL 2xZ6 GetIntegerv KEEP Stencil depth 4.1.4 stencil-buffer |
| buffer fail action |
| STENCIL_PASS_DEPTH_PASS 2xZ6 GetIntegerv KEEP Stencil depth 4.1.4 stencil-buffer |
| buffer pass action |
| |
| [Type field is amended with "2x" prefix.] |
| |
| (table 6.15, page 205) add the following entries: |
| |
| Get Value Type Get Command Initial Value Description Sec Attribute |
| ------------------------- ---- ----------- ------------- ----------------- ------ --------------------- |
| STENCIL_TEST_TWO_SIDE_EXT B IsEnabled False Two-sided stencil 4.1.4 stencil-buffer/enable |
| test enable |
| ACTIVE_STENCIL_FACE_EXT Z2 GetIntegerv FRONT Active stencil 4.1.4 stencil-buffer |
| face selector |
| |
| (table 6.16, page 205) ammend the following entry: |
| |
| Get Value Type Get Command Initial Value Description Sec Attribute |
| ------------------------- ---- ----------- ------------- ----------------- ------ -------------- |
| STENCIL_WRITE_MASK 2xZ+ GetIntegerv 1's Stencil buffer 4.2.2 stencil-buffer |
| writemask |
| |
| [Type field is amended with "2x" prefix.] |
| |
| |
| Revision History |
| |
| Rev. Date Author Changes |
| ---- -------- -------- -------------------------------------------- |
| 2 09/15/05 pbrown Clarified interaction with OpenGL 2.0 two- |
| sided stencil. |
| |
| 1 01/08/03 mjk Initial revision. |
