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=
"glCompressedTexImage3D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glCompressedTexImage3D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glCompressedTexImage3D
</refname>
17 <refpurpose>specify a three-dimensional texture image in a compressed format
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glCompressedTexImage3D
</function></funcdef>
23 <paramdef>GLenum
<parameter>target
</parameter></paramdef>
24 <paramdef>GLint
<parameter>level
</parameter></paramdef>
25 <paramdef>GLenum
<parameter>internalformat
</parameter></paramdef>
26 <paramdef>GLsizei
<parameter>width
</parameter></paramdef>
27 <paramdef>GLsizei
<parameter>height
</parameter></paramdef>
28 <paramdef>GLsizei
<parameter>depth
</parameter></paramdef>
29 <paramdef>GLint
<parameter>border
</parameter></paramdef>
30 <paramdef>GLsizei
<parameter>imageSize
</parameter></paramdef>
31 <paramdef>const GLvoid *
<parameter>data
</parameter></paramdef>
35 <!-- eqn: ignoring delim $$ -->
36 <refsect1 id=
"parameters"><title>Parameters
</title>
39 <term><parameter>target
</parameter></term>
42 Specifies the target texture.
43 Must be
<constant>GL_TEXTURE_3D
</constant>,
<constant>GL_PROXY_TEXTURE_3D
</constant>,
44 <constant>GL_TEXTURE_2D_ARRAY
</constant> or
<constant>GL_PROXY_TEXTURE_2D_ARRAY
</constant>.
49 <term><parameter>level
</parameter></term>
52 Specifies the level-of-detail number.
53 Level
0 is the base image level.
54 Level
<emphasis>n
</emphasis> is the
<emphasis>n
</emphasis>th mipmap reduction image.
59 <term><parameter>internalformat
</parameter></term>
62 Specifies the format of the compressed image data stored at address
<parameter>data
</parameter>.
67 <term><parameter>width
</parameter></term>
70 Specifies the width of the texture image.
71 All implementations support
3D texture images that are at least
16 texels wide.
76 <term><parameter>height
</parameter></term>
79 Specifies the height of the texture image.
80 All implementations support
3D texture images that are at least
16 texels
86 <term><parameter>depth
</parameter></term>
89 Specifies the depth of the texture image.
90 All implementations support
3D texture images that are at least
16 texels
96 <term><parameter>border
</parameter></term>
104 <term><parameter>imageSize
</parameter></term>
107 Specifies the number of unsigned bytes of image data starting at the
108 address specified by
<parameter>data
</parameter>.
113 <term><parameter>data
</parameter></term>
116 Specifies a pointer to the compressed image data in memory.
122 <refsect1 id=
"description"><title>Description
</title>
124 Texturing allows elements of an image array to be read by shaders.
127 <function>glCompressedTexImage3D
</function> loads a previously defined, and retrieved, compressed three-dimensional
128 texture image if
<parameter>target
</parameter> is
<constant>GL_TEXTURE_3D
</constant> (see
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>).
131 If
<parameter>target
</parameter> is
<constant>GL_TEXTURE_2D_ARRAY
</constant>,
<parameter>data
</parameter> is
132 treated as an array of compressed
2D textures.
135 If
<parameter>target
</parameter> is
<constant>GL_PROXY_TEXTURE_3D
</constant> or
<constant>GL_PROXY_TEXTURE_2D_ARRAY
</constant>,
136 no data is read from
<parameter>data
</parameter>, but
137 all of the texture image state is recalculated, checked for consistency,
138 and checked against the implementation's capabilities. If the
139 implementation cannot handle a texture of the requested texture size, it
140 sets all of the image state to
0, but does not generate an error (see
141 <citerefentry><refentrytitle>glGetError
</refentrytitle></citerefentry>). To query for an entire mipmap array, use an image array level
142 greater than or equal to
1.
145 <parameter>internalformat
</parameter> must be a known compressed image format (such as
<constant>GL_RGTC
</constant>)
146 or an extension-specified compressed-texture format.
147 When a texture is loaded with
<citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry> using a generic compressed
148 texture format (e.g.,
<constant>GL_COMPRESSED_RGB
</constant>), the GL selects from one of
149 its extensions supporting compressed textures. In order to load the
150 compressed texture image using
<function>glCompressedTexImage3D
</function>, query the compressed texture image's
151 size and format using
<citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry>.
154 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
155 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
156 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
159 <refsect1 id=
"errors"><title>Errors
</title>
161 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is not one of the generic
162 compressed internal formats:
163 <constant>GL_COMPRESSED_RED
</constant>,
164 <constant>GL_COMPRESSED_RG
</constant>,
165 <constant>GL_COMPRESSED_RGB
</constant>,
166 <constant>GL_COMPRESSED_RGBA
</constant>.
167 <constant>GL_COMPRESSED_SRGB
</constant>, or
168 <constant>GL_COMPRESSED_SRGB_ALPHA
</constant>.
171 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>imageSize
</parameter> is not consistent with
172 the format, dimensions, and contents of the specified compressed image data.
175 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>border
</parameter> is not
0.
178 <constant>GL_INVALID_OPERATION
</constant> is generated if parameter combinations are not
179 supported by the specific compressed internal format as specified in the
180 specific texture compression extension.
183 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
184 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
187 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
188 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
189 object such that the memory reads required would exceed the data store size.
192 Undefined results, including abnormal program termination, are generated if
<parameter>data
</parameter> is not encoded in a manner consistent with the extension specification defining the internal compression format.
195 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
197 <citerefentry><refentrytitle>glGetCompressedTexImage
</refentrytitle></citerefentry>
200 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_COMPRESSED
</constant>
203 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
206 <citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry> with arguments
<constant>GL_TEXTURE_INTERNAL_FORMAT
</constant>
207 and
<constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE
</constant>
210 <refsect1 id=
"seealso"><title>See Also
</title>
212 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
213 <citerefentry><refentrytitle>glCompressedTexImage1D
</refentrytitle></citerefentry>,
214 <citerefentry><refentrytitle>glCompressedTexImage2D
</refentrytitle></citerefentry>,
215 <citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>,
216 <citerefentry><refentrytitle>glCompressedTexSubImage2D
</refentrytitle></citerefentry>,
217 <citerefentry><refentrytitle>glCompressedTexSubImage3D
</refentrytitle></citerefentry>,
218 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
219 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
220 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
221 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
222 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
223 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
224 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
225 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
226 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
227 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>,
228 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
231 <refsect1 id=
"Copyright"><title>Copyright
</title>
233 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
234 Silicon Graphics, Inc. This document is licensed under the SGI
235 Free Software B License. For details, see
236 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.