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 <refsect1 id=
"errors"><title>Errors
</title>
128 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is not
129 a supported specific compressed internal formats, or is one of the generic
130 compressed internal formats:
131 <constant>GL_COMPRESSED_RED
</constant>,
132 <constant>GL_COMPRESSED_RG
</constant>,
133 <constant>GL_COMPRESSED_RGB
</constant>,
134 <constant>GL_COMPRESSED_RGBA
</constant>.
135 <constant>GL_COMPRESSED_SRGB
</constant>, or
136 <constant>GL_COMPRESSED_SRGB_ALPHA
</constant>.
139 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>imageSize
</parameter> is not consistent with
140 the format, dimensions, and contents of the specified compressed image data.
143 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>border
</parameter> is not
0.
146 <constant>GL_INVALID_OPERATION
</constant> is generated if parameter combinations are not
147 supported by the specific compressed internal format as specified in the
148 specific texture compression extension.
151 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
152 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
155 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
156 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
157 object such that the memory reads required would exceed the data store size.
160 Undefined results, including abnormal program termination, are generated if
161 <parameter>data
</parameter> is not encoded in a manner consistent with the extension
162 specification defining the internal compression format.
165 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
167 <citerefentry><refentrytitle>glGetCompressedTexImage
</refentrytitle></citerefentry>
170 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_COMPRESSED
</constant>
173 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_NUM_COMPRESSED_TEXTURE_FORMATS
</constant>
176 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_COMPRESSED_TEXTURE_FORMATS
</constant>
179 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
182 <citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry> with arguments
<constant>GL_TEXTURE_INTERNAL_FORMAT
</constant>
183 and
<constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE
</constant>
186 <refsect1 id=
"seealso"><title>See Also
</title>
188 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
189 <citerefentry><refentrytitle>glCompressedTexImage2D
</refentrytitle></citerefentry>,
190 <citerefentry><refentrytitle>glCompressedTexImage3D
</refentrytitle></citerefentry>,
191 <citerefentry><refentrytitle>glCompressedTexSubImage1D
</refentrytitle></citerefentry>,
192 <citerefentry><refentrytitle>glCompressedTexSubImage2D
</refentrytitle></citerefentry>,
193 <citerefentry><refentrytitle>glCompressedTexSubImage3D
</refentrytitle></citerefentry>,
194 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
195 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
196 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
197 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
198 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
199 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
200 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
201 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
202 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
203 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
204 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>,
205 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
208 <refsect1 id=
"Copyright"><title>Copyright
</title>
210 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
211 Silicon Graphics, Inc. This document is licensed under the SGI
212 Free Software B License. For details, see
213 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.