xref: /third_party/openGLES/extensions/APPLE/APPLE_copy_texture_levels.txt

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

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

Issues

    None
    
Revision History

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

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