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
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glClearTexImage">
<refentryinfo>
<copyright>
<year>2013</year>
<holder>Khronos Group</holder>
</copyright>
</refentryinfo>
<refmeta>
<refentrytitle>glClearTexImage</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glClearTexImage</refname>
<refpurpose>fills all a texture image with a constant value</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glClearTexImage</function></funcdef>
<paramdef>GLuint <parameter>texture</parameter></paramdef>
<paramdef>GLint <parameter>level</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 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>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 id="description"><title>Description</title>
<para>
<function>glClearTexImage</function> fills all 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>
<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 id="notes"><title>Notes</title>
<para>
<function>glClearTexImage</function> is available only if the GL version is 4.4 or greater.
</para>
</refsect1>
<refsect1 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> is generated if the image array identified by <parameter>level</parameter>
has not previously been defined by a call to <function>glTexImage*</function> or <function>glTexStorage*</function>.
</para>
</refsect1>
<refsect1 id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glGetInternalformat</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glClearTexSubImage</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 id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"></trademark> 2013 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.
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
</para>
</refsect1>
</refentry>
|
