1Name 2 3 ARB_texture_cube_map_array 4 5Name Strings 6 7 GL_ARB_texture_cube_map_array 8 9Contact 10 11 Nick Haemel, AMD (nick.haemel 'at' amd.com) 12 13Contributors 14 Jeff Bolz, NVIDIA 15 Yunjun Zhang, AMD 16 Bill Licea-Kane, AMD 17 Graham Sellers, AMD 18 Daniel Koch, TransGaming 19 Mark Young, AMD 20 21Notice 22 23 Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at 24 http://www.khronos.org/registry/speccopyright.html 25 26Specification Update Policy 27 28 Khronos-approved extension specifications are updated in response to 29 issues and bugs prioritized by the Khronos OpenGL Working Group. For 30 extensions which have been promoted to a core Specification, fixes will 31 first appear in the latest version of that core Specification, and will 32 eventually be backported to the extension document. This policy is 33 described in more detail at 34 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 35 36Status 37 38 Complete. Approved by the ARB on July 3, 2009. 39 40Version 41 42 Last Modified Date: 12/07/2009 43 Author revision: 9 44 45Number 46 47 ARB Extension #71 48 49Dependencies 50 51 This extension is written against the OpenGL 3.0 specification and 52 version 1.30.08 of the OpenGL Shading Language specification. 53 54Overview 55 56 The GL_EXT_texture_array extension, and subsequently OpenGL 3.0 have 57 introduced the concept of one- and two-dimensional array textures. 58 An array texture is an ordered set of images with the same size and 59 format. Each image in an array texture has a unique level. This 60 extension expands texture array support to include cube map 61 textures. 62 63 A cube map array texture is a 2-dimensional array texture that may 64 contain many cube map layers. Each cube map layer is a unique cube 65 map image set. Images in a cube map array have the same size and 66 format limitations as one- and two-dimensional array textures. A 67 cube map array texture is specified using TexImage3D in a similar 68 manner to two-dimensional arrays. Cube map array textures can be 69 bound to a render targets of a frame buffer object as 70 two-dimensional arrays are using FramebufferTextureLayer. 71 72 When accessed by a programmable shader, a cube map array texture 73 acts as a single unit. The "s", "t", "r" texture coordinates are 74 treated as a regular cube map texture fetch. The "q" texture is 75 treated as an unnormalized floating-point value identifying the 76 layer of the cube map array texture. Cube map array texture lookups 77 do not filter between layers. 78 79 This extension does not provide for the use of cube map array 80 textures with fixed-function fragment processing. 81 82New Procedures and Functions 83 84 None 85 86New Tokens 87 88 Accepted by the <target> parameter of TexParameteri, TexParameteriv, 89 TexParameterf, TexParameterfv, BindTexture, and GenerateMipmap: 90 91 TEXTURE_CUBE_MAP_ARRAY_ARB 0x9009 92 93 Accepted by the <pname> parameter of GetBooleanv, GetDoublev, 94 GetIntegerv and GetFloatv: 95 96 TEXTURE_BINDING_CUBE_MAP_ARRAY_ARB 0x900A 97 98 Accepted by the <target> parameter of TexImage3D, TexSubImage3D, 99 CompressedTeximage3D, CompressedTexSubImage3D and CopyTexSubImage3D: 100 101 TEXTURE_CUBE_MAP_ARRAY_ARB 102 PROXY_TEXTURE_CUBE_MAP_ARRAY_ARB 0x900B 103 104 Accepted by the <tex> parameter of GetTexImage: 105 106 TEXTURE_CUBE_MAP_ARRAY_ARB 107 108 Returned by the <type> parameter of GetActiveUniform: 109 110 SAMPLER_CUBE_MAP_ARRAY_ARB 0x900C 111 SAMPLER_CUBE_MAP_ARRAY_SHADOW_ARB 0x900D 112 INT_SAMPLER_CUBE_MAP_ARRAY_ARB 0x900E 113 UNSIGNED_INT_SAMPLER_CUBE_MAP_ARRAY_ARB 0x900F 114 115Additions to Chapter 2 of OpenGL 3.0 Specification (OpenGL Operation) 116 117 Modify section 2.20.3 "Shader Variables", page 91 118 119 (Add the following new return type to the 3rd paragraph on p.97) 120 121 SAMPLER_CUBE_MAP_ARRAY_ARB, 122 SAMPLER_CUBE_MAP_ARRAY_SHADOW_ARB, 123 INT_SAMPLER_CUBE_MAP_ARRAY_ARB, 124 UNSIGNED_INT_SAMPLER_CUBE_MAP_ARRAY_ARB, 125 126Addition to Chapter 3 of OpenGL 3.0 Specification (Rasterization) 127 128 Modify section 3.9, "Texturing", page 175 129 130 (modify the 3rd paragraph, p.175) 131 132 Six types of texture are supported; each is a collection of images 133 built from one-, two-, or three-dimensional array of image elements 134 referred to as texels. One-, two-, and three-dimensional textures 135 consist respectively of one-, two-, or three-dimensional texel 136 arrays. One- and two-dimensional array textures are arrays of one- 137 or two-dimensional images, consisting of one or more layers. A cube 138 map is a special two-dimensional array texture with six layers that 139 represent the faces of a cube. When accessing a cube map, the 140 texture coordinates are projected onto one of the six faces of the 141 cube. Finally a cube map array is a collection of cube map layers 142 stored as a two-dimensional array texture. When accessing a cube map 143 array, the texture coordinate "s", "t", "r" are applied similarly as 144 cube map while the last texture coordinate "q" is used as the index 145 of on the cube map slices. 146 147 148 Modify Section 3.9.1, Texture Image Specification, page 176 149 150 (modify the first paragraph of section, p. 176) 151 152 The command 153 154 void TexImage3D( enum target, int level, int internalformat, 155 sizei width, sizei height, sizei depth, int border, 156 enum format, enum type, void *data ); 157 158 is used to specify a three-dimensional texture image. <target> must 159 be one of TEXTURE_3D for a three-dimensional texture or 160 TEXTURE_2D_ARRAY for a two-dimensional array texture or 161 TEXTURE_CUBE_MAP_ARRAY_ARB. Additionally, target may be 162 PROXY_TEXTURE_3D for a three-dimensional proxy texture, 163 PROXY_TEXTURE_2D_ARRAY for a two-dimensional proxy array texture, or 164 PROXY_TEXTURE_CUBE_MAP_ARRAY_ARB for a proxy cube map array texture. 165 If target is TEXTURE_CUBE_MAP_ARRAY_ARB or 166 PROXY_TEXTURE_CUBE_MAP_ARRAY_ARB, specifying a depth value that is 167 not a multiple of six results in an error of INVALID_VALUE. 168 INVALID_VALUE is also generated if the width and the height 169 parameters are not equal. ... 170 171 When <target> is TEXTURE_CUBE_MAP_ARRAY_ARB or 172 PROXY_TEXTURE_CUBE_MAP_ARRAY_ARB <width> and <height> must be equal, 173 otherwise the error INVALID_VALUE is generated. Also, <depth> must 174 be a multiple of six indicating 6N layer-faces in the cube map 175 array, otherwise the error INVALID_VALUE is generated. 176 177 178 (modify the third paragraph of section, p. 177) 179 180 Textures with a base internal format of DEPTH_COMPONENT or 181 DEPTH_STENCIL are supported by texture image specification commands 182 only if target is TEXTURE_1D, TEXTURE_2D, TEXTURE_1D_ARRAY, 183 TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP, TEXTURE_CUBE_MAP_ARRAY_ARB, 184 PROXY_TEXTURE_1D, PROXY_TEXTURE_2D, PROXY_TEXTURE_1D_ARRAY, 185 PROXY_TEXTURE_2D_ARRAY, PROXY_TEXTURE_CUBE_MAP or 186 PROXY_TEXTURE_CUBE_MAP_ARRAY_ARB. ... 187 188 189 (modify the second paragraph of section, p.186) 190 191 and w_b, h_b, and d_b are the specified border width, height, and 192 depth. wb and hb are the specified border value; d_b is the 193 specified border value if target is TEXTURE_3D, or zero if target is 194 TEXTURE_2D_ARRAY or TEXTURE_CUBE_MAP_ARRAY_ARB. Thus the last 195 two-dimensional image slice of the three-dimensional image is 196 indexed with the highest value of k. When <target> is 197 TEXTURE_CUBE_MAP_ARRAY_ARB. specifying a cube map array texture, k 198 refers to a layer-face. The layer is given by 199 200 layer = floor(k/6), 201 202 and the face is given by 203 204 face = k mod 6 205 206 When 207 208 face = 0: TEXTURE_CUBE_MAP_POSITVE_X, 209 face = 1: TEXTURE_CUBE_MAP_NEGATIVE_X, 210 face = 2: TEXTURE_CUBE_MAP_POSITVE_Y, 211 face = 3: TEXTURE_CUBE_MAP_NEGATIVE_Y, 212 face = 4: TEXTURE_CUBE_MAP_POSITVE_Z, 213 face = 5: TEXTURE_CUBE_MAP_NEGATIVE_Z. 214 215 216 (modify the fifth paragraph of section, p. 187) 217 218 ... The maximum allowable width and height of a cube map or cube map 219 array texture must be the same, and must be at least 2^(k-lod) + 2 * 220 b_t for image arrays level 0 through k, where k is the log base 2 of 221 MAX_CUBE_MAP_TEXTURE_SIZE. The maximum number of layers for one- and 222 two-dimensional array textures (height or depth, respectively), and 223 the maximum number of layer-faces for cube map array textures 224 (depth) must be at least MAX_ARRAY_TEXTURE_LAYERS_EXT for all 225 levels. 226 227 (modify the second last paragraph, p. 189) 228 229 An element (i, j, k) of the texel array is called a texel (for a 230 two-dimensional texture or one-dimensional array texture, k is 231 irrelevant; for a one-dimensional texture, j and k are both 232 irrelevant). If target is TEXTURE_2D_ARRAY or TEXTURE_3D, the 233 texture value for a fragment is determined by that fragment's 234 associated (s, t, r) coordinates, but may not correspond to any 235 actual texel. See figure 3.10. If target is 236 TEXTURE_CUBE_MAP_ARRAY_ARB, the texture value is determined by (s, 237 t, r, q) coordinates where "s", "t", "r" is defined to be the same 238 as for TEXTURE_CUBE_MAP and "q" is defined as the index of a 239 specific cube map in the cube map array. 240 241 242 (modify the first paragraph, p. 193) 243 244 ... and the target arguments of TexSubImage3D and CopyTexSubImage3D 245 must be TEXTURE_3D, TEXTURE_2D_ARRAY, or TEXTURE_CUBE_MAP_ARRAY_ARB. 246 The level parameter of each command specifies the level of the texel 247 array that is modified. If level is less than zero or greater than 248 the base 2 logarithm of the maximum texture width, height, or depth, 249 the error INVALID VALUE is generated. 250 251 (modify the second to last paragraph, p. 193) 252 253 Arguments <xoffset>, <yoffset>, and <zoffset> of TexSubImage3D and 254 CopyTex- SubImage3D specify the lower left texel coordinates of a 255 <width>-wide by <height>-high by <depth>-deep rectangular subregion 256 of the texel array. For cube map array textures, <zoffset> is the 257 first layer-face to update, and <depth> is the number layer-faces to 258 update. The depth argument ... 259 260 261 Modify Section 3.9.4, Texture Parameters, page 200 262 263 (modify the first paragraph of section, p. 200) 264 265 ... target is the target, either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, 266 TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP or 267 TEXTURE_CUBE_MAP_ARRAY_ARB. ... 268 269 270 (modify third paragraph, p. 204) 271 272 ... For a one-dimensional or one-dimensional array texture, define 273 v(x, y) == 0 and w(x, y) == 0; for a two-dimensional, 274 two-dimensional array, cube map, or cube map array texture define 275 w(x, y) == 0. ... 276 277 278 (modify the first paragraph of "Mipmapping", p.209) 279 280 If the image array of level level_base, excluding its border, has 281 dimensions, w_t x h_t x d_t, then there are floor(log2(maxsize)) + 1 282 levels in the mipmap, where 283 284 maxsize = w_t, for one-dimensional and one-dimensional 285 array textures, 286 287 max(w_t, h_t), for two-dimensional, two-dimensional array, 288 cube map and cube map array textures, 289 290 max(w_t, h_t, d_t), for three dimensional textures. 291 292 293 (modify the third paragraph in the "Automatic Mipmap Generation", p. 211) 294 295 The contents of the derived arrays are computed by repeated, 296 filtered reduction of the level_base array. For one- , 297 two-dimensional or cube map array textures, each layer is filtered 298 independently. ... 299 300 301 (modify the first paragraph in the "Manual Mipmap Generation", p. 211) 302 Mipmaps can be generated manually with the command 303 304 void GenerateMipmap( enum target ); 305 306 where target is one of TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, 307 TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP, or 308 TEXTURE_CUBE_MAP_ARRAY_ARB. ... 309 310 311 Modify Section 3.9.10, Texture Completeness, page 212 312 313 (add a new paragraph in the end of the section, p. 213) 314 315 A cube map array texture is cube array complete if it is complete 316 when treated as a two-dimensional array and cube complete for every 317 cube map slice within the array texture. 318 319 320 Modify Section 3.9.11, Texture State and Proxy State, page 214 321 322 (modify second and third paragraphs, p. 214) 323 324 In addition to image arrays for one-, two-, and three-dimensional 325 textures, one- and two-dimensional array textures, and the six image 326 arrays for the cube map texture, partially instantiated image arrays 327 are maintained for one-, two-, and three-dimensional textures and 328 one- and two-dimensional array textures, and cube map array 329 textures. Additionally, a single proxy image array is maintained for 330 the cube map texture. Each proxy image array includes width, height, 331 depth, border width, and internal format state values, as well as 332 state for the red, green, blue, alpha, luminance, and intensity 333 component resolutions. Proxy image arrays do not include image data, 334 nor do they include texture properties. ... 335 336 337 (update the first paragraph, p. 215) 338 339 Proxy arrays for one- and two-dimensional textures and one- and 340 two-dimensional array textures and cube map array textures are 341 operated on in the same way when TexImage1D is executed with target 342 specified as PROXY_TEXTURE_1D, TexImage2D is executed with target 343 specified as PROXY_TEXTURE_2D or PROXY_TEXTURE_1D_ARRAY, or 344 TexImage3D is executed with target specified as 345 PROXY_TETXURE_2D_ARRAY or PROXY_TEXTURE_CUBE_MAP_ARRAY_ARB. 346 347 348 Modify Section 3.9.12 Texture Objects, page 215 349 350 (update the beginning to add cube map array textures, p. 215) 351 352 In addition to the default textures TEXTURE_1D, TEXTURE_2D, 353 TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, 354 and TEXTURE_CUBE_MAP_ARRAY_ARB, named one-, two-, and 355 three-dimensional, cube map, and one- , two-dimensional array 356 texture and cube map array texture objects can be created and 357 operated upon. The name space for texture objects is the unsigned 358 integers, with zero reserved by the GL. 359 360 A texture object is created by binding an unused name to TEXTURE_1D, 361 TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY, 362 TEXTURE_2D_ARRAY, or TEXTURE_CUBE_MAP_ARRAY_ARB. The binding is 363 effected by calling 364 365 void BindTexture( enum target, uint texture ); 366 367 with <target> set to the desired texture target and <texture> set to 368 the unused name. The resulting texture object is a new state vector, 369 comprising all the state values listed in section 3.8.11, set to the 370 same initial values. If the new texture object is bound to 371 TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, 372 TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, or TEXTURE_CUBE_MAP_ARRAY_ARB, 373 it is and remains a one-, two-, three-dimensional, cube map, one- , 374 two-dimensional array texture OR cube map array texture respectively 375 until it is deleted. 376 377 BindTexture may also be used to bind an existing texture object to 378 either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, 379 TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, or TEXTURE_CUBE_MAP_ARRAY_ARB. 380 The error INVALID_OPERATION is generated if an attempt is made to 381 bind a texture object of different dimensionality than the specified 382 target. If the bind is successful no change is made to the state of 383 the bound texture object, and any previous binding to target is 384 broken. 385 386 While a texture object is bound, GL operations on the target to 387 which it is bound affect the bound object, and queries of the target 388 to which it is bound return state from the bound object. If texture 389 mapping of the dimensionality of the target to which a texture 390 object is bound is enabled, the state of the bound texture object 391 directs the texturing operation. 392 393 In the initial state, TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, 394 TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, and 395 TEXTURE_CUBE_MAP_ARRAY_ARB have one-, two-, three-dimensional, cube 396 map, and one- and two-dimensional array and cube map array texture 397 state vectors respectively associated with them. In order that 398 access to these initial textures not be lost, they are treated as 399 texture objects all of whose names are 0. The initial one-, two-, 400 three-dimensional, cube map, one- and two-dimensional array and cube 401 map array textures are therefore operated upon, queried, and applied 402 as TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, 403 TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, and TEXTURE_CUBE_MAP_ARRAY_ARB 404 respectively while 0 is bound to the corresponding targets. 405 406 407 (modify the first paragraph, p. 217) 408 409 ... a texture that is currently bound to one of the targets 410 TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, 411 TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, or TEXTURE_CUBE_MAP_ARRAY_ARB is 412 deleted, it is as though BindTexture had been executed with the same 413 target and texture zero. ... 414 415 416 (modify the second paragraph, p. 218) 417 418 The texture object name space, including the initial one-, two-, and 419 three dimensional, one- and two-dimensional array, cube map and cube 420 map array texture objects, is shared among all texture units. ... 421 422Additions to Chapter 4 of the OpenGL 3.0 Specification (Per-fragment Operations and the Frame Buffer) 423 424 Modify Section 4.4.2, Attaching Images to Framebuffer Objects, page 281 425 426 (modify the third paragraph in the section, p. 287) 427 428 The command 429 430 void FramebufferTextureLayer(enum target, enum attachment, 431 uint texture, int level, int layer); 432 433 operates identically to FramebufferTexture3D, except that it 434 attaches a single layer of a three-dimensional texture or a one- or 435 two-dimensional array texture, or a cube map array texture. <layer> 436 is an integer indicating the layer number, and is treated 437 identically to the <zoffset> parameter in FramebufferTexture3D for 438 three-dimensional textures, one- and two-dimensional textures. For 439 cube map array textures, <layer> mod 6 indicates a face of a cube 440 map slice within the cube map array. the order of the face is 441 defined as in 3.9.1. The error INVALID_VALUE is generated if <layer> 442 is negative. The error INVALID_OPERATION is generated if <texture> 443 is non-zero and is not the name of a three dimensional texture, one- 444 or two-dimensional array texture, or cube map array texture. Unlike 445 FramebufferTexture3D, no <textarget> parameter is accepted. 446 447 (modify last condition for framebuffer attachment completeness, p. 291) 448 449 * If FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE is TEXTURE and 450 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME names a one-dimensional, 451 two-dimensional or cube map array texture, then 452 FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER must be smaller than the 453 number of layers in the texture. 454 455 Modify Section 4.4.4.2, Framebuffer Completeness 456 457 (modify the completeness requirements of layered framebuffer 458 completeness added by GL_ARB_geometry_shader4) 459 460 * If any framebuffer attachment is layered, ... (i.e., three- 461 dimensional, cube map, one- or two dimensional array, or cube map 462 array textures). 463 { FRAMEBUFFER_INCOMPLETE_LAYER_TARGETS_{EXT|ARB} } 464 465 * If any framebuffer attachment is layered, ... For one- and two- 466 dimensional array textures, and cube map array textures, the layer 467 count is the number of layers in the array texture. 468 { FRAMEBUFFER_INCOMPLETE_LAYER_COUNT_{EXT|ARB} } 469 470 Modify Section 4.4.7, Layered Framebuffers 471 472 (add the following paragraph following table X.4, Layer numbers 473 for cube map texture faces) 474 475 When cube map array texture levels are attached to a layered 476 framebuffer, the layer number corresponds to a layer-face. The 477 layer-face can be translated into an array layer and a cube map face 478 by 479 480 array_layer = floor(layer/6), and 481 face = layer mod 6. 482 483 The face number correspond to the cube map faces as listed in 484 table X.4. 485 486Additions to Chapter 5 of the OpenGL 3.0 specification (Special Functions) 487 488 Modify Section 5.4, Display List, page 306 489 490 (modify the fifth paragraph in the section, p. 311) 491 492 TexImage3D, TexImage2D, TexImage1D, Histogram, and ColorTable are 493 executed immediately when called with the corresponding proxy 494 arguments PROXY_TEXTURE_3D or PROXY_TEXTURE_2D_ARRAY or 495 PROXY_TEXTURE_CUBE_MAP_ARRAY_ARB; ... 496 497Additions to Chapter 6 of the OpenGL 3.0 specification (State and State Requests) 498 499 Modify Section 6.1.3, Enumerated Queries, page 316 500 501 (modify the last paragraph, p. 317) 502 503 GetTexParameter parameter <target> may be one of TEXTURE_1D, 504 TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY, 505 TEXTURE_2D_ARRAY, or TEXTURE_CUBE_MAP_ARRAY_ARB, indicating the 506 currently bound one-, two-, three-dimensional, cube map, or one- or 507 two-dimensional array texture or cube map array texture. 508 GetTexLevelParameter parameter target may be one of TEXTURE_1D, 509 TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP_POSITIVE_X, 510 TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y, 511 TEXTURE_CUBE_MAP_NEGATIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, 512 TEXTURE_CUBE_MAP_NEGATIVE_Z, TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, 513 PROXY_TEXTURE_1D, PROXY_TEXTURE_2D, PROXY_TEXTURE_3D, 514 PROXY_TEXTURE_CUBE_MAP, PROXY_TEXTURE_1D_ARRAY, 515 PROXY_TEXTURE_2D_ARRAY, or PROXY_TEXTURE_CUBE_MAP_ARRAY, indicating 516 the one-, two-, or three-dimensional texture, one of the six 517 distinct 2D images making up the cube map texture, the one- or 518 two-dimensional array texture, or the one-, two-, three-dimensional, 519 cube map, or one- or two-dimensional array or cube map array proxy 520 state vector. ... 521 522 523 Modify Section 6.1.4, Texture Queries, page 322 524 525 (modify the first paragraph, p. 322) 526 527 The command 528 529 void GetTexImage( enum tex, int lod, enum format, 530 enum type, void *img ); 531 532 is used to obtain texture images. It is somewhat different from the 533 other get commands; tex is a symbolic value indicating which texture 534 (or texture face in the case of a cube map texture target name) is 535 to be obtained. TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, 536 TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY and TEXTURE_CUBE_MAP_ARRAY_ARB 537 indicate a one-, two-, or three-dimensional texture, or one- or 538 two-dimensional array texture, or cube map array texture, 539 respectively. ... 540 541 (modify the third paragraph, p. 322) 542 543 GetTexImage obtains... from the first image to the last for 544 three-dimensional textures. One- and two-dimensional array textures 545 and cube map array textures are treated as two-dimensional 546 three-dimensional and three-dimensional images, respectively, where 547 the layers are treated as rows or images. These groups are then... 548 549 (modify the first paragraph, p. 323) 550 551 For three-dimensional ,two-dimensional array and cube map array 552 textures, pixel storage operations are applied as if the image were 553 two-dimensional, except that the additional pixel storage state 554 values PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES are applied. ... 555 556Dependencies on EXT_gpu_shader4 and the OpenGL Shading Language (GLSL) 557 558 Because there is no fixed-function pipeline access for cube map 559 array textures, this extension is only valid when EXT_gpu_shader4 560 and GLSL is supported. if GLSL is not supported, the shading 561 language modifications and references to SAMPLER_CUBE_MAP_ARRAY_ARB 562 and SAMPLER_CUBE_MAP_ARRAY_SHADOW_ARB should be removed. 563 564Errors 565 566 TexImage3D generates the error INVALID_VALUE if <target> is 567 TEXTURE_CUBE_MAP_ARRAY_ARB and <depth> is not a multiple of 6. 568 569 TexImage3D generates the error INVALID_VALUE if <target> is 570 TEXTURE_CUBE_MAP_ARRAY_ARB and <width> and <height> are not equal. 571 572New State 573 574 (add to table 6.19, p. 357) 575 Initial 576 Get Value Type Get Command Value Description Sec. Attribute 577 ---------------------------------- ------- ----------- ---------- ----------------------------- ------ --------- 578 TEXTURE_BINDING_CUBE_MAP_ARRAY_ARB 2*x3xZ+ GetIntegerv 0 texture object bound 3.9.12 texture 579 to TEXTURE_CUBE_MAP_ARRAY_ARB 580 581 TEXTURE_CUBE_MAP_ARRAY_ARB nxI GetTexImage see 3.9.1 cube map array texture image 3.9.1 - 582 at lod i 583 584Modification to the OpenGL shading Language Specification, Version 1.30.08 585 586 #extension GL_ARB_texture_cube_map_array: <behavior> 587 588 The above line is needed to control the GLSL features described in 589 this section. 590 591 592 A new preprocessor #define is added to the OpenGL Shading Language: 593 594 #define GL_ARB_texture_cube_map_array 1 595 596 597 Add to Section 3.6 "Keywords" 598 599 (add new sampler type ) 600 601 samplerCubeArray, samplerCubeArrayShadow, isamplerCubeArray, 602 usamplerCubeArray 603 604 605 Add to Section 4.1 "Basic Types" 606 607 (add the following entries to the table: Floating Point Sampler Types) 608 609 samplerCubeArray handle for accessing a cube map array texture 610 611 samplerCubeArrayShadow handle for accessing a cube map array depth 612 texture with comparison 613 614 (add the following entries to the table: Signed Integer Sampler Types) 615 616 isamplerCubeArray handle for accessing an integer cube map 617 array texture 618 619 (add the following entries to the table: Unsigned Integer Sampler Types) 620 621 usamplerCubeArray handle for accessing an unsigned integer 622 cube map array texture 623 624 Add at the end of Section 7.1 625 "Vertex and Geometry Shader Special Variables" 626 627 (after last paragraph already talking about gl_Layer) 628 629 The output variable gl_Layer takes on a special value when used with 630 an array of cubemap textures. Instead of simply refering to the 631 layer, it is used to reference a cube map face inside a particular 632 layer as well. Setting gl_Layer to the value (layer*6+face) will 633 render to the appropriate <face> of the cube defined in <layer>. The 634 face values are defined in Table 4.x of Section 4.4.7 'Layered 635 Framebuffers' of the GL spec, but repeated here for clarity: 636 637 face value resulting target 638 -------------- ------------------------------ 639 0 TEXTURE_CUBE_MAP_POSITVE_X 640 1 TEXTURE_CUBE_MAP_NEGATIVE_X 641 2 TEXTURE_CUBE_MAP_POSITVE_Y 642 3 TEXTURE_CUBE_MAP_NEGATIVE_Y 643 4 TEXTURE_CUBE_MAP_POSITVE_Z 644 5 TEXTURE_CUBE_MAP_NEGATIVE_Z 645 646 For example, to render to the Positive Y cube map face located in 647 the 5th layer of the cube map array, gl_Layer should be set to 648 (5*6+2). 649 650 Add to section 8.7 "Texture Lookup Functions" 651 652 (Add new functions to the set of allowed texture lookup functions p. 85): 653 Syntax: 654 655 ivec3 textureSize(samplerCubeArray sampler, int lod) 656 gvec4 texture(gsamplerCubeArray sampler, vec4 coord 657 [, float bias]) 658 gvec4 textureLod(gsamplerCubeArray sampler, vec4 coord, float lod) 659 ivec3 textureSize(samplerCubeArrayShadow sampler, int lod) 660 float texture(samplerCubeArrayShadow sampler, vec4 coord, float compare) 661 gvec4 textureGrad(gsamplerCubeArray sampler, vec4 coord, 662 vec3 ddx, vec3 ddy); 663 664 Description: 665 666 Cube map array functions are similar to the equivalent cube map or 667 2D array functions. The value of coord.w is used to select the 668 layer of the array and the value coord.xyz is used to select the 669 location within the selected layer of the cubemap. See section 3.8 670 for more details. The shadow comparison texture functions take the 671 comparison value from a separate input rather than from the 672 primary coord vector. 673 674 Modify the Description of the textureSize function. 675 676 For the array forms, the last component of the return value is 677 the number of layers in the texture array, or the number of cubes 678 in the texture cube map array. 679 680Issues 681 682 (1) When fetching the Cubemap array texture in shader, should the 683 "q" coordinate be used to index a single layer of the whole 684 array as 2D array texture does, or to index a specific cubemap 685 within the array? 686 687 RESOLVED: "q" is used to index a specific cubemap in the array. 688 This is an intuitive selection because otherwise the it only need 689 2 coordinates instead of 3 to fetch a value in one layer of the 690 array. 691 692 693 (2) When specifying and indexing cube map array texture, should the 694 depth(layer) be the absolute number of layers in the array or 695 the number of cube maps? 696 697 RESOLVED: To support the indexing of cube map in cube map array, a 698 list of new api calls needs to be added, which may not be a 699 preferred direction. 700 701 702 (3) Should partial updates to a cube map set in a cube map array 703 texture be allowed? 704 705 RESOLVED: No, maintain the same restriction as updating a cube map 706 texture to retain orthogonality. 707 708 709 (4) Are cube map arrays cube maps where each "face" is an array or 710 arrays where each layer is a cube map? Should the API follow the 711 cube map or texture array paradigm? Should the data organization 712 for cube map arrays be exposed to or hidden from applications? 713 714 RESOLVED: Cube map arrays are specified in a manner similar to 715 two-dimensional array textures (as described in the 716 EXT_texture_array extension), where each mipmap level is 717 represented as a set of two-dimensional images. Each of these 718 two-dimensional images corresponds to a single face of a single 719 layer of the full cube map array, referred to as a "layer-face". 720 The first six two-dimensional images of the mipmap level 721 correspond to the six faces of the first layer of the cube map 722 array, and subsequent groups of six layer-faces correspond to 723 subsequent cube map array layers. For each cube map array layer, 724 the six two-dimensional images correspond to the positive X, 725 negative X, positive Y, negative Y, positive Z and negative Z 726 faces, respectively. A valid cube map array texture will thus 727 always have a multiple of 6 texture layers. 728 729 Cube maps and array textures use different paradigms for texture 730 image specification. Cube maps are specified one face at a time 731 (using TEXTURE_CUBE_MAP_POSITIVE_X, etc.). Sub-texture updates to 732 cube maps are also performed one face at a time. On the other 733 hand, array textures are specified entirely at once, and 734 sub-texture updates can span a subset of layers. 735 736 Cube map arrays follow the array texture paradigm. Cube map arrays 737 are specified all layer-faces at once or as a subset of 738 layer-faces. This avoids adding complexity to the API and targets 739 higher performance by lowering the number of calls necessary to 740 build a cube map array texture. It also ensures that there will 741 not be any texture completeness problems because of missing faces 742 or faces with mismatched sizes. 743 744 Since cube map array textures use the array texture paradigm, it 745 is necessary for applications to understand the data organization 746 of a cube map array. The data organization is exposed both at the 747 bitmap level and at the depth/zoffset/layer level. The <depth> 748 parameter used when specifying cube map array data is the number 749 of layer-faces. The <zoffset> parameter used for sub-texture 750 updates is also given as a layer-face. The <layer> parameter used 751 with the FBO API is also a layer-face. 752 753 754 (5) Should this organization be exposed when using geometry 755 programs/shaders to select layer-faces for rendering? 756 757 RESOLVED: Yes. Since layer-faces (layer*6+face) are exposed at the 758 API level, it is reasonable to expose this at the shader level. 759 The single layer output is preserved, and the value written to it 760 is interpreted as a layer-face. 761 762 Since the cube map array is treated as a special array of 2 763 dimensional textures, the user may render to it inside of a 764 geometry shader using the layered rendering functionality. The 765 user must first attach the cube map texture array to a framebuffer 766 color attachment using: 767 768 void FramebufferTextureARB(enum target, enum attachment, 769 uint texture, int level) 770 771 where <texture> defines the texture object containing a cube map 772 array texture. 773 774 Inside of the geometry shader, setting 'gl_Layer' to the value 775 (layer*6+face) will render to the appropriate <face> of the cube 776 defined in <layer>. The face values are defined in Table 4.x of 777 Section 4.4.7 'Layered Framebuffers' of the GL spec, but repeated 778 here for clarity: 779 780 face value resulting target 781 -------------- ------------------------------ 782 0 TEXTURE_CUBE_MAP_POSITVE_X 783 1 TEXTURE_CUBE_MAP_NEGATIVE_X 784 2 TEXTURE_CUBE_MAP_POSITVE_Y 785 3 TEXTURE_CUBE_MAP_NEGATIVE_Y 786 4 TEXTURE_CUBE_MAP_POSITVE_Z 787 5 TEXTURE_CUBE_MAP_NEGATIVE_Z 788 789 For example, to render to the Positive Y cube map face located in 790 the 5th layer of the cube map array, gl_Layer should be set to 791 (5*6+2). 792 793 794 (6) Should TexImage3D be enhanced to take TEXTURE_CUBE_MAP as a 795 <target> where the data is the whole cube map? 796 797 RESOLVED: No. From an implementation perspective this may be quite 798 simple (a cube map is a cube map array with one layer). However, 799 there is not much value added by doing this. An abundance of 800 existing code that uses cube maps would not benefit from the 801 change. 802 803 804 (7) Should the FBO API provide a mechanism for attaching a single 805 cube map from an array as an attachment for layered rendering? 806 807 RESOLVED: No. This is an interesting idea, but it doesn't provide 808 much functionality. This can easily be done as part of the geometry 809 program/shader. A more interesting idea for future versions of 810 OpenGL or as an extension is to allow texture data specified with 811 one texture target to be "typecast" or viewed as if specified with 812 a different target. Such an extension would allow an application to 813 view an array (or subset of an array) of two-dimensional texture 814 images as a two-dimensional array, a three-dimensional texture, or 815 a cube map array. 816 817 818 (8) How do you determine the maximum number of cube map array 819 texture layers allowed by an implementation? 820 821 RESOLVED: This extension treats cube map array textures like 822 two-dimensional array textures, except that the number of 823 layer-faces must be a multiple of six, and the width and height 824 must be equal. There is no separate query for the number of layers 825 in a cube map array, but the limit on the number of layers in an 826 array texture (EXT_texture_array) also applies to the total number 827 of layer-faces in a cube map array texture. 828 829 For example, if an implementation supporting this extension has a 830 limit of 512 layers for array, a cube map array texture may have 831 no more than floor(512/6) = 85 layers. 832 833 (9) Do we really need to define integer versions of cube map array 834 sampler types? 835 836 RESOLVED: Yes. It's not clear if they will be useful to any 837 applications, but there is no real reason no to provide them. 838 839 (10) Should we provide texture LOD functions for shadow sampler 840 targets? 841 842 RESOLVED: Yes. The level of detail computations for a texture used 843 as a shadow map are completely identical to that for other 844 textures. 845 846 However, we provide separate data types for the two textures 847 (e.g., sampler2D vs. sampler2DShadow), and there is no mechanism 848 to cast from one to the other. If we didn't provide these 849 functions, the only way to perform an LOD computation for a 850 texture used as a shadow map would be to bind the same texture 851 object to two different texture image units, one associated with a 852 shadow sampler and the other associated with a normal sampler. 853 854 (11) What built-in functions are available for 2D arrays that are 855 not provided for cube map arrays? 856 857 RESOLVED: Functions equivalent to the following 2D array functions 858 are not available for cube map arrays: 859 860 vec4 texelFetch2DArray(sampler2DArray sampler, ivec3 coord, int lod) 861 vec4 shadow2DArrayGrad(sampler2DArrayShadow sampler, vec4 coord, 862 vec2 ddx, vec2 ddy); 863 vec4 texelFetch2DArrayOffset(sampler2DArray sampler, ivec3 coord, 864 int lod, ivec2 offset) 865 vec4 shadow2DArrayGradOffset(sampler2DArrayShadow sampler, 866 vec4 coord, vec2 ddx, vec2 ddy, 867 ivec2 offset); 868 869 (12) What does ivec3 textureSize(samplerCubeArray sampler, int lod) 870 in the z component? 871 872 Resolved: array_layer (that is, number of cube maps in the array). 873 874 The spec is currently ambiguous, and can be interpreted as 875 layer (the number of cube map faces) or array_layer = floor(layer/6), 876 the number of cube maps. 877 878Revision History 879 880 Rev. Date Author Changes 881 ---- -------- -------- ----------------------------------------- 882 9 12/07/09 wwlk Edit texture function table description 883 as resolved in issue 12 884 8 12/07/09 wwlk Resolved issue 12 885 7 11/13/09 wwlk Added array size returned issue 12 886 6 11/11/09 wwlk Correct more mistaken GLSL prototypes 887 gSamplerCube takes vec3 ddx and ddy 888 gSamplerCube do not have offsets 889 gSamplerCubeArray should match. 890 5 09/09/09 groth Correct some mistaken GLSL prototypes 891 4 08/02/09 Jon Leech Reformat to 80 columns and assign ARB 892 extension number. 893 3 07/22/09 myoung Fix gl_layer interaction description 894 2 06/30/09 gsellers Fix enumerant values 895 1 05/06/09 nickh First draft 896