OpenGL.GL.EXT.stencil_clear_tag
index
/home/mcfletch/pylive/OpenGL/GL/EXT/stencil_clear_tag.py

OpenGL extension EXT.stencil_clear_tag
 
This module customises the behaviour of the 
OpenGL.raw.GL.EXT.stencil_clear_tag to provide a more 
Python-friendly API
 
Overview (from the spec)
        
        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.
 
The official definition of this extension is available here:
http://www.opengl.org/registry/specs/EXT/stencil_clear_tag.txt

 
Modules
       
OpenGL.arrays
OpenGL.constant
OpenGL.constants
ctypes
OpenGL.extensions
OpenGL.GL.glget
OpenGL.platform
OpenGL.wrapper

 
Data
        EXTENSION_NAME = 'GL_EXT_stencil_clear_tag'
GL_STENCIL_CLEAR_TAG_VALUE_EXT = GL_STENCIL_CLEAR_TAG_VALUE_EXT
GL_STENCIL_TAG_BITS_EXT = GL_STENCIL_TAG_BITS_EXT
__file__ = '/home/mcfletch/pylive/OpenGL/GL/EXT/stencil_clear_tag.pyc'
__name__ = 'OpenGL.GL.EXT.stencil_clear_tag'
__package__ = 'OpenGL.GL.EXT'
glStencilClearTagEXT = <OpenGL.platform.baseplatform.glStencilClearTagEXT object at 0x76ea7d0>