1Name 2 3 EXT_shadow_samplers 4 5Name Strings 6 7 GL_EXT_shadow_samplers 8 9Contributors 10 11 Contributors to ARB_shadow and EXT_shadow_funcs on which this extension 12 is based 13 Galo Avila 14 Kelvin Chiu 15 Richard Schreyer 16 17Contacts 18 19 Benj Lipchak, Apple (lipchak 'at' apple.com) 20 21Status 22 23 Complete 24 25Version 26 27 Date: June 25, 2012 28 Revision: 4 29 30Number 31 32 OpenGL ES Extension #102 33 34Dependencies 35 36 Requires OpenGL ES 2.0. 37 38 Written based on the wording of the OpenGL ES 2.0.25 Full Specification 39 (November 2, 2010). 40 41 Written based on the wording of The OpenGL ES Shading Language 1.0.17 42 Specification (May 12, 2009). 43 44 Requires OES_depth_texture. 45 46 OES_packed_depth_stencil affects the definition of this extension. 47 48Overview 49 50 This extension supports comparing the texture R coordinate to a depth 51 texture value returning the result as a float value in the range [0,1]. 52 This can be used to implement shadow maps. 53 54New Procedures and Functions 55 56 None 57 58New Tokens 59 60 Accepted by the <pname> parameter of TexParameterf, TexParameteri, 61 TexParameterfv, TexParameteriv, GetTexParameterfv, and GetTexParameteriv: 62 63 TEXTURE_COMPARE_MODE_EXT 0x884C 64 TEXTURE_COMPARE_FUNC_EXT 0x884D 65 66 Accepted by the <param> parameter of TexParameterf, TexParameteri, 67 TexParameterfv, and TexParameteriv when the <pname> parameter is 68 TEXTURE_COMPARE_MODE_EXT: 69 70 COMPARE_REF_TO_TEXTURE_EXT 0x884E 71 72 Returned in <type> by glGetActiveUniform: 73 74 GL_SAMPLER_2D_SHADOW_EXT 0x8B62 75 76New GLSL defines 77 78 #extension GL_EXT_shadow_samplers : require 79 80New GLSL sampler types 81 82 sampler2DShadow 83 84New GLSL functions 85 86 float shadow2DEXT(sampler2DShadow sampler, vec3 coord); 87 float shadow2DProjEXT(sampler2DShadow sampler, vec4 coord); 88 89Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation) 90 91 In Section 2.10.4, replace the final sentence on p. 36 with: 92 93 "The type returned can be any of FLOAT, FLOAT_VEC2, FLOAT_VEC3, FLOAT_VEC4, 94 INT, INT_VEC2, INT_VEC3, INT_VEC4, BOOL, BOOL_VEC2, BOOL_VEC3, BOOL_VEC4, 95 FLOAT_MAT2, FLOAT_MAT3, FLOAT_MAT4, SAMPLER_2D, SAMPLER_CUBE, or 96 SAMPLER_2D_SHADOW_EXT." 97 98Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) 99 100 Section 3.7.4, Texture Parameters, p. 76, append table 3.10 with the 101 following: 102 103 Name Type Legal Values 104 ------------------------ ---- ------------------------------- 105 TEXTURE_COMPARE_MODE_EXT enum NONE, COMPARE_REF_TO_TEXTURE_EXT 106 TEXTURE_COMPARE_FUNC_EXT enum LEQUAL, GEQUAL, LESS, GREATER, EQUAL, 107 NOTEQUAL, ALWAYS, NEVER 108 109 After section 3.7.13, Texture Objects, p. 86, insert the following new 110 section: 111 112 "3.7.14 Texture Comparison Modes 113 114 Texture values can also be computed according to a specified comparison 115 function. Texture parameter TEXTURE_COMPARE_MODE_EXT specifies the 116 comparison operands, and parameter TEXTURE_COMPARE_FUNC_EXT specifies 117 the comparison function. 118 119 3.7.14.1 Depth Texture Comparison Mode 120 121 If the currently bound texture's base internal format is 122 DEPTH_COMPONENT or DEPTH_STENCIL_OES, then TEXTURE_COMPARE_MODE_EXT 123 and TEXTURE_COMPARE_FUNC_EXT control the output of the texture unit 124 as described below. Otherwise, the texture unit operates in the normal 125 manner and texture comparison is bypassed. 126 127 Let D_t be the depth texture value and D_ref be the reference value, 128 provided by the shader's texture lookup function. D_t and D_ref are 129 clamped to the range [0,1]. Then the effective texture value is 130 computed as follows: 131 132 If the value of TEXTURE_COMPARE_MODE_EXT is NONE, then 133 134 r = D_t 135 136 If the value of TEXTURE_COMPARE_MODE_EXT is 137 COMPARE_REF_TO_TEXTURE_EXT, then r depends on the texture Comparison 138 function as shown in table 3.X. 139 140 141 Texture Comparison Function Computed result r 142 --------------------------- ----------------- 143 { 1.0, if D_ref <= Dt 144 LEQUAL r = { 145 { 0.0, if D_ref > Dt 146 147 { 1.0, if D_ref >= Dt 148 GEQUAL r = { 149 { 0.0, if D_ref < Dt 150 151 { 1.0, if D_ref < Dt 152 LESS r = { 153 { 0.0, if D_ref >= Dt 154 155 { 1.0, if D_ref > Dt 156 GREATER r = { 157 { 0.0, if D_ref < Dt 158 159 { 1.0, if D_ref == Dt 160 EQUAL r = { 161 { 0.0, if D_ref != Dt 162 163 { 1.0, if D_ref != Dt 164 NOTEQUAL r = { 165 { 0.0, if D_ref == Dt 166 167 ALWAYS r = 1.0 168 169 NEVER r = 0.0 170 171 Table 3.X: Depth texture comparison functions. 172 173 174 The resulting r is assigned to R_t. 175 176 If the value of TEXTURE_MAG_FILTER is not NEAREST, or the value of 177 TEXTURE_MIN_FILTER is not NEAREST or NEAREST_MIPMAP_NEAREST, then r may 178 be computed by comparing more than one depth texture value to the 179 texture reference value. The details of this are implementation- 180 dependent, but r should be a value in the range [0, 1] which is 181 proportional to the number of comparison passes or failures." 182 183Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 184Operations and the Framebuffer) 185 186 None 187 188Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions) 189 190 None 191 192Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and 193State Requests) 194 195 None 196 197Additions to OpenGL ES Shading Language 1.00 Specification 198 199 Append the following row to the table in section 4.1, Basic Types: 200 201 Type Meaning 202 --------------- --------------------------------------------------------- 203 sampler2DShadow a handle for accessing a 2D depth texture with comparison 204 205 Insert the following paragraph after the first paragraph in section 8.7, 206 Texture Lookup Functions: 207 208 "For shadow forms (the sampler parameter is a shadow-type), a depth 209 comparison lookup on the depth texture bound to sampler is done as 210 described in section 3.7.14 “Texture Comparison Modes” of the OpenGL ES 211 Specification. See the table below for which component specifies D_ref. The 212 texture bound to sampler must be a depth texture, or results are undefined. 213 If a non-shadow texture call is made to a sampler that represents a depth 214 texture with depth comparisons turned on, then results are undefined. If a 215 shadow texture call is made to a sampler that represents a depth texture 216 with depth comparisons turned off, then results are undefined. If a shadow 217 texture call is made to a sampler that does not represent a depth texture, 218 then results are undefined." 219 220 Append "precision lowp sampler2DShadow;" to the default precision statements 221 in section 4.5.3. 222 223Dependencies on OES_packed_depth_stencil 224 225 If OES_packed_depth_stencil is not supported, then all references to 226 DEPTH_STENCIL_OES should be omitted. 227 228Issues 229 230 (1) Should the result of the texture comparison be interpreted as 231 a LUMINANCE, INTENSITY or ALPHA texel? 232 233 RESOLVED: A scalar value is returned from the shadow lookup built-in 234 function in the fragment shader, so it can be interpreted however desired. 235 236Revision History 237 238 Date: 6/16/2011 239 Revision: 1 (Benj Lipchak) 240 - Initial draft 241 242 Date: 7/22/2011 243 Revision: 2 (Benj Lipchak) 244 - Rename from APPLE to EXT 245 246 Date: 1/18/2012 247 Revision: 3 (Kelvin Chiu) 248 - Add GL_SAMPLER_2D_SHADOW_EXT for glGetActiveUniform type 249 250 Date: 6/25/2012 251 Revision: 4 (Benj Lipchak) 252 - Specify lowp as the default precision of sampler2DShadow 253