• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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