1Name 2 3 EXT_texture_storage 4 5Name Strings 6 7 GL_EXT_texture_storage 8 9Contact 10 11 Bruce Merry (bmerry 'at' gmail.com) 12 Ian Romanick, Intel (ian.d.romanick 'at' intel.com) 13 14Contributors 15 16 Jeremy Sandmel, Apple 17 Bruce Merry, ARM 18 Tom Olson, ARM 19 Benji Bowman, Imagination Technologies 20 Ian Romanick, Intel 21 Jeff Bolz, NVIDIA 22 Pat Brown, NVIDIA 23 Maurice Ribble, Qualcomm 24 Lingjun Chen, Qualcomm 25 Daniel Koch, Transgaming Inc 26 Benj Lipchak, Apple 27 28Status 29 30 Complete. 31 32Version 33 34 Last Modified Date: 18 September, 2013 35 Author Revision: 28 36 37Number 38 39 OpenGL ES Extension #108 40 41Dependencies 42 43 OpenGL ES 1.0, OpenGL ES 2.0 or OpenGL 1.2 is required. 44 45 OES_texture_npot, OES_texture_cube_map, OES_texture_3D, 46 OES_depth_texture, OES_packed_depth_stencil, 47 OES_compressed_paletted_texture, OES_texture_float, OES_texture_half_float 48 EXT_texture_type_2_10_10_10_REV, EXT_texture_format_BGRA8888, 49 EXT_texture3D, EXT_texture_rg, APPLE_texture_2D_limited_npot, 50 APPLE_rgb_422, APPLE_texture_format_BGRA8888, 51 ARB_texture_cube_map, ARB_texture_cube_map_array, 52 ARB_texture_rectangle, SGIS_generate_mipmap, 53 EXT_direct_state_access, OES_EGL_image, WGL_ARB_render_texture, 54 GLX_EXT_texture_from_pixmap, and core specifications that 55 incorporate these extensions affect the definition of this 56 extension. 57 58 This extension is written against the OpenGL 3.2 Core Profile 59 specification. 60 61Overview 62 63 The texture image specification commands in OpenGL allow each level 64 to be separately specified with different sizes, formats, types and 65 so on, and only imposes consistency checks at draw time. This adds 66 overhead for implementations. 67 68 This extension provides a mechanism for specifying the entire 69 structure of a texture in a single call, allowing certain 70 consistency checks and memory allocations to be done up front. Once 71 specified, the format and dimensions of the image array become 72 immutable, to simplify completeness checks in the implementation. 73 74 When using this extension, it is no longer possible to supply texture 75 data using TexImage*. Instead, data can be uploaded using TexSubImage*, 76 or produced by other means (such as render-to-texture, mipmap generation, 77 or rendering to a sibling EGLImage). 78 79 This extension has complicated interactions with other extensions. 80 The goal of most of these interactions is to ensure that a texture 81 is always mipmap complete (and cube complete for cubemap textures). 82 83IP Status 84 85 No known IP claims 86 87New Procedures and Functions 88 89 void TexStorage1DEXT(enum target, sizei levels, 90 enum internalformat, 91 sizei width); 92 93 void TexStorage2DEXT(enum target, sizei levels, 94 enum internalformat, 95 sizei width, sizei height); 96 97 void TexStorage3DEXT(enum target, sizei levels, 98 enum internalformat, 99 sizei width, sizei height, sizei depth); 100 101 void TextureStorage1DEXT(uint texture, enum target, sizei levels, 102 enum internalformat, 103 sizei width); 104 105 void TextureStorage2DEXT(uint texture, enum target, sizei levels, 106 enum internalformat, 107 sizei width, sizei height); 108 109 void TextureStorage3DEXT(uint texture, enum target, sizei levels, 110 enum internalformat, 111 sizei width, sizei height, sizei depth); 112 113New Types 114 115 None 116 117New Tokens 118 119 Accepted by the <value> parameter of GetTexParameter{if}v: 120 121 TEXTURE_IMMUTABLE_FORMAT_EXT 0x912F 122 123 Accepted by the <internalformat> parameter of TexStorage* when 124 implemented on OpenGL ES: 125 126 ALPHA8_EXT 0x803C /* reuse tokens from EXT_texture */ 127 LUMINANCE8_EXT 0x8040 128 LUMINANCE8_ALPHA8_EXT 0x8045 129 130 (if OES_texture_float is supported) 131 RGBA32F_EXT 0x8814 /* reuse tokens from ARB_texture_float */ 132 RGB32F_EXT 0x8815 133 ALPHA32F_EXT 0x8816 134 LUMINANCE32F_EXT 0x8818 135 LUMINANCE_ALPHA32F_EXT 0x8819 136 137 (if OES_texture_half_float is supported) 138 RGBA16F_EXT 0x881A /* reuse tokens from ARB_texture_float */ 139 RGB16F_EXT 0x881B 140 ALPHA16F_EXT 0x881C 141 LUMINANCE16F_EXT 0x881E 142 LUMINANCE_ALPHA16F_EXT 0x881F 143 144 (if EXT_texture_type_2_10_10_10_REV is supported) 145 RGB10_A2_EXT 0x8059 /* reuse tokens from EXT_texture */ 146 RGB10_EXT 0x8052 147 148 (if EXT_texture_format_BGRA8888 or APPLE_texture_format_BGRA8888 is supported) 149 BGRA8_EXT 0x93A1 150 151 (if EXT_texture_rg is supported) 152 R8_EXT 0x8229 /* reuse tokens from ARB_texture_rg */ 153 RG8_EXT 0x822B 154 155 (if EXT_texture_rg and OES_texture_float are supported) 156 R32F_EXT 0x822E /* reuse tokens from ARB_texture_rg */ 157 RG32F_EXT 0x8230 158 159 (if EXT_texture_rg and OES_texture_half_float are supported) 160 R16F_EXT 0x822D /* reuse tokens from ARB_texture_g */ 161 RG16F_EXT 0x822F 162 163 (APPLE_rgb_422 is supported) 164 RGB_RAW_422_APPLE 0x8A51 165 166 167Additions to Chapter 2 of the OpenGL 3.2 Core Profile Specification 168(OpenGL Operation) 169 170 None 171 172Additions to Chapter 3 of the OpenGL 3.2 Core Profile Specification 173(Rasterization) 174 175 After section 3.8.1 (Texture Image Specification) add a new 176 subsection called "Immutable-format texture images": 177 178 "An alterative set of commands is provided for specifying the 179 properties of all levels of a texture at once. Once a texture is 180 specified with such a command, the format and dimensions of all 181 levels becomes immutable, unless it is a proxy texture (since 182 otherwise it would no longer be possible to use the proxy). The 183 contents of the images and the parameters can still be modified. 184 Such a texture is referred to as an "immutable-format" texture. The 185 immutability status of a texture can be determined by calling 186 GetTexParameter with <pname> TEXTURE_IMMUTABLE_FORMAT_EXT. 187 188 Each of the commands below is described by pseudo-code which 189 indicates the effect on the dimensions and format of the texture. 190 For all of the commands, the following apply in addition to the 191 pseudo-code: 192 193 - If the default texture object is bound to <target>, an 194 INVALID_OPERATION error is generated. 195 - If executing the pseudo-code would lead to an error, the error is 196 generated and the command will have no effect. 197 - Any existing levels that are not replaced are reset to their 198 initial state. 199 - If <width>, <height>, <depth> or <levels> is less than 1, the 200 error INVALID_VALUE is generated. 201 - The pixel unpack buffer should be considered to be zero i.e., 202 the image contents are unspecified. 203 - Since no pixel data are provided, the <format> and <type> values 204 used in the pseudo-code are irrelevant; they can be considered to 205 be any values that are legal to use with <internalformat>. 206 - If the command is successful, TEXTURE_IMMUTABLE_FORMAT_EXT becomes 207 TRUE. 208 - If <internalformat> is a specific compressed texture format, then 209 references to TexImage* should be replaced by CompressedTexImage*, 210 with <format>, <type> and <data> replaced by any valid <imageSize> and 211 <data>. If there is no <imageSize> for which this command would have 212 been valid, an INVALID_OPERATION error is generated [fn: This 213 condition is not required for OpenGL, but is necessary for OpenGL 214 ES which does not support on-the-fly compression.] 215 - If <internalformat> is one of the internal formats listed in table 216 3.11, an INVALID_ENUM error is generated. [fn: The corresponding table 217 in OpenGL ES 2.0 is table 3.8.] 218 219 The command 220 221 void TexStorage1DEXT(enum target, sizei levels, 222 enum internalformat, 223 sizei width); 224 225 specifies all the levels of a one-dimensional texture (or proxy) at 226 the same time. It is described by the pseudo-code below: 227 228 for (i = 0; i < levels; i++) 229 { 230 TexImage1D(target, i, internalformat, width, 0, 231 format, type, NULL); 232 width = max(1, floor(width / 2)); 233 } 234 235 If <target> is not TEXTURE_1D or PROXY_TEXTURE_1D then INVALID_ENUM 236 is generated. If <levels> is greater than floor(log_2(width)) + 1 237 then INVALID_OPERATION is generated. 238 239 The command 240 241 void TexStorage2DEXT(enum target, sizei levels, 242 enum internalformat, 243 sizei width, sizei height); 244 245 specifies all the levels of a two-dimensional, cube-map, 246 one-dimension array or rectangle texture (or proxy) at the same 247 time. The pseudo-code depends on the <target>: 248 249 [PROXY_]TEXTURE_2D, [PROXY_]TEXTURE_RECTANGLE or 250 PROXY_TEXTURE_CUBE_MAP: 251 252 for (i = 0; i < levels; i++) 253 { 254 TexImage2D(target, i, internalformat, width, height, 0, 255 format, type, NULL); 256 width = max(1, floor(width / 2)); 257 height = max(1, floor(height / 2)); 258 } 259 260 TEXTURE_CUBE_MAP: 261 262 for (i = 0; i < levels; i++) 263 { 264 for face in (+X, -X, +Y, -Y, +Z, -Z) 265 { 266 TexImage2D(face, i, internalformat, width, height, 0, 267 format, type, NULL); 268 } 269 width = max(1, floor(width / 2)); 270 height = max(1, floor(height / 2)); 271 } 272 273 [PROXY_]TEXTURE_1D_ARRAY: 274 275 for (i = 0; i < levels; i++) 276 { 277 TexImage2D(target, i, internalformat, width, height, 0, 278 format, type, NULL); 279 width = max(1, floor(width / 2)); 280 } 281 282 If <target> is not one of those listed above, the error INVALID_ENUM 283 is generated. 284 285 The error INVALID_OPERATION is generated if any of the following 286 conditions hold: 287 - <target> is [PROXY_]TEXTURE_1D_ARRAY and <levels> is greater than 288 floor(log_2(width)) + 1 289 - <target> is not [PROXY_]TEXTURE_1D_ARRAY and <levels> is greater 290 than floor(log_2(max(width, height))) + 1 291 292 The command 293 294 void TexStorage3DEXT(enum target, sizei levels, enum internalformat, 295 sizei width, sizei height, sizei depth); 296 297 specifies all the levels of a three-dimensional, two-dimensional 298 array texture, or cube-map array texture (or proxy). The pseudo-code 299 depends on <target>: 300 301 [PROXY_]TEXTURE_3D: 302 303 for (i = 0; i < levels; i++) 304 { 305 TexImage3D(target, i, internalformat, width, height, depth, 0, 306 format, type, NULL); 307 width = max(1, floor(width / 2)); 308 height = max(1, floor(height / 2)); 309 depth = max(1, floor(depth / 2)); 310 } 311 312 [PROXY_]TEXTURE_2D_ARRAY, [PROXY_]TEXTURE_CUBE_MAP_ARRAY_ARB: 313 314 for (i = 0; i < levels; i++) 315 { 316 TexImage3D(target, i, internalformat, width, height, depth, 0, 317 format, type, NULL); 318 width = max(1, floor(width / 2)); 319 height = max(1, floor(height / 2)); 320 } 321 322 If <target> is not one of those listed above, the error INVALID_ENUM 323 is generated. 324 325 The error INVALID_OPERATION is generated if any of the following 326 conditions hold: 327 - <target> is [PROXY_]TEXTURE_3D and <levels> is greater than 328 floor(log_2(max(width, height, depth))) + 1 329 - <target> is [PROXY_]TEXTURE_2D_ARRAY or 330 [PROXY_]TEXTURE_CUBE_MAP_ARRAY_EXT and <levels> is greater than 331 floor(log_2(max(width, height))) + 1 332 333 After a successful call to any TexStorage* command with a non-proxy 334 target, the value of TEXTURE_IMMUTABLE_FORMAT_EXT for this texture 335 object is set to TRUE, and no further changes to the dimensions or 336 format of the texture object may be made. Other commands may only 337 alter the texel values and texture parameters. Using any of the 338 following commands with the same texture will result in the error 339 INVALID_OPERATION being generated, even if it does not affect the 340 dimensions or format: 341 342 - TexImage* 343 - CompressedTexImage* 344 - CopyTexImage* 345 - TexStorage* 346 347 The TextureStorage* commands operate identically to the 348 corresponding command where "Texture" is substituted for "Tex" 349 except, rather than updating the current bound texture for the 350 texture unit indicated by the current active texture state and the 351 target parameter, these "Texture" commands update the texture object 352 named by the initial texture parameter. The error INVALID_VALUE 353 is generated if <texture> is zero. 354 " 355 356 In section 3.8.6 (Texture Parameters), after the sentence 357 358 "In the remainder of section 3.8, denote by lod_min, lod_max, 359 level_base, and level_max the values of the texture parameters 360 TEXTURE_MIN_LOD, TEXTURE_MAX_LOD, TEXTURE_BASE_LEVEL, and 361 TEXTURE_MAX_LEVEL respectively." 362 363 add 364 365 "However, if TEXTURE_IMMUTABLE_FORMAT_EXT is 366 TRUE, then level_base is clamped to the range [0, <levels> - 1] and 367 level_max is then clamped to the range [level_base, <levels> - 1], 368 where <levels> is the parameter passed the call to TexStorage* for 369 the texture object. 370 371 In section 3.8.9 (Rendering feedback loops) replace all references 372 to TEXTURE_BASE_LEVEL by level_base. 373 374 In section 3.8.9 (Mipmapping), replace the paragraph starting "Each 375 array in a mipmap is defined..." by 376 377 "Each array in a mipmap is defined using TexImage3D, TexImage2D, 378 CopyTexImage2D, TexImage1D, CopyTexImage1D, or by functions that are 379 defined in terms of these functions. Level-of-detail numbers proceed 380 from level_base for the original texel array through the maximum 381 level p, with each unit increase indicating an array of half the 382 dimensions of the previous one (rounded down to the next integer if 383 fractional) as already described. For immutable-format textures, 384 p is one less than the <levels> parameter passed to TexStorage*; 385 otherwise p = floor(log_2(maxsize)) + level_base. All arrays from 386 level_base through q = min(p, level_max) must be defined, as 387 discussed in section 3.8.12." 388 389 In section 3.8.12 (Texture Completeness), modify the last sentence 390 to avoid refering to level_base and level_max: 391 392 "An implementation may allow a texture image array of level 1 or 393 greater to be created only if a mipmap complete set of image arrays 394 consistent with the requested array can be supported where the 395 values of TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL are 0 and 1000 396 respectively." 397 398 Modify section 3.8.13 (Texture State and Proxy State) to add the new 399 state: 400 401 "Each set consists of ..., and a boolean flag indicating whether the 402 format and dimensions of the texture are immutable." 403 404 Add 405 "The initial value of TEXTURE_IMMUTABLE_FORMAT_EXT is FALSE." 406 407Additions to Chapter 4 of the OpenGL 3.2 Core Profile Specification 408(Per-Fragment Operations and the Frame Buffer) 409 410 None 411 412Additions to Chapter 5 of the OpenGL 3.2 Compatibility Profile Specification 413(Special Functions) 414 415 In section 5.4.1 (Commands Not Usable in Display Lists), add 416 TexStorage* to the list of commands that cannot be used. 417 418Additions to Chapter 6 of the OpenGL 3.2 Core Profile Specification 419(State and State Requests) 420 421 Replace the following statement in 6.1.3 (Enumerated Queries): 422 423 "<value> must be one of the symbolic values in table 3.10." 424 425 with 426 427 "<value> must be TEXTURE_IMMUTABLE_FORMAT_EXT or one of the symbolic 428 values in table 3.22." 429 430Additions to the AGL/EGL/GLX/WGL Specifications 431 432 None 433 434Additions to OES_compressed_ETC1_RGB8_texture 435 436 Add the following to the additions to Chapter 3: 437 438 "Since ETC1 images are easily edited along 4x4 texel boundaries, the 439 limitations on CompressedTexSubImage2D are relaxed. 440 CompressedTexSubImage2D will result in an INVALID_OPERATION error 441 only if one of the following conditions occurs: 442 443 * <width> is not a multiple of four, and <width> plus <xoffset> is not 444 equal to the texture width; 445 446 * <height> is not a multiple of four, and <height> plus <yoffset> is 447 not equal to the texture height; or 448 449 * <xoffset> or <yoffset> is not a multiple of four. 450 451 Remove CompressedTexSubImage2D from this error: 452 453 "INVALID_OPERATION is generated by CompressedTexSubImage2D, 454 TexSubImage2D, or CopyTexSubImage2D if the texture image <level> 455 bound to <target> has internal format ETC1_RGB8_OES." 456 457 Add the following error: 458 459 "INVALID_OPERATION is generated by CompressedTexSubImage2D 460 if the region to be modified is not aligned to block boundaries 461 (refer to the extension text for details)." 462 463Additions to AMD_compressed_ATC_texture and AMD_compressed_3DC_texture: 464 465 Apply the same changes as for OES_compressed_ETC1_RGB8_texture 466 above, substituting the appropriate internal format tokens from 467 these extensions. 468 469Dependencies on EXT_direct_state_access 470 471 If EXT_direct_state_access is not present, references to 472 TextureStorage* should be ignored. 473 474Dependencies on OpenGL ES 475 476 On OpenGL ES without extensions introducing TEXTURE_MAX_LEVEL, 477 mipmapped textures specified with TexStorage are required to have a 478 full set of mipmaps. If TEXTURE_MAX_LEVEL is not supported, this 479 extension is modified as follows: 480 481 - Where an upper bound is placed on <levels> in this extension (i.e. 482 the maximum number of mipmap levels for a texture of the given 483 target and dimensions), an INVALID_OPERATION error is generated if 484 <levels> is neither 1 nor this upper bound. 485 - q (the effective maximum number of levels) is redefined to clamp 486 to the number of levels present in immutable-format textures. 487 488 OpenGL ES does not accept sized internal formats (e.g., RGBA8) and 489 instead derives an internal format from the <format> and <type> 490 parameters of TexImage2D. Since TexStorage* does not specify texel 491 data, the API doesn't include <format> and <type> parameters. 492 On an OpenGL ES implementation, the values in the <internalformat> 493 column in the tables below are accepted as <internalformat> 494 parameters, and base internal formats are not accepted. The 495 TexImage* calls in the TexStorage* pseudocode are modified so that 496 the <internalformat>, <format> and <type> parameters are 497 taken from the <format>, <format> and <type> columns (respectively) 498 in the tables below, according to the <internalformat> 499 specified in the TexStorage* command. 500 501 <internalformat> <format> <type> 502 ---------------- -------- ------ 503 RGB565 RGB UNSIGNED_SHORT_5_6_5 504 RGBA4 RGBA UNSIGNED_SHORT_4_4_4_4 505 RGB5_A1 RGBA UNSIGNED_SHORT_5_5_5_1 506 RGB8_OES RGB UNSIGNED_BYTE 507 RGBA8_OES RGBA UNSIGNED_BYTE 508 LUMINANCE8_ALPHA8_EXT LUMINANCE_ALPHA UNSIGNED_BYTE 509 LUMINANCE8_EXT LUMINANCE UNSIGNED_BYTE 510 ALPHA8_EXT ALPHA UNSIGNED_BYTE 511 512 If OES_depth_texture is supported: 513 514 <internalformat> <format> <type> 515 ---------------- -------- ------ 516 DEPTH_COMPONENT16_OES DEPTH_COMPONENT UNSIGNED_SHORT 517 DEPTH_COMPONENT32_OES DEPTH_COMPONENT UNSIGNED_INT 518 519 If OES_packed_depth_stencil is supported: 520 521 <internalformat> <format> <type> 522 ---------------- -------- ------ 523 DEPTH24_STENCIL8_OES DEPTH_STENCIL_OES UNSIGNED_INT 524 525 If OES_texture_float is supported: 526 527 <internalformat> <format> <type> 528 ---------------- -------- ------ 529 RGBA32F_EXT RGBA FLOAT 530 RGB32F_EXT RGB FLOAT 531 LUMINANCE_ALPHA32F_EXT LUMINANCE_ALPHA FLOAT 532 LUMINANCE32F_EXT LUMINANCE FLOAT 533 ALPHA32F_EXT ALPHA FLOAT 534 535 If OES_texture_half_float is supported: 536 537 <internalformat> <format> <type> 538 ---------------- -------- ------ 539 RGBA16F_EXT RGBA HALF_FLOAT_OES 540 RGB16F_EXT RGB HALF_FLOAT_OES 541 LUMINANCE_ALPHA16F_EXT LUMINANCE_ALPHA HALF_FLOAT_OES 542 LUMINANCE16F_EXT LUMINANCE HALF_FLOAT_OES 543 ALPHA16F_EXT ALPHA HALF_FLOAT_OES 544 545 If EXT_texture_type_2_10_10_10_REV is supported: 546 547 <internalformat> <format> <type> 548 ---------------- -------- ------ 549 RGB10_A2_EXT RGBA UNSIGNED_INT_2_10_10_10_REV_EXT 550 RGB10_EXT RGB UNSIGNED_INT_2_10_10_10_REV_EXT 551 552 If EXT_texture_format_BGRA8888 or APPLE_texture_format_BGRA8888 is supported: 553 554 <internalformat> <format> <type> 555 ---------------- -------- ------ 556 BGRA8_EXT BGRA_EXT UNSIGNED_BYTE 557 558 If EXT_texture_rg is supported: 559 560 <internalformat> <format> <type> 561 ---------------- -------- ------ 562 R8_EXT RED_EXT UNSIGNED_BYTE 563 RG8_EXT RG_EXT UNSIGNED_BYTE 564 565 If EXT_texture_rg and OES_texture_float are supported: 566 567 <internalformat> <format> <type> 568 ---------------- -------- ------ 569 R32F_EXT RED_EXT FLOAT 570 RG32F_EXT RG_EXT FLOAT 571 572 If EXT_texture_rg and OES_texture_half_float are supported: 573 574 <internalformat> <format> <type> 575 ---------------- -------- ------ 576 R16F_EXT RED_EXT HALF_FLOAT_OES 577 RG16F_EXT RG_EXT HALF_FLOAT_OES 578 579 If APPLE_rgb_422 is supported: 580 581 <internalformat> <format> <type> 582 ---------------- -------- ------ 583 RGB_RAW_422_APPLE RGB_422_APPLE UNSIGNED_SHORT_8_8_APPLE 584 585 586Dependencies on texture targets 587 588 If a particular texture target is not supported by the 589 implementation, passing it as a <target> to TexStorage* will 590 generate an INVALID_ENUM error. If as a result, any of the commands 591 defined in this extension would no longer have any valid <target>, 592 all references to the command should be ignored. 593 594 In particular, note that OpenGL ES 1.x/2.0 do not have proxy textures, 595 1D textures, or 3D textures, and thus only the TexStorage2DEXT 596 entry point is required. If OES_texture_3D is supported, the 597 TexStorage3DEXT entry point is also required. 598 599Dependencies on OES_texture_npot 600 601 If OpenGL ES 2.0 or APPLE_texture_2D_limited_npot is present but 602 OES_texture_npot is not present, then INVALID_OPERATION is 603 generated by TexStorage* and TexStorage3DEXT if <levels> is 604 not one and <width>, <height> or <depth> is not a power of 605 two. 606 607Dependencies on WGL_ARB_render_texture, GLX_EXT_texture_from_pixmap, EGL 6081.4 and GL_OES_EGL_image 609 610 The commands eglBindTexImage, wglBindTexImageARB, glXBindTexImageEXT or 611 EGLImageTargetTexture2DOES are not permitted on an immutable-format 612 texture. 613 They will generate the following errors: 614 - EGLImageTargetTexture2DOES: INVALID_OPERATION 615 - eglBindTexImage: EGL_BAD_MATCH 616 - wglBindTexImage: ERROR_INVALID_OPERATION 617 - glXBindTexImageEXT: BadMatch 618 619Dependencies on OES_compressed_paletted_texture 620 621 The compressed texture formats exposed by 622 OES_compressed_paletted_texture are not supported by TexStorage*. 623 Passing one of these tokens to TexStorage* will generate an 624 INVALID_ENUM error. 625 626Dependencies on APPLE_rgb_422 627 628 UNSIGNED_SHORT_8_8_APPLE is implied as the <type> when TexStorage2DEXT 629 is called with <internalformat> RGB_RAW_422_APPLE. Subsequently supplying 630 UNSIGNED_SHORT_8_8_REV_APPLE as the <type> to a TexSubImage2D updating 631 such an immutable texture will generate an INVALID_OPERATION error. 632 633Errors 634 635 Note that dependencies above modify the errors. 636 637 If TexStorage* is called with a <width>, <height>, <depth> or 638 <levels> parameter that is less than one, then the error 639 INVALID_VALUE is generated. 640 641 If the <target> parameter to TexStorage1DEXT is not 642 [PROXY_]TEXTURE_1D, then the error INVALID_ENUM is generated. 643 644 If the <target> parameter to TexStorage2DEXT is not 645 [PROXY_]TEXTURE_2D, [PROXY_]TEXTURE_CUBE_MAP, 646 [PROXY_]TEXTURE_RECTANGLE or [PROXY_]TEXTURE_1D_ARRAY, then the 647 error INVALID_ENUM is generated. 648 649 If the <target> parameter to TexStorage3DEXT is not 650 [PROXY_]TEXTURE_3D, [PROXY_]TEXTURE_2D_ARRAY or 651 [PROXY_]TEXTURE_CUBE_MAP_ARRAY then the error INVALID_ENUM is 652 generated. 653 654 If the <levels> parameter to TexStorage* is greater than the 655 <target>-specific value listed below then the error 656 INVALID_OPERATION is generated: 657 [PROXY_]TEXTURE_{1D,1D_ARRAY}: 658 floor(log_2(width)) + 1 659 [PROXY_]TEXTURE_{2D,2D_ARRAY,CUBE_MAP,CUBE_MAP_ARRAY}: 660 floor(log_2(max(width, height))) + 1 661 [PROXY_]TEXTURE_3D: 662 floor(log_2(max(width, height, depth))) + 1 663 [PROXY_]TEXTURE_RECTANGLE: 664 1 665 666 If the default texture object is bound to the <target> passed to 667 TexStorage*, then the error INVALID_OPERATION is generated. 668 669 If the <target> parameter to TextureStorage* does not match the 670 dimensionality of <texture>, then the error INVALID_OPERATION is 671 generated. 672 673 If the <texture> parameter to TextureStorage* is zero, then the 674 INVALID_VALUE is generated. 675 676 If any pseudo-code listed in this extension would generate an error, 677 then that error is generated. 678 679 Calling any of the following functions on a texture for which 680 TEXTURE_IMMUTABLE_FORMAT_EXT is TRUE will generate an 681 INVALID_OPERATION error: 682 - TexImage* 683 - CompressedTexImage* 684 - CopyTexImage* 685 686New State 687 688 Additions to Table 6.8 Textures (state per texture object) 689 690 Initial 691 Get Value Type Get Command Value Description Sec. 692 --------- ---- ----------- ------- ----------- ---- 693 TEXTURE_IMMUTABLE_FORMAT_EXT B GetTexParameter FALSE Size and format immutable 2.6 694 695New Implementation Dependent State 696 697 None 698 699Issues 700 701 1. What should this extension be called? 702 703 RESOLVED: EXT_texture_storage is chosen for consistency with the 704 glRenderbufferStorage entry point. 705 706 2. Should TexStorage* accept a border parameter? 707 708 RESOLVED: no. 709 710 DISCUSSION: Currently it does not, since borders are a deprecated 711 feature which is not supported by all hardware. Users of the 712 compatibility profile can continue to use the existing texture 713 specification functions, but there is an argument that users of 714 compatibility profile may also want to use this extension. 715 716 3. What is the correct error when <levels> specifies a partial 717 mipmap pyramid for OpenGL ES? 718 719 RESOLVED: INVALID_OPERATION, since it is an interaction between 720 parameters rather than a single value being invalid. It also makes 721 sense to relax this condition for desktop GL where it makes sense to 722 use a truncated pyramid with TEXTURE_MAX_LEVEL. 723 724 4. Should use of these entry-points make the metadata (format and 725 dimensions) immutable? 726 727 RESOLVED: Yes. 728 729 DISCUSSION: The benefits of knowing metadata can't change will 730 probably outweigh the extra cost of checking the 731 TEXTURE_IMMUTABLE_FORMAT_EXT flag on each texture specification 732 call. 733 734 5. Should it be legal to completely replace the texture using a new call 735 to TexStorage*? 736 737 RESOLVED. It will not be allowed. 738 739 DISCUSSION: This is useful to invalidate all levels of a texture. 740 Allowing the metadata to be changed here seems easier than trying to 741 define a portable definition of what it means to change the metadata 742 (e.g. what if you used an unsized internal format the first time and 743 the corresponding sized internal format the second time, or vice 744 versa)? 745 746 However, while this is largely similar to deleting the old texture 747 object and replacing it with a new one, it does lose some of the 748 advantages of immutability. Specifically, because doing so does not 749 reset bindings, it doesn't allow a migration path to an API that 750 validates the texture format at bind time. 751 752 6. Should it be legal to use TexImage* after TexStorage* if it doesn't 753 affect the metadata? 754 755 RESOLVED: No. 756 757 DISCUSSION: A potential use case is to allow a single level of a 758 texture to be invalidated using a NULL pointer. However, as noted 759 above it is non-trivial to determine what constitutes a change. 760 761 7. How does this extension interact with APPLE_texture_2D_limited_npot? 762 763 RESOLVED. APPLE_texture_2D_limited_npot is equivalent to the NPOT 764 support in OpenGL ES 2.0. 765 766 8. Should this extension be written to work with desktop OpenGL? 767 768 RESOLVED: Yes. 769 770 DISCUSSION: There has been been interest and it will future-proof it 771 against further additions to OpenGL ES. 772 773 9. Which texture targets should be supported? 774 775 RESOLVED. All targets except multisample and buffer textures are 776 supported. 777 778 Initially all targets except TEXTURE_BUFFER were supported. It was 779 noted that the entrypoints for multisample targets added no useful 780 functionality, since multisample textures have no completeness 781 checks beyond being non-empty. 782 783 Rectangle textures have completeness checks to prevent filtering of 784 integer textures. However, since we decided to only force mipmap 785 completeness, this becomes less useful. 786 787 10. Should this extension support proxy textures? 788 789 RESOLVED: Yes. 790 791 DISCUSSION: It should be orthogonal. 792 793 11. Are the <format> and <type> parameters necessary? 794 795 RESOLVED. No, they will be removed. 796 797 DISCUSSION: For OpenGL ES the type parameter was necessary to 798 determine the precision of the texture, but this can be solved by 799 having these functions accept sized internal formats (which are 800 already accepted by renderbuffers). 801 802 12. Should it be legal to make the default texture (id 0) 803 immutable-format? 804 805 RESOLVED: No. 806 807 DISCUSSION: This would make it impossible to restore the context to 808 it's default state, which is deemed undesirable. There is no good 809 reason not to use named texture objects. 810 811 13. Should we try to guarantee that textures made through this path 812 will always be complete? 813 814 RESOLVED: It should be guaranteed that the texture will be mipmap 815 complete. 816 817 DISCUSSION: Future separation between images and samplers will still 818 allow users to create combinations that are invalid, but 819 constraining the simple cases will make these APIs easier to use for 820 beginners. 821 822 14. Should these functions use a EXT_direct_state_access approach to 823 specifying the texture objects? 824 825 UNRESOLVED. 826 827 DISCUSSION: as a standalone extension, no DSA-like functions will be 828 added. However, interactions with EXT_direct_state_access and 829 ARB_direct_state_access need to be resolved. 830 831 15. Should these functions accept generic compressed formats? 832 833 RESOLVED: Yes. Note that the spec language will need to be modified 834 to allow this for ES, since the pseudocode is written in terms of 835 TexImage2D, which does not allow compressed texture formats in ES. 836 See also issues 23 and 27. 837 838 16. How should completeness be forced when TEXTURE_MAX_LEVEL is not 839 present? 840 841 RESOLVED. The maximum level q will be redefined to clamp to the 842 highest level available. 843 844 DISCUSSION: A single-level texture can be made complete either by 845 making it mipmap complete (by setting TEXTURE_MAX_LEVEL to 0) or by 846 turning off mipmapping (by choose an appropriate minification 847 filter). 848 849 Some options: 850 851 A: Specify that TexStorage* changes the default minification filter 852 for OpenGL ES. This makes it awkward to add TEXTURE_MAX_LEVEL 853 support to OpenGL ES later, since switching to match GL would break 854 compatibility. The two mechanisms also do not give identical 855 results, since the magnification threshold depends on the 856 minification filter. 857 858 B: Specify that the texture behaves as though TEXTURE_MAX_LEVEL were 859 zero. To specify this properly probably requires fairly intrusive 860 changes to the OpenGL ES full specification to add back all the 861 language relating to the max level. It also does not solve the 862 similar problem of what to do with NPOT textures; and it may have 863 hardware impacts due to the change in the min/mag crossover. 864 865 C: Specify that TexStorage* changes the default minification filter 866 for all implementations when a single-level texture is specified. 867 This may be slightly counter-intuitive to desktop GL users, but will 868 give consistent behaviour across variants of GL and avoids changing 869 the functional behaviour of this extension based on the presence or 870 absence of some other feature. 871 872 Currently B is specified. This has potential hardware implications 873 for OpenGL ES because of the effect of the minification filter on 874 the min/mag crossover. However, C has potential hardware implications 875 for OpenGL due to the separation of texture and sampler state. 876 877 17. How should completeness be forced when only ES2-style NPOT is 878 available? 879 880 RESOLVED. It is not worth trying to do this, in light of issue 13. 881 882 Previous revisions of this extension overrode the minification 883 filter and wrap modes, but that is no longer the case. Since 884 OES_texture_npot removes the caveats on NPOT textures anyway, it 885 might not be worth trying to "fix" this. 886 887 18. For OpenGL ES, how do the new sized internal formats interact 888 with OES_required_internal_format? 889 890 RESOLVED. 891 892 If OES_required_internal_format is not present, then the 893 <internalformat> parameter is intended merely to indicate what the 894 corresponding <format> and <type> would have been, had TexImage* 895 been used instead. If OES_required_internal_format is present, then 896 it is intended that the <internalformat> will be interpreted as if 897 it had been passed directly to TexImage*. 898 899 19. Should there be some hinting mechanism to indicate whether data 900 is coming immediately or later? 901 902 RESOLVED. No parameter is needed. An extension can be added to provide 903 a TexParameter value which is latched at TexStorage time. 904 905 DISCUSSION: Some members felt that this would be useful so that they 906 could defer allocation when suitable, particularly if higher- 907 resolution images will be streamed in later; or to choose a memory 908 type or layout appropriate to the usage. However, implementation 909 experience with BufferData is that developers frequently provide 910 wrong values and implementations have to guess anyway. 911 912 One option suggested was the <usage> parameter currently passed to 913 BufferData. Another option was to set it with TexParameter. 914 915 20. How should this extension interact with 916 EGLImageTargetTexture2DOES, eglBindTexImage, glXBindTexImage and 917 wglBindTexImage? 918 919 RESOLVED. These functions will not be permitted after glTexStorage*. 920 921 Several options are possible: 922 923 A) Disallow these functions. 924 B) Allow them, but have them reset the TEXTURE_IMMUTABLE_FORMAT_EXT 925 flag. 926 C) Allow them unconditionally. 927 928 C would violate the design principle that the dimensions and format 929 of the mipmap array are immutable. B does not so much modify the 930 dimension and formats as replace them with an entirely different 931 set. 932 933 21. Should there be a single function for specifying 1D, 2D and 3D 934 targets? 935 936 RESOLVED. No, we will stick with existing precedent. 937 938 22. Is it possible to use GenerateMipmap with an incomplete mipmap 939 pyramid? 940 941 RESOLVED. Yes, because the effective max level is limited to the 942 levels that were specified, and so GenerateMipmap does not generate 943 any new levels. 944 945 However, to make automatic mipmap generation work, it is necessary 946 to redefine p rather than q, since automatic mipmap generation 947 ignores the max level. 948 949 23. How should this extension interact with 950 OES_compressed_paletted_texture? 951 952 RESOLVED. Paletted textures will not be permitted, and will 953 generate INVALID_ENUM. 954 955 DISCUSSION: OES_compressed_paletted_texture supplies all the mipmaps 956 in a single function call, with the palette specified once. That's 957 incompatible with the upload model in this extension. 958 959 24. How can ETC1 textures be used with this extension? 960 961 RESOLVED. Add language in this extension to allow subregion uploads 962 for ETC1. 963 964 DISCUSSION: GL_OES_compressed_ETC1_RGB8_texture doesn't allow 965 CompressedTexSubImage*, so it would be impossible to use this 966 extension with ETC1. This is seen as an oversight in the ETC1 967 extension. While it cannot be fixed in that extension (since it is 968 already shipping), this extension can add that capability. 969 970 25. Should any other compressed formats be similarly modified? 971 972 RESOLVED. Yes, AMD_compressed_ATC_texture and 973 AMD_compressed_3DC_texture can be modified similarly to ETC1 974 (Maurice Ribble indicated that both formats use 4x4 blocks). Desktop 975 OpenGL requires that whole-image replacement is supported for any 976 compressed texture format, and the OpenGL ES extensions 977 EXT_texture_compression_dxt1 and IMG_texture_compression_pvrtc 978 already allow whole-image replacement, so it is not necessary to 979 modify them to be used with this extension. 980 981 26. Should these commands be permitted in display lists? 982 983 RESOLVED. No. 984 985 DISCUSSION: Display lists are most useful for repeating commands, 986 and TexStorage* commands cannot be repeated because the first call 987 makes the format immutable. 988 989 27. Should these commands accept unsized internal formats? 990 991 RESOLVED: No, for both OpenGL and OpenGL ES. 992 993 DISCUSSION: normally the <type> parameter to TexImage* can serve as 994 a hint to select a sized format (and in OpenGL ES, this is the only 995 mechanism available); since TexStorage* does not have a <type> 996 parameter, the implementation has no information on which to base a 997 decision. 998 999Revision History 1000 1001 Revision 28, 2013/09/18 (Benj Lipchak) 1002 - Add interaction with APPLE_texture_format_BGRA8888. 1003 - Fix interaction with APPLE_rgb_422. 1004 1005 Revision 27, 2012/07/24 (Benj Lipchak) 1006 - Add interaction with APPLE_rgb_422. 1007 1008 Revision 26, 2012/02/29 (Benj Lipchak) 1009 - Add interaction with EXT_texture_rg. 1010 1011 Revision 25, 2012/01/19 (bmerry) 1012 - Clarify that the pixel unpack buffer has no effect. 1013 1014 Revision 24, 2011/11/11 (dgkoch) 1015 - Mark complete. Clarify ES clarifications. 1016 1017 Revision 23, 2011/11/10 (dgkoch) 1018 - Add GLES clarifcations and interactions with more GLES extensions 1019 1020 Revision 22, 2011/11/10 (bmerry) 1021 - Update my contact details 1022 1023 Revision 21, 2011/07/25 (bmerry) 1024 - Remove dangling references to MultiTexStorage in Errors section 1025 1026 Revision 20, 2011/07/21 (bmerry) 1027 - Remove dangling reference to <samples> in Errors section 1028 1029 Revision 19, 2011/05/02 (Jon Leech) 1030 - Assign enum value 1031 1032 Revision 18, 2011/01/24 (bmerry) 1033 - Disallow unsized internal formats (oversight in revision 17). 1034 1035 Revision 17, 2011/01/24 (bmerry) 1036 - Added and resolved issue 26. 1037 - Split issue 27 out from issue 15. 1038 - Disallow TexStorage* in display lists. 1039 - Use the term "immutable-format" consistently (bug 7281). 1040 1041 Revision 16, 2010/11/23 (bmerry) 1042 - Disallowed TexStorage on an immutable-format texture 1043 (resolves issue 5). 1044 - Deleted MultiTexStorage* commands (other DSA functions still 1045 unresolved). 1046 - Some minor wording changes suggested by Pat Brown (bug 7002). 1047 1048 Revision 15, 2010/11/09 (bmerry) 1049 - Reopened issue 5. 1050 - Reopened issue 14, pending stabilisation of 1051 ARB_direct_state_access. 1052 - Marked issue 9 resolved, pending any objections. 1053 - Fix references to no object being bound (was meant to refer to 1054 the default object). 1055 - Adding missing pseudocode for TEXTURE_1D_ARRAY. 1056 - Corrected TEXTURE_2D_ARRAY -> TEXTURE_1D_ARRAY in error checks. 1057 - Changed "levels... are removed" to "levels... are reset to their 1058 init state", since desktop GL has per-level state apart from the 1059 texels. 1060 - Miscellaneous wording fixes. 1061 1062 Revision 14, 2010/09/25 (bmerry) 1063 - Add issues 24-25 and alterations to 1064 OES_compressed_ETC1_RGB8_texture, AMD_compressed_ATC_texture and 1065 AMD_compressed_3DC_texture. 1066 1067 Revision 13, 2010/09/19 (bmerry) 1068 - Two typo fixes from Daniel Koch 1069 1070 Revision 12, 2010/09/18 (bmerry) 1071 - Changed resolution to issue 20 1072 - Added and resolved issue 23 1073 - Added explanation of how to upload data (in overview) 1074 - Added spec language to implement resolution to issue 15 1075 1076 Revision 11, 2010/07/21 (bmerry) 1077 - Resolved issue 16 1078 - Reopen issue 20 1079 - Fix some typos 1080 1081 Revision 10, 2010/07/15 (bmerry) 1082 - Update some issues to match core text 1083 - Resolved issue 17 1084 1085 Revision 9, 2010/05/24 (bmerry) 1086 - Marked issue 2 as resolved 1087 - Resolved issue 19 (as no change) 1088 - Resolved issue 20 1089 - Add issues 21-22 1090 - Add in spec language to forbid use on default textures 1091 - Redefine level_base, level_max to be clamped forms of 1092 TEXTURE_BASE_LEVEL/TEXTURE_MAX_LEVEL when using immutable 1093 textures 1094 - Redefine p to also be clamped to the provided levels for 1095 immutable textures, to support automatic mipmap generation 1096 - Removed multisample functions 1097 - Removed language stating that texture parameters were reset to 1098 defaults 1099 1100 Revision 8, 2010/05/18 (bmerry) 1101 - Added issue about EGLimage 1102 - Marked issue 14 as resolved 1103 1104 Revision 7, 2010/05/04 (bmerry) 1105 - Removed some lingering <format>, <type> parameters to the new 1106 functions that should have been removed in revision 4 1107 - Trivial typo fixes 1108 1109 Revision 6, 2010/02/18 (bmerry) 1110 - Resolved issues 5, 6 and 18 1111 - Added MultiTexStorage* functions for DSA interaction 1112 - Added error for texture-target mismatch in DSA 1113 - Allowed TexStorage* to be called again 1114 1115 Revision 5, 2010/01/25 (bmerry) 1116 - Added to contributors list 1117 - Require OpenGL 1.2, to simplify interactions with 1118 TEXTURE_BASE_LEVEL/TEXTURE_MAX_LEVEL and CLAMP_TO_EDGE 1119 - Change default wrap modes to always be CLAMP_TO_EDGE 1120 - Change default filters to always be NEAREST 1121 - Moved language about generating new levels into an interaction, 1122 since it can only happen on OpenGL ES 1123 - Added interaction with EXT_direct_state_access 1124 - Added extra <internalformats> for GL ES when OES_depth_texture, 1125 OES_packed_depth_stencil and EXT_texture_type_2_10_10_10_REV are 1126 present. 1127 - Minor non-functional wording fixes and typos 1128 - Resolved issue 16 1129 - Added issues 17-19 1130 1131 Revision 4, 2010/01/13 (bmerry) 1132 - Changed suffix from ARM to EXT 1133 - Added list of contributors 1134 - Added language to force the texture to always be complete 1135 - Removed <format> and <type> arguments 1136 - Added issues 14-16 1137 - Reopened issue 2 1138 - Reformatted issues to separate resolution and discussion 1139 - Resolved issues 1, 9 and 11-13 1140 - Fixed the max number of levels in a cube map array 1141 1142 Revision 3, 2009/12/17 (bmerry) 1143 - Added missing vendor suffix to TEXTURE_IMMUTABLE_FORMAT_ARM 1144 - Rewritten to against desktop OpenGL 1145 - Added prototypes for 1D and multisample storage functions 1146 - Added issues 8-13 1147 1148 Revision 2, 2009/08/20 (bmerry) 1149 - Resolved issue 2 (no border parameter) 1150 - Resolved issue 4 (metadata becomes immutable) 1151 - Added interaction with OES_texture_cube_map 1152 - Added error if width != height in a cube map 1153 - Added issues 5-7 1154 1155 Revision 1, 2009/05/06 (bmerry) 1156 - First draft 1157