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=
"glCopyTexImage2D">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glCopyTexImage2D
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glCopyTexImage2D
</refname>
17 <refpurpose>copy pixels into a
2D texture image
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glCopyTexImage2D
</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>GLsizei
<parameter>height
</parameter></paramdef>
30 <paramdef>GLint
<parameter>border
</parameter></paramdef>
34 <!-- 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_2D
</constant>,
43 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X
</constant>,
44 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X
</constant>,
45 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y
</constant>,
46 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
</constant>,
47 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z
</constant>, or
48 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
</constant>.
53 <term><parameter>level
</parameter></term>
56 Specifies the level-of-detail number.
57 Level
0 is the base image level.
58 Level
<emphasis>n
</emphasis> is the
<emphasis>n
</emphasis>th mipmap reduction image.
63 <term><parameter>internalformat
</parameter></term>
66 Specifies the internal format of the texture.
67 Must be one of the following symbolic constants:
68 <constant>GL_ALPHA
</constant>,
69 <constant>GL_ALPHA4
</constant>,
70 <constant>GL_ALPHA8
</constant>,
71 <constant>GL_ALPHA12
</constant>,
72 <constant>GL_ALPHA16
</constant>,
73 <constant>GL_COMPRESSED_ALPHA
</constant>,
74 <constant>GL_COMPRESSED_LUMINANCE
</constant>,
75 <constant>GL_COMPRESSED_LUMINANCE_ALPHA
</constant>,
76 <constant>GL_COMPRESSED_INTENSITY
</constant>,
77 <constant>GL_COMPRESSED_RGB
</constant>,
78 <constant>GL_COMPRESSED_RGBA
</constant>,
79 <constant>GL_DEPTH_COMPONENT
</constant>,
80 <constant>GL_DEPTH_COMPONENT16
</constant>,
81 <constant>GL_DEPTH_COMPONENT24
</constant>,
82 <constant>GL_DEPTH_COMPONENT32
</constant>,
83 <constant>GL_LUMINANCE
</constant>,
84 <constant>GL_LUMINANCE4
</constant>,
85 <constant>GL_LUMINANCE8
</constant>,
86 <constant>GL_LUMINANCE12
</constant>,
87 <constant>GL_LUMINANCE16
</constant>,
88 <constant>GL_LUMINANCE_ALPHA
</constant>,
89 <constant>GL_LUMINANCE4_ALPHA4
</constant>,
90 <constant>GL_LUMINANCE6_ALPHA2
</constant>,
91 <constant>GL_LUMINANCE8_ALPHA8
</constant>,
92 <constant>GL_LUMINANCE12_ALPHA4
</constant>,
93 <constant>GL_LUMINANCE12_ALPHA12
</constant>,
94 <constant>GL_LUMINANCE16_ALPHA16
</constant>,
95 <constant>GL_INTENSITY
</constant>,
96 <constant>GL_INTENSITY4
</constant>,
97 <constant>GL_INTENSITY8
</constant>,
98 <constant>GL_INTENSITY12
</constant>,
99 <constant>GL_INTENSITY16
</constant>,
100 <constant>GL_RGB
</constant>,
101 <constant>GL_R3_G3_B2
</constant>,
102 <constant>GL_RGB4
</constant>,
103 <constant>GL_RGB5
</constant>,
104 <constant>GL_RGB8
</constant>,
105 <constant>GL_RGB10
</constant>,
106 <constant>GL_RGB12
</constant>,
107 <constant>GL_RGB16
</constant>,
108 <constant>GL_RGBA
</constant>,
109 <constant>GL_RGBA2
</constant>,
110 <constant>GL_RGBA4
</constant>,
111 <constant>GL_RGB5_A1
</constant>,
112 <constant>GL_RGBA8
</constant>,
113 <constant>GL_RGB10_A2
</constant>,
114 <constant>GL_RGBA12
</constant>,
115 <constant>GL_RGBA16
</constant>,
116 <constant>GL_SLUMINANCE
</constant>,
117 <constant>GL_SLUMINANCE8
</constant>,
118 <constant>GL_SLUMINANCE_ALPHA
</constant>,
119 <constant>GL_SLUMINANCE8_ALPHA8
</constant>,
120 <constant>GL_SRGB
</constant>,
121 <constant>GL_SRGB8
</constant>,
122 <constant>GL_SRGB_ALPHA
</constant>, or
123 <constant>GL_SRGB8_ALPHA8
</constant>.
128 <term><parameter>x
</parameter></term>
129 <term><parameter>y
</parameter></term>
132 Specify the window coordinates of the lower left corner
133 of the rectangular region of pixels to be copied.
138 <term><parameter>width
</parameter></term>
141 Specifies the width of the texture image.
143 <inlineequation><mml:math>
144 <!-- eqn: 2 sup n + 2 ( border ):-->
146 <mml:msup><mml:mn>2</mml:mn>
147 <mml:mi mathvariant=
"italic">n
</mml:mi>
152 <mml:mo>⁡</mml:mo>
153 <mml:mfenced open=
"(" close=
")">
154 <mml:mi mathvariant=
"italic">border
</mml:mi>
158 </mml:math></inlineequation>
160 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>.
165 <term><parameter>height
</parameter></term>
168 Specifies the height of the texture image.
170 <inlineequation><mml:math>
171 <!-- eqn: 2 sup m + 2 ( border ):-->
173 <mml:msup><mml:mn>2</mml:mn>
174 <mml:mi mathvariant=
"italic">m
</mml:mi>
179 <mml:mo>⁡</mml:mo>
180 <mml:mfenced open=
"(" close=
")">
181 <mml:mi mathvariant=
"italic">border
</mml:mi>
185 </mml:math></inlineequation>
187 <inlineequation><mml:math><mml:mi mathvariant=
"italic">m
</mml:mi></mml:math></inlineequation>.
192 <term><parameter>border
</parameter></term>
195 Specifies the width of the border.
196 Must be either
0 or
1.
202 <refsect1 id=
"description"><title>Description
</title>
204 <function>glCopyTexImage2D
</function> defines a two-dimensional texture image, or cube-map texture image
205 with pixels from the current
206 <constant>GL_READ_BUFFER
</constant>.
209 The screen-aligned pixel rectangle with lower left corner at (
<parameter>x
</parameter>,
210 <parameter>y
</parameter>) and with a width of
211 <inlineequation><mml:math>
212 <!-- eqn: width + 2 ( border ):-->
214 <mml:mi mathvariant=
"italic">width
</mml:mi>
218 <mml:mo>⁡</mml:mo>
219 <mml:mfenced open=
"(" close=
")">
220 <mml:mi mathvariant=
"italic">border
</mml:mi>
224 </mml:math></inlineequation>
226 <inlineequation><mml:math>
227 <!-- eqn: height + 2 ( border ):-->
229 <mml:mi mathvariant=
"italic">height
</mml:mi>
233 <mml:mo>⁡</mml:mo>
234 <mml:mfenced open=
"(" close=
")">
235 <mml:mi mathvariant=
"italic">border
</mml:mi>
239 </mml:math></inlineequation>
240 defines the texture array
241 at the mipmap level specified by
<parameter>level
</parameter>.
242 <parameter>internalformat
</parameter> specifies the internal format of the texture array.
245 The pixels in the rectangle are processed exactly as if
246 <citerefentry><refentrytitle>glCopyPixels
</refentrytitle></citerefentry> had been called, but the process stops just before
248 At this point all pixel component values are clamped to the range
249 <inlineequation><mml:math>
251 <mml:mfenced open=
"[" close=
"]">
255 </mml:math></inlineequation>
256 and then converted to the texture's internal format for storage in the texel
260 Pixel ordering is such that lower
261 <inlineequation><mml:math><mml:mi mathvariant=
"italic">x
</mml:mi></mml:math></inlineequation>
263 <inlineequation><mml:math><mml:mi mathvariant=
"italic">y
</mml:mi></mml:math></inlineequation>
264 screen coordinates correspond to
266 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
268 <inlineequation><mml:math><mml:mi mathvariant=
"italic">t
</mml:mi></mml:math></inlineequation>
272 If any of the pixels within the specified rectangle of the current
273 <constant>GL_READ_BUFFER
</constant> are outside the window associated with the current
274 rendering context, then the values obtained for those pixels are undefined.
277 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.
280 <refsect1 id=
"notes"><title>Notes
</title>
282 <function>glCopyTexImage2D
</function> is available only if the GL version is
1.1 or greater.
285 Texturing has no effect in color index mode.
288 1,
2,
3, and
4 are not accepted values for
<parameter>internalformat
</parameter>.
291 An image with height or width of
0 indicates a NULL texture.
294 When the
<code>ARB_imaging
</code> extension is supported, the RGBA components read from the framebuffer may be processed by the imaging pipeline. See
<citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry> for specific details.
297 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X
</constant>,
298 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X
</constant>,
299 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y
</constant>,
300 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
</constant>,
301 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z
</constant>,
302 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
</constant>, or
303 <constant>GL_PROXY_TEXTURE_CUBE_MAP
</constant> are available only if the GL version is
1.3
307 <constant>GL_DEPTH_COMPONENT
</constant>,
<constant>GL_DEPTH_COMPONENT16
</constant>,
<constant>GL_DEPTH_COMPONENT24
</constant>,
308 and
<constant>GL_DEPTH_COMPONENT32
</constant> are available only if the GL version is
1.4
313 <constant>GL_SRGB
</constant>,
314 <constant>GL_SRGB8
</constant>,
315 <constant>GL_SRGB_ALPHA
</constant>,
316 <constant>GL_SRGB8_ALPHA8
</constant>,
317 <constant>GL_SLUMINANCE
</constant>,
318 <constant>GL_SLUMINANCE8
</constant>,
319 <constant>GL_SLUMINANCE_ALPHA
</constant>, and
320 <constant>GL_SLUMINANCE8_ALPHA8
</constant>
321 internal formats are only available if the GL version is
2.1 or greater. See
<citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry> for specific details about sRGB conversion.
324 <refsect1 id=
"errors"><title>Errors
</title>
326 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>target
</parameter> is not
<constant>GL_TEXTURE_2D
</constant>,
327 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X
</constant>,
328 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X
</constant>,
329 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y
</constant>,
330 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
</constant>,
331 <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z
</constant>, or
332 <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z
</constant>.
335 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>level
</parameter> is less than
0.
338 <constant>GL_INVALID_VALUE
</constant> may be generated if
<parameter>level
</parameter> is greater
340 <inlineequation><mml:math>
341 <!-- eqn: log sub 2 max:-->
343 <mml:msub><mml:mi mathvariant=
"italic">log
</mml:mi>
346 <mml:mo>⁢</mml:mo>
347 <mml:mi mathvariant=
"italic">max
</mml:mi>
349 </mml:math></inlineequation>,
351 <inlineequation><mml:math><mml:mi mathvariant=
"italic">max
</mml:mi></mml:math></inlineequation>
352 is the returned value of
<constant>GL_MAX_TEXTURE_SIZE
</constant>.
355 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>width
</parameter> is less than
0
357 2 +
<constant>GL_MAX_TEXTURE_SIZE
</constant>.
360 <constant>GL_INVALID_VALUE
</constant> is generated if non-power-of-two textures are not supported and the
<parameter>width
</parameter> or
<parameter>depth
</parameter> cannot be represented as
361 <inlineequation><mml:math>
362 <!-- eqn: 2 sup k + 2 ( border ):-->
364 <mml:msup><mml:mn>2</mml:mn>
365 <mml:mi mathvariant=
"italic">k
</mml:mi>
370 <mml:mo>⁡</mml:mo>
371 <mml:mfenced open=
"(" close=
")">
372 <mml:mi mathvariant=
"italic">border
</mml:mi>
376 </mml:math></inlineequation>
378 <inlineequation><mml:math><mml:mi mathvariant=
"italic">k
</mml:mi></mml:math></inlineequation>.
381 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>border
</parameter> is not
0 or
1.
384 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>internalformat
</parameter> is not an
388 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glCopyTexImage2D
</function> is executed
389 between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry> and the corresponding
390 execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
393 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>internalformat
</parameter> is
394 <constant>GL_DEPTH_COMPONENT
</constant>,
<constant>GL_DEPTH_COMPONENT16
</constant>,
395 <constant>GL_DEPTH_COMPONENT24
</constant>, or
<constant>GL_DEPTH_COMPONENT32
</constant> and there is no depth
399 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
401 <citerefentry><refentrytitle>glGetTexImage
</refentrytitle></citerefentry>
404 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_TEXTURE_2D
</constant> or
<constant>GL_TEXTURE_CUBE_MAP
</constant>
407 <refsect1 id=
"seealso"><title>See Also
</title>
409 <citerefentry><refentrytitle>glCopyPixels
</refentrytitle></citerefentry>,
410 <citerefentry><refentrytitle>glCopyTexImage1D
</refentrytitle></citerefentry>,
411 <citerefentry><refentrytitle>glCopyTexSubImage1D
</refentrytitle></citerefentry>,
412 <citerefentry><refentrytitle>glCopyTexSubImage2D
</refentrytitle></citerefentry>,
413 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
414 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>,
415 <citerefentry><refentrytitle>glTexEnv
</refentrytitle></citerefentry>,
416 <citerefentry><refentrytitle>glTexGen
</refentrytitle></citerefentry>,
417 <citerefentry><refentrytitle>glTexImage1D
</refentrytitle></citerefentry>,
418 <citerefentry><refentrytitle>glTexImage2D
</refentrytitle></citerefentry>,
419 <citerefentry><refentrytitle>glTexSubImage1D
</refentrytitle></citerefentry>,
420 <citerefentry><refentrytitle>glTexSubImage2D
</refentrytitle></citerefentry>,
421 <citerefentry><refentrytitle>glTexParameter
</refentrytitle></citerefentry>
424 <refsect1 id=
"Copyright"><title>Copyright
</title>
426 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
427 Silicon Graphics, Inc. This document is licensed under the SGI
428 Free Software B License. For details, see
429 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.