_C_ License Applicability. Except to the extent portions of this file are
_C_ made subject to an alternative license as permitted in the SGI Free
_C_ Software License B, Version 1.1 (the "License"), the contents of this
_C_ file are subject only to the provisions of the License. You may not use
_C_ this file except in compliance with the License. You may obtain a copy
_C_ of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
_C_ Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
_C_ 
_C_ http://oss.sgi.com/projects/FreeB
_C_ 
_C_ Note that, as provided in the License, the Software is distributed on an
_C_ "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
_C_ DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
_C_ CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
_C_ PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
_C_ 
_C_ Original Code. The Original Code is: OpenGL Sample Implementation,
_C_ Version 1.2.1, released January 26, 2000, developed by Silicon Graphics,
_C_ Inc. The Original Code is Copyright (c) 1991-2000 Silicon Graphics, Inc.
_C_ Copyright in any portions created by third parties is as indicated
_C_ elsewhere herein. All Rights Reserved.
_C_ 
_C_ Additional Notice Provisions: The application programming interfaces
_C_ established by SGI in conjunction with the Original Code are The
_C_ OpenGL(R) Graphics System: A Specification (Version 1.2.1), released
_C_ April 1, 1999; The OpenGL(R) Graphics System Utility Library (Version
_C_ 1.3), released November 4, 1998; and OpenGL(R) Graphics with the X
_C_ Window System(R) (Version 1.3), released October 19, 1998. This software
_C_ was created using the OpenGL(R) version 1.2.1 Sample Implementation
_C_ published by SGI, but has not been independently verified as being
_C_ compliant with the OpenGL(R) version 1.2.1 Specification.
_C_
_C_ The first character in this file must be an '_'!
_C_ Anything on a line after _C_ is ignored
_define(_filters,eqn)_C_
_C_      eqn is automatically replaced with neqn for nroff
_header(CopyTexImage2D,copy pixels into a 2D texture image)
_names(CopyTexImage2D)
.EQ
delim $$
.EN
.SH PARAMETERS
_phead(_param1)
Specifies the target texture.
Must be _const(TEXTURE_2D).
_phead(_param2)
Specifies the level-of-detail number.
Level 0 is the base image level.
Level \f2n\fP is the \f2n\fPth mipmap reduction image.
_phead(_param3)
Specifies the internal format of the texture.
Must be one of the following symbolic constants:
_const(ALPHA),
_const(ALPHA4),
_const(ALPHA8),
_const(ALPHA12),
_const(ALPHA16),
_const(LUMINANCE),
_const(LUMINANCE4),
_const(LUMINANCE8),
_const(LUMINANCE12),
_const(LUMINANCE16),
_const(LUMINANCE_ALPHA),
_const(LUMINANCE4_ALPHA4),
_const(LUMINANCE6_ALPHA2),
_const(LUMINANCE8_ALPHA8),
_const(LUMINANCE12_ALPHA4),
_const(LUMINANCE12_ALPHA12),
_const(LUMINANCE16_ALPHA16),
_const(INTENSITY),
_const(INTENSITY4),
_const(INTENSITY8),
_const(INTENSITY12),
_const(INTENSITY16),
_const(RGB),
_const(R3_G3_B2),
_const(RGB4),
_const(RGB5),
_const(RGB8),
_const(RGB10),
_const(RGB12),
_const(RGB16),
_const(RGBA),
_const(RGBA2),
_const(RGBA4),
_const(RGB5_A1),
_const(RGBA8),
_const(RGB10_A2),
_const(RGBA12), or
_const(RGBA16).
_phead(_param4 _param5)
Specify the window coordinates of the lower left corner
of the rectangular region of pixels to be copied.
_phead(_param6)
Specifies the width of the texture image.
Must be 0 or $2 sup n ~+~ 2*$_param8 for some integer $n$.
_phead(_param7)
Specifies the height of the texture image.
Must be 0 or $2 sup m ~+~ 2*$_param8 for some integer $m$.
_phead(_param8)
Specifies the width of the border.
Must be either 0 or 1.
.SH DESCRIPTION
_cmnd defines a two-dimensional texture image with pixels from the current
_const(READ_BUFFER).
.P
The screen-aligned pixel rectangle with lower left corner at (_param4,
_param5) and with a width of _param6$~+~2~*~$_param8 and a height of
_param7$~+~2~*~$_param8 
defines the texture array
at the mipmap level specified by _param2.
_param3 specifies the internal format of the texture array.
.P
The pixels in the rectangle are processed exactly as if
_cmnd(CopyPixels) had been called, but the process stops just before
final conversion.
At this point all pixel component values are clamped to the range $[0,1]$
and then converted to the texture's internal format for storage in the texel
array.
.P
Pixel ordering is such that lower $x$ and $y$ screen coordinates correspond to 
lower $s$ and $t$ texture coordinates.
.P
If any of the pixels within the specified rectangle of the current
_const(READ_BUFFER) are outside the window associated with the current
rendering context, then the values obtained for those pixels are undefined.
.P
.SH NOTES
_cmnd is available only if the GL version is 1.1 or greater.
.P
Texturing has no effect in color index mode.
.P
1, 2, 3, and 4 are not accepted values for _param3.
.P 
An image with height or width of 0 indicates a NULL texture. 
.P
When the _arbstring(imaging) extension is supported, the RGBA components
read from the framebuffer may be processed by the imaging pipeline.  See
_cmnd(TexImage1D) for specific details.
.SH ERRORS
_const(INVALID_ENUM) is generated if _param1 is not _const(TEXTURE_2D).
.P
_const(INVALID_VALUE) is generated if _param2 is less than 0.
.P 
_const(INVALID_VALUE) may be generated if _param2 is greater
than $log sub 2 max$,
where $max$ is the returned value of _const(MAX_TEXTURE_SIZE).
.P
_const(INVALID_VALUE) is generated if _param6 or _param7 is less than 0,
greater than $2~+~$_const(MAX_TEXTURE_SIZE), or if _param6 or _param7 cannot be
represented as $2 sup k ~+~ 2~*~$_param8 for some integer
$k$.
.P
_const(INVALID_VALUE) is generated if _param8 is not 0 or 1.
.P
_const(INVALID_VALUE) is generated if _param3 is not one of the
allowable values.
.P
_const(INVALID_OPERATION) is generated if _cmnd is executed
between the execution of _cmnd(Begin) and the corresponding
execution of _cmnd(End).
.SH ASSOCIATED GETS
_cmnd(GetTexImage)
.br
_cmnd(IsEnabled) with argument _const(TEXTURE_2D)
.SH SEE ALSO
_cmnd(CopyPixels),
_cmnd(CopyTexImage1D),
_cmnd(CopyTexSubImage1D),
_cmnd(CopyTexSubImage2D),
_cmnd(PixelStore),
_cmnd(PixelTransfer),
_cmnd(TexEnv),
_cmnd(TexGen),
_cmnd(TexImage1D),
_cmnd(TexImage2D),
_cmnd(TexSubImage1D),
_cmnd(TexSubImage2D),
.br
_cmnd(TexParameter)