1 <?xml version=
"1.0" encoding=
"UTF-8"?>
2 <!DOCTYPE book PUBLIC
"-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
3 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
4 <refentry id=
"glTexSubImage2D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glTexSubImage2D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glTexSubImage2D
</refname>
17 <refpurpose>specify a two-dimensional texture subimage
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glTexSubImage2D
</function></funcdef>
23 <paramdef>GLenum
<parameter>target
</parameter></paramdef>
24 <paramdef>GLint
<parameter>level
</parameter></paramdef>
25 <paramdef>GLint
<parameter>xoffset
</parameter></paramdef>
26 <paramdef>GLint
<parameter>yoffset
</parameter></paramdef>
27 <paramdef>GLsizei
<parameter>width
</parameter></paramdef>
28 <paramdef>GLsizei
<parameter>height
</parameter></paramdef>
29 <paramdef>GLenum
<parameter>format
</parameter></paramdef>
30 <paramdef>GLenum
<parameter>type
</parameter></paramdef>
31 <paramdef>const GLvoid *
<parameter>data
</parameter></paramdef>
35 <!-- eqn: ignoring delim $$ -->
38 <refsect1 id=
"parameters"><title>Parameters
</title>
41 <term><parameter>target
</parameter></term>
44 Specifies the target texture.
45 Must be
<constant>GL_TEXTURE_2D
</constant>,
46 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X
</constant>,
47 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X
</constant>,
48 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y
</constant>,
49 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
</constant>,
50 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z
</constant>, or
51 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
</constant>.
56 <term><parameter>level
</parameter></term>
59 Specifies the level-of-detail number.
60 Level
0 is the base image level.
61 Level
<emphasis>n
</emphasis> is the
<emphasis>n
</emphasis>th mipmap reduction image.
66 <term><parameter>xoffset
</parameter></term>
69 Specifies a texel offset in the x direction within the texture array.
74 <term><parameter>yoffset
</parameter></term>
77 Specifies a texel offset in the y direction within the texture array.
82 <term><parameter>width
</parameter></term>
85 Specifies the width of the texture subimage.
90 <term><parameter>height
</parameter></term>
93 Specifies the height of the texture subimage.
98 <term><parameter>format
</parameter></term>
101 Specifies the format of the pixel data.
102 The following symbolic values are accepted:
103 <constant>GL_COLOR_INDEX
</constant>,
104 <constant>GL_RED
</constant>,
105 <constant>GL_GREEN
</constant>,
106 <constant>GL_BLUE
</constant>,
107 <constant>GL_ALPHA
</constant>,
108 <constant>GL_RGB
</constant>,
109 <constant>GL_BGR
</constant>,
110 <constant>GL_RGBA
</constant>,
111 <constant>GL_BGRA
</constant>,
112 <constant>GL_LUMINANCE
</constant>, and
113 <constant>GL_LUMINANCE_ALPHA
</constant>.
118 <term><parameter>type
</parameter></term>
121 Specifies the data type of the pixel data.
122 The following symbolic values are accepted:
123 <constant>GL_UNSIGNED_BYTE
</constant>,
124 <constant>GL_BYTE
</constant>,
125 <constant>GL_BITMAP
</constant>,
126 <constant>GL_UNSIGNED_SHORT
</constant>,
127 <constant>GL_SHORT
</constant>,
128 <constant>GL_UNSIGNED_INT
</constant>,
129 <constant>GL_INT
</constant>,
130 <constant>GL_FLOAT
</constant>,
131 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
132 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
133 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>,
134 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>,
135 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
136 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
137 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
138 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
139 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
140 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
141 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, and
142 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant>.
147 <term><parameter>data
</parameter></term>
150 Specifies a pointer to the image data in memory.
156 <refsect1 id=
"description"><title>Description
</title>
158 Texturing maps a portion of a specified texture image
159 onto each graphical primitive for which texturing is enabled.
160 To enable and disable two-dimensional texturing, call
<citerefentry><refentrytitle>glEnable
</refentrytitle></citerefentry>
161 and
<citerefentry><refentrytitle>glDisable
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_2D
</constant>.
164 <function>glTexSubImage2D
</function> redefines a contiguous subregion of an existing two-dimensional
166 The texels referenced by
<parameter>data
</parameter> replace the portion of the
167 existing texture array with x indices
<parameter>xoffset
</parameter> and
168 <inlineequation><mml:math>
169 <!-- eqn: xoffset + width - 1:-->
171 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
173 <mml:mi mathvariant=
"italic">width
</mml:mi>
177 </mml:math></inlineequation>,
179 and y indices
<parameter>yoffset
</parameter> and
180 <inlineequation><mml:math>
181 <!-- eqn: yoffset + height - 1:-->
183 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
185 <mml:mi mathvariant=
"italic">height
</mml:mi>
189 </mml:math></inlineequation>,
191 This region may not include any texels outside the range of the
192 texture array as it was originally specified.
193 It is not an error to specify a subtexture with zero width or height, but
194 such a specification has no effect.
197 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
198 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
199 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
202 <refsect1 id=
"notes"><title>Notes
</title>
204 <function>glTexSubImage2D
</function> is available only if the GL version is
1.1 or greater.
207 Texturing has no effect in color index mode.
210 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry> modes affect texture images
211 in exactly the way they affect
<citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>.
214 Formats
<constant>GL_BGR
</constant>, and
<constant>GL_BGRA
</constant> and types
215 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
216 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
217 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>,
218 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>,
219 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
220 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
221 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
222 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
223 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
224 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
225 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, and
226 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant> are available only if the GL version
230 For OpenGL versions
1.3 and greater, or when the
<code>ARB_multitexture
</code> extension is supported,
<function>glTexSubImage2D
</function>
231 specifies a two-dimensional subtexture for the current texture unit,
232 specified with
<citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>.
235 When the
<code>ARB_imaging
</code> extension is supported, the RGBA components
236 specified in
<parameter>data
</parameter> may be processed by the imaging pipeline. See
237 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry> for specific details.
240 <refsect1 id=
"errors"><title>Errors
</title>
242 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>target
</parameter> is not
<constant>GL_TEXTURE_2D
</constant>,
243 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X
</constant>,
244 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X
</constant>,
245 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y
</constant>,
246 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
</constant>,
247 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z
</constant>, or
248 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
</constant>.
251 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>format
</parameter> is not an accepted
255 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>type
</parameter> is not a type constant.
258 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>type
</parameter> is
<constant>GL_BITMAP
</constant> and
259 <parameter>format
</parameter> is not
<constant>GL_COLOR_INDEX
</constant>.
262 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>level
</parameter> is less than
0.
265 <constant>GL_INVALID_VALUE
</constant> may be generated if
<parameter>level
</parameter> is greater
267 <inlineequation><mml:math>
268 <!-- eqn: log sub 2:-->
269 <mml:msub><mml:mi mathvariant=
"italic">log
</mml:mi>
272 </mml:math></inlineequation>
273 <emphasis>max
</emphasis>,
274 where
<emphasis>max
</emphasis> is the returned value of
<constant>GL_MAX_TEXTURE_SIZE
</constant>.
277 <constant>GL_INVALID_VALUE
</constant> is generated if
278 <inlineequation><mml:math>
279 <!-- eqn: xoffset < -b:-->
281 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
282 <mml:mo><</mml:mo>
285 <mml:mi mathvariant=
"italic">b
</mml:mi>
288 </mml:math></inlineequation>,
289 <inlineequation><mml:math>
290 <!-- eqn: (xoffset + width) > (w - b):-->
292 <mml:mfenced open=
"(" close=
")">
294 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
296 <mml:mi mathvariant=
"italic">width
</mml:mi>
299 <mml:mo>></mml:mo>
300 <mml:mfenced open=
"(" close=
")">
302 <mml:mi mathvariant=
"italic">w
</mml:mi>
304 <mml:mi mathvariant=
"italic">b
</mml:mi>
308 </mml:math></inlineequation>,
309 <inlineequation><mml:math>
310 <!-- eqn: yoffset < -b:-->
312 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
313 <mml:mo><</mml:mo>
316 <mml:mi mathvariant=
"italic">b
</mml:mi>
319 </mml:math></inlineequation>,
321 <inlineequation><mml:math>
322 <!-- eqn: (yoffset + height) > (h - b):-->
324 <mml:mfenced open=
"(" close=
")">
326 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
328 <mml:mi mathvariant=
"italic">height
</mml:mi>
331 <mml:mo>></mml:mo>
332 <mml:mfenced open=
"(" close=
")">
334 <mml:mi mathvariant=
"italic">h
</mml:mi>
336 <mml:mi mathvariant=
"italic">b
</mml:mi>
340 </mml:math></inlineequation>,
342 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
343 is the
<constant>GL_TEXTURE_WIDTH
</constant>,
344 <inlineequation><mml:math><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math></inlineequation>
345 is the
<constant>GL_TEXTURE_HEIGHT
</constant>, and
346 <inlineequation><mml:math><mml:mi mathvariant=
"italic">b
</mml:mi></mml:math></inlineequation>
348 of the texture image being modified.
350 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
352 <inlineequation><mml:math><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math></inlineequation>
353 include twice the border width.
356 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>width
</parameter> or
<parameter>height
</parameter> is less than
0.
359 <constant>GL_INVALID_OPERATION
</constant> is generated if the texture array has not
360 been defined by a previous
<citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry> operation.
363 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>type
</parameter> is one of
364 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
365 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
366 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>, or
367 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>
368 and
<parameter>format
</parameter> is not
<constant>GL_RGB
</constant>.
371 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>type
</parameter> is one of
372 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
373 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
374 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
375 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
376 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
377 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
378 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, or
379 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant>
380 and
<parameter>format
</parameter> is neither
<constant>GL_RGBA
</constant> nor
<constant>GL_BGRA
</constant>.
383 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
384 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
387 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
388 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
389 object such that the memory reads required would exceed the data store size.
392 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
393 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and
<parameter>data
</parameter> is not evenly divisible
394 into the number of bytes needed to store in memory a datum indicated by
<parameter>type
</parameter>.
397 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glTexSubImage2D
</function> is executed
398 between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry> and the corresponding
399 execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
402 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
404 <citerefentry><refentrytitle>glGetTexImage
</refentrytitle></citerefentry>
407 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_2D
</constant>
410 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
413 <refsect1 id=
"seealso"><title>See Also
</title>
415 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
416 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
417 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
418 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
419 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
420 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
421 <citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>,
422 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
423 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>,
424 <citerefentry><refentrytitle>glTexEnv
</refentrytitle></citerefentry>,
425 <citerefentry><refentrytitle>glTexGen
</refentrytitle></citerefentry>,
426 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
427 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
428 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
429 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
430 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>,
431 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
434 <refsect1 id=
"Copyright"><title>Copyright
</title>
436 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
437 Silicon Graphics, Inc. This document is licensed under the SGI
438 Free Software B License. For details, see
439 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.