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=
"glCopyTexImage1D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glCopyTexImage1D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glCopyTexImage1D
</refname>
17 <refpurpose>copy pixels into a
1D texture image
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glCopyTexImage1D
</function></funcdef>
23 <paramdef>GLenum
<parameter>target
</parameter></paramdef>
24 <paramdef>GLint
<parameter>level
</parameter></paramdef>
25 <paramdef>GLenum
<parameter>internalformat
</parameter></paramdef>
26 <paramdef>GLint
<parameter>x
</parameter></paramdef>
27 <paramdef>GLint
<parameter>y
</parameter></paramdef>
28 <paramdef>GLsizei
<parameter>width
</parameter></paramdef>
29 <paramdef>GLint
<parameter>border
</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>internalformat
</parameter></term>
59 Specifies the internal format of the texture.
60 Must be one of the following symbolic constants:
61 <constant>GL_COMPRESSED_RED
</constant>,
62 <constant>GL_COMPRESSED_RG
</constant>,
63 <constant>GL_COMPRESSED_RGB
</constant>,
64 <constant>GL_COMPRESSED_RGBA
</constant>.
65 <constant>GL_COMPRESSED_SRGB
</constant>,
66 <constant>GL_COMPRESSED_SRGB_ALPHA
</constant>.
67 <constant>GL_DEPTH_COMPONENT
</constant>,
68 <constant>GL_DEPTH_COMPONENT16
</constant>,
69 <constant>GL_DEPTH_COMPONENT24
</constant>,
70 <constant>GL_DEPTH_COMPONENT32
</constant>,
71 <constant>GL_RED
</constant>,
72 <constant>GL_RG
</constant>,
73 <constant>GL_RGB
</constant>,
74 <constant>GL_R3_G3_B2
</constant>,
75 <constant>GL_RGB4
</constant>,
76 <constant>GL_RGB5
</constant>,
77 <constant>GL_RGB8
</constant>,
78 <constant>GL_RGB10
</constant>,
79 <constant>GL_RGB12
</constant>,
80 <constant>GL_RGB16
</constant>,
81 <constant>GL_RGBA
</constant>,
82 <constant>GL_RGBA2
</constant>,
83 <constant>GL_RGBA4
</constant>,
84 <constant>GL_RGB5_A1
</constant>,
85 <constant>GL_RGBA8
</constant>,
86 <constant>GL_RGB10_A2
</constant>,
87 <constant>GL_RGBA12
</constant>,
88 <constant>GL_RGBA16
</constant>,
89 <constant>GL_SRGB
</constant>,
90 <constant>GL_SRGB8
</constant>,
91 <constant>GL_SRGB_ALPHA
</constant>, or
92 <constant>GL_SRGB8_ALPHA8
</constant>.
97 <term><parameter>x
</parameter></term>
98 <term><parameter>y
</parameter></term>
101 Specify the window coordinates of the left corner
102 of the row of pixels to be copied.
107 <term><parameter>width
</parameter></term>
110 Specifies the width of the texture image.
112 <inlineequation><mml:math>
113 <!-- eqn: 2 sup n + 2 ( border ): -->
115 <mml:msup><mml:mn>2</mml:mn>
116 <mml:mi mathvariant=
"italic">n
</mml:mi>
121 <mml:mo>⁡</mml:mo>
122 <mml:mfenced open=
"(" close=
")">
123 <mml:mi mathvariant=
"italic">border
</mml:mi>
127 </mml:math></inlineequation>
129 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>.
130 The height of the texture image is
1.
135 <term><parameter>border
</parameter></term>
138 Specifies the width of the border.
139 Must be either
0 or
1.
145 <refsect1 id=
"description"><title>Description
</title>
147 <function>glCopyTexImage1D
</function> defines a one-dimensional texture image with pixels from the current
148 <constant>GL_READ_BUFFER
</constant>.
151 The screen-aligned pixel row with left corner at
152 <inlineequation><mml:math>
153 <!-- eqn: (x, y): -->
154 <mml:mfenced open=
"(" close=
")">
155 <mml:mi mathvariant=
"italic">x
</mml:mi>
156 <mml:mi mathvariant=
"italic">y
</mml:mi>
158 </mml:math></inlineequation>
160 <inlineequation><mml:math>
161 <!-- eqn: width + 2 ( border ): -->
163 <mml:mi mathvariant=
"italic">width
</mml:mi>
167 <mml:mo>⁡</mml:mo>
168 <mml:mfenced open=
"(" close=
")">
169 <mml:mi mathvariant=
"italic">border
</mml:mi>
173 </mml:math></inlineequation>
174 defines the texture array
175 at the mipmap level specified by
<parameter>level
</parameter>.
176 <parameter>internalformat
</parameter> specifies the internal format of the texture array.
179 The pixels in the row are processed exactly as if
180 <citerefentry><refentrytitle>glReadPixels
</refentrytitle></citerefentry> had been called, but the process stops just before
182 At this point all pixel component values are clamped to the range
183 <inlineequation><mml:math>
185 <mml:mfenced open=
"[" close=
"]">
189 </mml:math></inlineequation>
190 and then converted to the texture's internal format for storage in the texel
194 Pixel ordering is such that lower
195 <inlineequation><mml:math><mml:mi mathvariant=
"italic">x
</mml:mi></mml:math></inlineequation>
196 screen coordinates correspond to
197 lower texture coordinates.
200 If any of the pixels within the specified row of the current
201 <constant>GL_READ_BUFFER
</constant> are outside the window associated with the current
202 rendering context, then the values obtained for those pixels are undefined.
205 <function>glCopyTexImage1D
</function> defines a one-dimensional texture image with pixels from the current
206 <constant>GL_READ_BUFFER
</constant>.
209 When
<parameter>internalformat
</parameter> is one of the sRGB types, the GL does not automatically convert the source pixels to the sRGB color space. In this case, the
<function>glPixelMap
</function> function can be used to accomplish the conversion.
212 <refsect1 id=
"notes"><title>Notes
</title>
214 1,
2,
3, and
4 are not accepted values for
<parameter>internalformat
</parameter>.
217 An image with
0 width indicates a NULL texture.
220 <refsect1 id=
"errors"><title>Errors
</title>
222 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>target
</parameter> is not one of the allowable values.
225 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>level
</parameter> is less than
0.
228 <constant>GL_INVALID_VALUE
</constant> may be generated if
<parameter>level
</parameter> is greater
230 <inlineequation><mml:math>
231 <!-- eqn: log sub 2 max: -->
233 <mml:msub><mml:mi mathvariant=
"italic">log
</mml:mi>
236 <mml:mo>⁢</mml:mo>
237 <mml:mi mathvariant=
"italic">max
</mml:mi>
239 </mml:math></inlineequation>,
241 <inlineequation><mml:math><mml:mi mathvariant=
"italic">max
</mml:mi></mml:math></inlineequation>
242 is the returned value of
<constant>GL_MAX_TEXTURE_SIZE
</constant>.
245 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>internalformat
</parameter> is not an allowable value.
248 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>width
</parameter> is less than
0 or greater than
249 <constant>GL_MAX_TEXTURE_SIZE
</constant>.
252 <constant>GL_INVALID_VALUE
</constant> is generated if non-power-of-two textures are not supported and the
<parameter>width
</parameter> cannot be represented as
253 <inlineequation><mml:math>
254 <!-- eqn: 2 sup n + 2 ( border ): -->
256 <mml:msup><mml:mn>2</mml:mn>
257 <mml:mi mathvariant=
"italic">n
</mml:mi>
262 <mml:mo>⁡</mml:mo>
263 <mml:mfenced open=
"(" close=
")">
264 <mml:mi mathvariant=
"italic">border
</mml:mi>
268 </mml:math></inlineequation>
269 for some integer value of
<emphasis>n
</emphasis>.
272 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>border
</parameter> is not
0 or
1.
275 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>internalformat
</parameter> is
276 <constant>GL_DEPTH_COMPONENT
</constant>,
<constant>GL_DEPTH_COMPONENT16
</constant>,
277 <constant>GL_DEPTH_COMPONENT24
</constant>, or
<constant>GL_DEPTH_COMPONENT32
</constant> and there is no depth
281 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
283 <citerefentry><refentrytitle>glGetTexImage
</refentrytitle></citerefentry>
286 <refsect1 id=
"seealso"><title>See Also
</title>
288 <citerefentry><refentrytitle>glCopyTexImage2D
</refentrytitle></citerefentry>,
289 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
290 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
291 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
292 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
293 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
294 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
295 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
296 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
299 <refsect1 id=
"Copyright"><title>Copyright
</title>
301 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
302 Silicon Graphics, Inc. This document is licensed under the SGI
303 Free Software B License. For details, see
304 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.