Opentk/Source/Bind/Specifications/Docs/ES20/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 of the active texture unit.
                    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_LUMINANCE</constant>,
                    <constant>GL_LUMINANCE_ALPHA</constant>,
                    <constant>GL_RGB</constant>, or
                    <constant>GL_RGBA</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.
                    All implementations support 2D texture images that are at least 64 texels
                    wide and cube-mapped texture images that are at least 16 texels wide.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>height</parameter></term>
            <listitem>
                <para>
                    Specifies the height of the texture image.
                    All implementations support 2D texture images that are at least 64 texels
                    high and cube-mapped texture images that are at least 16 texels high.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>border</parameter></term>
            <listitem>
                <para>
                    Specifies the width of the border.
                    Must be 0.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            Texturing maps a portion of a specified texture image 
            onto each graphical primitive for which texturing is
            active.  Texturing is active when the current fragment shader or
            vertex shader makes use of built-in texture lookup 
            functions.
        </para>
        <para>
            <function>glCopyTexImage2D</function> defines a two-dimensional texture image or cube-map texture image
            with pixels from the current framebuffer (rather than from
            client memory, as is the case for <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>).
        </para>
        <para>
            The screen-aligned pixel rectangle with lower left corner at (<parameter>x</parameter>,
            <parameter>y</parameter>) and with a width of <parameter>width</parameter>
            and a height of <parameter>height</parameter>
            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>glReadPixels</refentrytitle></citerefentry> had been called with 
            <parameter>format</parameter> set to <constant>GL_RGBA</constant>, but the process stops just after
            conversion of RGBA values. Subsequent processing is identical to that
            described for <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>, 
            beginning with the clamping of the R, G, B, and A values 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 conversion to the texture's internal format for storage in the texel
            array.
        </para>
        <para>
            The components required for <parameter>internalformat</parameter> must be a subset of
            those present in the framebuffer's format.  For example, a <constant>GL_RGBA</constant>
            framebuffer can be used to supply components for any <parameter>internalformat</parameter>.
            However, a <constant>GL_RGB</constant> framebuffer can only be used to supply components for
            <constant>GL_RGB</constant> or <constant>GL_LUMINANCE</constant> base internal format textures,
            not <constant>GL_ALPHA</constant>, <constant>GL_LUMINANCE_ALPHA</constant>, or
            <constant>GL_RGBA</constant> textures.
        </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 are outside the framebuffer associated with the current
            rendering context, then the values obtained for those pixels are undefined.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            A GL implementation may choose to store the texture
            array at any internal resolution it chooses.
        </para>
        <para>
            An image with height or width of 0 indicates a NULL texture.
        </para>
        <para>
            <function>glCopyTexImage2D</function>
            specifies a two-dimensional or cube-map texture for the current texture unit,
            specified with <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>.
        </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_ENUM</constant> is generated if <parameter>internalformat</parameter> is not an
            accepted format.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>target</parameter> is one of the six cube map 2D image targets and the width and height parameters are not equal.
        </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> when <parameter>target</parameter>
            is <constant>GL_TEXTURE_2D</constant> or <constant>GL_MAX_CUBE_MAP_TEXTURE_SIZE</constant> when
            <parameter>target</parameter> is not <constant>GL_TEXTURE_2D</constant>.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> or <parameter>height</parameter> is less than 0
            or greater than <constant>GL_MAX_TEXTURE_SIZE</constant> when <parameter>target</parameter>
            is <constant>GL_TEXTURE_2D</constant> or <constant>GL_MAX_CUBE_MAP_TEXTURE_SIZE</constant> when
            <parameter>target</parameter> is not <constant>GL_TEXTURE_2D</constant>.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>border</parameter> is not 0.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if 
            the currently bound framebuffer's format does not contain a superset of
            the components required by the base format of <parameter>internalformat</parameter>.
        </para>
        <para>
            <constant>GL_INVALID_FRAMEBUFFER_OPERATION</constant> is generated if 
            the currently bound framebuffer is not framebuffer complete (i.e. the
            return value from <citerefentry><refentrytitle>glCheckFramebufferStatus</refentrytitle></citerefentry>
            is not <constant>GL_FRAMEBUFFER_COMPLETE</constant>).
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
            with argument <constant>GL_MAX_TEXTURE_SIZE</constant> or
            <constant>GL_MAX_CUBE_MAP_TEXTURE_SIZE</constant>
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCheckFramebufferStatus</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexSubImage2D</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>