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=
"glCompressedTexImage2D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glCompressedTexImage2D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glCompressedTexImage2D
</refname>
17 <refpurpose>specify a two-dimensional texture image in a compressed format
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glCompressedTexImage2D
</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>GLint
<parameter>border
</parameter></paramdef>
29 <paramdef>GLsizei
<parameter>imageSize
</parameter></paramdef>
30 <paramdef>const GLvoid *
<parameter>data
</parameter></paramdef>
34 <!-- eqn: ignoring delim $$ -->
35 <refsect1 id=
"parameters"><title>Parameters
</title>
38 <term><parameter>target
</parameter></term>
41 Specifies the target texture.
42 Must be
<constant>GL_TEXTURE_2D
</constant>,
<constant>GL_PROXY_TEXTURE_2D
</constant>,
43 <constant>GL_TEXTURE_1D_ARRAY
</constant>,
<constant>GL_PROXY_TEXTURE_1D_ARRAY
</constant>,
44 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X
</constant>,
45 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X
</constant>,
46 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y
</constant>,
47 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
</constant>,
48 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z
</constant>,
49 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
</constant>, or
50 <constant>GL_PROXY_TEXTURE_CUBE_MAP
</constant>.
55 <term><parameter>level
</parameter></term>
58 Specifies the level-of-detail number.
59 Level
0 is the base image level.
60 Level
<emphasis>n
</emphasis> is the
<emphasis>n
</emphasis>th mipmap reduction image.
65 <term><parameter>internalformat
</parameter></term>
68 Specifies the format of the compressed image data stored at address
<parameter>data
</parameter>.
73 <term><parameter>width
</parameter></term>
76 Specifies the width of the texture image.
77 All implementations support
2D texture and cube map texture images that are at least
16384 texels wide.
82 <term><parameter>height
</parameter></term>
85 Specifies the height of the texture image.
86 All implementations support
2D texture and cube map texture images that are at least
16384 texels high.
91 <term><parameter>border
</parameter></term>
99 <term><parameter>imageSize
</parameter></term>
102 Specifies the number of unsigned bytes of image data starting at the
103 address specified by
<parameter>data
</parameter>.
108 <term><parameter>data
</parameter></term>
111 Specifies a pointer to the compressed image data in memory.
117 <refsect1 id=
"description"><title>Description
</title>
119 Texturing allows elements of an image array to be read by shaders.
122 <function>glCompressedTexImage2D
</function> loads a previously defined, and retrieved, compressed two-dimensional
123 texture image if
<parameter>target
</parameter> is
<constant>GL_TEXTURE_2D
</constant>, or one of the
124 cube map faces such as
<constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X
</constant>.
125 (see
<citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>).
128 If
<parameter>target
</parameter> is
<constant>GL_TEXTURE_1D_ARRAY
</constant>,
<parameter>data
</parameter>
129 is treated as an array of compressed
1D textures.
132 If
<parameter>target
</parameter> is
<constant>GL_PROXY_TEXTURE_2D
</constant>,
<constant>GL_PROXY_TEXTURE_1D_ARRAY
</constant>
133 or
<constant>GL_PROXY_CUBE_MAP
</constant>, no data is read from
<parameter>data
</parameter>, but
134 all of the texture image state is recalculated, checked for consistency,
135 and checked against the implementation's capabilities. If the
136 implementation cannot handle a texture of the requested texture size, it
137 sets all of the image state to
0, but does not generate an error (see
138 <citerefentry><refentrytitle>glGetError
</refentrytitle></citerefentry>). To query for an entire mipmap array,
139 use an image array level greater than or equal to
1.
142 <parameter>internalformat
</parameter> must be a known compressed image format (such as
<constant>GL_RGTC
</constant>)
143 or an extension-specified compressed-texture format.
144 When a texture is loaded with
<citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry> using a generic compressed
145 texture format (e.g.,
<constant>GL_COMPRESSED_RGB
</constant>), the GL selects from one of
146 its extensions supporting compressed textures. In order to load the
147 compressed texture image using
<function>glCompressedTexImage2D
</function>, query the compressed texture image's
148 size and format using
<citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry>.
151 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
152 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
153 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
156 If the compressed data are arranged into fixed-size blocks of texels, the pixel
157 storage modes can be used to select a sub-rectangle from a larger containing rectangle.
158 These pixel storage modes operate in the same way as they do for
<citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>.
159 In the following description, denote by
<mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>s
</mml:mi></mml:msub></mml:mrow></mml:math>,
160 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>w
</mml:mi></mml:msub></mml:mrow></mml:math>,
161 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>h
</mml:mi></mml:msub></mml:mrow></mml:math>, and
162 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>d
</mml:mi></mml:msub></mml:mrow></mml:math>,
163 the values of pixel storage modes
<constant>GL_UNPACK_COMPRESSED_BLOCK_SIZE
</constant>,
164 <constant>GL_UNPACK_COMPRESSED_BLOCK_WIDTH
</constant>,
<constant>GL_UNPACK_COMPRESSED_BLOCK_HEIGHT
</constant>,
165 and
<constant>GL_UNPACK_COMPRESSED_BLOCK_DEPTH
</constant>, respectively.
166 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>s
</mml:mi></mml:msub></mml:mrow></mml:math> is
167 the compressed block size in bytes;
<mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>w
</mml:mi></mml:msub></mml:mrow></mml:math>,
168 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>h
</mml:mi></mml:msub></mml:mrow></mml:math>,
169 and
<mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>d
</mml:mi></mml:msub></mml:mrow></mml:math> are the compressed block width, height, and depth in pixels.
172 By default the pixel storage modes
<constant>GL_UNPACK_ROW_LENGTH
</constant>,
173 <constant>GL_UNPACK_SKIP_ROWS
</constant>,
<constant>GL_UNPACK_SKIP_PIXELS
</constant>,
174 <constant>GL_UNPACK_IMAGE_HEIGHT
</constant> and
<constant>GL_UNPACK_SKIP_IMAGES
</constant>
175 are ignored for compressed images. To enable
<constant>GL_UNPACK_SKIP_PIXELS
</constant>
176 and
<constant>GL_UNPACK_ROW_LENGTH
</constant>,
<mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>s
</mml:mi></mml:msub></mml:mrow></mml:math>
177 and
<mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>w
</mml:mi></mml:msub></mml:mrow></mml:math> must both be non-zero.
178 To also enable
<constant>GL_UNPACK_SKIP_ROWS
</constant> and
<constant>GL_UNPACK_IMAGE_HEIGHT
</constant>,
179 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>h
</mml:mi></mml:msub></mml:mrow></mml:math> must be non-zero.
180 To also enable
<constant>GL_UNPACK_SKIP_IMAGES
</constant>,
<mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>d
</mml:mi></mml:msub></mml:mrow></mml:math>
181 must be non-zero. All parameters must be consistent with the compressed format to produce the desired results.
184 When selecting a sub-rectangle from a compressed image:
186 <listitem>the value of
<constant>GL_UNPACK_SKIP_PIXELS
</constant> must be a multiple of
<mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>w
</mml:mi></mml:msub></mml:mrow></mml:math>;
</listitem>
187 <listitem>the value of
<constant>GL_UNPACK_SKIP_ROWS
</constant> must be a multiple of
<mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>w
</mml:mi></mml:msub></mml:mrow></mml:math>.
</listitem>
191 <parameter>imageSize
</parameter> must be equal to:
194 <mml:math display = 'block'
>
200 <mml:mo lspace='
2px' rspace='
2px'
>×</mml:mo>
201 <mml:mfenced open = '
⌈' close = '
⌉'
>
203 <mml:mi>width
</mml:mi>
210 <mml:mo lspace='
2px' rspace='
2px'
>×</mml:mo>
211 <mml:mfenced open = '
⌈' close = '
⌉'
>
213 <mml:mi>height
</mml:mi>
224 <refsect1 id=
"notes"><title>Notes
</title>
226 The specific compressed internal formats
<constant>GL_COMPRESSED_RGB8_ETC2
</constant>,
227 <constant>GL_COMPRESSED_SRGB8_ETC2
</constant>,
228 <constant>GL_COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2
</constant>,
229 <constant>GL_COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2
</constant>,
230 <constant>GL_COMPRESSED_RGBA8_ETC2_EAC
</constant>,
231 <constant>GL_COMPRESSED_SRGB8_ALPHA8_ETC2_EAC
</constant>,
232 <constant>GL_COMPRESSED_R11_EAC
</constant>,
233 <constant>GL_COMPRESSED_SIGNED_R11_EAC
</constant>,
234 <constant>GL_COMPRESSED_RG11_EAC
</constant>, and
235 <constant>GL_COMPRESSED_SIGNED_RG11_EAC
</constant> are available only if the GL version
239 <refsect1 id=
"errors"><title>Errors
</title>
241 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is not one of the specific
242 compressed internal formats:
243 <constant>GL_COMPRESSED_RED_RGTC1
</constant>,
244 <constant>GL_COMPRESSED_SIGNED_RED_RGTC1
</constant>,
245 <constant>GL_COMPRESSED_RG_RGTC2
</constant>,
246 <constant>GL_COMPRESSED_SIGNED_RG_RGTC2
</constant>.
247 <constant>GL_COMPRESSED_RGBA_BPTC_UNORM
</constant>,
248 <constant>GL_COMPRESSED_SRGB_ALPHA_BPTC_UNORM
</constant>,
249 <constant>GL_COMPRESSED_RGB_BPTC_SIGNED_FLOAT
</constant>,
250 <constant>GL_COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT
</constant>,
251 <constant>GL_COMPRESSED_RGB8_ETC2
</constant>,
252 <constant>GL_COMPRESSED_SRGB8_ETC2
</constant>,
253 <constant>GL_COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2
</constant>,
254 <constant>GL_COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2
</constant>,
255 <constant>GL_COMPRESSED_RGBA8_ETC2_EAC
</constant>,
256 <constant>GL_COMPRESSED_SRGB8_ALPHA8_ETC2_EAC
</constant>,
257 <constant>GL_COMPRESSED_R11_EAC
</constant>,
258 <constant>GL_COMPRESSED_SIGNED_R11_EAC
</constant>,
259 <constant>GL_COMPRESSED_RG11_EAC
</constant>, or
260 <constant>GL_COMPRESSED_SIGNED_RG11_EAC
</constant>.
263 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>imageSize
</parameter> is not consistent with
264 the format, dimensions, and contents of the specified compressed image
268 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>border
</parameter> is not
0.
271 <constant>GL_INVALID_OPERATION
</constant> is generated if parameter combinations are not
272 supported by the specific compressed internal format as specified in the
273 specific texture compression extension.
276 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
277 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
280 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
281 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
282 object such that the memory reads required would exceed the data store size.
285 Undefined results, including abnormal program termination, are generated if
286 <parameter>data
</parameter> is not encoded in a manner consistent with the extension
287 specification defining the internal compression format.
290 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
292 <citerefentry><refentrytitle>glGetCompressedTexImage
</refentrytitle></citerefentry>
295 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_COMPRESSED
</constant>
298 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
301 <citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry> with arguments
<constant>GL_TEXTURE_INTERNAL_FORMAT
</constant>
302 and
<constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE
</constant>
305 <refsect1 id=
"seealso"><title>See Also
</title>
307 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
308 <citerefentry><refentrytitle>glCompressedTexImage1D
</refentrytitle></citerefentry>,
309 <citerefentry><refentrytitle>glCompressedTexImage3D
</refentrytitle></citerefentry>,
310 <citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>,
311 <citerefentry><refentrytitle>glCompressedTexSubImage2D
</refentrytitle></citerefentry>,
312 <citerefentry><refentrytitle>glCompressedTexSubImage3D
</refentrytitle></citerefentry>,
313 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
314 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
315 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
316 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
317 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
318 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
319 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
320 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
321 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
322 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>,
323 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
326 <refsect1 id=
"Copyright"><title>Copyright
</title>
328 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
329 Silicon Graphics, Inc.
<trademark class=
"copyright"></trademark> 2011
330 Khronos Group. This document is licensed under the SGI
331 Free Software B License. For details, see
332 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.