Name APPLE_copy_texture_levels Name Strings GL_APPLE_copy_texture_levels Contact Eric Sunalp, Apple Inc., (esunalp 'at' apple.com) Contributors Alex Eddy, Apple Richard Schreyer, Apple Eric Sunalp, Apple Michael Swift, Apple Status Complete Version Last Modified Date: November 29, 2011 Revision: 2 Number OpenGL ES Extension #123 Dependencies OpenGL ES 1.1 or OpenGL ES 2.0 is required. EXT_texture_storage is required. This specification is written against the OpenGL ES 2.0.25 (Full Specification). Overview This extension provides an efficient path for copying a contiguous subset of mipmap levels from one texture to the matching subset of mipmap levels of another texture, where matches are determined by the equality of a level's dimensions. This extension is dependent on the existence of the extension EXT_texture_storage. Immutable textures are used to guarantee that storage is allocated up front for the source and destination textures and that the internal formats of those textures are sized the same. An efficient copy can be achieved by implementations because the internal storage requirements are the same between textures and will remain unchanged when moving data. It is expected that in all cases, moving levels from one texture to another is a simple copy operation without any necessary conversion. This extension can be used as an alternative to TEXTURE_BASE_LEVEL. In some implementations, changing the value of TEXTURE_BASE_LEVEL can incur a costly re-allocation at runtime. Texture streaming is an expected use case for this extension. For example, a developer may want to stream in a larger base level for a given texture from a storage device. To achieve this, a copy of the current mipmap levels are made into a destination whose storage was specified to accommodate the source levels and the larger base level. The efficiency of the copy without conversion allows for the smaller mipmap levels to be in place while the larger base level is being read from the storage device and uploaded. New Tokens None New Procedures and Functions void CopyTextureLevelsAPPLE(uint destinationTexture, uint sourceTexture, int sourceBaseLevel, sizei sourceLevelCount); New State None New Implementation Dependent State None Additions to Chapter 3 of the 2.0.25 Specification (Rasterization) -- Restate the first paragraph of section 3.7.2, Alternate Texture Image Specification Commands Texture images may also be specified using image data taken directly from the framebuffer or from a subset of levels of a given texture. Rectangular subregions of existing texture images may also be respecified. -- Append to section 3.7.2, Alternate Texture Image Specification Commands The command void CopyTextureLevelsAPPLE(uint destinationTexture, uint sourceTexture, int sourceBaseLevel, sizei sourceLevelCount); is used to specify a texture image by copying a contiguous subset of mipmap levels from one texture to the matching subset of mipmap levels of another texture, where matches are determined by the equality of a level's dimensions. An INVALID_OPERATION is generated when the count and dimensions of the source texture levels don't exactly match the count and dimensions of a subset of corresponding destination texture levels. Both and specify the texture object names to act as the source and destination of the copy as apposed to operating on the currently bound textures for a given set of texture units. It is a requirement that both and are immutable textures and that they are both specified with the same sized internal format enumeration. An INVALID_OPERATION is generated if either texture's TEXTURE_IMMUTABLE_FORMAT_EXT is FALSE or if the sized internal formats don't match. It is a requirement that the 's target specification is the same as the 's target specification. If not, then an INVALID_OPERATION is generated. and are used to specify the inclusive range of mipmap levels to be copied from the source texture to the destination texture. can assume a value from zero to n-1, where n is the number of levels for which the source texture was specified. Anything outside of this range will result in the generation of an INVALID_VALUE error. is added to to specify the range of levels to be copied to the destination. An INVALID_VALUE is generated if that value is greater than the number of levels for which the source texture was specified. Additionally, must be equal to or greater than one, or an INVALID_VALUE will be generated. Errors The error INVALID_OPERATION is generated by CopyTextureLevelsAPPLE when the count and dimensions of the source texture levels, from source base level to source base level plus source level count, don't exactly match the count and dimensions of a subset of matching destination texture levels. The error INVALID_OPERATION is generated by CopyTextureLevelsAPPLE if either the source texture or destination texture is a texture for which TEXTURE_IMMUTABLE_FORMAT_EXT is FALSE. The error INVALID_OPERATION is generated by CopyTextureLevelsAPPLE if the internal format of the source texture is different than that of the destination texture. The error INVALID_OPERATION is generated by CopyTextureLevelsAPPLE if the source and the destination target specification differ. The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to the parameter or is zero. The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to the parameter is less than zero. The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to the parameter is greater than n-1, where n is the number of levels for which the source texture was specified. The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to the parameter , is less than one, or when added to the parameter , is greater than n-1, where n is the number of levels for which the source texture was specified. Issues None Revision History Revision 2, 2011/11/29 (Eric Sunalp) - Incorporate initial feedback. Revision 1, 2011/11/10 (Eric Sunalp) - Draft proposal.