EXT_shadow_samplers

GL_EXT_shadow_samplers

Contributors to ARB_shadow and EXT_shadow_funcs on which this extension 
    is based
Galo Avila
Kelvin Chiu
Richard Schreyer

Benj Lipchak, Apple (lipchak 'at' apple.com)

Complete

Date: June 25, 2012
Revision: 4

OpenGL ES Extension #102

Requires OpenGL ES 2.0.

Written based on the wording of the OpenGL ES 2.0.25 Full Specification
(November 2, 2010).

Written based on the wording of The OpenGL ES Shading Language 1.0.17
Specification (May 12, 2009).

Requires OES_depth_texture.

OES_packed_depth_stencil affects the definition of this extension.

This extension supports comparing the texture R coordinate to a depth
texture value returning the result as a float value in the range [0,1]. 
This can be used to implement shadow maps.

None

Accepted by the <pname> parameter of TexParameterf, TexParameteri,
TexParameterfv, TexParameteriv, GetTexParameterfv, and GetTexParameteriv:

TEXTURE_COMPARE_MODE_EXT    0x884C
TEXTURE_COMPARE_FUNC_EXT    0x884D

Accepted by the <param> parameter of TexParameterf, TexParameteri,
TexParameterfv, and TexParameteriv when the <pname> parameter is
TEXTURE_COMPARE_MODE_EXT:

COMPARE_REF_TO_TEXTURE_EXT  0x884E

Returned in <type> by glGetActiveUniform:

GL_SAMPLER_2D_SHADOW_EXT    0x8B62 

#extension GL_EXT_shadow_samplers : require

sampler2DShadow

float shadow2DEXT(sampler2DShadow sampler, vec3 coord);
float shadow2DProjEXT(sampler2DShadow sampler, vec4 coord);

In Section 2.10.4, replace the final sentence on p. 36 with:

"The type returned can be any of FLOAT, FLOAT_VEC2, FLOAT_VEC3, FLOAT_VEC4,
INT, INT_VEC2, INT_VEC3, INT_VEC4, BOOL, BOOL_VEC2, BOOL_VEC3, BOOL_VEC4, 
FLOAT_MAT2, FLOAT_MAT3, FLOAT_MAT4, SAMPLER_2D, SAMPLER_CUBE, or 
SAMPLER_2D_SHADOW_EXT."

Section 3.7.4, Texture Parameters, p. 76, append table 3.10 with the
following:

Name                       Type   Legal Values
------------------------   ----   -------------------------------
TEXTURE_COMPARE_MODE_EXT   enum   NONE, COMPARE_REF_TO_TEXTURE_EXT
TEXTURE_COMPARE_FUNC_EXT   enum   LEQUAL, GEQUAL, LESS, GREATER, EQUAL, 
                                  NOTEQUAL, ALWAYS, NEVER

After section 3.7.13, Texture Objects, p. 86, insert the following new 
section:

    "3.7.14 Texture Comparison Modes

    Texture values can also be computed according to a specified comparison
    function. Texture parameter TEXTURE_COMPARE_MODE_EXT specifies the 
    comparison operands, and parameter TEXTURE_COMPARE_FUNC_EXT specifies
    the comparison function.
    
    3.7.14.1 Depth Texture Comparison Mode

    If the currently bound texture's base internal format is 
    DEPTH_COMPONENT or DEPTH_STENCIL_OES, then TEXTURE_COMPARE_MODE_EXT 
    and TEXTURE_COMPARE_FUNC_EXT control the output of the texture unit
    as described below. Otherwise, the texture unit operates in the normal
    manner and texture comparison is bypassed.

    Let D_t be the depth texture value and D_ref be the reference value, 
    provided by the shader's texture lookup function. D_t and D_ref are 
    clamped to the range [0,1]. Then the effective texture value is
    computed as follows:

    If the value of TEXTURE_COMPARE_MODE_EXT is NONE, then

        r = D_t

    If the value of TEXTURE_COMPARE_MODE_EXT is 
    COMPARE_REF_TO_TEXTURE_EXT, then r depends on the texture Comparison
    function as shown in table 3.X.


    Texture Comparison Function  Computed result r
    ---------------------------  -----------------
                                     { 1.0,  if D_ref <= Dt
    LEQUAL                       r = {
                                     { 0.0,  if D_ref > Dt

                                     { 1.0,  if D_ref >= Dt
    GEQUAL                       r = {
                                     { 0.0,  if D_ref < Dt

                                     { 1.0,  if D_ref < Dt
    LESS                         r = {
                                     { 0.0,  if D_ref >= Dt

                                     { 1.0,  if D_ref > Dt
    GREATER                      r = {
                                     { 0.0,  if D_ref < Dt

                                     { 1.0,  if D_ref == Dt
    EQUAL                        r = {
                                     { 0.0,  if D_ref != Dt

                                     { 1.0,  if D_ref != Dt
    NOTEQUAL                     r = {
                                     { 0.0,  if D_ref == Dt

    ALWAYS                       r = 1.0

    NEVER                        r = 0.0

         Table 3.X: Depth texture comparison functions.


    The resulting r is assigned to R_t.

    If the value of TEXTURE_MAG_FILTER is not NEAREST, or the value of 
    TEXTURE_MIN_FILTER is not NEAREST or NEAREST_MIPMAP_NEAREST, then r may 
    be computed by comparing more than one depth texture value to the 
    texture reference value. The details of this are implementation-
    dependent, but r should be a value in the range [0, 1] which is 
    proportional to the number of comparison passes or failures."

None

None

None

Append the following row to the table in section 4.1, Basic Types:

Type             Meaning
---------------  ---------------------------------------------------------
sampler2DShadow  a handle for accessing a 2D depth texture with comparison

Insert the following paragraph after the first paragraph in section 8.7, 
Texture Lookup Functions:

"For shadow forms (the sampler parameter is a shadow-type), a depth 
comparison lookup on the depth texture bound to sampler is done as 
described in section 3.7.14 "Texture Comparison Modes" of the OpenGL ES 
Specification. See the table below for which component specifies D_ref. The
texture bound to sampler must be a depth texture, or results are undefined.
If a non-shadow texture call is made to a sampler that represents a depth 
texture with depth comparisons turned on, then results are undefined. If a 
shadow texture call is made to a sampler that represents a depth texture 
with depth comparisons turned off, then results are undefined. If a shadow 
texture call is made to a sampler that does not represent a depth texture, 
then results are undefined."

Append "precision lowp sampler2DShadow;" to the default precision statements
in section 4.5.3.

If OES_packed_depth_stencil is not supported, then all references to
DEPTH_STENCIL_OES should be omitted. 

(1) Should the result of the texture comparison be interpreted as 
a LUMINANCE, INTENSITY or ALPHA texel?

RESOLVED: A scalar value is returned from the shadow lookup built-in
function in the fragment shader, so it can be interpreted however desired.