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>glReadPixels
</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 The
<citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry> mode affects texture images.
141 <refsect1 id=
"errors"><title>Errors
</title>
143 <constant>GL_INVALID_ENUM
</constant> is generated if /
<parameter>target
</parameter> is not
<constant>GL_TEXTURE_1D
</constant>.
146 <constant>GL_INVALID_OPERATION
</constant> is generated if the texture array has not
147 been defined by a previous
<citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry> or
<citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry> operation.
150 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>level
</parameter> is less than
0.
153 <constant>GL_INVALID_VALUE
</constant> may be generated if
154 <inlineequation><mml:math>
155 <!-- eqn: level > log sub 2(max): -->
157 <mml:mi mathvariant=
"italic">level
</mml:mi>
158 <mml:mo>></mml:mo>
160 <mml:msub><mml:mi mathvariant=
"italic">log
</mml:mi>
163 <mml:mo>⁡</mml:mo>
164 <mml:mfenced open=
"(" close=
")">
165 <mml:mi mathvariant=
"italic">max
</mml:mi>
169 </mml:math></inlineequation>,
170 where
<emphasis>max
</emphasis> is the returned value of
<constant>GL_MAX_TEXTURE_SIZE
</constant>.
173 <constant>GL_INVALID_VALUE
</constant> is generated if
174 <inlineequation><mml:math>
175 <!-- eqn: xoffset < -b: -->
177 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
178 <mml:mo><</mml:mo>
181 <mml:mi mathvariant=
"italic">b
</mml:mi>
184 </mml:math></inlineequation>,
186 <inlineequation><mml:math>
187 <!-- eqn: (xoffset + width) > (w-b): -->
189 <mml:mfenced open=
"(" close=
")">
191 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
193 <mml:mi mathvariant=
"italic">width
</mml:mi>
196 <mml:mo>></mml:mo>
197 <mml:mfenced open=
"(" close=
")">
199 <mml:mi mathvariant=
"italic">w
</mml:mi>
201 <mml:mi mathvariant=
"italic">b
</mml:mi>
205 </mml:math></inlineequation>,
207 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
208 is the
<constant>GL_TEXTURE_WIDTH
</constant> and
209 <inlineequation><mml:math><mml:mi mathvariant=
"italic">b
</mml:mi></mml:math></inlineequation>
210 is the
<constant>GL_TEXTURE_BORDER
</constant>
211 of the texture image being modified.
213 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
214 includes twice the border width.
219 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
221 <citerefentry><refentrytitle>glGetTexImage
</refentrytitle></citerefentry>
224 <refsect1 id=
"seealso"><title>See Also
</title>
226 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
227 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
228 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
229 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
230 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
231 <citerefentry><refentrytitle>glReadBuffer
</refentrytitle></citerefentry>,
232 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
233 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
234 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
235 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>,
236 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
237 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
238 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>
241 <refsect1 id=
"Copyright"><title>Copyright
</title>
243 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
244 Silicon Graphics, Inc. This document is licensed under the SGI
245 Free Software B License. For details, see
246 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.