[clinton/guile-figl.git] / upstream-doc / man2 / glCopyTexImage2D.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glCopyTexImage2D">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glCopyTexImage2D</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glCopyTexImage2D</refname>
        <refpurpose>copy pixels into a 2D texture image</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glCopyTexImage2D</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLint <parameter>level</parameter></paramdef>
                <paramdef>GLenum <parameter>internalformat</parameter></paramdef>
                <paramdef>GLint <parameter>x</parameter></paramdef>
                <paramdef>GLint <parameter>y</parameter></paramdef>
                <paramdef>GLsizei <parameter>width</parameter></paramdef>
                <paramdef>GLsizei <parameter>height</parameter></paramdef>
                <paramdef>GLint <parameter>border</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specifies the target texture.
                    Must be <constant>GL_TEXTURE_2D</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
                    <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>level</parameter></term>
            <listitem>
                <para>
                    Specifies the level-of-detail number.
                    Level 0 is the base image level.
                    Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>internalformat</parameter></term>
            <listitem>
                <para>
                    Specifies the internal format of the texture.
                    Must be one of the following symbolic constants:
                    <constant>GL_ALPHA</constant>,
                    <constant>GL_ALPHA4</constant>,
                    <constant>GL_ALPHA8</constant>,
                    <constant>GL_ALPHA12</constant>,
                    <constant>GL_ALPHA16</constant>,
                    <constant>GL_COMPRESSED_ALPHA</constant>,
                    <constant>GL_COMPRESSED_LUMINANCE</constant>,
                    <constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
                    <constant>GL_COMPRESSED_INTENSITY</constant>,
                    <constant>GL_COMPRESSED_RGB</constant>,
                    <constant>GL_COMPRESSED_RGBA</constant>,
                    <constant>GL_DEPTH_COMPONENT</constant>,
                    <constant>GL_DEPTH_COMPONENT16</constant>,
                    <constant>GL_DEPTH_COMPONENT24</constant>,
                    <constant>GL_DEPTH_COMPONENT32</constant>,
                    <constant>GL_LUMINANCE</constant>,
                    <constant>GL_LUMINANCE4</constant>,
                    <constant>GL_LUMINANCE8</constant>,
                    <constant>GL_LUMINANCE12</constant>,
                    <constant>GL_LUMINANCE16</constant>,
                    <constant>GL_LUMINANCE_ALPHA</constant>,
                    <constant>GL_LUMINANCE4_ALPHA4</constant>,
                    <constant>GL_LUMINANCE6_ALPHA2</constant>,
                    <constant>GL_LUMINANCE8_ALPHA8</constant>,
                    <constant>GL_LUMINANCE12_ALPHA4</constant>,
                    <constant>GL_LUMINANCE12_ALPHA12</constant>,
                    <constant>GL_LUMINANCE16_ALPHA16</constant>,
                    <constant>GL_INTENSITY</constant>,
                    <constant>GL_INTENSITY4</constant>,
                    <constant>GL_INTENSITY8</constant>,
                    <constant>GL_INTENSITY12</constant>,
                    <constant>GL_INTENSITY16</constant>,
                    <constant>GL_RGB</constant>,
                    <constant>GL_R3_G3_B2</constant>,
                    <constant>GL_RGB4</constant>,
                    <constant>GL_RGB5</constant>,
                    <constant>GL_RGB8</constant>,
                    <constant>GL_RGB10</constant>,
                    <constant>GL_RGB12</constant>,
                    <constant>GL_RGB16</constant>,
                    <constant>GL_RGBA</constant>,
                    <constant>GL_RGBA2</constant>,
                    <constant>GL_RGBA4</constant>,
                    <constant>GL_RGB5_A1</constant>,
                    <constant>GL_RGBA8</constant>,
                    <constant>GL_RGB10_A2</constant>,
                    <constant>GL_RGBA12</constant>,
                    <constant>GL_RGBA16</constant>,
                    <constant>GL_SLUMINANCE</constant>,
                    <constant>GL_SLUMINANCE8</constant>,
                    <constant>GL_SLUMINANCE_ALPHA</constant>,
                    <constant>GL_SLUMINANCE8_ALPHA8</constant>,
                    <constant>GL_SRGB</constant>,
                    <constant>GL_SRGB8</constant>,
                    <constant>GL_SRGB_ALPHA</constant>, or 
                    <constant>GL_SRGB8_ALPHA8</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>x</parameter></term>
            <term><parameter>y</parameter></term>
            <listitem>
                <para>
                    Specify the window coordinates of the lower left corner
                    of the rectangular region of pixels to be copied.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>width</parameter></term>
            <listitem>
                <para>
                    Specifies the width of the texture image.
                    Must be 0 or 
                    <inlineequation><mml:math>
                        <!-- eqn: 2 sup n  +  2 ( border ):-->
                        <mml:mrow>
                            <mml:msup><mml:mn>2</mml:mn>
                            <mml:mi mathvariant="italic">n</mml:mi>
                            </mml:msup>
                            <mml:mo>+</mml:mo>
                            <mml:mrow>
                                <mml:mn>2</mml:mn>
                                <mml:mo>&af;</mml:mo>
                                <mml:mfenced open="(" close=")">
                                    <mml:mi mathvariant="italic">border</mml:mi>
                                </mml:mfenced>
                            </mml:mrow>
                        </mml:mrow>
                    </mml:math></inlineequation>
                    for some integer 
                    <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>height</parameter></term>
            <listitem>
                <para>
                    Specifies the height of the texture image.
                    Must be 0 or 
                    <inlineequation><mml:math>
                        <!-- eqn: 2 sup m  +  2 ( border ):-->
                        <mml:mrow>
                            <mml:msup><mml:mn>2</mml:mn>
                            <mml:mi mathvariant="italic">m</mml:mi>
                            </mml:msup>
                            <mml:mo>+</mml:mo>
                            <mml:mrow>
                                <mml:mn>2</mml:mn>
                                <mml:mo>&af;</mml:mo>
                                <mml:mfenced open="(" close=")">
                                    <mml:mi mathvariant="italic">border</mml:mi>
                                </mml:mfenced>
                            </mml:mrow>
                        </mml:mrow>
                    </mml:math></inlineequation>
                    for some integer 
                    <inlineequation><mml:math><mml:mi mathvariant="italic">m</mml:mi></mml:math></inlineequation>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>border</parameter></term>
            <listitem>
                <para>
                    Specifies the width of the border.
                    Must be either 0 or 1.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glCopyTexImage2D</function> defines a two-dimensional texture image, or cube-map texture image
            with pixels from the current
            <constant>GL_READ_BUFFER</constant>.
        </para>
        <para>
            The screen-aligned pixel rectangle with lower left corner at (<parameter>x</parameter>,
            <parameter>y</parameter>) and with a width of 
            <inlineequation><mml:math>
                <!-- eqn: width  +  2 ( border ):-->
                <mml:mrow>
                    <mml:mi mathvariant="italic">width</mml:mi>
                    <mml:mo>+</mml:mo>
                    <mml:mrow>
                        <mml:mn>2</mml:mn>
                        <mml:mo>&af;</mml:mo>
                        <mml:mfenced open="(" close=")">
                            <mml:mi mathvariant="italic">border</mml:mi>
                        </mml:mfenced>
                    </mml:mrow>
                </mml:mrow>
            </mml:math></inlineequation>
            and a height of
            <inlineequation><mml:math>
                <!-- eqn: height  +  2 ( border ):-->
                <mml:mrow>
                    <mml:mi mathvariant="italic">height</mml:mi>
                    <mml:mo>+</mml:mo>
                    <mml:mrow>
                        <mml:mn>2</mml:mn>
                        <mml:mo>&af;</mml:mo>
                        <mml:mfenced open="(" close=")">
                            <mml:mi mathvariant="italic">border</mml:mi>
                        </mml:mfenced>
                    </mml:mrow>
                </mml:mrow>
            </mml:math></inlineequation>
            defines the texture array
            at the mipmap level specified by <parameter>level</parameter>.
            <parameter>internalformat</parameter> specifies the internal format of the texture array.
        </para>
        <para>
            The pixels in the rectangle are processed exactly as if
            <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry> had been called, but the process stops just before
            final conversion.
            At this point all pixel component values are clamped to the range 
            <inlineequation><mml:math>
                <!-- eqn: [0,1]:-->
                <mml:mfenced open="[" close="]">
                    <mml:mn>0</mml:mn>
                    <mml:mn>1</mml:mn>
                </mml:mfenced>
            </mml:math></inlineequation>
            and then converted to the texture's internal format for storage in the texel
            array.
        </para>
        <para>
            Pixel ordering is such that lower 
            <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
            and 
            <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
            screen coordinates correspond to
            lower 
            <inlineequation><mml:math><mml:mi mathvariant="italic">s</mml:mi></mml:math></inlineequation>
            and 
            <inlineequation><mml:math><mml:mi mathvariant="italic">t</mml:mi></mml:math></inlineequation>
            texture coordinates.
        </para>
        <para>
            If any of the pixels within the specified rectangle of the current
            <constant>GL_READ_BUFFER</constant> are outside the window associated with the current
            rendering context, then the values obtained for those pixels are undefined.
        </para>
         <para>
            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.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            <function>glCopyTexImage2D</function> is available only if the GL version is 1.1 or greater.
        </para>
        <para>
            Texturing has no effect in color index mode.
        </para>
        <para>
            1, 2, 3, and 4 are not accepted values for <parameter>internalformat</parameter>.
        </para>
        <para>
            An image with height or width of 0 indicates a NULL texture.
        </para>
        <para>
            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.
        </para>
        <para>
            <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
            <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant> are available only if the GL version is 1.3
            or greater.
        </para>
        <para>
            <constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_DEPTH_COMPONENT16</constant>, <constant>GL_DEPTH_COMPONENT24</constant>,
            and <constant>GL_DEPTH_COMPONENT32</constant> are available only if the GL version is 1.4
            or greater.
        </para>
        <para>
            The 
			<constant>GL_SRGB</constant>,
			<constant>GL_SRGB8</constant>,
			<constant>GL_SRGB_ALPHA</constant>,
			<constant>GL_SRGB8_ALPHA8</constant>,
			<constant>GL_SLUMINANCE</constant>,
			<constant>GL_SLUMINANCE8</constant>,
			<constant>GL_SLUMINANCE_ALPHA</constant>, and
			<constant>GL_SLUMINANCE8_ALPHA8</constant>
			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.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_2D</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
            <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
            than 
            <inlineequation><mml:math>
                <!-- eqn: log sub 2 max:-->
                <mml:mrow>
                    <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
                    <mml:mn>2</mml:mn>
                    </mml:msub>
                    <mml:mo>&it;</mml:mo>
                    <mml:mi mathvariant="italic">max</mml:mi>
                </mml:mrow>
            </mml:math></inlineequation>,
            where 
            <inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
            is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than 0
            or greater than
            2 + <constant>GL_MAX_TEXTURE_SIZE</constant>.
        </para>
        <para>
            <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  
            <inlineequation><mml:math>
                <!-- eqn: 2 sup k  +  2 ( border ):-->
                <mml:mrow>
                    <mml:msup><mml:mn>2</mml:mn>
                    <mml:mi mathvariant="italic">k</mml:mi>
                    </mml:msup>
                    <mml:mo>+</mml:mo>
                    <mml:mrow>
                        <mml:mn>2</mml:mn>
                        <mml:mo>&af;</mml:mo>
                        <mml:mfenced open="(" close=")">
                            <mml:mi mathvariant="italic">border</mml:mi>
                        </mml:mfenced>
                    </mml:mrow>
                </mml:mrow>
            </mml:math></inlineequation>
            for some integer 
            <inlineequation><mml:math><mml:mi mathvariant="italic">k</mml:mi></mml:math></inlineequation>.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>border</parameter> is not 0 or 1.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>internalformat</parameter> is not an
            accepted format.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyTexImage2D</function> is executed
            between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
            execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>internalformat</parameter> is
            <constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_DEPTH_COMPONENT16</constant>,
            <constant>GL_DEPTH_COMPONENT24</constant>, or <constant>GL_DEPTH_COMPONENT32</constant> and there is no depth
            buffer.
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
        </para>
        <para>
            <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_2D</constant> or <constant>GL_TEXTURE_CUBE_MAP</constant> 
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
        </para>
    </refsect1>
