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=
"glTexSubImage3D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glTexSubImage3D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glTexSubImage3D
</refname>
17 <refpurpose>specify a three-dimensional texture subimage
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glTexSubImage3D
</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>GLint
<parameter>zoffset
</parameter></paramdef>
28 <paramdef>GLsizei
<parameter>width
</parameter></paramdef>
29 <paramdef>GLsizei
<parameter>height
</parameter></paramdef>
30 <paramdef>GLsizei
<parameter>depth
</parameter></paramdef>
31 <paramdef>GLenum
<parameter>format
</parameter></paramdef>
32 <paramdef>GLenum
<parameter>type
</parameter></paramdef>
33 <paramdef>const GLvoid *
<parameter>data
</parameter></paramdef>
37 <!-- eqn: ignoring delim $$ -->
40 <refsect1 id=
"parameters"><title>Parameters
</title>
43 <term><parameter>target
</parameter></term>
46 Specifies the target texture.
47 Must be
<constant>GL_TEXTURE_3D
</constant>.
52 <term><parameter>level
</parameter></term>
55 Specifies the level-of-detail number.
56 Level
0 is the base image level.
57 Level
<emphasis>n
</emphasis> is the
<emphasis>n
</emphasis>th mipmap reduction image.
62 <term><parameter>xoffset
</parameter></term>
65 Specifies a texel offset in the x direction within the texture array.
70 <term><parameter>yoffset
</parameter></term>
73 Specifies a texel offset in the y direction within the texture array.
78 <term><parameter>zoffset
</parameter></term>
81 Specifies a texel offset in the z direction within the texture array.
86 <term><parameter>width
</parameter></term>
89 Specifies the width of the texture subimage.
94 <term><parameter>height
</parameter></term>
97 Specifies the height of the texture subimage.
102 <term><parameter>depth
</parameter></term>
105 Specifies the depth of the texture subimage.
110 <term><parameter>format
</parameter></term>
113 Specifies the format of the pixel data.
114 The following symbolic values are accepted:
115 <constant>GL_COLOR_INDEX
</constant>,
116 <constant>GL_RED
</constant>,
117 <constant>GL_GREEN
</constant>,
118 <constant>GL_BLUE
</constant>,
119 <constant>GL_ALPHA
</constant>,
120 <constant>GL_RGB
</constant>,
121 <constant>GL_BGR
</constant>,
122 <constant>GL_RGBA
</constant>,
123 <constant>GL_BGRA
</constant>,
124 <constant>GL_LUMINANCE
</constant>, and
125 <constant>GL_LUMINANCE_ALPHA
</constant>.
130 <term><parameter>type
</parameter></term>
133 Specifies the data type of the pixel data.
134 The following symbolic values are accepted:
135 <constant>GL_UNSIGNED_BYTE
</constant>,
136 <constant>GL_BYTE
</constant>,
137 <constant>GL_BITMAP
</constant>,
138 <constant>GL_UNSIGNED_SHORT
</constant>,
139 <constant>GL_SHORT
</constant>,
140 <constant>GL_UNSIGNED_INT
</constant>,
141 <constant>GL_INT
</constant>,
142 <constant>GL_FLOAT
</constant>,
143 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
144 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
145 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>,
146 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>,
147 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
148 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
149 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
150 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
151 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
152 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
153 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, and
154 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant>.
159 <term><parameter>data
</parameter></term>
162 Specifies a pointer to the image data in memory.
168 <refsect1 id=
"description"><title>Description
</title>
170 Texturing maps a portion of a specified texture image
171 onto each graphical primitive for which texturing is enabled.
172 To enable and disable three-dimensional texturing, call
<citerefentry><refentrytitle>glEnable
</refentrytitle></citerefentry>
173 and
<citerefentry><refentrytitle>glDisable
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_3D
</constant>.
176 <function>glTexSubImage3D
</function> redefines a contiguous subregion of an existing three-dimensional
178 The texels referenced by
<parameter>data
</parameter> replace the portion of the
179 existing texture array with x indices
<parameter>xoffset
</parameter> and
180 <inlineequation><mml:math>
181 <!-- eqn: xoffset + width - 1:-->
183 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
185 <mml:mi mathvariant=
"italic">width
</mml:mi>
189 </mml:math></inlineequation>,
191 y indices
<parameter>yoffset
</parameter> and
192 <inlineequation><mml:math>
193 <!-- eqn: yoffset + height - 1:-->
195 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
197 <mml:mi mathvariant=
"italic">height
</mml:mi>
201 </mml:math></inlineequation>,
203 and z indices
<parameter>zoffset
</parameter> and
204 <inlineequation><mml:math>
205 <!-- eqn: zoffset + depth - 1:-->
207 <mml:mi mathvariant=
"italic">zoffset
</mml:mi>
209 <mml:mi mathvariant=
"italic">depth
</mml:mi>
213 </mml:math></inlineequation>,
215 This region may not include any texels outside the range of the
216 texture array as it was originally specified.
217 It is not an error to specify a subtexture with zero width, height, or
218 depth but such a specification has no effect.
221 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
222 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
223 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
226 <refsect1 id=
"notes"><title>Notes
</title>
228 <function>glTexSubImage3D
</function> is available only if the GL version is
1.2 or greater.
231 Texturing has no effect in color index mode.
234 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry> modes affect texture images
235 in exactly the way they affect
<citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>.
238 Formats
<constant>GL_BGR
</constant>, and
<constant>GL_BGRA
</constant> and types
239 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
240 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
241 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>,
242 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>,
243 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
244 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
245 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
246 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
247 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
248 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
249 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, and
250 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant> are available only if the GL version
254 For OpenGL versions
1.3 and greater, or when the
<code>ARB_multitexture
</code> extension is supported,
<function>glTexSubImage3D
</function>
255 specifies a three-dimensional subtexture for the current texture unit,
256 specified with
<citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>.
259 When the
<code>ARB_imaging
</code> extension is supported, the RGBA components
260 specified in
<parameter>data
</parameter> may be processed by the imaging pipeline. See
261 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> for specific details.
264 <refsect1 id=
"errors"><title>Errors
</title>
266 <constant>GL_INVALID_ENUM
</constant> is generated if /
<parameter>target
</parameter> is not
<constant>GL_TEXTURE_3D
</constant>.
269 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>format
</parameter> is not an accepted
273 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>type
</parameter> is not a type constant.
276 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>type
</parameter> is
<constant>GL_BITMAP
</constant> and
277 <parameter>format
</parameter> is not
<constant>GL_COLOR_INDEX
</constant>.
280 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>level
</parameter> is less than
0.
283 <constant>GL_INVALID_VALUE
</constant> may be generated if
<parameter>level
</parameter> is greater
285 <inlineequation><mml:math>
286 <!-- eqn: log sub 2:-->
287 <mml:msub><mml:mi mathvariant=
"italic">log
</mml:mi>
290 </mml:math></inlineequation>
291 <emphasis>max
</emphasis>,
292 where
<emphasis>max
</emphasis> is the returned value of
<constant>GL_MAX_TEXTURE_SIZE
</constant>.
295 <constant>GL_INVALID_VALUE
</constant> is generated if
296 <inlineequation><mml:math>
297 <!-- eqn: xoffset < -b:-->
299 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
300 <mml:mo><</mml:mo>
303 <mml:mi mathvariant=
"italic">b
</mml:mi>
306 </mml:math></inlineequation>,
307 <inlineequation><mml:math>
308 <!-- eqn: (xoffset + width) > (w - b):-->
310 <mml:mfenced open=
"(" close=
")">
312 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
314 <mml:mi mathvariant=
"italic">width
</mml:mi>
317 <mml:mo>></mml:mo>
318 <mml:mfenced open=
"(" close=
")">
320 <mml:mi mathvariant=
"italic">w
</mml:mi>
322 <mml:mi mathvariant=
"italic">b
</mml:mi>
326 </mml:math></inlineequation>,
327 <inlineequation><mml:math>
328 <!-- eqn: yoffset < -b:-->
330 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
331 <mml:mo><</mml:mo>
334 <mml:mi mathvariant=
"italic">b
</mml:mi>
337 </mml:math></inlineequation>,
339 <inlineequation><mml:math>
340 <!-- eqn: (yoffset + height) > (h - b):-->
342 <mml:mfenced open=
"(" close=
")">
344 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
346 <mml:mi mathvariant=
"italic">height
</mml:mi>
349 <mml:mo>></mml:mo>
350 <mml:mfenced open=
"(" close=
")">
352 <mml:mi mathvariant=
"italic">h
</mml:mi>
354 <mml:mi mathvariant=
"italic">b
</mml:mi>
358 </mml:math></inlineequation>,
360 <inlineequation><mml:math>
361 <!-- eqn: zoffset < -b:-->
363 <mml:mi mathvariant=
"italic">zoffset
</mml:mi>
364 <mml:mo><</mml:mo>
367 <mml:mi mathvariant=
"italic">b
</mml:mi>
370 </mml:math></inlineequation>,
372 <inlineequation><mml:math>
373 <!-- eqn: (zoffset + depth) > (d - b):-->
375 <mml:mfenced open=
"(" close=
")">
377 <mml:mi mathvariant=
"italic">zoffset
</mml:mi>
379 <mml:mi mathvariant=
"italic">depth
</mml:mi>
382 <mml:mo>></mml:mo>
383 <mml:mfenced open=
"(" close=
")">
385 <mml:mi mathvariant=
"italic">d
</mml:mi>
387 <mml:mi mathvariant=
"italic">b
</mml:mi>
391 </mml:math></inlineequation>,
393 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
394 is the
<constant>GL_TEXTURE_WIDTH
</constant>,
395 <inlineequation><mml:math><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math></inlineequation>
396 is the
<constant>GL_TEXTURE_HEIGHT
</constant>,
397 <inlineequation><mml:math><mml:mi mathvariant=
"italic">d
</mml:mi></mml:math></inlineequation>
398 is the
<constant>GL_TEXTURE_DEPTH
</constant>
400 <inlineequation><mml:math><mml:mi mathvariant=
"italic">b
</mml:mi></mml:math></inlineequation>
401 is the border width of the texture image being modified.
403 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>,
404 <inlineequation><mml:math><mml:mi mathvariant=
"italic">h
</mml:mi></mml:math></inlineequation>,
406 <inlineequation><mml:math><mml:mi mathvariant=
"italic">d
</mml:mi></mml:math></inlineequation>
407 include twice the border width.
410 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>width
</parameter>,
<parameter>height
</parameter>, or
<parameter>depth
</parameter>
414 <constant>GL_INVALID_OPERATION
</constant> is generated if the texture array has not
415 been defined by a previous
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry> operation.
418 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>type
</parameter> is one of
419 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
420 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
421 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>, or
422 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>
423 and
<parameter>format
</parameter> is not
<constant>GL_RGB
</constant>.
426 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>type
</parameter> is one of
427 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
428 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
429 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
430 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
431 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
432 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
433 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, or
434 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant>
435 and
<parameter>format
</parameter> is neither
<constant>GL_RGBA
</constant> nor
<constant>GL_BGRA
</constant>.
438 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
439 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
442 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
443 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
444 object such that the memory reads required would exceed the data store size.
447 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
448 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and
<parameter>data
</parameter> is not evenly divisible
449 into the number of bytes needed to store in memory a datum indicated by
<parameter>type
</parameter>.
452 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glTexSubImage3D
</function> is executed
453 between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry> and the corresponding
454 execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
457 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
459 <citerefentry><refentrytitle>glGetTexImage
</refentrytitle></citerefentry>
462 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_3D
</constant>
465 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
468 <refsect1 id=
"seealso"><title>See Also
</title>
470 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
471 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
472 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
473 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
474 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
475 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
476 <citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>,
477 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
478 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>,
479 <citerefentry><refentrytitle>glTexEnv
</refentrytitle></citerefentry>,
480 <citerefentry><refentrytitle>glTexGen
</refentrytitle></citerefentry>,
481 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
482 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
483 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
484 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
485 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
486 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
489 <refsect1 id=
"Copyright"><title>Copyright
</title>
491 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
492 Silicon Graphics, Inc. This document is licensed under the SGI
493 Free Software B License. For details, see
494 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.