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 allows elements of an image array to be read by shaders.
131 <function>glCompressedTexSubImage3D
</function> redefines a contiguous subregion of an existing three-dimensional
132 texture image. The texels referenced by
<parameter>data
</parameter> replace the portion of the
133 existing texture array with x indices
<parameter>xoffset
</parameter> and
134 <inlineequation><mml:math>
135 <!-- eqn: xoffset + width - 1: -->
137 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
139 <mml:mi mathvariant=
"italic">width
</mml:mi>
143 </mml:math></inlineequation>,
144 and the y indices
<parameter>yoffset
</parameter> and
145 <inlineequation><mml:math>
146 <!-- eqn: yoffset + height - 1: -->
148 <mml:mi mathvariant=
"italic">yoffset
</mml:mi>
150 <mml:mi mathvariant=
"italic">height
</mml:mi>
154 </mml:math></inlineequation>,
155 and the z indices
<parameter>zoffset
</parameter> and
156 <inlineequation><mml:math>
157 <!-- eqn: zoffset + depth - 1: -->
159 <mml:mi mathvariant=
"italic">zoffset
</mml:mi>
161 <mml:mi mathvariant=
"italic">depth
</mml:mi>
165 </mml:math></inlineequation>,
166 inclusive. This region may not include
167 any texels outside the range of the texture array as it was originally
168 specified. It is not an error to specify a subtexture with width of
0,
169 but such a specification has no effect.
172 <parameter>internalformat
</parameter> must be a known compressed image format (such as
<constant>GL_RGTC
</constant>)
173 or an extension-specified compressed-texture format.
174 The
<parameter>format
</parameter> of the compressed texture
175 image is selected by the GL implementation that compressed it (see
176 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>) and should be queried at the time the texture was
177 compressed with
<citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry>.
180 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
181 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
182 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
185 <refsect1 id=
"errors"><title>Errors
</title>
187 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is one of the generic compressed internal formats:
188 <constant>GL_COMPRESSED_RED
</constant>,
189 <constant>GL_COMPRESSED_RG
</constant>,
190 <constant>GL_COMPRESSED_RGB
</constant>,
191 <constant>GL_COMPRESSED_RGBA
</constant>.
192 <constant>GL_COMPRESSED_SRGB
</constant>, or
193 <constant>GL_COMPRESSED_SRGB_ALPHA
</constant>.
196 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>imageSize
</parameter> is not consistent with
197 the format, dimensions, and contents of the specified compressed image
201 <constant>GL_INVALID_OPERATION
</constant> is generated if parameter combinations are not
202 supported by the specific compressed internal format as specified in the
203 specific texture compression extension.
206 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
207 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
210 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
211 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
212 object such that the memory reads required would exceed the data store size.
215 Undefined results, including abnormal program termination, are generated if
216 <parameter>data
</parameter> is not encoded in a manner consistent with the extension
217 specification defining the internal compression format.
220 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
222 <citerefentry><refentrytitle>glGetCompressedTexImage
</refentrytitle></citerefentry>
225 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_COMPRESSED
</constant>
228 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
231 <citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry> with arguments
<constant>GL_TEXTURE_INTERNAL_FORMAT
</constant>
232 and
<constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE
</constant>
235 <refsect1 id=
"seealso"><title>See Also
</title>
237 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
238 <citerefentry><refentrytitle>glCompressedTexImage1D
</refentrytitle></citerefentry>,
239 <citerefentry><refentrytitle>glCompressedTexImage2D
</refentrytitle></citerefentry>,
240 <citerefentry><refentrytitle>glCompressedTexImage3D
</refentrytitle></citerefentry>,
241 <citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>,
242 <citerefentry><refentrytitle>glCompressedTexSubImage2D
</refentrytitle></citerefentry>,
243 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
244 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
245 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
246 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
247 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
248 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
249 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
250 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
251 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
252 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
253 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>,
254 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
257 <refsect1 id=
"Copyright"><title>Copyright
</title>
259 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
260 Silicon Graphics, Inc. This document is licensed under the SGI
261 Free Software B License. For details, see
262 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.