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