1Name 2 3 OES_texture_cube_map 4 5Name Strings 6 7 GL_OES_texture_cube_map 8 9Contact 10 11 Benj Lipchak (benj.lipchak 'at' amd.com) 12 13Notice 14 15 Copyright (c) 2007-2013 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28Status 29 30 Ratified by the Khronos BOP 31 32Version 33 34 Version 2, April 16, 2015 35 36Number 37 38 OpenGL ES Extension #20 39 40Dependencies 41 42 OpenGL ES 1.0 is required. 43 44 This extension is based on the ARB_texture_cube_map extension specification. 45 46Overview 47 48 This extension provides a new texture generation scheme for cube 49 map textures. Instead of the current texture providing a 1D, 2D, 50 or 3D lookup into a 1D, 2D, or 3D texture image, the texture is a 51 set of six 2D images representing the faces of a cube. The (s,t,r) 52 texture coordinates are treated as a direction vector emanating from 53 the center of a cube. At texture generation time, the interpolated 54 per-fragment (s,t,r) selects one cube face 2D image based on the 55 largest magnitude coordinate (the major axis). A new 2D (s,t) is 56 calculated by dividing the two other coordinates (the minor axes 57 values) by the major axis value. Then the new (s,t) is used to 58 lookup into the selected 2D texture image face of the cube map. 59 60 Unlike a standard 1D, 2D, or 3D texture that have just one target, 61 a cube map texture has six targets, one for each of its six 2D texture 62 image cube faces. All these targets must be consistent, complete, 63 and have equal width and height (ie, square dimensions). 64 65 This extension also provides two new texture coordinate generation modes 66 for use in conjunction with cube map texturing. The reflection map 67 mode generates texture coordinates (s,t,r) matching the vertex's 68 eye-space reflection vector. The reflection map mode 69 is useful for environment mapping without the singularity inherent 70 in sphere mapping. The normal map mode generates texture coordinates 71 (s,t,r) matching the vertex's transformed eye-space 72 normal. The normal map mode is useful for sophisticated cube 73 map texturing-based diffuse lighting models. 74 75 The intent of the new texgen functionality is that an application using 76 cube map texturing can use the new texgen modes to automatically 77 generate the reflection or normal vectors used to look up into the 78 cube map texture. 79 80 An application note: When using cube mapping with dynamic cube 81 maps (meaning the cube map texture is re-rendered every frame), 82 by keeping the cube map's orientation pointing at the eye position, 83 the texgen-computed reflection or normal vector texture coordinates 84 can be always properly oriented for the cube map. However if the 85 cube map is static (meaning that when view changes, the cube map 86 texture is not updated), the texture matrix must be used to rotate 87 the texgen-computed reflection or normal vector texture coordinates 88 to match the orientation of the cube map. The rotation can be 89 computed based on two vectors: 1) the direction vector from the cube 90 map center to the eye position (both in world coordinates), and 2) 91 the cube map orientation in world coordinates. The axis of rotation 92 is the cross product of these two vectors; the angle of rotation is 93 the arcsin of the dot product of these two vectors. 94 95Issues 96 97 Please refer to the ARB_texture_cube_map extension specification. 98 99New Procedures and Functions 100 101 void glTexGenfOES(GLenum coord, GLenum pname, GLfloat param); 102 void glTexGenfvOES(GLenum coord, GLenum pname, const GLfloat *params); 103 void glTexGeniOES(GLenum coord, GLenum pname, GLint param); 104 void glTexGenivOES(GLenum coord, GLenum pname, const GLint *params); 105 void glTexGenxOES(GLenum coord, GLenum pname, GLfixed param); 106 void glTexGenxvOES(GLenum coord, GLenum pname, const GLfixed *params); 107 108 void glGetTexGenfvOES(GLenum coord, GLenum pname, GLfloat *params); 109 void glGetTexGenivOES(GLenum coord, GLenum pname, GLint *params); 110 void glGetTexGenxvOES(GLenum coord, GLenum pname, GLfixed *params); 111 112New Tokens 113 114 Accepted by the <pname> parameter of TexGenfOES, TexGeniOES, TexGenxOES, 115 TexGenfvOES, TexGenivOES, TexGenxvOES, GetTexGenfvOES, GetTexGenivOES, and 116 GetTexGenxvOES: 117 118 TEXTURE_GEN_MODE_OES 0x2500 119 120 Accepted by the <params> parameter of TexGenfOES, TexGeniOES, TexGenxOES, 121 TexGenfvOES, TexGenivOES, and TexGenxvOES when <pname> parameter is 122 TEXTURE_GEN_MODE_OES: 123 124 NORMAL_MAP_OES 0x8511 125 REFLECTION_MAP_OES 0x8512 126 127 Accepted by the <cap> parameter of Enable, Disable, IsEnabled, by the 128 <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetFixedv, and 129 by the <target> parameter of BindTexture, GetTexParameterfv, 130 GetTexParameteriv, GetTexParameterxv, TexParameterf, TexParameteri, 131 TexParameterx, TexParameterfv, TexParameteriv, and TexParameterxv: 132 133 TEXTURE_CUBE_MAP_OES 0x8513 134 135 Accepted by the <cap> parameter of Enable, Disable, IsEnabled, by the 136 <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetFixedv, and 137 by the <coord> parameter of TexGenfOES, TexGeniOES, TexGenxOES, TexGenfvOES, 138 TexGenivOES, TexGenxvOES, GetTexGenfvOES, GetTexGenivOES, and 139 GetTexGenxvOES: 140 141 TEXTURE_GEN_STR_OES 0x8D60 142 143 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 144 GetFloatv, and GetDoublev: 145 146 TEXTURE_BINDING_CUBE_MAP_OES 0x8514 147 148 Accepted by the <target> parameter of TexImage2D, CopyTexImage2D, 149 TexSubImage2D, and CopySubTexImage2D: 150 151 TEXTURE_CUBE_MAP_POSITIVE_X_OES 0x8515 152 TEXTURE_CUBE_MAP_NEGATIVE_X_OES 0x8516 153 TEXTURE_CUBE_MAP_POSITIVE_Y_OES 0x8517 154 TEXTURE_CUBE_MAP_NEGATIVE_Y_OES 0x8518 155 TEXTURE_CUBE_MAP_POSITIVE_Z_OES 0x8519 156 TEXTURE_CUBE_MAP_NEGATIVE_Z_OES 0x851A 157 158 Accepted by the <pname> parameter of GetBooleanv, GetDoublev, 159 GetIntegerv, and GetFloatv: 160 161 MAX_CUBE_MAP_TEXTURE_SIZE_OES 0x851C 162 163Additions to Chapter 2 of the OpenGL 1.5 Specification (OpenGL Operation) 164 165 -- Section 2.11.4 "Generating Texture Coordinates" 166 167 Change the last sentence in the 1st paragraph (page 37) to: 168 169 "If <pname> is TEXTURE_GEN_MODE_OES, then either <params> points to 170 or <param> is an integer that is one of the symbolic constants 171 REFLECTION_MAP_OES, or NORMAL_MAP_OES." OBJECT_LINEAR, EYE_LINEAR, 172 and SPHERE_MAP texture coordinate generation modes are not supported. 173 174 Add these paragraphs after the 4th paragraph (page 38): 175 176 "If TEXTURE_GEN_MODE_OES indicates REFLECTION_MAP_OES, compute the 177 reflection vector r as described for the SPHERE_MAP mode. Then the 178 value assigned to an s coordinate is s = rx; the value assigned to a t 179 coordinate is t = ry; and the value assigned to a r coordinate is r = rz. 180 181 If TEXTURE_GEN_MODE_OES indicates NORMAL_MAP_OES, compute the normal 182 vector nf as described in section 2.10.3. Then the value assigned 183 to an s coordinate is s = nfx; the value assigned to a t coordinate is 184 t = nfy; and the value assigned to a r coordinate is r = nfz. (The values 185 nfx, nfy, and nfz are the components of nf.) 186 187 A texture coordinate generation function is enabled or disabled 188 using Enable and Disable with an argument of TEXTURE_GEN_STR_OES. 189 TEXTURE_GEN_S, TEXTURE_GEN_T, TEXTURE_GEN_R and TEXTURE_GEN_Q 190 argument values to Enable and Disable are not supported. 191 192 The last paragraph's last sentence (page 38) should be changed to: 193 194 "Initially all texture generation modes are set to REFLECTION_MAP_OES" 195 196Additions to Chapter 3 of the 1.5 Specification (Rasterization) 197 198 -- Section 3.8.1 "Texture Image Specification" 199 200 Change the second and third to last sentences on page 116 to: 201 202 "<target> must be one of TEXTURE_2D for a 2D texture, or one of 203 TEXTURE_CUBE_MAP_POSITIVE_X_OES, TEXTURE_CUBE_MAP_NEGATIVE_X_OES, 204 TEXTURE_CUBE_MAP_POSITIVE_Y_OES, TEXTURE_CUBE_MAP_NEGATIVE_Y_OES, 205 TEXTURE_CUBE_MAP_POSITIVE_Z_OES, or TEXTURE_CUBE_MAP_NEGATIVE_Z_OES 206 for a cube map texture." 207 208 Add the following paragraphs after the first paragraph on page 117: 209 210 "A 2D texture consists of a single 2D texture image. A cube 211 map texture is a set of six 2D texture images. The six cube map 212 texture targets form a single cube map texture though each target 213 names a distinct face of the cube map. The TEXTURE_CUBE_MAP_*_OES 214 targets listed above update their appropriate cube map face 2D 215 texture image. Note that the six cube map 2D image tokens such as 216 TEXTURE_CUBE_MAP_POSITIVE_X_OES are used when specifying, updating, 217 or querying one of a cube map's six 2D image, but when enabling 218 cube map texturing or binding to a cube map texture object (that is 219 when the cube map is accessed as a whole as opposed to a particular 220 2D image), the TEXTURE_CUBE_MAP_OES target is specified. 221 222 When the target parameter to TexImage2D is one of the six cube map 223 2D image targets, the error INVALID_VALUE is generated if the width 224 and height parameters are not equal. 225 226 If cube map texturing is enabled at the time a primitive is 227 rasterized and if the set of six targets are not "cube complete", 228 then it is as if texture mapping were disabled. The targets of 229 a cube map texture are "cube complete" if the array 0 of all six 230 targets have identical, positive, and square dimensions, the array 231 0 of all six targets were specified with the same internalformat, 232 and the array 0 of all six targets have the same border width." 233 234 After the 14th paragraph (page 116) add: 235 236 "In a similiar fashion, the maximum allowable width and height 237 (they must be the same) of a cube map texture must be at least 238 2^(k-lod) for image arrays level 0 through k, where k is the 239 log base 2 of MAX_CUBE_MAP_TEXTURE_SIZE_OES." 240 241 -- Section 3.8.2 "Alternate Texture Image Specification Commands" 242 243 Update the second paragraph (page 120) to say: 244 245 ... "Currently, <target> must be 246 TEXTURE_2D, TEXTURE_CUBE_MAP_POSITIVE_X_OES, 247 TEXTURE_CUBE_MAP_NEGATIVE_X_OES, TEXTURE_CUBE_MAP_POSITIVE_Y_OES, 248 TEXTURE_CUBE_MAP_NEGATIVE_Y_OES, TEXTURE_CUBE_MAP_POSITIVE_Z_OES, 249 or TEXTURE_CUBE_MAP_NEGATIVE_Z_OES." ... 250 251 Add after the second paragraph (page 120), the following: 252 253 "When the target parameter to CopyTexImage2D is one of the six cube 254 map 2D image targets, the error INVALID_VALUE is generated if the 255 width and height parameters are not equal." 256 257 -- Section 3.8.3 "Texture Parameters" 258 259 Change paragraph one (page 124) to say: 260 261 ... "<target> is the target, either TEXTURE_2D or TEXTURE_CUBE_MAP_OES." 262 263 Add a final paragraph saying: 264 265 "Texture parameters for a cube map texture apply to cube map 266 as a whole; the six distinct 2D texture images use the 267 texture parameters of the cube map itself. 268 269 -- Section 3.8.5 "Texture Minification" under "Mipmapping" 270 271 Change the first full paragraph on page 130 to: 272 273 ... "If texturing is enabled for two-dimensional texturing but not cube map 274 texturing (and TEXTURE_MIN_FILTER is one that requires a mipmap) at the 275 time a primitive is rasterized and if the set of arrays 276 TEXTURE_BASE_LEVEL through q = min{p,TEXTURE_MAX_LEVEL} is incomplete, 277 based on the dimensions of array 0, then it is as if texture mapping were 278 disabled." 279 280 Follow the first full paragraph on page 130 with: 281 282 "If cube map texturing is enabled and TEXTURE_MIN_FILTER is one that 283 requires mipmap levels at the time a primitive is rasterized and 284 if the set of six targets are not "mipmap cube complete", then it 285 is as if texture mapping were disabled. The targets of a cube map 286 texture are "mipmap cube complete" if the six cube map targets are 287 "cube complete" and the set of arrays TEXTURE_BASE_LEVEL through 288 q are not incomplete (as described above)." 289 290 -- Section 3.8.7 "Texture State and Proxy State" 291 292 Change the first sentence of the first paragraph (page 131) to say: 293 294 "The state necessary for texture can be divided into two categories. 295 First, there are the nine sets of mipmap arrays (one each for the 296 one-, two-, and three-dimensional texture targets and six for the 297 cube map texture targets) and their number." ... 298 299 Change the second paragraph (page 132) to say: 300 301 "In addition to the one-, two-, three-dimensional, and the six cube 302 map sets of image arrays, the partially instantiated one-, two-, 303 and three-dimensional and one cube map sets of proxy image arrays 304 are maintained." ... 305 306 -- Section 3.8.8 "Texture Objects" 307 308 Change the first sentence of the first paragraph (page 132) to say: 309 310 "In addition to the default textures TEXTURE_2D and TEXTURE_CUBE_MAP_OES, 311 named two-dimensional texture objects and cube map texture objects can be 312 created and operated on." ... 313 314 Change the second paragraph (page 132) to say: 315 316 "A texture object is created by binding an unused name to 317 TEXTURE_2D or TEXTURE_CUBE_MAP_OES." ... 318 "If the new texture object is bound to TEXTURE_2D or TEXTURE_CUBE_MAP_OES, 319 it remains a two-dimensional or cube map texture until it is deleted." 320 321 Change the third paragraph (page 133) to say: 322 323 "BindTexture may also be used to bind an existing texture object to 324 either TEXTURE_2D or TEXTURE_CUBE_MAP_OES." 325 326 Change paragraph five (page 133) to say: 327 328 "In the initial state, TEXTURE_2D and TEXTURE_CUBE_MAP_OES have two- 329 dimensional and cube map state vectors associated with them respectively." 330 ... "The initial two-dimensional and cube map texture is therefore 331 operated upon, queried, and applied as TEXTUER_2D and TEXTURE_CUBE_MAP_OES 332 respectively while 0 is bound to the corresponding targets." 333 334 Change paragraph six (page 133) to say: 335 336 ... "If a texture that is currently bound to one of the targets TEXTURE_2D 337 or TEXTURE_CUBE_MAP_OES is deleted, it is as though BindTexture has been 338 executed with the same <target> and <texture> zero." ... 339 340 -- Section 3.8.10 "Texture Application" 341 342 Replace the beginning sentences of the first paragraph (page 138) 343 with: 344 345 "Texturing is enabled or disabled using the generic Enable 346 and Disable commands, respectively, with the symbolic constants 347 TEXTURE_2D or TEXTURE_CUBE_MAP_OES to enable the two-dimensional or cube 348 map texturing respectively. If the cube map texture and the two- 349 dimensional texture are enabled, then cube map texturing is used. If 350 texturing is disabled, a rasterized fragment is passed on unaltered to the 351 next stage of the GL (although its texture coordinates may be discarded). 352 Otherwise, a texture value is found according to the parameter values of 353 the currently bound texture image of the appropriate dimensionality. 354 355 However, when cube map texturing is enabled, the rules are 356 more complicated. For cube map texturing, the (s,t,r) texture 357 coordinates are treated as a direction vector (rx,ry,rz) emanating 358 from the center of a cube. (The q coordinate can be ignored since 359 it merely scales the vector without affecting the direction.) At 360 texture application time, the interpolated per-fragment (s,t,r) 361 selects one of the cube map face's 2D image based on the largest 362 magnitude coordinate direction (the major axis direction). If two 363 or more coordinates have the identical magnitude, the implementation 364 may define the rule to disambiguate this situation. The rule must 365 be deterministic and depend only on (rx,ry,rz). The target column 366 in the table below explains how the major axis direction maps to 367 the 2D image of a particular cube map target. 368 369 major axis 370 direction target sc tc ma 371 ---------- ------------------------------- --- --- --- 372 +rx TEXTURE_CUBE_MAP_POSITIVE_X_OES -rz -ry rx 373 -rx TEXTURE_CUBE_MAP_NEGATIVE_X_OES +rz -ry rx 374 +ry TEXTURE_CUBE_MAP_POSITIVE_Y_OES +rx +rz ry 375 -ry TEXTURE_CUBE_MAP_NEGATIVE_Y_OES +rx -rz ry 376 +rz TEXTURE_CUBE_MAP_POSITIVE_Z_OES +rx -ry rz 377 -rz TEXTURE_CUBE_MAP_NEGATIVE_Z_OES -rx -ry rz 378 379 Using the sc, tc, and ma determined by the major axis direction as 380 specified in the table above, an updated (s,t) is calculated as 381 follows 382 383 s = ( sc/|ma| + 1 ) / 2 384 t = ( tc/|ma| + 1 ) / 2 385 386 This new (s,t) is used to find a texture value in the determined 387 face's 2D texture image using the rules given in sections 3.8.5 388 and 3.8.6." ... 389 390Additions to Chapter 4 of the 1.2 Specification (Per-Fragment Operations 391and the Frame Buffer) 392 393 None 394 395Additions to Chapter 5 of the 1.2 Specification (Special Functions) 396 397Additions to Chapter 6 of the 1.2 Specification (State and State Requests) 398 399 -- Section 6.1.3 "Enumerated Queries" 400 401 Change the fourth paragraph (page 183) to say: 402 403 "The GetTexParameter parameter <target> may be one of TEXTURE_2D, 404 or TEXTURE_CUBE_MAP_OES, indicating the currently bound two-dimensional 405 or cube map texture object." 406 407Additions to the GLX Specification 408 409 None 410 411Errors 412 413 INVALID_VALUE is generated when the target parameter to TexImage2D 414 or CopyTexImage2D is one of the six cube map 2D image targets and 415 the width and height parameters are not equal. 416 417New State 418 419(table 6.12, p202) add the following entries: 420 421Get Value Type Get Command Initial Value Description Sec Attribute 422--------- ---- ----------- ------------- ----------- ------ -------------- 423TEXTURE_CUBE_MAP_OES B IsEnabled False True if cube map 3.8.10 texture/enable 424 texturing is enabled 425TEXTURE_BINDING_CUBE_MAP_OES Z+ GetIntegerv 0 Texture object 3.8.8 texture 426 for TEXTURE_CUBE_MAP 427TEXTURE_CUBE_MAP_POSITIVE_X_OES nxI N/A see 3.8 positive x face 3.8 - 428 cube map texture 429 image at lod i 430TEXTURE_CUBE_MAP_NEGATIVE_X_OES nxI N/A see 3.8 negative x face 3.8 - 431 cube map texture 432 image at lod i 433TEXTURE_CUBE_MAP_POSITIVE_Y_OES nxI N/A see 3.8 positive y face 3.8 - 434 cube map texture 435 image at lod i 436TEXTURE_CUBE_MAP_NEGATIVE_Y_OES nxI N/A see 3.8 negative y face 3.8 - 437 cube map texture 438 image at lod i 439TEXTURE_CUBE_MAP_POSITIVE_Z_OES nxI N/A see 3.8 positive z face 3.8 - 440 cube map texture 441 image at lod i 442TEXTURE_CUBE_MAP_NEGATIVE_Z_OES nxI N/A see 3.8 negative z face 3.8 - 443 cube map texture 444 image at lod i 445 446(table 6.14, p204) add the following entries: 447 448Get Value Type Get Command Initial Value Description Sec Attribute 449--------- ---- ----------- ------------- ----------- ------ --------- 450TEXTURE_GEN_MODE_OES Z2 GetTexGenivOES REFLECTION_MAP_OES Function used for 2.10.4 texture 451 texgen (for s,t,r) 452TEXTURE_GEN_STR_OES B IsEnabled FALSE True if texgen is 2.10.4 texture 453 enabled (for s,t,r) 454 455New Implementation Dependent State 456 457(table 6.24, p214) add the following entry: 458 459Get Value Type Get Command Minimum Value Description Sec Attribute 460--------- ---- ----------- ------------- ----------- ------ -------------- 461MAX_CUBE_MAP_TEXTURE_SIZE_OES Z+ GetIntegerv 16 Maximum cube map 3.8.1 - 462 texture image 463 dimension 464 465Revision History 466 467Version 1, November 8, 2007 (Benj Lipchak) - First version cleaned up for ES 468Version 2, April 16, 2015 (Jon Leech) - Remove border width term bt (nonexistent in ES) 469