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=
"glCompressedTexSubImage3D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glCompressedTexSubImage3D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glCompressedTexSubImage3D
</refname>
17 <refpurpose>specify a three-dimensional texture subimage in a compressed format
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glCompressedTexSubImage3D
</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>GLsizei
<parameter>imageSize
</parameter></paramdef>
33 <paramdef>const GLvoid *
<parameter>data
</parameter></paramdef>
37 <!-- 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_3D
</constant>.
50 <term><parameter>level
</parameter></term>
53 Specifies the level-of-detail number.
54 Level
0 is the base image level.
55 Level
<emphasis>n
</emphasis> is the
<emphasis>n
</emphasis>th mipmap reduction image.
60 <term><parameter>xoffset
</parameter></term>
63 Specifies a texel offset in the x direction within the texture array.
68 <term><parameter>yoffset
</parameter></term>
71 Specifies a texel offset in the y direction within the texture array.
76 <term><parameter>width
</parameter></term>
79 Specifies the width of the texture subimage.
84 <term><parameter>height
</parameter></term>
87 Specifies the height of the texture subimage.
92 <term><parameter>depth
</parameter></term>
95 Specifies the depth of the texture subimage.
100 <term><parameter>format
</parameter></term>
103 Specifies the format of the compressed image data stored at address
<parameter>data
</parameter>.
108 <term><parameter>imageSize
</parameter></term>
111 Specifies the number of unsigned bytes of image data starting at the
112 address specified by
<parameter>data
</parameter>.
117 <term><parameter>data
</parameter></term>
120 Specifies a pointer to the compressed image data in memory.
126 <refsect1 id=
"description"><title>Description
</title>
128 Texturing maps a portion of a specified texture image onto each graphical
129 primitive for which texturing is enabled. To enable and disable
130 three-dimensional texturing, call
<citerefentry><refentrytitle>glEnable
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glDisable
</refentrytitle></citerefentry> with argument
131 <constant>GL_TEXTURE_3D
</constant>.
134 <function>glCompressedTexSubImage3D
</function> redefines a contiguous subregion of an existing three-dimensional
135 texture image. The texels referenced by
<parameter>data
</parameter> replace the portion of the
136 existing texture array with x indices
<parameter>xoffset
</parameter> and
137 <inlineequation><mml:math>
138 <!-- eqn: xoffset + width - 1:-->
140 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
142 <mml:mi mathvariant=
"italic">width
</mml:mi>
146 </mml:math></inlineequation>,
147 and the y indices
<parameter>yoffset
</parameter> and
148 <inlineequation><mml:math>
149 <!-- eqn: yoffset + height - 1:-->
151 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
153 <mml:mi mathvariant=
"italic">height
</mml:mi>
157 </mml:math></inlineequation>,
158 and the z indices
<parameter>zoffset
</parameter> and
159 <inlineequation><mml:math>
160 <!-- eqn: zoffset + depth - 1:-->
162 <mml:mi mathvariant=
"italic">zoffset
</mml:mi>
164 <mml:mi mathvariant=
"italic">depth
</mml:mi>
168 </mml:math></inlineequation>,
169 inclusive. This region may not include
170 any texels outside the range of the texture array as it was originally
171 specified. It is not an error to specify a subtexture with width of
0,
172 but such a specification has no effect.
175 <parameter>format
</parameter> must be an extension-specified
176 compressed-texture format. The
<parameter>format
</parameter> of the compressed texture
177 image is selected by the GL implementation that compressed it (see
178 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>) and should be queried at the time the texture was
179 compressed with
<citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry>.
182 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
183 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
184 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
187 <refsect1 id=
"notes"><title>Notes
</title>
189 <function>glCompressedTexSubImage3D
</function> is available only if the GL version is
1.3 or greater.
192 <refsect1 id=
"errors"><title>Errors
</title>
194 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>format
</parameter> is one of these generic compressed internal formats:
195 <constant>GL_COMPRESSED_ALPHA
</constant>,
196 <constant>GL_COMPRESSED_LUMINANCE
</constant>,
197 <constant>GL_COMPRESSED_LUMINANCE_ALPHA
</constant>,
198 <constant>GL_COMPRESSED_INTENSITY
</constant>,
199 <constant>GL_COMPRESSED_RGB
</constant>,
200 <constant>GL_COMPRESSED_RGBA
</constant>,
201 <constant>GL_COMPRESSED_SLUMINANCE
</constant>,
202 <constant>GL_COMPRESSED_SLUMINANCE_ALPHA
</constant>,
203 <constant>GL_COMPRESSED_SRGB
</constant>,
204 <constant>GL_COMPRESSED_SRGBA
</constant>, or
205 <constant>GL_COMPRESSED_SRGB_ALPHA
</constant>.
208 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>imageSize
</parameter> is not consistent with
209 the format, dimensions, and contents of the specified compressed image
213 <constant>GL_INVALID_OPERATION
</constant> is generated if parameter combinations are not
214 supported by the specific compressed internal format as specified in the
215 specific texture compression extension.
218 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
219 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
222 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
223 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
224 object such that the memory reads required would exceed the data store size.
227 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glCompressedTexSubImage3D
</function>
228 is executed between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry>
229 and the corresponding execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
232 Undefined results, including abnormal program termination, are generated if
233 <parameter>data
</parameter> is not encoded in a manner consistent with the extension
234 specification defining the internal compression format.
237 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
239 <citerefentry><refentrytitle>glGetCompressedTexImage
</refentrytitle></citerefentry>
242 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_COMPRESSED
</constant>
245 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
248 <citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry> with arguments
<constant>GL_TEXTURE_INTERNAL_FORMAT
</constant>
249 and
<constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE
</constant>
252 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_3D
</constant>
255 <refsect1 id=
"seealso"><title>See Also
</title>
257 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
258 <citerefentry><refentrytitle>glColorTable
</refentrytitle></citerefentry>,
259 <citerefentry><refentrytitle>glCompressedTexImage1D
</refentrytitle></citerefentry>,
260 <citerefentry><refentrytitle>glCompressedTexImage2D
</refentrytitle></citerefentry>,
261 <citerefentry><refentrytitle>glCompressedTexImage3D
</refentrytitle></citerefentry>,
262 <citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>,
263 <citerefentry><refentrytitle>glCompressedTexSubImage2D
</refentrytitle></citerefentry>,
264 <citerefentry><refentrytitle>glConvolutionFilter1D
</refentrytitle></citerefentry>,
265 <citerefentry><refentrytitle>glCopyPixels
</refentrytitle></citerefentry>,
266 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
267 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
268 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
269 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
270 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
271 <citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>,
272 <citerefentry><refentrytitle>glMatrixMode
</refentrytitle></citerefentry>,
273 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
274 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>,
275 <citerefentry><refentrytitle>glTexEnv
</refentrytitle></citerefentry>,
276 <citerefentry><refentrytitle>glTexGen
</refentrytitle></citerefentry>,
277 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
278 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
279 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
280 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
281 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>,
282 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
285 <refsect1 id=
"Copyright"><title>Copyright
</title>
287 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
288 Silicon Graphics, Inc. This document is licensed under the SGI
289 Free Software B License. For details, see
290 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.