1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
|
<!DOCTYPE refentry [ <!ENTITY % mathent SYSTEM "math.ent"> %mathent; ]>
<!-- Converted by db4-upgrade version 1.1 -->
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="glClearTexSubImage">
<info>
<copyright>
<year>2013-2014</year>
<holder>Khronos Group</holder>
</copyright>
</info>
<refmeta>
<refentrytitle>glClearTexSubImage</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClearTexSubImage</refname>
<refpurpose>fills all or part of a texture image with a constant value</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClearTexSubImage</function></funcdef>
<paramdef>GLuint <parameter>texture</parameter></paramdef>
<paramdef>GLint <parameter>level</parameter></paramdef>
<paramdef>GLint <parameter>xoffset</parameter></paramdef>
<paramdef>GLint <parameter>yoffset</parameter></paramdef>
<paramdef>GLint <parameter>zoffset</parameter></paramdef>
<paramdef>GLsizei <parameter>width</parameter></paramdef>
<paramdef>GLsizei <parameter>height</parameter></paramdef>
<paramdef>GLsizei <parameter>depth</parameter></paramdef>
<paramdef>GLenum <parameter>format</parameter></paramdef>
<paramdef>GLenum <parameter>type</parameter></paramdef>
<paramdef>const void * <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>texture</parameter></term>
<listitem>
<para>
The name of an existing texture object containing the image to be cleared.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>level</parameter></term>
<listitem>
<para>
The level of <parameter>texture</parameter> containing the region to be cleared.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>xoffset</parameter></term>
<listitem>
<para>
The coordinate of the left edge of the region to be cleared.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>yoffset</parameter></term>
<listitem>
<para>
The coordinate of the lower edge of the region to be cleared.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>zoffset</parameter></term>
<listitem>
<para>
The coordinate of the front of the region to be cleared.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter></term>
<listitem>
<para>
The width of the region to be cleared.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>height</parameter></term>
<listitem>
<para>
The height of the region to be cleared.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>depth</parameter></term>
<listitem>
<para>
The depth of the region to be cleared.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
The format of the data whose address in memory is given by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
The type of the data whose address in memory is given by <parameter>data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
The address in memory of the data to be used to clear the specified region.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="description"><title>Description</title>
<para>
<function>glClearTexSubImage</function> fills all or part of an image contained in a
texture with an application supplied value. <parameter>texture</parameter> must be
the name of an existing texture. Further, <parameter>texture</parameter> may not be
the name of a buffer texture, nor may its internal format be compressed.
</para>
<para>
Arguments <parameter>xoffset</parameter>, <parameter>yoffset</parameter>, and
<parameter>zoffset</parameter> specify the lower left texel coordinates of
a width-wide by height-high by depth-deep rectangular subregion of the texel array.
</para>
<para>
For one-dimensional array textures, <parameter>yoffset</parameter> is interpreted as the first layer to
be cleared and <parameter>height</parameter> is the number of layers to clear. For two-dimensional array
textures, <parameter>zoffset</parameter> is interpreted as the first layer to be cleared and <parameter>depth</parameter> is the number
of layers to clear. Cube map textures are treated as an array of six slices in the z-dimension,
where the value of <parameter>zoffset</parameter> is interpreted as specifying the cube map face
for the corresponding layer and <parameter>depth</parameter> is the number of faces to clear.
For cube map array textures, <parameter>zoffset</parameter> is the first layer-face to clear,
and <parameter>depth</parameter> is the number of layer-faces to clear. Each layer-face is
translated into an array layer and a cube map face as described in the OpenGL Specification.
</para>
<para>
Negative values of <parameter>xoffset</parameter>, <parameter>yoffset</parameter>, and <parameter>zoffset</parameter> correspond to the coordinates of
border texels. Taking
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">ws</mml:mi></mml:math>
</inlineequation>,
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">hs</mml:mi></mml:math>
</inlineequation>,
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">ds</mml:mi></mml:math>
</inlineequation>,
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">wb</mml:mi></mml:math>
</inlineequation>,
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">hb</mml:mi></mml:math>
</inlineequation>, and
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">db</mml:mi></mml:math>
</inlineequation> to be
the specified <parameter>width</parameter>, <parameter>height</parameter>, <parameter>depth</parameter>, and the border width, border height, and border
depth of the texel array and taking
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">x</mml:mi></mml:math>
</inlineequation>,
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">y</mml:mi></mml:math>
</inlineequation>,
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">z</mml:mi></mml:math>
</inlineequation>,
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">w</mml:mi></mml:math>
</inlineequation>,
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">h</mml:mi></mml:math>
</inlineequation>, and
<inlineequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">d</mml:mi></mml:math>
</inlineequation>
to be the <parameter>xoffset</parameter>, <parameter>yoffset</parameter>,
<parameter>zoffset</parameter>, <parameter>width</parameter>, <parameter>height</parameter>, and <parameter>depth</parameter> argument values,
any of the following relationships generates a <constant>GL_INVALID_OPERATION</constant> error:
<itemizedlist>
<listitem>
<informalequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
<mml:mrow>
<mml:mtext>x</mml:mtext>
<mml:mo><</mml:mo>
<mml:msub>
<mml:mtext>w</mml:mtext>
<mml:mtext>b</mml:mtext>
</mml:msub>
</mml:mrow>
</mml:math>
</informalequation>
</listitem>
<listitem>
<informalequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
<mml:mrow>
<mml:mtext mathvariant="italic">x</mml:mtext>
<mml:mo>+</mml:mo>
<mml:mtext mathvariant="italic">w</mml:mtext>
<mml:mo>></mml:mo>
<mml:msub>
<mml:mtext mathvariant="italic">w</mml:mtext>
<mml:mtext mathvariant="italic">s</mml:mtext>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub>
<mml:mtext mathvariant="italic">w</mml:mtext>
<mml:mtext mathvariant="italic">b</mml:mtext>
</mml:msub>
</mml:mrow>
</mml:math>
</informalequation>
</listitem>
<listitem>
<informalequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
<mml:mrow>
<mml:mtext mathvariant="italic">y</mml:mtext>
<mml:mo><</mml:mo>
<mml:mo>-</mml:mo>
<mml:msub>
<mml:mtext mathvariant="italic">h</mml:mtext>
<mml:mtext mathvariant="italic">b</mml:mtext>
</mml:msub>
</mml:mrow>
</mml:math>
</informalequation>
</listitem>
<listitem>
<informalequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
<mml:mrow>
<mml:mtext mathvariant="italic">y</mml:mtext>
<mml:mo>+</mml:mo>
<mml:mtext mathvariant="italic">h</mml:mtext>
<mml:mo>></mml:mo>
<mml:msub>
<mml:mtext mathvariant="italic">h</mml:mtext>
<mml:mtext mathvariant="italic">s</mml:mtext>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub>
<mml:mtext mathvariant="italic">h</mml:mtext>
<mml:mtext mathvariant="italic">b</mml:mtext>
</mml:msub>
</mml:mrow>
</mml:math>
</informalequation>
</listitem>
<listitem>
<informalequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
<mml:mrow>
<mml:mtext mathvariant="italic">z</mml:mtext>
<mml:mo><</mml:mo>
<mml:mo>-</mml:mo>
<mml:msub>
<mml:mtext mathvariant="italic">d</mml:mtext>
<mml:mtext mathvariant="italic">b</mml:mtext>
</mml:msub>
</mml:mrow>
</mml:math>
</informalequation>
</listitem>
<listitem>
<informalequation>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
<mml:mrow>
<mml:mtext mathvariant="italic">z</mml:mtext>
<mml:mo>+</mml:mo>
<mml:mtext mathvariant="italic">d</mml:mtext>
<mml:mo>></mml:mo>
<mml:msub>
<mml:mtext mathvariant="italic">d</mml:mtext>
<mml:mtext mathvariant="italic">s</mml:mtext>
</mml:msub>
<mml:mo>-</mml:mo>
<mml:msub>
<mml:mtext mathvariant="italic">d</mml:mtext>
<mml:mtext mathvariant="italic">b</mml:mtext>
</mml:msub>
</mml:mrow>
</mml:math>
</informalequation>
</listitem>
</itemizedlist>
</para>
<para>
For texture types that do not have certain dimensions, this command treats those
dimensions as having a size of 1. For example, to clear a portion of a two-dimensional
texture, use <parameter>zoffset</parameter> equal to zero and <parameter>depth</parameter> equal to one.
</para>
<para>
<parameter>format</parameter> and <parameter>type</parameter> specify the format and type of the
source data and are interpreted as they are for <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>.
Textures with a base internal format of <constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_STENCIL_INDEX</constant>, or <constant>GL_DEPTH_STENCIL</constant>
require depth component, stencil, or depth-stencil component data respectively.
Textures with other base internal formats require RGBA formats. Textures with integer
internal formats require integer data.
</para>
<para>
<parameter>data</parameter> is a pointer to an array of between one and four components of texel
data that will be used as the source for the constant fill value. The elements of
data are converted by the GL into the internal format of the texture image (that
was specified when the level was defined by any of the <function>glTexImage*</function>, <function>glTexStorage*</function>
or <function>glCopyTexImage*</function> commands), and then
used to fill the specified range of the destination texture level. If <parameter>data</parameter> is <constant>NULL</constant>, then
the pointer is ignored and the sub-range of the texture image is filled with zeros. If
texture is a multisample texture, all the samples in a texel are cleared to the value
specified by data.
</para>
</refsect1>
<refsect1 xml:id="notes"><title>Notes</title>
<para>
<function>glClearTexSubImage</function> is available only if the GL version is 4.4 or greater.
</para>
</refsect1>
<refsect1 xml:id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>texture</parameter> is zero or not the
name of an existing texture object.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>texture</parameter> is a buffer texture.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>texture</parameter> has a compressed
internal format.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the base internal format is
<constant>GL_DEPTH_COMPONENT</constant> and <parameter>format</parameter> is not <constant>GL_DEPTH_COMPONENT</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the base internal format is
<constant>GL_DEPTH_STENCIL</constant> and <parameter>format</parameter> is not <constant>GL_DEPTH_STENCIL</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the base internal format is
<constant>GL_STENCIL_INDEX</constant> and <parameter>format</parameter> is not <constant>GL_STENCIL_INDEX</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the base internal format is
<constant>GL_RGBA</constant> and <parameter>format</parameter> is <constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_STENCIL_INDEX</constant>, or <constant>GL_DEPTH_STENCIL</constant>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the internal format is integer and <parameter>format</parameter> does not specify integer data.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the internal format is not
integer and <parameter>format</parameter> specifies integer data.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> error is generated if the <parameter>xoffset</parameter>, <parameter>yoffset</parameter>, <parameter>zoffset</parameter>,
<parameter>width</parameter>, <parameter>height</parameter>, and <parameter>depth</parameter> parameters (or combinations thereof) specify a region that falls outside the
defined texture image array (including border, if any).
</para>
</refsect1>
<refsect1 xml:id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glGetInternalformat</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 xml:id="versions"><title>Version Support</title>
<informaltable>
<tgroup cols="13" align="left">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apifunchead.xml" xpointer="xpointer(/*/*)"/>
<tbody>
<row>
<entry><function>glClearTexSubImage</function></entry>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='44']/*)"/>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 xml:id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClearTexImage</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexStorage3D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 xml:id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"/> 2013-2014 Khronos Group.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://opencontent.org/openpub/">http://opencontent.org/openpub/</link>.
</para>
</refsect1>
</refentry>
|
