1 <?xml version=
"1.0" encoding=
"UTF-8"?>
2 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
3 <!-- saved from url=(0013)about:internet -->
4 <?xml-stylesheet type=
"text/xsl" href=
"mathml.xsl"?><html xmlns=
"http://www.w3.org/1999/xhtml" xmlns:
pref=
"http://www.w3.org/2002/Math/preference" pref:
renderer=
"mathplayer-dl"><head><meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" /><link rel=
"stylesheet" type=
"text/css" href=
"opengl-man.css" /><title>glTexSubImage2D - OpenGL
4 Reference Pages
</title><meta name=
"generator" content=
"DocBook XSL Stylesheets V1.69.1" /></head><body><div class=
"refentry" lang=
"en" xml:
lang=
"en"><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 border=
"0" summary=
"Function synopsis" cellspacing=
"0" cellpadding=
"0"><tr><td><code class=
"funcdef">void
<b class=
"fsfunc">glTexSubImage2D
</b>(
</code></td><td>GLenum
</td><td><var class=
"pdparam">target
</var>,
</td></tr><tr><td> </td><td>GLint
</td><td><var class=
"pdparam">level
</var>,
</td></tr><tr><td> </td><td>GLint
</td><td><var class=
"pdparam">xoffset
</var>,
</td></tr><tr><td> </td><td>GLint
</td><td><var class=
"pdparam">yoffset
</var>,
</td></tr><tr><td> </td><td>GLsizei
</td><td><var class=
"pdparam">width
</var>,
</td></tr><tr><td> </td><td>GLsizei
</td><td><var class=
"pdparam">height
</var>,
</td></tr><tr><td> </td><td>GLenum
</td><td><var class=
"pdparam">format
</var>,
</td></tr><tr><td> </td><td>GLenum
</td><td><var class=
"pdparam">type
</var>,
</td></tr><tr><td> </td><td>const GLvoid *
</td><td><var class=
"pdparam">data
</var><code>)
</code>;
</td></tr></table></div></div><p>
5 </p><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"parameters"></a><h2>Parameters
</h2><div class=
"variablelist"><dl><dt><span class=
"term"><em class=
"parameter"><code>target
</code></em></span></dt><dd><p>
6 Specifies the target texture.
7 Must be
<code class=
"constant">GL_TEXTURE_2D
</code>,
8 <code class=
"constant">GL_TEXTURE_CUBE_MAP_POSITIVE_X
</code>,
9 <code class=
"constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_X
</code>,
10 <code class=
"constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Y
</code>,
11 <code class=
"constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
</code>,
12 <code class=
"constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Z
</code>,
13 <code class=
"constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
</code>,
14 or
<code class=
"constant">GL_TEXTURE_1D_ARRAY
</code>.
15 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>level
</code></em></span></dt><dd><p>
16 Specifies the level-of-detail number.
17 Level
0 is the base image level.
18 Level
<span class=
"emphasis"><em>n
</em></span> is the
<span class=
"emphasis"><em>n
</em></span>th mipmap reduction image.
19 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>xoffset
</code></em></span></dt><dd><p>
20 Specifies a texel offset in the x direction within the texture array.
21 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>yoffset
</code></em></span></dt><dd><p>
22 Specifies a texel offset in the y direction within the texture array.
23 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>width
</code></em></span></dt><dd><p>
24 Specifies the width of the texture subimage.
25 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>height
</code></em></span></dt><dd><p>
26 Specifies the height of the texture subimage.
27 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>format
</code></em></span></dt><dd><p>
28 Specifies the format of the pixel data.
29 The following symbolic values are accepted:
30 <code class=
"constant">GL_RED
</code>,
31 <code class=
"constant">GL_RG
</code>,
32 <code class=
"constant">GL_RGB
</code>,
33 <code class=
"constant">GL_BGR
</code>,
34 <code class=
"constant">GL_RGBA
</code>, and
35 <code class=
"constant">GL_BGRA
</code>.
36 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>type
</code></em></span></dt><dd><p>
37 Specifies the data type of the pixel data.
38 The following symbolic values are accepted:
39 <code class=
"constant">GL_UNSIGNED_BYTE
</code>,
40 <code class=
"constant">GL_BYTE
</code>,
41 <code class=
"constant">GL_UNSIGNED_SHORT
</code>,
42 <code class=
"constant">GL_SHORT
</code>,
43 <code class=
"constant">GL_UNSIGNED_INT
</code>,
44 <code class=
"constant">GL_INT
</code>,
45 <code class=
"constant">GL_FLOAT
</code>,
46 <code class=
"constant">GL_UNSIGNED_BYTE_3_3_2
</code>,
47 <code class=
"constant">GL_UNSIGNED_BYTE_2_3_3_REV
</code>,
48 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5
</code>,
49 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5_REV
</code>,
50 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4
</code>,
51 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4_REV
</code>,
52 <code class=
"constant">GL_UNSIGNED_SHORT_5_5_5_1
</code>,
53 <code class=
"constant">GL_UNSIGNED_SHORT_1_5_5_5_REV
</code>,
54 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8
</code>,
55 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8_REV
</code>,
56 <code class=
"constant">GL_UNSIGNED_INT_10_10_10_2
</code>, and
57 <code class=
"constant">GL_UNSIGNED_INT_2_10_10_10_REV
</code>.
58 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>data
</code></em></span></dt><dd><p>
59 Specifies a pointer to the image data in memory.
60 </p></dd></dl></div></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"description"></a><h2>Description
</h2><p>
61 Texturing maps a portion of a specified texture image
62 onto each graphical primitive for which texturing is enabled.
64 <code class=
"function">glTexSubImage2D
</code> redefines a contiguous subregion of an existing two-dimensional
65 or one-dimensional arary texture image.
66 The texels referenced by
<em class=
"parameter"><code>data
</code></em> replace the portion of the
67 existing texture array with x indices
<em class=
"parameter"><code>xoffset
</code></em> and
68 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
71 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
73 <mml:mi mathvariant=
"italic">width
</mml:mi>
79 and y indices
<em class=
"parameter"><code>yoffset
</code></em> and
80 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
83 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
85 <mml:mi mathvariant=
"italic">height
</mml:mi>
91 This region may not include any texels outside the range of the
92 texture array as it was originally specified.
93 It is not an error to specify a subtexture with zero width or height, but
94 such a specification has no effect.
96 If a non-zero named buffer object is bound to the
<code class=
"constant">GL_PIXEL_UNPACK_BUFFER
</code> target
97 (see
<a href=
"glBindBuffer.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glBindBuffer
</span></span></a>) while a texture image is
98 specified,
<em class=
"parameter"><code>data
</code></em> is treated as a byte offset into the buffer object's data store.
99 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"notes"></a><h2>Notes
</h2><p>
100 <a href=
"glPixelStore.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelStore
</span></span></a> modes affect texture images.
102 <code class=
"function">glTexSubImage2D
</code> specifies a two-dimensional subtexture for the current texture unit,
103 specified with
<a href=
"glActiveTexture.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glActiveTexture
</span></span></a>.
104 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"errors"></a><h2>Errors
</h2><p>
105 <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>,
106 <code class=
"constant">GL_TEXTURE_CUBE_MAP_POSITIVE_X
</code>,
107 <code class=
"constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_X
</code>,
108 <code class=
"constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Y
</code>,
109 <code class=
"constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
</code>,
110 <code class=
"constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Z
</code>,
111 <code class=
"constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
</code>, or
112 <code class=
"constant">GL_TEXTURE_1D_ARRAY
</code>.
114 <code class=
"constant">GL_INVALID_ENUM
</code> is generated if
<em class=
"parameter"><code>format
</code></em> is not an accepted
117 <code class=
"constant">GL_INVALID_ENUM
</code> is generated if
<em class=
"parameter"><code>type
</code></em> is not a type constant.
119 <code class=
"constant">GL_INVALID_VALUE
</code> is generated if
<em class=
"parameter"><code>level
</code></em> is less than
0.
121 <code class=
"constant">GL_INVALID_VALUE
</code> may be generated if
<em class=
"parameter"><code>level
</code></em> is greater
123 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
125 <mml:msub><mml:mi mathvariant=
"italic">log
</mml:mi>
129 <span class=
"emphasis"><em>max
</em></span>,
130 where
<span class=
"emphasis"><em>max
</em></span> is the returned value of
<code class=
"constant">GL_MAX_TEXTURE_SIZE
</code>.
132 <code class=
"constant">GL_INVALID_VALUE
</code> is generated if
133 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
136 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
137 <mml:mo><</mml:mo>
140 <mml:mi mathvariant=
"italic">b
</mml:mi>
144 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
147 <mml:mfenced open=
"(" close=
")">
149 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
151 <mml:mi mathvariant=
"italic">width
</mml:mi>
154 <mml:mo>></mml:mo>
155 <mml:mfenced open=
"(" close=
")">
157 <mml:mi mathvariant=
"italic">w
</mml:mi>
159 <mml:mi mathvariant=
"italic">b
</mml:mi>
164 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
167 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
168 <mml:mo><</mml:mo>
171 <mml:mi mathvariant=
"italic">b
</mml:mi>
176 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
179 <mml:mfenced open=
"(" close=
")">
181 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
183 <mml:mi mathvariant=
"italic">height
</mml:mi>
186 <mml:mo>></mml:mo>
187 <mml:mfenced open=
"(" close=
")">
189 <mml:mi mathvariant=
"italic">h
</mml:mi>
191 <mml:mi mathvariant=
"italic">b
</mml:mi>
197 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math>
198 is the
<code class=
"constant">GL_TEXTURE_WIDTH
</code>,
199 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math>
200 is the
<code class=
"constant">GL_TEXTURE_HEIGHT
</code>, and
201 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">b
</mml:mi></mml:math>
203 of the texture image being modified.
205 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math>
207 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math>
208 include twice the border width.
210 <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.
212 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if the texture array has not
213 been defined by a previous
<a href=
"glTexImage2D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glTexImage2D
</span></span></a> operation.
215 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if
<em class=
"parameter"><code>type
</code></em> is one of
216 <code class=
"constant">GL_UNSIGNED_BYTE_3_3_2
</code>,
217 <code class=
"constant">GL_UNSIGNED_BYTE_2_3_3_REV
</code>,
218 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5
</code>, or
219 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5_REV
</code>
220 and
<em class=
"parameter"><code>format
</code></em> is not
<code class=
"constant">GL_RGB
</code>.
222 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if
<em class=
"parameter"><code>type
</code></em> is one of
223 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4
</code>,
224 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4_REV
</code>,
225 <code class=
"constant">GL_UNSIGNED_SHORT_5_5_5_1
</code>,
226 <code class=
"constant">GL_UNSIGNED_SHORT_1_5_5_5_REV
</code>,
227 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8
</code>,
228 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8_REV
</code>,
229 <code class=
"constant">GL_UNSIGNED_INT_10_10_10_2
</code>, or
230 <code class=
"constant">GL_UNSIGNED_INT_2_10_10_10_REV
</code>
231 and
<em class=
"parameter"><code>format
</code></em> is neither
<code class=
"constant">GL_RGBA
</code> nor
<code class=
"constant">GL_BGRA
</code>.
233 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if a non-zero buffer object name is bound to the
234 <code class=
"constant">GL_PIXEL_UNPACK_BUFFER
</code> target and the buffer object's data store is currently mapped.
236 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if a non-zero buffer object name is bound to the
237 <code class=
"constant">GL_PIXEL_UNPACK_BUFFER
</code> target and the data would be unpacked from the buffer
238 object such that the memory reads required would exceed the data store size.
240 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if a non-zero buffer object name is bound to the
241 <code class=
"constant">GL_PIXEL_UNPACK_BUFFER
</code> target and
<em class=
"parameter"><code>data
</code></em> is not evenly divisible
242 into the number of bytes needed to store in memory a datum indicated by
<em class=
"parameter"><code>type
</code></em>.
243 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"associatedgets"></a><h2>Associated Gets
</h2><p>
244 <a href=
"glGetTexImage.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glGetTexImage
</span></span></a>
246 <a href=
"glGet.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glGet
</span></span></a> with argument
<code class=
"constant">GL_PIXEL_UNPACK_BUFFER_BINDING
</code>
247 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"seealso"></a><h2>See Also
</h2><p>
248 <a href=
"glActiveTexture.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glActiveTexture
</span></span></a>,
249 <a href=
"glCopyTexImage1D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glCopyTexImage1D
</span></span></a>,
250 <a href=
"glCopyTexImage2D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glCopyTexImage2D
</span></span></a>,
251 <a href=
"glCopyTexSubImage1D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glCopyTexSubImage1D
</span></span></a>,
252 <a href=
"glCopyTexSubImage2D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glCopyTexSubImage2D
</span></span></a>,
253 <a href=
"glCopyTexSubImage3D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glCopyTexSubImage3D
</span></span></a>,
254 <a href=
"glPixelStore.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelStore
</span></span></a>,
255 <a href=
"glTexImage1D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glTexImage1D
</span></span></a>,
256 <a href=
"glTexImage2D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glTexImage2D
</span></span></a>,
257 <a href=
"glTexImage3D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glTexImage3D
</span></span></a>,
258 <a href=
"glTexSubImage1D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glTexSubImage1D
</span></span></a>,
259 <a href=
"glTexSubImage3D.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glTexSubImage3D
</span></span></a>,
260 <a href=
"glTexParameter.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glTexParameter
</span></span></a>
261 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"Copyright"></a><h2>Copyright
</h2><p>
262 Copyright
<span class=
"trademark"></span>©
1991-
2006
263 Silicon Graphics, Inc. This document is licensed under the SGI
264 Free Software B License. For details, see
265 <a href=
"http://oss.sgi.com/projects/FreeB/" target=
"_top">http://oss.sgi.com/projects/FreeB/
</a>.
266 </p></div></div></body></html>