michael@0: Name michael@0: michael@0: EXT_texture_storage michael@0: michael@0: Name Strings michael@0: michael@0: GL_EXT_texture_storage michael@0: michael@0: Contact michael@0: michael@0: Bruce Merry (bmerry 'at' gmail.com) michael@0: Ian Romanick, Intel (ian.d.romanick 'at' intel.com) michael@0: michael@0: Contributors michael@0: michael@0: Jeremy Sandmel, Apple michael@0: Bruce Merry, ARM michael@0: Tom Olson, ARM michael@0: Benji Bowman, Imagination Technologies michael@0: Ian Romanick, Intel michael@0: Jeff Bolz, NVIDIA michael@0: Pat Brown, NVIDIA michael@0: Maurice Ribble, Qualcomm michael@0: Lingjun Chen, Qualcomm michael@0: Daniel Koch, Transgaming Inc michael@0: michael@0: Status michael@0: michael@0: Complete. michael@0: michael@0: Version michael@0: michael@0: Last Modified Date: November 11, 2011 michael@0: Author Revision: 24 michael@0: michael@0: Number michael@0: michael@0: OpenGL ES Extension #108 michael@0: michael@0: Dependencies michael@0: michael@0: OpenGL ES 1.0, OpenGL ES 2.0 or OpenGL 1.2 is required. michael@0: michael@0: OES_texture_npot, OES_texture_cube_map, OES_texture_3D, michael@0: OES_depth_texture, OES_packed_depth_stencil, michael@0: OES_compressed_paletted_texture, OES_texture_float, OES_texture_half_float michael@0: EXT_texture_type_2_10_10_10_REV, EXT_texture_format_BGRA8888, michael@0: EXT_texture3D, OES_texture_npot, APPLE_texture_2D_limited_npot, michael@0: ARB_texture_cube_map, ARB_texture_cube_map_array, michael@0: ARB_texture_rectangle, SGIS_generate_mipmap, michael@0: EXT_direct_state_access, OES_EGL_image, WGL_ARB_render_texture, michael@0: GLX_EXT_texture_from_pixmap, and core specifications that michael@0: incorporate these extensions affect the definition of this michael@0: extension. michael@0: michael@0: This extension is written against the OpenGL 3.2 Core Profile michael@0: specification. michael@0: michael@0: Overview michael@0: michael@0: The texture image specification commands in OpenGL allow each level michael@0: to be separately specified with different sizes, formats, types and michael@0: so on, and only imposes consistency checks at draw time. This adds michael@0: overhead for implementations. michael@0: michael@0: This extension provides a mechanism for specifying the entire michael@0: structure of a texture in a single call, allowing certain michael@0: consistency checks and memory allocations to be done up front. Once michael@0: specified, the format and dimensions of the image array become michael@0: immutable, to simplify completeness checks in the implementation. michael@0: michael@0: When using this extension, it is no longer possible to supply texture michael@0: data using TexImage*. Instead, data can be uploaded using TexSubImage*, michael@0: or produced by other means (such as render-to-texture, mipmap generation, michael@0: or rendering to a sibling EGLImage). michael@0: michael@0: This extension has complicated interactions with other extensions. michael@0: The goal of most of these interactions is to ensure that a texture michael@0: is always mipmap complete (and cube complete for cubemap textures). michael@0: michael@0: IP Status michael@0: michael@0: No known IP claims michael@0: michael@0: New Procedures and Functions michael@0: michael@0: void TexStorage1DEXT(enum target, sizei levels, michael@0: enum internalformat, michael@0: sizei width); michael@0: michael@0: void TexStorage2DEXT(enum target, sizei levels, michael@0: enum internalformat, michael@0: sizei width, sizei height); michael@0: michael@0: void TexStorage3DEXT(enum target, sizei levels, michael@0: enum internalformat, michael@0: sizei width, sizei height, sizei depth); michael@0: michael@0: void TextureStorage1DEXT(uint texture, enum target, sizei levels, michael@0: enum internalformat, michael@0: sizei width); michael@0: michael@0: void TextureStorage2DEXT(uint texture, enum target, sizei levels, michael@0: enum internalformat, michael@0: sizei width, sizei height); michael@0: michael@0: void TextureStorage3DEXT(uint texture, enum target, sizei levels, michael@0: enum internalformat, michael@0: sizei width, sizei height, sizei depth); michael@0: michael@0: New Types michael@0: michael@0: None michael@0: michael@0: New Tokens michael@0: michael@0: Accepted by the parameter of GetTexParameter{if}v: michael@0: michael@0: TEXTURE_IMMUTABLE_FORMAT_EXT 0x912F michael@0: michael@0: Accepted by the parameter of TexStorage* when michael@0: implemented on OpenGL ES: michael@0: michael@0: ALPHA8_EXT 0x803C /* reuse tokens from EXT_texture */ michael@0: LUMINANCE8_EXT 0x8040 michael@0: LUMINANCE8_ALPHA8_EXT 0x8045 michael@0: michael@0: (if OES_texture_float is supported) michael@0: RGBA32F_EXT 0x8814 /* reuse tokens from ARB_texture_float */ michael@0: RGB32F_EXT 0x8815 michael@0: ALPHA32F_EXT 0x8816 michael@0: LUMINANCE32F_EXT 0x8818 michael@0: LUMINANCE_ALPHA32F_EXT 0x8819 michael@0: michael@0: (if OES_texture_half_float is supported) michael@0: RGBA16F_EXT 0x881A /* reuse tokens from ARB_texture_float */ michael@0: RGB16F_EXT 0x881B michael@0: ALPHA16F_EXT 0x881C michael@0: LUMINANCE16F_EXT 0x881E michael@0: LUMINANCE_ALPHA16F_EXT 0x881F michael@0: michael@0: (if EXT_texture_type_2_10_10_10_REV is supported) michael@0: RGB10_A2_EXT 0x8059 /* reuse tokens from EXT_texture */ michael@0: RGB10_EXT 0x8052 michael@0: michael@0: (if EXT_texture_format_BGRA8888 is supported) michael@0: BGRA8_EXT 0x93A1 michael@0: michael@0: michael@0: Additions to Chapter 2 of the OpenGL 3.2 Core Profile Specification michael@0: (OpenGL Operation) michael@0: michael@0: None michael@0: michael@0: Additions to Chapter 3 of the OpenGL 3.2 Core Profile Specification michael@0: (Rasterization) michael@0: michael@0: After section 3.8.1 (Texture Image Specification) add a new michael@0: subsection called "Immutable-format texture images": michael@0: michael@0: "An alterative set of commands is provided for specifying the michael@0: properties of all levels of a texture at once. Once a texture is michael@0: specified with such a command, the format and dimensions of all michael@0: levels becomes immutable, unless it is a proxy texture (since michael@0: otherwise it would no longer be possible to use the proxy). The michael@0: contents of the images and the parameters can still be modified. michael@0: Such a texture is referred to as an "immutable-format" texture. The michael@0: immutability status of a texture can be determined by calling michael@0: GetTexParameter with TEXTURE_IMMUTABLE_FORMAT_EXT. michael@0: michael@0: Each of the commands below is described by pseudo-code which michael@0: indicates the effect on the dimensions and format of the texture. michael@0: For all of the commands, the following apply in addition to the michael@0: pseudo-code: michael@0: michael@0: - If the default texture object is bound to , an michael@0: INVALID_OPERATION error is generated. michael@0: - If executing the pseudo-code would lead to an error, the error is michael@0: generated and the command will have no effect. michael@0: - Any existing levels that are not replaced are reset to their michael@0: initial state. michael@0: - If , , or is less than 1, the michael@0: error INVALID_VALUE is generated. michael@0: - Since no pixel data are provided, the and values michael@0: used in the pseudo-code are irrelevant; they can be considered to michael@0: be any values that are legal to use with . michael@0: - If the command is successful, TEXTURE_IMMUTABLE_FORMAT_EXT becomes michael@0: TRUE. michael@0: - If is a specific compressed texture format, then michael@0: references to TexImage* should be replaced by CompressedTexImage*, michael@0: with , and replaced by any valid and michael@0: . If there is no for which this command would have michael@0: been valid, an INVALID_OPERATION error is generated [fn: This michael@0: condition is not required for OpenGL, but is necessary for OpenGL michael@0: ES which does not support on-the-fly compression.] michael@0: - If is one of the internal formats listed in table michael@0: 3.11, an INVALID_ENUM error is generated. [fn: The corresponding table michael@0: in OpenGL ES 2.0 is table 3.8.] michael@0: michael@0: The command michael@0: michael@0: void TexStorage1DEXT(enum target, sizei levels, michael@0: enum internalformat, michael@0: sizei width); michael@0: michael@0: specifies all the levels of a one-dimensional texture (or proxy) at michael@0: the same time. It is described by the pseudo-code below: michael@0: michael@0: for (i = 0; i < levels; i++) michael@0: { michael@0: TexImage1D(target, i, internalformat, width, 0, michael@0: format, type, NULL); michael@0: width = max(1, floor(width / 2)); michael@0: } michael@0: michael@0: If is not TEXTURE_1D or PROXY_TEXTURE_1D then INVALID_ENUM michael@0: is generated. If is greater than floor(log_2(width)) + 1 michael@0: then INVALID_OPERATION is generated. michael@0: michael@0: The command michael@0: michael@0: void TexStorage2DEXT(enum target, sizei levels, michael@0: enum internalformat, michael@0: sizei width, sizei height); michael@0: michael@0: specifies all the levels of a two-dimensional, cube-map, michael@0: one-dimension array or rectangle texture (or proxy) at the same michael@0: time. The pseudo-code depends on the : michael@0: michael@0: [PROXY_]TEXTURE_2D, [PROXY_]TEXTURE_RECTANGLE or michael@0: PROXY_TEXTURE_CUBE_MAP: michael@0: michael@0: for (i = 0; i < levels; i++) michael@0: { michael@0: TexImage2D(target, i, internalformat, width, height, 0, michael@0: format, type, NULL); michael@0: width = max(1, floor(width / 2)); michael@0: height = max(1, floor(height / 2)); michael@0: } michael@0: michael@0: TEXTURE_CUBE_MAP: michael@0: michael@0: for (i = 0; i < levels; i++) michael@0: { michael@0: for face in (+X, -X, +Y, -Y, +Z, -Z) michael@0: { michael@0: TexImage2D(face, i, internalformat, width, height, 0, michael@0: format, type, NULL); michael@0: } michael@0: width = max(1, floor(width / 2)); michael@0: height = max(1, floor(height / 2)); michael@0: } michael@0: michael@0: [PROXY_]TEXTURE_1D_ARRAY: michael@0: michael@0: for (i = 0; i < levels; i++) michael@0: { michael@0: TexImage2D(target, i, internalformat, width, height, 0, michael@0: format, type, NULL); michael@0: width = max(1, floor(width / 2)); michael@0: } michael@0: michael@0: If is not one of those listed above, the error INVALID_ENUM michael@0: is generated. michael@0: michael@0: The error INVALID_OPERATION is generated if any of the following michael@0: conditions hold: michael@0: - is [PROXY_]TEXTURE_1D_ARRAY and is greater than michael@0: floor(log_2(width)) + 1 michael@0: - is not [PROXY_]TEXTURE_1D_ARRAY and is greater michael@0: than floor(log_2(max(width, height))) + 1 michael@0: michael@0: The command michael@0: michael@0: void TexStorage3DEXT(enum target, sizei levels, enum internalformat, michael@0: sizei width, sizei height, sizei depth); michael@0: michael@0: specifies all the levels of a three-dimensional, two-dimensional michael@0: array texture, or cube-map array texture (or proxy). The pseudo-code michael@0: depends on : michael@0: michael@0: [PROXY_]TEXTURE_3D: michael@0: michael@0: for (i = 0; i < levels; i++) michael@0: { michael@0: TexImage3D(target, i, internalformat, width, height, depth, 0, michael@0: format, type, NULL); michael@0: width = max(1, floor(width / 2)); michael@0: height = max(1, floor(height / 2)); michael@0: depth = max(1, floor(depth / 2)); michael@0: } michael@0: michael@0: [PROXY_]TEXTURE_2D_ARRAY, [PROXY_]TEXTURE_CUBE_MAP_ARRAY_ARB: michael@0: michael@0: for (i = 0; i < levels; i++) michael@0: { michael@0: TexImage3D(target, i, internalformat, width, height, depth, 0, michael@0: format, type, NULL); michael@0: width = max(1, floor(width / 2)); michael@0: height = max(1, floor(height / 2)); michael@0: } michael@0: michael@0: If is not one of those listed above, the error INVALID_ENUM michael@0: is generated. michael@0: michael@0: The error INVALID_OPERATION is generated if any of the following michael@0: conditions hold: michael@0: - is [PROXY_]TEXTURE_3D and is greater than michael@0: floor(log_2(max(width, height, depth))) + 1 michael@0: - is [PROXY_]TEXTURE_2D_ARRAY or michael@0: [PROXY_]TEXTURE_CUBE_MAP_ARRAY_EXT and is greater than michael@0: floor(log_2(max(width, height))) + 1 michael@0: michael@0: After a successful call to any TexStorage* command with a non-proxy michael@0: target, the value of TEXTURE_IMMUTABLE_FORMAT_EXT for this texture michael@0: object is set to TRUE, and no further changes to the dimensions or michael@0: format of the texture object may be made. Other commands may only michael@0: alter the texel values and texture parameters. Using any of the michael@0: following commands with the same texture will result in the error michael@0: INVALID_OPERATION being generated, even if it does not affect the michael@0: dimensions or format: michael@0: michael@0: - TexImage* michael@0: - CompressedTexImage* michael@0: - CopyTexImage* michael@0: - TexStorage* michael@0: michael@0: The TextureStorage* commands operate identically to the michael@0: corresponding command where "Texture" is substituted for "Tex" michael@0: except, rather than updating the current bound texture for the michael@0: texture unit indicated by the current active texture state and the michael@0: target parameter, these "Texture" commands update the texture object michael@0: named by the initial texture parameter. The error INVALID_VALUE michael@0: is generated if is zero. michael@0: " michael@0: michael@0: In section 3.8.6 (Texture Parameters), after the sentence michael@0: michael@0: "In the remainder of section 3.8, denote by lod_min, lod_max, michael@0: level_base, and level_max the values of the texture parameters michael@0: TEXTURE_MIN_LOD, TEXTURE_MAX_LOD, TEXTURE_BASE_LEVEL, and michael@0: TEXTURE_MAX_LEVEL respectively." michael@0: michael@0: add michael@0: michael@0: "However, if TEXTURE_IMMUTABLE_FORMAT_EXT is michael@0: TRUE, then level_base is clamped to the range [0, - 1] and michael@0: level_max is then clamped to the range [level_base, - 1], michael@0: where is the parameter passed the call to TexStorage* for michael@0: the texture object. michael@0: michael@0: In section 3.8.9 (Rendering feedback loops) replace all references michael@0: to TEXTURE_BASE_LEVEL by level_base. michael@0: michael@0: In section 3.8.9 (Mipmapping), replace the paragraph starting "Each michael@0: array in a mipmap is defined..." by michael@0: michael@0: "Each array in a mipmap is defined using TexImage3D, TexImage2D, michael@0: CopyTexImage2D, TexImage1D, CopyTexImage1D, or by functions that are michael@0: defined in terms of these functions. Level-of-detail numbers proceed michael@0: from level_base for the original texel array through the maximum michael@0: level p, with each unit increase indicating an array of half the michael@0: dimensions of the previous one (rounded down to the next integer if michael@0: fractional) as already described. For immutable-format textures, michael@0: p is one less than the parameter passed to TexStorage*; michael@0: otherwise p = floor(log_2(maxsize)) + level_base. All arrays from michael@0: level_base through q = min(p, level_max) must be defined, as michael@0: discussed in section 3.8.12." michael@0: michael@0: In section 3.8.12 (Texture Completeness), modify the last sentence michael@0: to avoid refering to level_base and level_max: michael@0: michael@0: "An implementation may allow a texture image array of level 1 or michael@0: greater to be created only if a mipmap complete set of image arrays michael@0: consistent with the requested array can be supported where the michael@0: values of TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL are 0 and 1000 michael@0: respectively." michael@0: michael@0: Modify section 3.8.13 (Texture State and Proxy State) to add the new michael@0: state: michael@0: michael@0: "Each set consists of ..., and a boolean flag indicating whether the michael@0: format and dimensions of the texture are immutable." michael@0: michael@0: Add michael@0: "The initial value of TEXTURE_IMMUTABLE_FORMAT_EXT is FALSE." michael@0: michael@0: Additions to Chapter 4 of the OpenGL 3.2 Core Profile Specification michael@0: (Per-Fragment Operations and the Frame Buffer) michael@0: michael@0: None michael@0: michael@0: Additions to Chapter 5 of the OpenGL 3.2 Compatibility Profile Specification michael@0: (Special Functions) michael@0: michael@0: In section 5.4.1 (Commands Not Usable in Display Lists), add michael@0: TexStorage* to the list of commands that cannot be used. michael@0: michael@0: Additions to Chapter 6 of the OpenGL 3.2 Core Profile Specification michael@0: (State and State Requests) michael@0: michael@0: Replace the following statement in 6.1.3 (Enumerated Queries): michael@0: michael@0: " must be one of the symbolic values in table 3.10." michael@0: michael@0: with michael@0: michael@0: " must be TEXTURE_IMMUTABLE_FORMAT_EXT or one of the symbolic michael@0: values in table 3.22." michael@0: michael@0: Additions to the AGL/EGL/GLX/WGL Specifications michael@0: michael@0: None michael@0: michael@0: Additions to OES_compressed_ETC1_RGB8_texture michael@0: michael@0: Add the following to the additions to Chapter 3: michael@0: michael@0: "Since ETC1 images are easily edited along 4x4 texel boundaries, the michael@0: limitations on CompressedTexSubImage2D are relaxed. michael@0: CompressedTexSubImage2D will result in an INVALID_OPERATION error michael@0: only if one of the following conditions occurs: michael@0: michael@0: * is not a multiple of four, and plus is not michael@0: equal to the texture width; michael@0: michael@0: * is not a multiple of four, and plus is michael@0: not equal to the texture height; or michael@0: michael@0: * or is not a multiple of four. michael@0: michael@0: Remove CompressedTexSubImage2D from this error: michael@0: michael@0: "INVALID_OPERATION is generated by CompressedTexSubImage2D, michael@0: TexSubImage2D, or CopyTexSubImage2D if the texture image michael@0: bound to has internal format ETC1_RGB8_OES." michael@0: michael@0: Add the following error: michael@0: michael@0: "INVALID_OPERATION is generated by CompressedTexSubImage2D michael@0: if the region to be modified is not aligned to block boundaries michael@0: (refer to the extension text for details)." michael@0: michael@0: Additions to AMD_compressed_ATC_texture and AMD_compressed_3DC_texture: michael@0: michael@0: Apply the same changes as for OES_compressed_ETC1_RGB8_texture michael@0: above, substituting the appropriate internal format tokens from michael@0: these extensions. michael@0: michael@0: Dependencies on EXT_direct_state_access michael@0: michael@0: If EXT_direct_state_access is not present, references to michael@0: TextureStorage* should be ignored. michael@0: michael@0: Dependencies on OpenGL ES michael@0: michael@0: On OpenGL ES without extensions introducing TEXTURE_MAX_LEVEL, michael@0: mipmapped textures specified with TexStorage are required to have a michael@0: full set of mipmaps. If TEXTURE_MAX_LEVEL is not supported, this michael@0: extension is modified as follows: michael@0: michael@0: - Where an upper bound is placed on in this extension (i.e. michael@0: the maximum number of mipmap levels for a texture of the given michael@0: target and dimensions), an INVALID_OPERATION error is generated if michael@0: is neither 1 nor this upper bound. michael@0: - q (the effective maximum number of levels) is redefined to clamp michael@0: to the number of levels present in immutable-format textures. michael@0: michael@0: OpenGL ES does not accept sized internal formats (e.g., RGBA8) and michael@0: instead derives an internal format from the and michael@0: parameters of TexImage2D. Since TexStorage* does not specify texel michael@0: data, the API doesn't include and parameters. michael@0: On an OpenGL ES implementation, the values in the michael@0: column in the tables below are accepted as michael@0: parameters, and base internal formats are not accepted. The michael@0: TexImage* calls in the TexStorage* pseudocode are modified so that michael@0: the , and parameters are michael@0: taken from the , and columns (respectively) michael@0: in the tables below, according to the michael@0: specified in the TexStorage* command. michael@0: michael@0: michael@0: ---------------- -------- ------ michael@0: RGB565 RGB UNSIGNED_SHORT_5_6_5 michael@0: RGBA4 RGBA UNSIGNED_SHORT_4_4_4_4 michael@0: RGB5_A1 RGBA UNSIGNED_SHORT_5_5_5_1 michael@0: RGB8_OES RGB UNSIGNED_BYTE michael@0: RGBA8_OES RGBA UNSIGNED_BYTE michael@0: LUMINANCE8_ALPHA8_EXT LUMINANCE_ALPHA UNSIGNED_BYTE michael@0: LUMINANCE8_EXT LUMINANCE UNSIGNED_BYTE michael@0: ALPHA8_EXT ALPHA UNSIGNED_BYTE michael@0: michael@0: If OES_depth_texture is supported: michael@0: michael@0: michael@0: ---------------- -------- ------ michael@0: DEPTH_COMPONENT16_OES DEPTH_COMPONENT UNSIGNED_SHORT michael@0: DEPTH_COMPONENT32_OES DEPTH_COMPONENT UNSIGNED_INT michael@0: michael@0: If OES_packed_depth_stencil is supported: michael@0: michael@0: michael@0: ---------------- -------- ------ michael@0: DEPTH24_STENCIL8_OES DEPTH_STENCIL_OES UNSIGNED_INT michael@0: michael@0: If OES_texture_float is supported: michael@0: michael@0: michael@0: ---------------- -------- ------ michael@0: RGBA32F_EXT RGBA FLOAT michael@0: RGB32F_EXT RGB FLOAT michael@0: LUMINANCE_ALPHA32F_EXT LUMINANCE_ALPHA FLOAT michael@0: LUMINANCE32F_EXT LUMINANCE FLOAT michael@0: ALPHA32F_EXT ALPHA FLOAT michael@0: michael@0: If OES_texture_half_float is supported: michael@0: michael@0: michael@0: ---------------- -------- ------ michael@0: RGBA16F_EXT RGBA HALF_FLOAT_OES michael@0: RGB16F_EXT RGB HALF_FLOAT_OES michael@0: LUMINANCE_ALPHA16F_EXT LUMINANCE_ALPHA HALF_FLOAT_OES michael@0: LUMINANCE16F_EXT LUMINANCE HALF_FLOAT_OES michael@0: ALPHA16F_EXT ALPHA HALF_FLOAT_OES michael@0: michael@0: If EXT_texture_type_2_10_10_10_REV is supported: michael@0: michael@0: michael@0: ---------------- -------- ------ michael@0: RGB10_A2_EXT RGBA UNSIGNED_INT_2_10_10_10_REV_EXT michael@0: RGB10_EXT RGB UNSIGNED_INT_2_10_10_10_REV_EXT michael@0: michael@0: If EXT_texture_format_BGRA8888 is supported: michael@0: michael@0: michael@0: ---------------- -------- ------ michael@0: BGRA8_EXT BGRA_EXT UNSIGNED_BYTE michael@0: michael@0: michael@0: Dependencies on texture targets michael@0: michael@0: If a particular texture target is not supported by the michael@0: implementation, passing it as a to TexStorage* will michael@0: generate an INVALID_ENUM error. If as a result, any of the commands michael@0: defined in this extension would no longer have any valid , michael@0: all references to the command should be ignored. michael@0: michael@0: In particular, note that OpenGL ES 1.x/2.0 do not have proxy textures, michael@0: 1D textures, or 3D textures, and thus only the TexStorage2DEXT michael@0: entry point is required. If OES_texture_3D is supported, the michael@0: TexStorage3DEXT entry point is also required. michael@0: michael@0: Dependencies on OES_texture_npot michael@0: michael@0: If OpenGL ES 2.0 or APPLE_texture_2D_limited_npot is present but michael@0: OES_texture_npot is not present, then INVALID_OPERATION is michael@0: generated by TexStorage* and TexStorage3DEXT if is michael@0: not one and , or is not a power of michael@0: two. michael@0: michael@0: Dependencies on WGL_ARB_render_texture, GLX_EXT_texture_from_pixmap, EGL michael@0: 1.4 and GL_OES_EGL_image michael@0: michael@0: The commands eglBindTexImage, wglBindTexImageARB, glXBindTexImageEXT or michael@0: EGLImageTargetTexture2DOES are not permitted on an immutable-format michael@0: texture. michael@0: They will generate the following errors: michael@0: - EGLImageTargetTexture2DOES: INVALID_OPERATION michael@0: - eglBindTexImage: EGL_BAD_MATCH michael@0: - wglBindTexImage: ERROR_INVALID_OPERATION michael@0: - glXBindTexImageEXT: BadMatch michael@0: michael@0: Dependencies on OES_compressed_paletted_texture michael@0: michael@0: The compressed texture formats exposed by michael@0: OES_compressed_paletted_texture are not supported by TexStorage*. michael@0: Passing one of these tokens to TexStorage* will generate an michael@0: INVALID_ENUM error. michael@0: michael@0: Errors michael@0: michael@0: Note that dependencies above modify the errors. michael@0: michael@0: If TexStorage* is called with a , , or michael@0: parameter that is less than one, then the error michael@0: INVALID_VALUE is generated. michael@0: michael@0: If the parameter to TexStorage1DEXT is not michael@0: [PROXY_]TEXTURE_1D, then the error INVALID_ENUM is generated. michael@0: michael@0: If the parameter to TexStorage2DEXT is not michael@0: [PROXY_]TEXTURE_2D, [PROXY_]TEXTURE_CUBE_MAP, michael@0: [PROXY_]TEXTURE_RECTANGLE or [PROXY_]TEXTURE_1D_ARRAY, then the michael@0: error INVALID_ENUM is generated. michael@0: michael@0: If the parameter to TexStorage3DEXT is not michael@0: [PROXY_]TEXTURE_3D, [PROXY_]TEXTURE_2D_ARRAY or michael@0: [PROXY_]TEXTURE_CUBE_MAP_ARRAY then the error INVALID_ENUM is michael@0: generated. michael@0: michael@0: If the parameter to TexStorage* is greater than the michael@0: -specific value listed below then the error michael@0: INVALID_OPERATION is generated: michael@0: [PROXY_]TEXTURE_{1D,1D_ARRAY}: michael@0: floor(log_2(width)) + 1 michael@0: [PROXY_]TEXTURE_{2D,2D_ARRAY,CUBE_MAP,CUBE_MAP_ARRAY}: michael@0: floor(log_2(max(width, height))) + 1 michael@0: [PROXY_]TEXTURE_3D: michael@0: floor(log_2(max(width, height, depth))) + 1 michael@0: [PROXY_]TEXTURE_RECTANGLE: michael@0: 1 michael@0: michael@0: If the default texture object is bound to the passed to michael@0: TexStorage*, then the error INVALID_OPERATION is generated. michael@0: michael@0: If the parameter to TextureStorage* does not match the michael@0: dimensionality of , then the error INVALID_OPERATION is michael@0: generated. michael@0: michael@0: If the parameter to TextureStorage* is zero, then the michael@0: INVALID_VALUE is generated. michael@0: michael@0: If any pseudo-code listed in this extension would generate an error, michael@0: then that error is generated. michael@0: michael@0: Calling any of the following functions on a texture for which michael@0: TEXTURE_IMMUTABLE_FORMAT_EXT is TRUE will generate an michael@0: INVALID_OPERATION error: michael@0: - TexImage* michael@0: - CompressedTexImage* michael@0: - CopyTexImage* michael@0: michael@0: New State michael@0: michael@0: Additions to Table 6.8 Textures (state per texture object) michael@0: michael@0: Initial michael@0: Get Value Type Get Command Value Description Sec. michael@0: --------- ---- ----------- ------- ----------- ---- michael@0: TEXTURE_IMMUTABLE_FORMAT_EXT B GetTexParameter FALSE Size and format immutable 2.6 michael@0: michael@0: New Implementation Dependent State michael@0: michael@0: None michael@0: michael@0: Issues michael@0: michael@0: 1. What should this extension be called? michael@0: michael@0: RESOLVED: EXT_texture_storage is chosen for consistency with the michael@0: glRenderbufferStorage entry point. michael@0: michael@0: 2. Should TexStorage* accept a border parameter? michael@0: michael@0: RESOLVED: no. michael@0: michael@0: DISCUSSION: Currently it does not, since borders are a deprecated michael@0: feature which is not supported by all hardware. Users of the michael@0: compatibility profile can continue to use the existing texture michael@0: specification functions, but there is an argument that users of michael@0: compatibility profile may also want to use this extension. michael@0: michael@0: 3. What is the correct error when specifies a partial michael@0: mipmap pyramid for OpenGL ES? michael@0: michael@0: RESOLVED: INVALID_OPERATION, since it is an interaction between michael@0: parameters rather than a single value being invalid. It also makes michael@0: sense to relax this condition for desktop GL where it makes sense to michael@0: use a truncated pyramid with TEXTURE_MAX_LEVEL. michael@0: michael@0: 4. Should use of these entry-points make the metadata (format and michael@0: dimensions) immutable? michael@0: michael@0: RESOLVED: Yes. michael@0: michael@0: DISCUSSION: The benefits of knowing metadata can't change will michael@0: probably outweigh the extra cost of checking the michael@0: TEXTURE_IMMUTABLE_FORMAT_EXT flag on each texture specification michael@0: call. michael@0: michael@0: 5. Should it be legal to completely replace the texture using a new call michael@0: to TexStorage*? michael@0: michael@0: RESOLVED. It will not be allowed. michael@0: michael@0: DISCUSSION: This is useful to invalidate all levels of a texture. michael@0: Allowing the metadata to be changed here seems easier than trying to michael@0: define a portable definition of what it means to change the metadata michael@0: (e.g. what if you used an unsized internal format the first time and michael@0: the corresponding sized internal format the second time, or vice michael@0: versa)? michael@0: michael@0: However, while this is largely similar to deleting the old texture michael@0: object and replacing it with a new one, it does lose some of the michael@0: advantages of immutability. Specifically, because doing so does not michael@0: reset bindings, it doesn't allow a migration path to an API that michael@0: validates the texture format at bind time. michael@0: michael@0: 6. Should it be legal to use TexImage* after TexStorage* if it doesn't michael@0: affect the metadata? michael@0: michael@0: RESOLVED: No. michael@0: michael@0: DISCUSSION: A potential use case is to allow a single level of a michael@0: texture to be invalidated using a NULL pointer. However, as noted michael@0: above it is non-trivial to determine what constitutes a change. michael@0: michael@0: 7. How does this extension interact with APPLE_texture_2D_limited_npot? michael@0: michael@0: RESOLVED. APPLE_texture_2D_limited_npot is equivalent to the NPOT michael@0: support in OpenGL ES 2.0. michael@0: michael@0: 8. Should this extension be written to work with desktop OpenGL? michael@0: michael@0: RESOLVED: Yes. michael@0: michael@0: DISCUSSION: There has been been interest and it will future-proof it michael@0: against further additions to OpenGL ES. michael@0: michael@0: 9. Which texture targets should be supported? michael@0: michael@0: RESOLVED. All targets except multisample and buffer textures are michael@0: supported. michael@0: michael@0: Initially all targets except TEXTURE_BUFFER were supported. It was michael@0: noted that the entrypoints for multisample targets added no useful michael@0: functionality, since multisample textures have no completeness michael@0: checks beyond being non-empty. michael@0: michael@0: Rectangle textures have completeness checks to prevent filtering of michael@0: integer textures. However, since we decided to only force mipmap michael@0: completeness, this becomes less useful. michael@0: michael@0: 10. Should this extension support proxy textures? michael@0: michael@0: RESOLVED: Yes. michael@0: michael@0: DISCUSSION: It should be orthogonal. michael@0: michael@0: 11. Are the and parameters necessary? michael@0: michael@0: RESOLVED. No, they will be removed. michael@0: michael@0: DISCUSSION: For OpenGL ES the type parameter was necessary to michael@0: determine the precision of the texture, but this can be solved by michael@0: having these functions accept sized internal formats (which are michael@0: already accepted by renderbuffers). michael@0: michael@0: 12. Should it be legal to make the default texture (id 0) michael@0: immutable-format? michael@0: michael@0: RESOLVED: No. michael@0: michael@0: DISCUSSION: This would make it impossible to restore the context to michael@0: it's default state, which is deemed undesirable. There is no good michael@0: reason not to use named texture objects. michael@0: michael@0: 13. Should we try to guarantee that textures made through this path michael@0: will always be complete? michael@0: michael@0: RESOLVED: It should be guaranteed that the texture will be mipmap michael@0: complete. michael@0: michael@0: DISCUSSION: Future separation between images and samplers will still michael@0: allow users to create combinations that are invalid, but michael@0: constraining the simple cases will make these APIs easier to use for michael@0: beginners. michael@0: michael@0: 14. Should these functions use a EXT_direct_state_access approach to michael@0: specifying the texture objects? michael@0: michael@0: UNRESOLVED. michael@0: michael@0: DISCUSSION: as a standalone extension, no DSA-like functions will be michael@0: added. However, interactions with EXT_direct_state_access and michael@0: ARB_direct_state_access need to be resolved. michael@0: michael@0: 15. Should these functions accept generic compressed formats? michael@0: michael@0: RESOLVED: Yes. Note that the spec language will need to be modified michael@0: to allow this for ES, since the pseudocode is written in terms of michael@0: TexImage2D, which does not allow compressed texture formats in ES. michael@0: See also issues 23 and 27. michael@0: michael@0: 16. How should completeness be forced when TEXTURE_MAX_LEVEL is not michael@0: present? michael@0: michael@0: RESOLVED. The maximum level q will be redefined to clamp to the michael@0: highest level available. michael@0: michael@0: DISCUSSION: A single-level texture can be made complete either by michael@0: making it mipmap complete (by setting TEXTURE_MAX_LEVEL to 0) or by michael@0: turning off mipmapping (by choose an appropriate minification michael@0: filter). michael@0: michael@0: Some options: michael@0: michael@0: A: Specify that TexStorage* changes the default minification filter michael@0: for OpenGL ES. This makes it awkward to add TEXTURE_MAX_LEVEL michael@0: support to OpenGL ES later, since switching to match GL would break michael@0: compatibility. The two mechanisms also do not give identical michael@0: results, since the magnification threshold depends on the michael@0: minification filter. michael@0: michael@0: B: Specify that the texture behaves as though TEXTURE_MAX_LEVEL were michael@0: zero. To specify this properly probably requires fairly intrusive michael@0: changes to the OpenGL ES full specification to add back all the michael@0: language relating to the max level. It also does not solve the michael@0: similar problem of what to do with NPOT textures; and it may have michael@0: hardware impacts due to the change in the min/mag crossover. michael@0: michael@0: C: Specify that TexStorage* changes the default minification filter michael@0: for all implementations when a single-level texture is specified. michael@0: This may be slightly counter-intuitive to desktop GL users, but will michael@0: give consistent behaviour across variants of GL and avoids changing michael@0: the functional behaviour of this extension based on the presence or michael@0: absence of some other feature. michael@0: michael@0: Currently B is specified. This has potential hardware implications michael@0: for OpenGL ES because of the effect of the minification filter on michael@0: the min/mag crossover. However, C has potential hardware implications michael@0: for OpenGL due to the separation of texture and sampler state. michael@0: michael@0: 17. How should completeness be forced when only ES2-style NPOT is michael@0: available? michael@0: michael@0: RESOLVED. It is not worth trying to do this, in light of issue 13. michael@0: michael@0: Previous revisions of this extension overrode the minification michael@0: filter and wrap modes, but that is no longer the case. Since michael@0: OES_texture_npot removes the caveats on NPOT textures anyway, it michael@0: might not be worth trying to "fix" this. michael@0: michael@0: 18. For OpenGL ES, how do the new sized internal formats interact michael@0: with OES_required_internal_format? michael@0: michael@0: RESOLVED. michael@0: michael@0: If OES_required_internal_format is not present, then the michael@0: parameter is intended merely to indicate what the michael@0: corresponding and would have been, had TexImage* michael@0: been used instead. If OES_required_internal_format is present, then michael@0: it is intended that the will be interpreted as if michael@0: it had been passed directly to TexImage*. michael@0: michael@0: 19. Should there be some hinting mechanism to indicate whether data michael@0: is coming immediately or later? michael@0: michael@0: RESOLVED. No parameter is needed. An extension can be added to provide michael@0: a TexParameter value which is latched at TexStorage time. michael@0: michael@0: DISCUSSION: Some members felt that this would be useful so that they michael@0: could defer allocation when suitable, particularly if higher- michael@0: resolution images will be streamed in later; or to choose a memory michael@0: type or layout appropriate to the usage. However, implementation michael@0: experience with BufferData is that developers frequently provide michael@0: wrong values and implementations have to guess anyway. michael@0: michael@0: One option suggested was the parameter currently passed to michael@0: BufferData. Another option was to set it with TexParameter. michael@0: michael@0: 20. How should this extension interact with michael@0: EGLImageTargetTexture2DOES, eglBindTexImage, glXBindTexImage and michael@0: wglBindTexImage? michael@0: michael@0: RESOLVED. These functions will not be permitted after glTexStorage*. michael@0: michael@0: Several options are possible: michael@0: michael@0: A) Disallow these functions. michael@0: B) Allow them, but have them reset the TEXTURE_IMMUTABLE_FORMAT_EXT michael@0: flag. michael@0: C) Allow them unconditionally. michael@0: michael@0: C would violate the design principle that the dimensions and format michael@0: of the mipmap array are immutable. B does not so much modify the michael@0: dimension and formats as replace them with an entirely different michael@0: set. michael@0: michael@0: 21. Should there be a single function for specifying 1D, 2D and 3D michael@0: targets? michael@0: michael@0: RESOLVED. No, we will stick with existing precedent. michael@0: michael@0: 22. Is it possible to use GenerateMipmap with an incomplete mipmap michael@0: pyramid? michael@0: michael@0: RESOLVED. Yes, because the effective max level is limited to the michael@0: levels that were specified, and so GenerateMipmap does not generate michael@0: any new levels. michael@0: michael@0: However, to make automatic mipmap generation work, it is necessary michael@0: to redefine p rather than q, since automatic mipmap generation michael@0: ignores the max level. michael@0: michael@0: 23. How should this extension interact with michael@0: OES_compressed_paletted_texture? michael@0: michael@0: RESOLVED. Paletted textures will not be permitted, and will michael@0: generate INVALID_ENUM. michael@0: michael@0: DISCUSSION: OES_compressed_paletted_texture supplies all the mipmaps michael@0: in a single function call, with the palette specified once. That's michael@0: incompatible with the upload model in this extension. michael@0: michael@0: 24. How can ETC1 textures be used with this extension? michael@0: michael@0: RESOLVED. Add language in this extension to allow subregion uploads michael@0: for ETC1. michael@0: michael@0: DISCUSSION: GL_OES_compressed_ETC1_RGB8_texture doesn't allow michael@0: CompressedTexSubImage*, so it would be impossible to use this michael@0: extension with ETC1. This is seen as an oversight in the ETC1 michael@0: extension. While it cannot be fixed in that extension (since it is michael@0: already shipping), this extension can add that capability. michael@0: michael@0: 25. Should any other compressed formats be similarly modified? michael@0: michael@0: RESOLVED. Yes, AMD_compressed_ATC_texture and michael@0: AMD_compressed_3DC_texture can be modified similarly to ETC1 michael@0: (Maurice Ribble indicated that both formats use 4x4 blocks). Desktop michael@0: OpenGL requires that whole-image replacement is supported for any michael@0: compressed texture format, and the OpenGL ES extensions michael@0: EXT_texture_compression_dxt1 and IMG_texture_compression_pvrtc michael@0: already allow whole-image replacement, so it is not necessary to michael@0: modify them to be used with this extension. michael@0: michael@0: 26. Should these commands be permitted in display lists? michael@0: michael@0: RESOLVED. No. michael@0: michael@0: DISCUSSION: Display lists are most useful for repeating commands, michael@0: and TexStorage* commands cannot be repeated because the first call michael@0: makes the format immutable. michael@0: michael@0: 27. Should these commands accept unsized internal formats? michael@0: michael@0: RESOLVED: No, for both OpenGL and OpenGL ES. michael@0: michael@0: DISCUSSION: normally the parameter to TexImage* can serve as michael@0: a hint to select a sized format (and in OpenGL ES, this is the only michael@0: mechanism available); since TexStorage* does not have a michael@0: parameter, the implementation has no information on which to base a michael@0: decision. michael@0: michael@0: Revision History michael@0: michael@0: Revision 24, 2011/11/11 (dgkoch) michael@0: - Mark complete. Clarify ES clarifications. michael@0: michael@0: Revision 23, 2011/11/10 (dgkoch) michael@0: - Add GLES clarifcations and interactions with more GLES extensions michael@0: michael@0: Revision 22, 2011/11/10 (bmerry) michael@0: - Update my contact details michael@0: michael@0: Revision 21, 2011/07/25 (bmerry) michael@0: - Remove dangling references to MultiTexStorage in Errors section michael@0: michael@0: Revision 20, 2011/07/21 (bmerry) michael@0: - Remove dangling reference to in Errors section michael@0: michael@0: Revision 19, 2011/05/02 (Jon Leech) michael@0: - Assign enum value michael@0: michael@0: Revision 18, 2011/01/24 (bmerry) michael@0: - Disallow unsized internal formats (oversight in revision 17). michael@0: michael@0: Revision 17, 2011/01/24 (bmerry) michael@0: - Added and resolved issue 26. michael@0: - Split issue 27 out from issue 15. michael@0: - Disallow TexStorage* in display lists. michael@0: - Use the term "immutable-format" consistently (bug 7281). michael@0: michael@0: Revision 16, 2010/11/23 (bmerry) michael@0: - Disallowed TexStorage on an immutable-format texture michael@0: (resolves issue 5). michael@0: - Deleted MultiTexStorage* commands (other DSA functions still michael@0: unresolved). michael@0: - Some minor wording changes suggested by Pat Brown (bug 7002). michael@0: michael@0: Revision 15, 2010/11/09 (bmerry) michael@0: - Reopened issue 5. michael@0: - Reopened issue 14, pending stabilisation of michael@0: ARB_direct_state_access. michael@0: - Marked issue 9 resolved, pending any objections. michael@0: - Fix references to no object being bound (was meant to refer to michael@0: the default object). michael@0: - Adding missing pseudocode for TEXTURE_1D_ARRAY. michael@0: - Corrected TEXTURE_2D_ARRAY -> TEXTURE_1D_ARRAY in error checks. michael@0: - Changed "levels... are removed" to "levels... are reset to their michael@0: init state", since desktop GL has per-level state apart from the michael@0: texels. michael@0: - Miscellaneous wording fixes. michael@0: michael@0: Revision 14, 2010/09/25 (bmerry) michael@0: - Add issues 24-25 and alterations to michael@0: OES_compressed_ETC1_RGB8_texture, AMD_compressed_ATC_texture and michael@0: AMD_compressed_3DC_texture. michael@0: michael@0: Revision 13, 2010/09/19 (bmerry) michael@0: - Two typo fixes from Daniel Koch michael@0: michael@0: Revision 12, 2010/09/18 (bmerry) michael@0: - Changed resolution to issue 20 michael@0: - Added and resolved issue 23 michael@0: - Added explanation of how to upload data (in overview) michael@0: - Added spec language to implement resolution to issue 15 michael@0: michael@0: Revision 11, 2010/07/21 (bmerry) michael@0: - Resolved issue 16 michael@0: - Reopen issue 20 michael@0: - Fix some typos michael@0: michael@0: Revision 10, 2010/07/15 (bmerry) michael@0: - Update some issues to match core text michael@0: - Resolved issue 17 michael@0: michael@0: Revision 9, 2010/05/24 (bmerry) michael@0: - Marked issue 2 as resolved michael@0: - Resolved issue 19 (as no change) michael@0: - Resolved issue 20 michael@0: - Add issues 21-22 michael@0: - Add in spec language to forbid use on default textures michael@0: - Redefine level_base, level_max to be clamped forms of michael@0: TEXTURE_BASE_LEVEL/TEXTURE_MAX_LEVEL when using immutable michael@0: textures michael@0: - Redefine p to also be clamped to the provided levels for michael@0: immutable textures, to support automatic mipmap generation michael@0: - Removed multisample functions michael@0: - Removed language stating that texture parameters were reset to michael@0: defaults michael@0: michael@0: Revision 8, 2010/05/18 (bmerry) michael@0: - Added issue about EGLimage michael@0: - Marked issue 14 as resolved michael@0: michael@0: Revision 7, 2010/05/04 (bmerry) michael@0: - Removed some lingering , parameters to the new michael@0: functions that should have been removed in revision 4 michael@0: - Trivial typo fixes michael@0: michael@0: Revision 6, 2010/02/18 (bmerry) michael@0: - Resolved issues 5, 6 and 18 michael@0: - Added MultiTexStorage* functions for DSA interaction michael@0: - Added error for texture-target mismatch in DSA michael@0: - Allowed TexStorage* to be called again michael@0: michael@0: Revision 5, 2010/01/25 (bmerry) michael@0: - Added to contributors list michael@0: - Require OpenGL 1.2, to simplify interactions with michael@0: TEXTURE_BASE_LEVEL/TEXTURE_MAX_LEVEL and CLAMP_TO_EDGE michael@0: - Change default wrap modes to always be CLAMP_TO_EDGE michael@0: - Change default filters to always be NEAREST michael@0: - Moved language about generating new levels into an interaction, michael@0: since it can only happen on OpenGL ES michael@0: - Added interaction with EXT_direct_state_access michael@0: - Added extra for GL ES when OES_depth_texture, michael@0: OES_packed_depth_stencil and EXT_texture_type_2_10_10_10_REV are michael@0: present. michael@0: - Minor non-functional wording fixes and typos michael@0: - Resolved issue 16 michael@0: - Added issues 17-19 michael@0: michael@0: Revision 4, 2010/01/13 (bmerry) michael@0: - Changed suffix from ARM to EXT michael@0: - Added list of contributors michael@0: - Added language to force the texture to always be complete michael@0: - Removed and arguments michael@0: - Added issues 14-16 michael@0: - Reopened issue 2 michael@0: - Reformatted issues to separate resolution and discussion michael@0: - Resolved issues 1, 9 and 11-13 michael@0: - Fixed the max number of levels in a cube map array michael@0: michael@0: Revision 3, 2009/12/17 (bmerry) michael@0: - Added missing vendor suffix to TEXTURE_IMMUTABLE_FORMAT_ARM michael@0: - Rewritten to against desktop OpenGL michael@0: - Added prototypes for 1D and multisample storage functions michael@0: - Added issues 8-13 michael@0: michael@0: Revision 2, 2009/08/20 (bmerry) michael@0: - Resolved issue 2 (no border parameter) michael@0: - Resolved issue 4 (metadata becomes immutable) michael@0: - Added interaction with OES_texture_cube_map michael@0: - Added error if width != height in a cube map michael@0: - Added issues 5-7 michael@0: michael@0: Revision 1, 2009/05/06 (bmerry) michael@0: - First draft