1Name
2
3    APPLE_copy_texture_levels
4    
5Name Strings
6
7    GL_APPLE_copy_texture_levels
8
9Contact
10
11    Eric Sunalp, Apple Inc., (esunalp 'at' apple.com)
12    
13Contributors
14
15    Alex Eddy, Apple
16    Richard Schreyer, Apple
17    Eric Sunalp, Apple
18    Michael Swift, Apple
19
20Status
21
22    Complete
23    
24Version
25
26    Last Modified Date:     November 29, 2011
27    Revision:               2
28
29Number
30
31    OpenGL ES Extension #123
32
33Dependencies
34
35    OpenGL ES 1.1 or OpenGL ES 2.0 is required.
36    
37    EXT_texture_storage is required.
38    
39    This specification is written against the OpenGL ES 2.0.25 (Full Specification).
40
41Overview
42
43    This extension provides an efficient path for copying a contiguous subset of mipmap 
44    levels from one texture to the matching subset of mipmap levels of another texture, 
45    where matches are determined by the equality of a level's dimensions.
46    
47    This extension is dependent on the existence of the extension EXT_texture_storage.
48    Immutable textures are used to guarantee that storage is allocated up front for the
49    source and destination textures and that the internal formats of those textures are 
50    sized the same.
51    
52    An efficient copy can be achieved by implementations because the internal storage 
53    requirements are the same between textures and will remain unchanged when moving data. 
54    It is expected that in all cases, moving levels from one texture to another is a 
55    simple copy operation without any necessary conversion. This extension can be used as
56    an alternative to TEXTURE_BASE_LEVEL. In some implementations, changing the value of
57    TEXTURE_BASE_LEVEL can incur a costly re-allocation at runtime.
58    
59    Texture streaming is an expected use case for this extension. For example, a developer
60    may want to stream in a larger base level for a given texture from a storage device. 
61    To achieve this, a copy of the current mipmap levels are made into a destination 
62    whose storage was specified to accommodate the source levels and the larger base 
63    level. The efficiency of the copy without conversion allows for the smaller mipmap 
64    levels to be in place while the larger base level is being read from the storage 
65    device and uploaded.
66
67New Tokens
68
69    None
70    
71New Procedures and Functions
72
73    void CopyTextureLevelsAPPLE(uint destinationTexture, uint sourceTexture,
74                           int sourceBaseLevel, sizei sourceLevelCount);
75
76New State
77
78   None
79
80New Implementation Dependent State
81
82   None
83
84Additions to Chapter 3 of the 2.0.25 Specification (Rasterization)
85
86    -- Restate the first paragraph of section 3.7.2, Alternate Texture Image Specification 
87       Commands
88
89    Texture images may also be specified using image data taken directly from the  
90    framebuffer or from a subset of levels of a given texture. Rectangular subregions of 
91    existing texture images may also be respecified.
92
93    -- Append to section 3.7.2, Alternate Texture Image Specification Commands
94
95    The command
96    
97        void CopyTextureLevelsAPPLE(uint destinationTexture, uint sourceTexture,
98                               int sourceBaseLevel, sizei sourceLevelCount);
99
100    is used to specify a texture image by copying a contiguous subset of mipmap levels 
101    from one texture to the matching subset of mipmap levels of another texture, where 
102    matches are determined by the equality of a level's dimensions. An INVALID_OPERATION 
103    is generated when the count and dimensions of the source texture levels don't exactly 
104    match the count and dimensions of a subset of corresponding destination texture 
105    levels.
106    
107    Both <sourceTexture> and <destinationTexture> specify the texture object names to act
108    as the source and destination of the copy as apposed to operating on the currently 
109    bound textures for a given set of texture units.
110    
111    It is a requirement that both <sourceTexture> and <destinationTexture> are immutable 
112    textures and that they are both specified with the same sized internal format 
113    enumeration. An INVALID_OPERATION is generated if either texture's 
114    TEXTURE_IMMUTABLE_FORMAT_EXT is FALSE or if the sized internal formats don't match.
115    It is a requirement that the <sourceTexture>'s target specification is the same as
116    the <destinationTexture>'s target specification. If not, then an INVALID_OPERATION
117    is generated.
118
119    <sourceBaseLevel> and <sourceLevelCount> are used to specify the inclusive range of 
120    mipmap levels to be copied from the source texture to the destination texture. 
121    <sourceBaseLevel> can assume a value from zero to n-1, where n is the number of levels
122    for which the source texture was specified. Anything outside of this range will result 
123    in the generation of an INVALID_VALUE error. <sourceLevelCount> is added to 
124    <sourceBaseLevel> to specify the range of levels to be copied to the destination. An 
125    INVALID_VALUE is generated if that value is greater than the number of levels for
126    which the source texture was specified. Additionally, <sourceLevelCount> must be 
127    equal to or greater than one, or an INVALID_VALUE will be generated.
128
129Errors
130
131    The error INVALID_OPERATION is generated by CopyTextureLevelsAPPLE when the count and 
132    dimensions of the source texture levels, from source base level to source base level 
133    plus source level count, don't exactly match the count and dimensions of a subset of 
134    matching destination texture levels.
135    
136    The error INVALID_OPERATION is generated by CopyTextureLevelsAPPLE if either the
137    source texture or destination texture is a texture for which
138    TEXTURE_IMMUTABLE_FORMAT_EXT is FALSE.
139    
140    The error INVALID_OPERATION is generated by CopyTextureLevelsAPPLE if the internal format
141    of the source texture is different than that of the destination texture.
142    
143    The error INVALID_OPERATION is generated by CopyTextureLevelsAPPLE if the source and
144    the destination target specification differ.
145    
146    The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to
147    the parameter <sourceTexture> or <destinationTexture> is zero.
148    
149    The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to
150    the parameter <sourceBaseLevel> is less than zero.
151    
152    The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to
153    the parameter <sourceBaseLevel> is greater than n-1, where n is the number of levels
154    for which the source texture was specified.
155    
156    The error INVALID_VALUE is generated by CopyTextureLevelsAPPLE if the value passed to
157    the parameter <sourceLevelCount>, is less than one, or when added to the parameter 
158    <sourceBaseLevel>, is greater than n-1, where n is the number of levels for which the 
159    source texture was specified.
160
161Issues
162
163    None
164    
165Revision History
166
167    Revision 2, 2011/11/29 (Eric Sunalp)
168        - Incorporate initial feedback.
169
170    Revision 1, 2011/11/10 (Eric Sunalp)
171        - Draft proposal.
172