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=
"glCompressedTexImage1D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glCompressedTexImage1D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glCompressedTexImage1D
</refname>
17 <refpurpose>specify a one-dimensional texture image in a compressed format
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glCompressedTexImage1D
</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>GLint
<parameter>border
</parameter></paramdef>
28 <paramdef>GLsizei
<parameter>imageSize
</parameter></paramdef>
29 <paramdef>const GLvoid *
<parameter>data
</parameter></paramdef>
33 <!-- eqn: ignoring delim $$ -->
34 <refsect1 id=
"parameters"><title>Parameters
</title>
37 <term><parameter>target
</parameter></term>
40 Specifies the target texture.
41 Must be
<constant>GL_TEXTURE_1D
</constant> or
<constant>GL_PROXY_TEXTURE_1D
</constant>.
46 <term><parameter>level
</parameter></term>
49 Specifies the level-of-detail number.
50 Level
0 is the base image level.
51 Level
<emphasis>n
</emphasis> is the
<emphasis>n
</emphasis>th mipmap reduction image.
56 <term><parameter>internalformat
</parameter></term>
59 Specifies the format of the compressed image data stored at address
<parameter>data
</parameter>.
64 <term><parameter>width
</parameter></term>
67 Specifies the width of the texture image.
68 All implementations support texture images that are at least
64 texels wide. The height of the
1D texture image is
1.
73 <term><parameter>border
</parameter></term>
81 <term><parameter>imageSize
</parameter></term>
84 Specifies the number of unsigned bytes of image data starting at the address specified by
<parameter>data
</parameter>.
89 <term><parameter>data
</parameter></term>
92 Specifies a pointer to the compressed image data in memory.
98 <refsect1 id=
"description"><title>Description
</title>
100 Texturing allows elements of an image array to be read by shaders.
103 <function>glCompressedTexImage1D
</function> loads a previously defined, and retrieved, compressed
104 one-dimensional texture image if
<parameter>target
</parameter> is
<constant>GL_TEXTURE_1D
</constant>
105 (see
<citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>).
108 If
<parameter>target
</parameter> is
<constant>GL_PROXY_TEXTURE_1D
</constant>, no data is read from
<parameter>data
</parameter>, but
109 all of the texture image state is recalculated, checked for consistency, and checked against the implementation's capabilities. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to
0, but does not generate an error (see
<citerefentry><refentrytitle>glGetError
</refentrytitle></citerefentry>). To query for an entire mipmap array, use an image array level greater than or equal to
1.
112 <parameter>internalformat
</parameter> must be an extension-specified compressed-texture format.
113 When a texture is loaded with
114 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry> using a generic compressed texture format
115 (e.g.,
<constant>GL_COMPRESSED_RGB
</constant>) the GL selects from one of
116 its extensions supporting compressed textures. In order to load the
117 compressed texture image using
<function>glCompressedTexImage1D
</function>, query the compressed texture image's size and
118 format using
<citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry>.
121 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
122 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
123 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
126 If the compressed data are arranged into fixed-size blocks of texels, the pixel
127 storage modes can be used to select a sub-rectangle from a larger containing rectangle.
128 These pixel storage modes operate in the same way as they do for
<citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>.
129 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>,
130 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>w
</mml:mi></mml:msub></mml:mrow></mml:math>,
131 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>h
</mml:mi></mml:msub></mml:mrow></mml:math>, and
132 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>d
</mml:mi></mml:msub></mml:mrow></mml:math>,
133 the values of pixel storage modes
<constant>GL_UNPACK_COMPRESSED_BLOCK_SIZE
</constant>,
134 <constant>GL_UNPACK_COMPRESSED_BLOCK_WIDTH
</constant>,
<constant>GL_UNPACK_COMPRESSED_BLOCK_HEIGHT
</constant>,
135 and
<constant>GL_UNPACK_COMPRESSED_BLOCK_DEPTH
</constant>, respectively.
136 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>s
</mml:mi></mml:msub></mml:mrow></mml:math> is
137 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>,
138 <mml:math><mml:mrow><mml:msub><mml:mi>b
</mml:mi><mml:mi>h
</mml:mi></mml:msub></mml:mrow></mml:math>,
139 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.
142 By default the pixel storage modes
<constant>GL_UNPACK_ROW_LENGTH
</constant>,
143 <constant>GL_UNPACK_SKIP_ROWS
</constant>,
<constant>GL_UNPACK_SKIP_PIXELS
</constant>,
144 <constant>GL_UNPACK_IMAGE_HEIGHT
</constant> and
<constant>GL_UNPACK_SKIP_IMAGES
</constant>
145 are ignored for compressed images. To enable
<constant>GL_UNPACK_SKIP_PIXELS
</constant>
146 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>
147 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.
148 To also enable
<constant>GL_UNPACK_SKIP_ROWS
</constant> and
<constant>GL_UNPACK_IMAGE_HEIGHT
</constant>,
149 <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.
150 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>
151 must be non-zero. All parameters must be consistent with the compressed format to produce the desired results.
154 When selecting a sub-rectangle from a compressed image:
156 <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>
160 <parameter>imageSize
</parameter> must be equal to:
163 <mml:math display = 'block'
>
169 <mml:mo lspace='
2px' rspace='
2px'
>×</mml:mo>
170 <mml:mfenced open = '
⌈' close = '
⌉'
>
172 <mml:mi>width
</mml:mi>
183 <refsect1 id=
"errors"><title>Errors
</title>
185 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is not
186 a supported specific compressed internal formats, or is one of the generic
187 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 data.
200 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>border
</parameter> is not
0.
203 <constant>GL_INVALID_OPERATION
</constant> is generated if parameter combinations are not
204 supported by the specific compressed internal format as specified in the
205 specific texture compression extension.
208 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
209 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
212 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
213 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
214 object such that the memory reads required would exceed the data store size.
217 Undefined results, including abnormal program termination, are generated if
218 <parameter>data
</parameter> is not encoded in a manner consistent with the extension
219 specification defining the internal compression format.
222 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
224 <citerefentry><refentrytitle>glGetCompressedTexImage
</refentrytitle></citerefentry>
227 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_COMPRESSED
</constant>
230 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_NUM_COMPRESSED_TEXTURE_FORMATS
</constant>
233 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_COMPRESSED_TEXTURE_FORMATS
</constant>
236 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
239 <citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry> with arguments
<constant>GL_TEXTURE_INTERNAL_FORMAT
</constant>
240 and
<constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE
</constant>
243 <refsect1 id=
"seealso"><title>See Also
</title>
245 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
246 <citerefentry><refentrytitle>glCompressedTexImage2D
</refentrytitle></citerefentry>,
247 <citerefentry><refentrytitle>glCompressedTexImage3D
</refentrytitle></citerefentry>,
248 <citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>,
249 <citerefentry><refentrytitle>glCompressedTexSubImage2D
</refentrytitle></citerefentry>,
250 <citerefentry><refentrytitle>glCompressedTexSubImage3D
</refentrytitle></citerefentry>,
251 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
252 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
253 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
254 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
255 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
256 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
257 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
258 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
259 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
260 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
261 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>,
262 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
265 <refsect1 id=
"Copyright"><title>Copyright
</title>
267 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
268 Silicon Graphics, Inc.
<trademark class=
"copyright"></trademark> 2011
269 Khronos Group. This document is licensed under the SGI
270 Free Software B License. For details, see
271 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.