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>Khronos Group
</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> or
<emphasis>width
</emphasis> parameters of the specified texture
132 array or to texel values outside the specified subregion.
135 <refsect1 id=
"notes"><title>Notes
</title>
137 The
<citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry> mode affects texture images.
140 <refsect1 id=
"errors"><title>Errors
</title>
142 <constant>GL_INVALID_ENUM
</constant> is generated if /
<parameter>target
</parameter> is not
<constant>GL_TEXTURE_1D
</constant>.
145 <constant>GL_INVALID_OPERATION
</constant> is generated if the texture array has not
146 been defined by a previous
<citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry> or
<citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry> operation.
149 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>level
</parameter> is less than
0.
152 <constant>GL_INVALID_VALUE
</constant> may be generated if
153 <inlineequation><mml:math>
154 <!-- eqn: level > log sub 2(max): -->
156 <mml:mi mathvariant=
"italic">level
</mml:mi>
157 <mml:mo>></mml:mo>
159 <mml:msub><mml:mi mathvariant=
"italic">log
</mml:mi>
162 <mml:mo>⁡</mml:mo>
163 <mml:mfenced open=
"(" close=
")">
164 <mml:mi mathvariant=
"italic">max
</mml:mi>
168 </mml:math></inlineequation>,
169 where
<emphasis>max
</emphasis> is the returned value of
<constant>GL_MAX_TEXTURE_SIZE
</constant>.
172 <constant>GL_INVALID_VALUE
</constant> is generated if
173 <inlineequation><mml:math>
174 <!-- eqn: xoffset < -b: -->
176 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
177 <mml:mo><</mml:mo>
180 </mml:math></inlineequation>,
182 <inlineequation><mml:math>
183 <!-- eqn: (xoffset + width) > (w-b): -->
185 <mml:mfenced open=
"(" close=
")">
187 <mml:mi mathvariant=
"italic">xoffset
</mml:mi>
189 <mml:mi mathvariant=
"italic">width
</mml:mi>
192 <mml:mo>></mml:mo>
193 <mml:mi mathvariant=
"italic">w
</mml:mi>
195 </mml:math></inlineequation>,
197 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>
198 is the
<constant>GL_TEXTURE_WIDTH
</constant>
199 of the texture image being modified.
204 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
206 <citerefentry><refentrytitle>glGetTexImage
</refentrytitle></citerefentry>
209 <refsect1 id=
"seealso"><title>See Also
</title>
211 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
212 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
213 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
214 <citerefentry><refentrytitle>glCopyTexSubImage3D
</refentrytitle></citerefentry>,
215 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
216 <citerefentry><refentrytitle>glReadBuffer
</refentrytitle></citerefentry>,
217 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
218 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
219 <citerefentry><refentrytitle>glTexImage3D
</refentrytitle></citerefentry>,
220 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>,
221 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
222 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
223 <citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>
226 <refsect1 id=
"Copyright"><title>Copyright
</title>
228 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
229 Silicon Graphics, Inc.
230 Copyright
<trademark class=
"copyright"></trademark> 2012-
2013 Khronos Group.
231 This document is licensed under the SGI
232 Free Software B License. For details, see
233 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.