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=
"glCompressedTexSubImage1D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glCompressedTexSubImage1D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glCompressedTexSubImage1D
</refname>
17 <refpurpose>specify a one-dimensional texture subimage in a compressed format
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glCompressedTexSubImage1D
</function></funcdef>
23 <paramdef>GLenum
<parameter>target
</parameter></paramdef>
24 <paramdef>GLint
<parameter>level
</parameter></paramdef>
25 <paramdef>GLint
<parameter>xoffset
</parameter></paramdef>
26 <paramdef>GLsizei
<parameter>width
</parameter></paramdef>
27 <paramdef>GLenum
<parameter>format
</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>.
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>xoffset
</parameter></term>
59 Specifies a texel offset in the x direction within the texture array.
64 <term><parameter>width
</parameter></term>
67 Specifies the width of the texture subimage.
72 <term><parameter>format
</parameter></term>
75 Specifies the format of the compressed image data stored at address
<parameter>data
</parameter>.
80 <term><parameter>imageSize
</parameter></term>
83 Specifies the number of unsigned bytes of image data starting at the
84 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>glCompressedTexSubImage1D
</function> redefines a contiguous subregion of an existing one-dimensional
104 texture image. The texels referenced by
<parameter>data
</parameter> replace the portion of the
105 existing texture array with x indices
<parameter>xoffset
</parameter> and
106 <inlineequation><mml:math>
107 <!-- eqn: xoffset + width - 1: -->
109 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
111 <mml:mi mathvariant=
"italic">width
</mml:mi>
115 </mml:math></inlineequation>,
116 inclusive. This region may not include any texels
117 outside the range of the texture array as it was originally specified. It
118 is not an error to specify a subtexture with width of
0, but such a
119 specification has no effect.
122 <parameter>internalformat
</parameter> must be a known compressed image format (such as
<constant>GL_RGTC
</constant>)
123 or an extension-specified compressed-texture format.
124 The
<parameter>format
</parameter> of the compressed texture
125 image is selected by the GL implementation that compressed it (see
126 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>), and should be queried at the time the texture was
127 compressed with
<citerefentry><refentrytitle>glGetTexLevelParameter
</refentrytitle></citerefentry>.
130 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
131 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
132 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
135 <refsect1 id=
"errors"><title>Errors
</title>
137 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>internalformat
</parameter> is not one of the generic
138 compressed internal formats:
139 <constant>GL_COMPRESSED_RED
</constant>,
140 <constant>GL_COMPRESSED_RG
</constant>,
141 <constant>GL_COMPRESSED_RGB
</constant>,
142 <constant>GL_COMPRESSED_RGBA
</constant>.
143 <constant>GL_COMPRESSED_SRGB
</constant>, or
144 <constant>GL_COMPRESSED_SRGB_ALPHA
</constant>.
147 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>imageSize
</parameter> is not consistent with
148 the format, dimensions, and contents of the specified compressed image
152 <constant>GL_INVALID_OPERATION
</constant> is generated if parameter combinations are not
153 supported by the specific compressed internal format as specified in the
154 specific texture compression extension.
157 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
158 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
161 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
162 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
163 object such that the memory reads required would exceed the data store size.
166 Undefined results, including abnormal program termination, are generated if
167 <parameter>data
</parameter> is not encoded in a manner consistent with the extension
168 specification defining the internal compression format.
171 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
173 <citerefentry><refentrytitle>glGetCompressedTexImage
</refentrytitle></citerefentry>
176 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_COMPRESSED
</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>glCompressedTexImage1D
</refentrytitle></citerefentry>,
190 <citerefentry><refentrytitle>glCompressedTexImage2D
</refentrytitle></citerefentry>,
191 <citerefentry><refentrytitle>glCompressedTexImage3D
</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>.