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> or
<constant>GL_PROXY_TEXTURE_3D
</constant>.
48 <term><parameter>level
</parameter></term>
51 Specifies the level-of-detail number.
52 Level
0 is the base image level.
53 Level
<emphasis>n
</emphasis> is the
<emphasis>n
</emphasis>th mipmap reduction image.
58 <term><parameter>internalformat
</parameter></term>
61 Specifies the format of the compressed image data stored at address
<parameter>data
</parameter>.
66 <term><parameter>width
</parameter></term>
69 Specifies the width of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
70 <inlineequation><mml:math>
71 <!-- eqn: 2 sup n + 2 ( border ):-->
73 <mml:msup><mml:mn>2</mml:mn>
74 <mml:mi mathvariant=
"italic">n
</mml:mi>
80 <mml:mfenced open=
"(" close=
")">
81 <mml:mi mathvariant=
"italic">border
</mml:mi>
85 </mml:math></inlineequation>
87 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>.
89 implementations support
3D texture images that are at least
16 texels
95 <term><parameter>height
</parameter></term>
98 Specifies the height of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
99 <inlineequation><mml:math>
100 <!-- eqn: 2 sup n + 2 ( border ):-->
102 <mml:msup><mml:mn>2</mml:mn>
103 <mml:mi mathvariant=
"italic">n
</mml:mi>
108 <mml:mo>⁡</mml:mo>
109 <mml:mfenced open=
"(" close=
")">
110 <mml:mi mathvariant=
"italic">border
</mml:mi>
114 </mml:math></inlineequation>
116 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>.
118 implementations support
3D texture images that are at least
16 texels
124 <term><parameter>depth
</parameter></term>
127 Specifies the depth of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
128 <inlineequation><mml:math>
129 <!-- eqn: 2 sup n + 2 ( border ):-->
131 <mml:msup><mml:mn>2</mml:mn>
132 <mml:mi mathvariant=
"italic">n
</mml:mi>
137 <mml:mo>⁡</mml:mo>
138 <mml:mfenced open=
"(" close=
")">
139 <mml:mi mathvariant=
"italic">border
</mml:mi>
143 </mml:math></inlineequation>
145 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>.
147 implementations support
3D texture images that are at least
16 texels
153 <term><parameter>border
</parameter></term>
156 Specifies the width of the border.
157 Must be either
0 or
1.
162 <term><parameter>imageSize
</parameter></term>
165 Specifies the number of unsigned bytes of image data starting at the
166 address specified by
<parameter>data
</parameter>.
171 <term><parameter>data
</parameter></term>
174 Specifies a pointer to the compressed image data in memory.
180 <refsect1 id=
"description"><title>Description
</title>
182 Texturing maps a portion of a specified texture image onto each graphical
183 primitive for which texturing is enabled. To enable and disable
184 three-dimensional texturing, call
<citerefentry><refentrytitle>glEnable
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glDisable
</refentrytitle></citerefentry> with argument
185 <constant>GL_TEXTURE_3D
</constant>.
188 <function>glCompressedTexImage3D
</function> loads a previously defined, and retrieved, compressed three-dimensional
189 texture image if
<parameter>target
</parameter> is
<constant>GL_TEXTURE_3D
</constant> (see
<citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>).
192 If
<parameter>target
</parameter> is
<constant>GL_PROXY_TEXTURE_3D
</constant>, no data is read from
<parameter>data
</parameter>, but
193 all of the texture image state is recalculated, checked for consistency,
194 and checked against the implementation's capabilities. If the
195 implementation cannot handle a texture of the requested texture size, it
196 sets all of the image state to
0, but does not generate an error (see
197 <citerefentry><refentrytitle>glGetError
</refentrytitle></citerefentry>). To query for an entire mipmap array, use an image array level
198 greater than or equal to
1.
201 <parameter>internalformat
</parameter> must be an extension-specified compressed-texture format.
202 When a texture is loaded with
<citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry> using a generic compressed
203 texture format (e.g.,
<constant>GL_COMPRESSED_RGB
</constant>), the GL selects from one of
204 its extensions supporting compressed textures. In order to load the
205 compressed texture image using
<function>glCompressedTexImage3D
</function>, query the compressed texture image's
206 size and format using
<citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry>.
209 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
210 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
211 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
214 <refsect1 id=
"notes"><title>Notes
</title>
216 <function>glCompressedTexImage3D
</function> is available only if the GL version is
1.3 or greater.
219 Non-power-of-two textures are supported if the GL version is
2.0 or greater, or if the implementation exports the
<constant>GL_ARB_texture_non_power_of_two
</constant> extension.
222 <refsect1 id=
"errors"><title>Errors
</title>
224 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is one of the generic compressed internal formats:
<constant>GL_COMPRESSED_ALPHA
</constant>,
225 <constant>GL_COMPRESSED_LUMINANCE
</constant>,
<constant>GL_COMPRESSED_LUMINANCE_ALPHA
</constant>,
226 <constant>GL_COMPRESSED_INTENSITY
</constant>,
<constant>GL_COMPRESSED_RGB
</constant>, or
227 <constant>GL_COMPRESSED_RGBA
</constant>.
230 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>imageSize
</parameter> is not consistent with
231 the format, dimensions, and contents of the specified compressed image data.
234 <constant>GL_INVALID_OPERATION
</constant> is generated if parameter combinations are not
235 supported by the specific compressed internal format as specified in the
236 specific texture compression extension.
239 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
240 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
243 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
244 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
245 object such that the memory reads required would exceed the data store size.
248 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glCompressedTexImage3D
</function>
249 is executed between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry>
250 and the corresponding execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
253 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.
256 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
258 <citerefentry><refentrytitle>glGetCompressedTexImage
</refentrytitle></citerefentry>
261 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_COMPRESSED
</constant>
264 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
267 <citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry> with arguments
<constant>GL_TEXTURE_INTERNAL_FORMAT
</constant>
268 and
<constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE
</constant>
271 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_3D
</constant>
274 <refsect1 id=
"seealso"><title>See Also
</title>
276 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
277 <citerefentry><refentrytitle>glColorTable
</refentrytitle></citerefentry>,
278 <citerefentry><refentrytitle>glCompressedTexImage1D
</refentrytitle></citerefentry>,
279 <citerefentry><refentrytitle>glCompressedTexImage2D
</refentrytitle></citerefentry>,
280 <citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>,
281 <citerefentry><refentrytitle>glCompressedTexSubImage2D
</refentrytitle></citerefentry>,
282 <citerefentry><refentrytitle>glCompressedTexSubImage3D
</refentrytitle></citerefentry>,
283 <citerefentry><refentrytitle>glConvolutionFilter1D
</refentrytitle></citerefentry>,
284 <citerefentry><refentrytitle>glCopyPixels
</refentrytitle></citerefentry>,
285 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
286 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
287 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
288 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
289 <citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>,
290 <citerefentry><refentrytitle>glMatrixMode
</refentrytitle></citerefentry>,
291 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
292 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>,
293 <citerefentry><refentrytitle>glTexEnv
</refentrytitle></citerefentry>,
294 <citerefentry><refentrytitle>glTexGen
</refentrytitle></citerefentry>,
295 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
296 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
297 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
298 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
299 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>,
300 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
303 <refsect1 id=
"Copyright"><title>Copyright
</title>
305 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
306 Silicon Graphics, Inc. This document is licensed under the SGI
307 Free Software B License. For details, see
308 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.