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=
"glTexSubImage1D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glTexSubImage1D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glTexSubImage1D
</refname>
17 <refpurpose>specify a one-dimensional texture subimage
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glTexSubImage1D
</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>GLenum
<parameter>type
</parameter></paramdef>
29 <paramdef>const GLvoid *
<parameter>data
</parameter></paramdef>
33 <!-- 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_1D
</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>xoffset
</parameter></term>
61 Specifies a texel offset in the x direction within the texture array.
66 <term><parameter>width
</parameter></term>
69 Specifies the width of the texture subimage.
74 <term><parameter>format
</parameter></term>
77 Specifies the format of the pixel data.
78 The following symbolic values are accepted:
79 <constant>GL_RED
</constant>,
80 <constant>GL_RG
</constant>,
81 <constant>GL_RGB
</constant>,
82 <constant>GL_BGR
</constant>,
83 <constant>GL_RGBA
</constant>, and
84 <constant>GL_BGRA
</constant>.
89 <term><parameter>type
</parameter></term>
92 Specifies the data type of the pixel data.
93 The following symbolic values are accepted:
94 <constant>GL_UNSIGNED_BYTE
</constant>,
95 <constant>GL_BYTE
</constant>,
96 <constant>GL_UNSIGNED_SHORT
</constant>,
97 <constant>GL_SHORT
</constant>,
98 <constant>GL_UNSIGNED_INT
</constant>,
99 <constant>GL_INT
</constant>,
100 <constant>GL_FLOAT
</constant>,
101 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
102 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
103 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>,
104 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>,
105 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
106 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
107 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
108 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
109 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
110 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
111 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, and
112 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant>.
117 <term><parameter>data
</parameter></term>
120 Specifies a pointer to the image data in memory.
126 <refsect1 id=
"description"><title>Description
</title>
128 Texturing maps a portion of a specified texture image
129 onto each graphical primitive for which texturing is enabled.
130 To enable or disable one-dimensional texturing, call
<citerefentry><refentrytitle>glEnable
</refentrytitle></citerefentry>
131 and
<citerefentry><refentrytitle>glDisable
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_1D
</constant>.
134 <function>glTexSubImage1D
</function> redefines a contiguous subregion of an existing one-dimensional
136 The texels referenced by
<parameter>data
</parameter> replace the portion of the
137 existing texture array with x indices
<parameter>xoffset
</parameter> and
138 <inlineequation><mml:math>
139 <!-- eqn: xoffset + width - 1: -->
141 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
143 <mml:mi mathvariant=
"italic">width
</mml:mi>
147 </mml:math></inlineequation>,
149 This region may not include any texels outside the range of the
150 texture array as it was originally specified.
151 It is not an error to specify a subtexture with width of
0, but
152 such a specification has no effect.
155 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
156 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a texture image is
157 specified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
160 <refsect1 id=
"notes"><title>Notes
</title>
162 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry> modes affect texture images.
165 <function>glTexSubImage1D
</function> specifies a one-dimensional subtexture for the current texture unit,
166 specified with
<citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>.
169 <refsect1 id=
"errors"><title>Errors
</title>
171 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>target
</parameter> is not one of the
175 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>format
</parameter> is not an accepted
179 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>type
</parameter> is not a type constant.
182 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>level
</parameter> is less than
0.
185 <constant>GL_INVALID_VALUE
</constant> may be generated if
<parameter>level
</parameter> is greater
187 <inlineequation><mml:math>
188 <!-- eqn: log sub 2: -->
189 <mml:msub><mml:mi mathvariant=
"italic">log
</mml:mi>
192 </mml:math></inlineequation>
193 <emphasis>max
</emphasis>,
194 where
<emphasis>max
</emphasis> is the returned value of
<constant>GL_MAX_TEXTURE_SIZE
</constant>.
197 <constant>GL_INVALID_VALUE
</constant> is generated if
198 <inlineequation><mml:math>
199 <!-- eqn: xoffset < -b: -->
201 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
202 <mml:mo><</mml:mo>
205 <mml:mi mathvariant=
"italic">b
</mml:mi>
208 </mml:math></inlineequation>,
210 <inlineequation><mml:math>
211 <!-- eqn: (xoffset + width) > (w - b): -->
213 <mml:mfenced open=
"(" close=
")">
215 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
217 <mml:mi mathvariant=
"italic">width
</mml:mi>
220 <mml:mo>></mml:mo>
221 <mml:mfenced open=
"(" close=
")">
223 <mml:mi mathvariant=
"italic">w
</mml:mi>
225 <mml:mi mathvariant=
"italic">b
</mml:mi>
229 </mml:math></inlineequation>,
231 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
232 is the
<constant>GL_TEXTURE_WIDTH
</constant>, and
233 <inlineequation><mml:math><mml:mi mathvariant=
"italic">b
</mml:mi></mml:math></inlineequation>
235 the width of the
<constant>GL_TEXTURE_BORDER
</constant>
236 of the texture image being modified.
238 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
239 includes twice the border width.
242 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>width
</parameter> is less than
0.
245 <constant>GL_INVALID_OPERATION
</constant> is generated if the texture array has not
246 been defined by a previous
<citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry> operation.
249 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>type
</parameter> is one of
250 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
251 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
252 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>, or
253 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>
254 and
<parameter>format
</parameter> is not
<constant>GL_RGB
</constant>.
257 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>type
</parameter> is one of
258 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
259 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
260 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
261 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
262 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
263 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
264 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, or
265 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant>
266 and
<parameter>format
</parameter> is neither
<constant>GL_RGBA
</constant> nor
<constant>GL_BGRA
</constant>.
269 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
270 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
273 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
274 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
275 object such that the memory reads required would exceed the data store size.
278 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
279 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and
<parameter>data
</parameter> is not evenly divisible
280 into the number of bytes needed to store in memory a datum indicated by
<parameter>type
</parameter>.
283 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
285 <citerefentry><refentrytitle>glGetTexImage
</refentrytitle></citerefentry>
288 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
291 <refsect1 id=
"seealso"><title>See Also
</title>
293 <citerefentry><refentrytitle>glActiveTexture
</refentrytitle></citerefentry>,
294 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
295 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
296 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
297 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
298 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
299 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
300 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
301 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
302 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
303 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>,
304 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
305 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>
308 <refsect1 id=
"Copyright"><title>Copyright
</title>
310 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
311 Silicon Graphics, Inc. This document is licensed under the SGI
312 Free Software B License. For details, see
313 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.