APPLE_copy_texture_levels

GL_APPLE_copy_texture_levels

Eric Sunalp, Apple Inc., (esunalp 'at' apple.com)

Alex Eddy, Apple
Richard Schreyer, Apple
Eric Sunalp, Apple
Michael Swift, Apple

Complete

Last Modified Date:     November 29, 2011
Revision:               2

OpenGL ES Extension #123

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).

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.

None

void CopyTextureLevelsAPPLE(uint destinationTexture, uint sourceTexture,
                       int sourceBaseLevel, sizei sourceLevelCount);

-- 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 <sourceTexture> and <destinationTexture> 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 <sourceTexture> and <destinationTexture> 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 <sourceTexture>'s target specification is the same as
the <destinationTexture>'s target specification. If not, then an INVALID_OPERATION
is generated.

<sourceBaseLevel> and <sourceLevelCount> are used to specify the inclusive range of 
mipmap levels to be copied from the source texture to the destination texture. 
<sourceBaseLevel> 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. <sourceLevelCount> is added to 
<sourceBaseLevel> 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, <sourceLevelCount> must be 
equal to or greater than one, or an INVALID_VALUE will be generated.

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 <sourceTexture> or <destinationTexture> is zero.

The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to
the parameter <sourceBaseLevel> is less than zero.

The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to
the parameter <sourceBaseLevel> 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 <sourceLevelCount>, is less than one, or when added to the parameter 
<sourceBaseLevel>, is greater than n-1, where n is the number of levels for which the 
source texture was specified.

None

Revision 2, 2011/11/29 (Eric Sunalp)
    - Incorporate initial feedback.

Revision 1, 2011/11/10 (Eric Sunalp)
    - Draft proposal.