/
glTexSubImage2D.xhtml
239 lines (232 loc) · 17.4 KB
/
glTexSubImage2D.xhtml
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
<div class="refentry"><a id="glTexSubImage2D"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glTexSubImage2D — specify a two-dimensional texture subimage</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table class="funcprototype-table" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <strong class="fsfunc">glTexSubImage2D</strong>(</code></td><td>GLenum <var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLint <var class="pdparam">level</var>, </td></tr><tr><td> </td><td>GLint <var class="pdparam">xoffset</var>, </td></tr><tr><td> </td><td>GLint <var class="pdparam">yoffset</var>, </td></tr><tr><td> </td><td>GLsizei <var class="pdparam">width</var>, </td></tr><tr><td> </td><td>GLsizei <var class="pdparam">height</var>, </td></tr><tr><td> </td><td>GLenum <var class="pdparam">format</var>, </td></tr><tr><td> </td><td>GLenum <var class="pdparam">type</var>, </td></tr><tr><td> </td><td>const GLvoid * <var class="pdparam">data</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><p>
</p><div class="refsect1"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
Specifies the target texture.
Must be <code class="constant">GL_TEXTURE_2D</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_POSITIVE_X</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_X</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Y</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Z</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</code>,
or <code class="constant">GL_TEXTURE_1D_ARRAY</code>.
</p></dd><dt><span class="term"><em class="parameter"><code>level</code></em></span></dt><dd><p>
Specifies the level-of-detail number.
Level 0 is the base image level.
Level <span class="emphasis"><em>n</em></span> is the <span class="emphasis"><em>n</em></span>th mipmap reduction image.
</p></dd><dt><span class="term"><em class="parameter"><code>xoffset</code></em></span></dt><dd><p>
Specifies a texel offset in the x direction within the texture array.
</p></dd><dt><span class="term"><em class="parameter"><code>yoffset</code></em></span></dt><dd><p>
Specifies a texel offset in the y direction within the texture array.
</p></dd><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p>
Specifies the width of the texture subimage.
</p></dd><dt><span class="term"><em class="parameter"><code>height</code></em></span></dt><dd><p>
Specifies the height of the texture subimage.
</p></dd><dt><span class="term"><em class="parameter"><code>format</code></em></span></dt><dd><p>
Specifies the format of the pixel data.
The following symbolic values are accepted:
<code class="constant">GL_RED</code>,
<code class="constant">GL_RG</code>,
<code class="constant">GL_RGB</code>,
<code class="constant">GL_BGR</code>,
<code class="constant">GL_RGBA</code>, and
<code class="constant">GL_BGRA</code>.
</p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p>
Specifies the data type of the pixel data.
The following symbolic values are accepted:
<code class="constant">GL_UNSIGNED_BYTE</code>,
<code class="constant">GL_BYTE</code>,
<code class="constant">GL_UNSIGNED_SHORT</code>,
<code class="constant">GL_SHORT</code>,
<code class="constant">GL_UNSIGNED_INT</code>,
<code class="constant">GL_INT</code>,
<code class="constant">GL_FLOAT</code>,
<code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,
<code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,
<code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>,
<code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>,
<code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,
<code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,
<code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,
<code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,
<code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,
<code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,
<code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, and
<code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>.
</p></dd><dt><span class="term"><em class="parameter"><code>data</code></em></span></dt><dd><p>
Specifies a pointer to the image data in memory.
</p></dd></dl></div></div><div class="refsect1"><a id="description"></a><h2>Description</h2><p>
Texturing maps a portion of a specified texture image
onto each graphical primitive for which texturing is enabled.
</p><p>
<code class="function">glTexSubImage2D</code> redefines a contiguous subregion of an existing two-dimensional
or one-dimensional array texture image.
The texels referenced by <em class="parameter"><code>data</code></em> replace the portion of the
existing texture array with x indices <em class="parameter"><code>xoffset</code></em> and
<math overflow="scroll">
<mrow>
<mi mathvariant="italic">xoffset</mi>
<mo>+</mo>
<mi mathvariant="italic">width</mi>
<mo>-</mo>
<mn>1</mn>
</mrow>
</math>,
inclusive,
and y indices <em class="parameter"><code>yoffset</code></em> and
<math overflow="scroll">
<mrow>
<mi mathvariant="italic">yoffset</mi>
<mo>+</mo>
<mi mathvariant="italic">height</mi>
<mo>-</mo>
<mn>1</mn>
</mrow>
</math>,
inclusive.
This region may not include any texels outside the range of the
texture array as it was originally specified.
It is not an error to specify a subtexture with zero width or height, but
such a specification has no effect.
</p><p>
If a non-zero named buffer object is bound to the <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target
(see <a class="citerefentry" href="glBindBuffer"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a>) while a texture image is
specified, <em class="parameter"><code>data</code></em> is treated as a byte offset into the buffer object's data store.
</p></div><div class="refsect1"><a id="notes"></a><h2>Notes</h2><p>
<a class="citerefentry" href="glPixelStore"><span class="citerefentry"><span class="refentrytitle">glPixelStore</span></span></a> modes affect texture images.
</p><p>
<code class="function">glTexSubImage2D</code> specifies a two-dimensional subtexture for the current texture unit,
specified with <a class="citerefentry" href="glActiveTexture"><span class="citerefentry"><span class="refentrytitle">glActiveTexture</span></span></a>.
</p></div><div class="refsect1"><a id="errors"></a><h2>Errors</h2><p>
<code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>target</code></em> is not <code class="constant">GL_TEXTURE_2D</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_POSITIVE_X</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_X</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Y</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</code>,
<code class="constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Z</code>, or
<code class="constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</code>.
</p><p>
<code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>format</code></em> is not an accepted
format constant.
</p><p>
<code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>type</code></em> is not a type constant.
</p><p>
<code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>level</code></em> is less than 0.
</p><p>
<code class="constant">GL_INVALID_VALUE</code> may be generated if <em class="parameter"><code>level</code></em> is greater
than
<math overflow="scroll">
<msub><mi mathvariant="italic">log</mi>
<mn>2</mn>
</msub>
</math>
<span class="emphasis"><em>max</em></span>,
where <span class="emphasis"><em>max</em></span> is the returned value of <code class="constant">GL_MAX_TEXTURE_SIZE</code>.
</p><p>
<code class="constant">GL_INVALID_VALUE</code> is generated if
<math overflow="scroll">
<mrow>
<mi mathvariant="italic">xoffset</mi>
<mo><</mo>
<mn>0</mn>
</mrow>
</math>,
<math overflow="scroll">
<mrow>
<mfenced open="(" close=")">
<mrow>
<mi mathvariant="italic">xoffset</mi>
<mo>+</mo>
<mi mathvariant="italic">width</mi>
</mrow>
</mfenced>
<mo>></mo>
<mi mathvariant="italic">w</mi>
</mrow>
</math>,
<math overflow="scroll">
<mrow>
<mi mathvariant="italic">yoffset</mi>
<mo><</mo>
<mn>0</mn>
</mrow>
</math>,
or
<math overflow="scroll">
<mrow>
<mfenced open="(" close=")">
<mrow>
<mi mathvariant="italic">yoffset</mi>
<mo>+</mo>
<mi mathvariant="italic">height</mi>
</mrow>
</mfenced>
<mo>></mo>
<mi mathvariant="italic">h</mi>
</mrow>
</math>,
where
<math overflow="scroll"><mi mathvariant="italic">w</mi></math>
is the <code class="constant">GL_TEXTURE_WIDTH</code>, and
<math overflow="scroll"><mi mathvariant="italic">h</mi></math>
is the <code class="constant">GL_TEXTURE_HEIGHT</code>
of the texture image being modified.
</p><p>
<code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>width</code></em> or <em class="parameter"><code>height</code></em> is less than 0.
</p><p>
<code class="constant">GL_INVALID_OPERATION</code> is generated if the texture array has not
been defined by a previous <a class="citerefentry" href="glTexImage2D"><span class="citerefentry"><span class="refentrytitle">glTexImage2D</span></span></a> operation.
</p><p>
<code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>type</code></em> is one of
<code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,
<code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,
<code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>, or
<code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>
and <em class="parameter"><code>format</code></em> is not <code class="constant">GL_RGB</code>.
</p><p>
<code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>type</code></em> is one of
<code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,
<code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,
<code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,
<code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,
<code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,
<code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,
<code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, or
<code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>
and <em class="parameter"><code>format</code></em> is neither <code class="constant">GL_RGBA</code> nor <code class="constant">GL_BGRA</code>.
</p><p>
<code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
<code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the buffer object's data store is currently mapped.
</p><p>
<code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
<code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
</p><p>
<code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
<code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and <em class="parameter"><code>data</code></em> is not evenly divisible
into the number of bytes needed to store in memory a datum indicated by <em class="parameter"><code>type</code></em>.
</p></div><div class="refsect1"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
<a class="citerefentry" href="glGetTexImage"><span class="citerefentry"><span class="refentrytitle">glGetTexImage</span></span></a>
</p><p>
<a class="citerefentry" href="glGet"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_PIXEL_UNPACK_BUFFER_BINDING</code>
</p></div>
{$pipelinestall}{$examples}
<div class="refsect1"><a id="seealso"></a><h2>See Also</h2><p>
<a class="citerefentry" href="glActiveTexture"><span class="citerefentry"><span class="refentrytitle">glActiveTexture</span></span></a>,
<a class="citerefentry" href="glCopyTexImage1D"><span class="citerefentry"><span class="refentrytitle">glCopyTexImage1D</span></span></a>,
<a class="citerefentry" href="glCopyTexImage2D"><span class="citerefentry"><span class="refentrytitle">glCopyTexImage2D</span></span></a>,
<a class="citerefentry" href="glCopyTexSubImage1D"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage1D</span></span></a>,
<a class="citerefentry" href="glCopyTexSubImage2D"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage2D</span></span></a>,
<a class="citerefentry" href="glCopyTexSubImage3D"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage3D</span></span></a>,
<a class="citerefentry" href="glPixelStore"><span class="citerefentry"><span class="refentrytitle">glPixelStore</span></span></a>,
<a class="citerefentry" href="glTexImage1D"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a>,
<a class="citerefentry" href="glTexImage2D"><span class="citerefentry"><span class="refentrytitle">glTexImage2D</span></span></a>,
<a class="citerefentry" href="glTexImage3D"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a>,
<a class="citerefentry" href="glTexSubImage1D"><span class="citerefentry"><span class="refentrytitle">glTexSubImage1D</span></span></a>,
<a class="citerefentry" href="glTexSubImage3D"><span class="citerefentry"><span class="refentrytitle">glTexSubImage3D</span></span></a>,
<a class="citerefentry" href="glTexParameter"><span class="citerefentry"><span class="refentrytitle">glTexParameter</span></span></a>
</p></div><div class="refsect1"><div id="Copyright"><h2>Copyright</h2><p>
Copyright © 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
<a class="ulink" href="https://web.archive.org/web/20171022161616/http://oss.sgi.com/projects/FreeB/" target="_top">https://web.archive.org/web/20171022161616/http://oss.sgi.com/projects/FreeB/</a>.
</p></div></div></div>