</refentry>
Commit	Line	Data
7faf1d71 AW	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">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>1991-2006</year>
	9	<holder>Silicon Graphics, Inc.</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glCopyTexImage2D</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glCopyTexImage2D</refname>
	17	<refpurpose>copy pixels into a 2D texture image</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	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>
	31	</funcprototype>
	32	</funcsynopsis>
	33	</refsynopsisdiv>
	34	<!-- eqn: ignoring delim $$ -->
	35	<refsect1 id="parameters"><title>Parameters</title>
	36	<variablelist>
	37	<varlistentry>
	38	<term><parameter>target</parameter></term>
	39	<listitem>
	40	<para>
	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>.
	49	</para>
	50	</listitem>
	51	</varlistentry>
	52	<varlistentry>
	53	<term><parameter>level</parameter></term>
	54	<listitem>
	55	<para>
	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.
	59	</para>
	60	</listitem>
	61	</varlistentry>
	62	<varlistentry>
	63	<term><parameter>internalformat</parameter></term>
	64	<listitem>
65	<para>
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>.
124	</para>
125	</listitem>
126	</varlistentry>
127	<varlistentry>
128	<term><parameter>x</parameter></term>
129	<term><parameter>y</parameter></term>
130	<listitem>
131	<para>
132	Specify the window coordinates of the lower left corner
133	of the rectangular region of pixels to be copied.
134	</para>
135	</listitem>
136	</varlistentry>
137	<varlistentry>
138	<term><parameter>width</parameter></term>
139	<listitem>
140	<para>
141	Specifies the width of the texture image.
142	Must be 0 or
143	<inlineequation><mml:math>
144	<!-- eqn: 2 sup n + 2 ( border ):-->
145	<mml:mrow>
146	<mml:msup><mml:mn>2</mml:mn>
147	<mml:mi mathvariant="italic">n</mml:mi>
148	</mml:msup>
149	<mml:mo>+</mml:mo>
150	<mml:mrow>
151	<mml:mn>2</mml:mn>
152	<mml:mo>⁡</mml:mo>
153	<mml:mfenced open="(" close=")">
154	<mml:mi mathvariant="italic">border</mml:mi>
155	</mml:mfenced>
156	</mml:mrow>
157	</mml:mrow>
158	</mml:math></inlineequation>
159	for some integer
160	<inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
161	</para>
162	</listitem>
163	</varlistentry>
164	<varlistentry>
165	<term><parameter>height</parameter></term>
166	<listitem>
167	<para>
168	Specifies the height of the texture image.
169	Must be 0 or
170	<inlineequation><mml:math>
171	<!-- eqn: 2 sup m + 2 ( border ):-->
172	<mml:mrow>
173	<mml:msup><mml:mn>2</mml:mn>
174	<mml:mi mathvariant="italic">m</mml:mi>
175	</mml:msup>
176	<mml:mo>+</mml:mo>
177	<mml:mrow>
178	<mml:mn>2</mml:mn>
179	<mml:mo>⁡</mml:mo>
180	<mml:mfenced open="(" close=")">
181	<mml:mi mathvariant="italic">border</mml:mi>
182	</mml:mfenced>
183	</mml:mrow>
184	</mml:mrow>
185	</mml:math></inlineequation>
186	for some integer
187	<inlineequation><mml:math><mml:mi mathvariant="italic">m</mml:mi></mml:math></inlineequation>.
188	</para>
189	</listitem>
190	</varlistentry>
191	<varlistentry>
192	<term><parameter>border</parameter></term>
193	<listitem>
194	<para>
195	Specifies the width of the border.
196	Must be either 0 or 1.
197	</para>
198	</listitem>
199	</varlistentry>
200	</variablelist>
201	</refsect1>
202	<refsect1 id="description"><title>Description</title>
203	<para>
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>.
207	</para>
208	<para>
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 ):-->
213	<mml:mrow>
214	<mml:mi mathvariant="italic">width</mml:mi>
215	<mml:mo>+</mml:mo>
216	<mml:mrow>
217	<mml:mn>2</mml:mn>
218	<mml:mo>⁡</mml:mo>
219	<mml:mfenced open="(" close=")">
220	<mml:mi mathvariant="italic">border</mml:mi>
221	</mml:mfenced>
222	</mml:mrow>
223	</mml:mrow>
224	</mml:math></inlineequation>
225	and a height of
226	<inlineequation><mml:math>
227	<!-- eqn: height + 2 ( border ):-->
228	<mml:mrow>
229	<mml:mi mathvariant="italic">height</mml:mi>
230	<mml:mo>+</mml:mo>
231	<mml:mrow>
232	<mml:mn>2</mml:mn>
233	<mml:mo>⁡</mml:mo>
234	<mml:mfenced open="(" close=")">
235	<mml:mi mathvariant="italic">border</mml:mi>
236	</mml:mfenced>
237	</mml:mrow>
238	</mml:mrow>
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.
243	</para>
244	<para>
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
247	final conversion.
248	At this point all pixel component values are clamped to the range
249	<inlineequation><mml:math>
250	<!-- eqn: [0,1]:-->
251	<mml:mfenced open="[" close="]">
252	<mml:mn>0</mml:mn>
253	<mml:mn>1</mml:mn>
254	</mml:mfenced>
255	</mml:math></inlineequation>
256	and then converted to the texture's internal format for storage in the texel
257	array.
258	</para>
259	<para>
260	Pixel ordering is such that lower
261	<inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
262	and
263	<inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
264	screen coordinates correspond to
265	lower
266	<inlineequation><mml:math><mml:mi mathvariant="italic">s</mml:mi></mml:math></inlineequation>
267	and
268	<inlineequation><mml:math><mml:mi mathvariant="italic">t</mml:mi></mml:math></inlineequation>
269	texture coordinates.
270	</para>
271	<para>
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.
275	</para>
276	<para>
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.
278	</para>
279	</refsect1>
280	<refsect1 id="notes"><title>Notes</title>
281	<para>
282	<function>glCopyTexImage2D</function> is available only if the GL version is 1.1 or greater.
283	</para>
284	<para>
285	Texturing has no effect in color index mode.
286	</para>
287	<para>
288	1, 2, 3, and 4 are not accepted values for <parameter>internalformat</parameter>.
289	</para>
290	<para>
291	An image with height or width of 0 indicates a NULL texture.
292	</para>
293	<para>
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.
295	</para>
296	<para>
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
304	or greater.
305	</para>
306	<para>
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
309	or greater.
310	</para>
311	<para>
312	The
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.
322	</para>
323	</refsect1>
324	<refsect1 id="errors"><title>Errors</title>
325	<para>
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>.
333	</para>
334	<para>
335	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
336	</para>
337	<para>
338	<constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
339	than
340	<inlineequation><mml:math>
341	<!-- eqn: log sub 2 max:-->
342	<mml:mrow>
343	<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
344	<mml:mn>2</mml:mn>
345	</mml:msub>
346	<mml:mo>⁢</mml:mo>
347	<mml:mi mathvariant="italic">max</mml:mi>
348	</mml:mrow>
349	</mml:math></inlineequation>,
350	where
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>.
353	</para>
354	<para>
355	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than 0
356	or greater than
357	2 + <constant>GL_MAX_TEXTURE_SIZE</constant>.
358	</para>
359	<para>
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 ):-->
363	<mml:mrow>
364	<mml:msup><mml:mn>2</mml:mn>
365	<mml:mi mathvariant="italic">k</mml:mi>
366	</mml:msup>
367	<mml:mo>+</mml:mo>
368	<mml:mrow>
369	<mml:mn>2</mml:mn>
370	<mml:mo>⁡</mml:mo>
371	<mml:mfenced open="(" close=")">
372	<mml:mi mathvariant="italic">border</mml:mi>
373	</mml:mfenced>
374	</mml:mrow>
375	</mml:mrow>
376	</mml:math></inlineequation>
377	for some integer
378	<inlineequation><mml:math><mml:mi mathvariant="italic">k</mml:mi></mml:math></inlineequation>.
379	</para>
380	<para>
381	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>border</parameter> is not 0 or 1.
382	</para>
383	<para>
384	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>internalformat</parameter> is not an
385	accepted format.
386	</para>
387	<para>
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>.
391	</para>
392	<para>
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
396	buffer.
397	</para>
398	</refsect1>
399	<refsect1 id="associatedgets"><title>Associated Gets</title>
400	<para>
401	<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
402	</para>
403	<para>
404	<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_2D</constant> or <constant>GL_TEXTURE_CUBE_MAP</constant>
405	</para>
406	</refsect1>
407	<refsect1 id="seealso"><title>See Also</title>
408	<para>
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>
422	</para>
423	</refsect1>
424	<refsect1 id="Copyright"><title>Copyright</title>
425	<para>
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>.
430	</para>
431	</refsect1>
432	</refentry>