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=
"glCopyTexSubImage1D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glCopyTexSubImage1D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glCopyTexSubImage1D
</refname>
17 <refpurpose>copy a one-dimensional texture subimage
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glCopyTexSubImage1D
</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>GLint
<parameter>x
</parameter></paramdef>
27 <paramdef>GLint
<parameter>y
</parameter></paramdef>
28 <paramdef>GLsizei
<parameter>width
</parameter></paramdef>
32 <!-- 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_1D
</constant>.
47 <term><parameter>level
</parameter></term>
50 Specifies the level-of-detail number.
51 Level
0 is the base image level.
52 Level
<emphasis>n
</emphasis> is the
<emphasis>n
</emphasis>th mipmap reduction image.
57 <term><parameter>xoffset
</parameter></term>
60 Specifies the texel offset within the texture array.
65 <term><parameter>x
</parameter></term>
66 <term><parameter>y
</parameter></term>
69 Specify the window coordinates of the left corner
70 of the row of pixels to be copied.
75 <term><parameter>width
</parameter></term>
78 Specifies the width of the texture subimage.
84 <refsect1 id=
"description"><title>Description
</title>
86 <function>glCopyTexSubImage1D
</function> replaces a portion of a one-dimensional
87 texture image with pixels from the current
<constant>GL_READ_BUFFER
</constant> (rather
88 than from main memory, as is the case for
<citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>).
91 The screen-aligned pixel row with left corner at (
<parameter>x
</parameter>,\
<parameter>y
</parameter>), and with
92 length
<parameter>width
</parameter> replaces the portion of the
93 texture array with x indices
<parameter>xoffset
</parameter> through
94 <inlineequation><mml:math>
95 <!-- eqn: xoffset + width - 1:-->
97 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
99 <mml:mi mathvariant=
"italic">width
</mml:mi>
103 </mml:math></inlineequation>,
104 inclusive. The destination in the texture array may not
105 include any texels outside the texture array as it was
106 originally specified.
109 The pixels in the row are processed exactly as if
110 <citerefentry><refentrytitle>glCopyPixels
</refentrytitle></citerefentry> had been called, but the process stops just before
112 At this point, all pixel component values are clamped to the range
113 <inlineequation><mml:math>
115 <mml:mfenced open=
"[" close=
"]">
119 </mml:math></inlineequation>
120 and then converted to the texture's internal format for storage in the texel
124 It is not an error to specify a subtexture with zero width, but
125 such a specification has no effect.
126 If any of the pixels within the specified row of the current
127 <constant>GL_READ_BUFFER
</constant> are outside the read window associated with the current
128 rendering context, then the values obtained for those pixels are undefined.
131 No change is made to the
<emphasis>internalformat
</emphasis>,
<emphasis>width
</emphasis>,
132 or
<emphasis>border
</emphasis> parameters of the specified texture
133 array or to texel values outside the specified subregion.
136 <refsect1 id=
"notes"><title>Notes
</title>
138 <function>glCopyTexSubImage1D
</function> is available only if the GL version is
1.1 or greater.
141 Texturing has no effect in color index mode.
144 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry> modes affect texture images
145 in exactly the way they affect
<citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>.
148 When the
<code>ARB_imaging
</code> extension is supported, the RGBA components
149 copied from the framebuffer may be processed by the imaging pipeline. See
150 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry> for specific details.
153 <refsect1 id=
"errors"><title>Errors
</title>
155 <constant>GL_INVALID_ENUM
</constant> is generated if /
<parameter>target
</parameter> is not
<constant>GL_TEXTURE_1D
</constant>.
158 <constant>GL_INVALID_OPERATION
</constant> is generated if the texture array has not
159 been defined by a previous
<citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry> or
<citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry> operation.
162 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>level
</parameter> is less than
0.
165 <constant>GL_INVALID_VALUE
</constant> may be generated if
166 <inlineequation><mml:math>
167 <!-- eqn: level > log sub 2(max):-->
169 <mml:mi mathvariant=
"italic">level
</mml:mi>
170 <mml:mo>></mml:mo>
172 <mml:msub><mml:mi mathvariant=
"italic">log
</mml:mi>
175 <mml:mo>⁡</mml:mo>
176 <mml:mfenced open=
"(" close=
")">
177 <mml:mi mathvariant=
"italic">max
</mml:mi>
181 </mml:math></inlineequation>,
182 where
<emphasis>max
</emphasis> is the returned value of
<constant>GL_MAX_TEXTURE_SIZE
</constant>.
185 <constant>GL_INVALID_VALUE
</constant> is generated if
186 <inlineequation><mml:math>
187 <!-- eqn: xoffset < -b:-->
189 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
190 <mml:mo><</mml:mo>
193 <mml:mi mathvariant=
"italic">b
</mml:mi>
196 </mml:math></inlineequation>,
198 <inlineequation><mml:math>
199 <!-- eqn: (xoffset + width) > (w-b):-->
201 <mml:mfenced open=
"(" close=
")">
203 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
205 <mml:mi mathvariant=
"italic">width
</mml:mi>
208 <mml:mo>></mml:mo>
209 <mml:mfenced open=
"(" close=
")">
211 <mml:mi mathvariant=
"italic">w
</mml:mi>
213 <mml:mi mathvariant=
"italic">b
</mml:mi>
217 </mml:math></inlineequation>,
219 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
220 is the
<constant>GL_TEXTURE_WIDTH
</constant> and
221 <inlineequation><mml:math><mml:mi mathvariant=
"italic">b
</mml:mi></mml:math></inlineequation>
222 is the
<constant>GL_TEXTURE_BORDER
</constant>
223 of the texture image being modified.
225 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
226 includes twice the border width.
231 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
233 <citerefentry><refentrytitle>glGetTexImage
</refentrytitle></citerefentry>
236 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_1D
</constant>
239 <refsect1 id=
"seealso"><title>See Also
</title>
241 <citerefentry><refentrytitle>glCopyPixels
</refentrytitle></citerefentry>,
242 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
243 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
244 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
245 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
246 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
247 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>,
248 <citerefentry><refentrytitle>glReadBuffer
</refentrytitle></citerefentry>,
249 <citerefentry><refentrytitle>glTexEnv
</refentrytitle></citerefentry>,
250 <citerefentry><refentrytitle>glTexGen
</refentrytitle></citerefentry>,
251 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
252 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
253 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
254 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>,
255 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
256 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
257 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>
260 <refsect1 id=
"Copyright"><title>Copyright
</title>
262 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
263 Silicon Graphics, Inc. This document is licensed under the SGI
264 Free Software B License. For details, see
265 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.