Opentk/Source/Bind/Specifications/Docs/glClearTexSubImage.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="glClearTexSubImage">
    <refentryinfo>
        <copyright>
            <year>2013</year>
            <holder>Khronos Group</holder>
        </copyright>
    </refentryinfo>
    <refmeta>
        <refentrytitle>glClearTexSubImage</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glClearTexSubImage</refname>
        <refpurpose>fills all or part of a texture image with a constant value</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glClearTexSubImage</function></funcdef>
                <paramdef>GLuint <parameter>texture</parameter></paramdef>
                <paramdef>GLint <parameter>level</parameter></paramdef>
                <paramdef>GLint <parameter>xoffset</parameter></paramdef>
                <paramdef>GLint <parameter>yoffset</parameter></paramdef>
                <paramdef>GLint <parameter>zoffset</parameter></paramdef>
                <paramdef>GLsizei <parameter>width</parameter></paramdef>
                <paramdef>GLsizei <parameter>height</parameter></paramdef>
                <paramdef>GLsizei <parameter>depth</parameter></paramdef>
                <paramdef>GLenum <parameter>format</parameter></paramdef>
                <paramdef>GLenum <parameter>type</parameter></paramdef>
                <paramdef>const void * <parameter>data</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>texture</parameter></term>
            <listitem>
                <para>
                    The name of an existing texture object containing the image to be cleared.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>level</parameter></term>
            <listitem>
                <para>
                    The level of <parameter>texture</parameter> containing the region to be cleared.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>xoffset</parameter></term>
            <listitem>
                <para>
                    The coordinate of the left edge of the region to be cleared.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>yoffset</parameter></term>
            <listitem>
                <para>
                    The coordinate of the lower edge of the region to be cleared.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>zoffset</parameter></term>
            <listitem>
                <para>
                    The coordinate of the front of the region to be cleared.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>width</parameter></term>
            <listitem>
                <para>
                    The width of the region to be cleared.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>height</parameter></term>
            <listitem>
                <para>
                    The height of the region to be cleared.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>depth</parameter></term>
            <listitem>
                <para>
                    The depth of the region to be cleared.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>format</parameter></term>
            <listitem>
                <para>
                    The format of the data whose address in memory is given by <parameter>data</parameter>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>type</parameter></term>
            <listitem>
                <para>
                    The type of the data whose address in memory is given by <parameter>data</parameter>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>data</parameter></term>
            <listitem>
                <para>
                    The address in memory of the data to be used to clear the specified region.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glClearTexSubImage</function> fills all or part of an image contained in a
            texture with an application supplied value. <parameter>texture</parameter> must be
            the name of an existing texture. Further, <parameter>texture</parameter> may not be
            the name of a buffer texture, nor may its internal format be compressed.
        </para>
        <para>
            Arguments <parameter>xoffset</parameter>, <parameter>yoffset</parameter>, and
            <parameter>zoffset</parameter> specify the lower left texel coordinates of
            a width-wide by height-high by depth-deep rectangular subregion of the texel array.
        </para>
        <para>
            For one-dimensional array textures, <parameter>yoffset</parameter> is interpreted as the first layer to
            be cleared and <parameter>height</parameter> is the number of layers to clear. For two-dimensional array
            textures, <parameter>zoffset</parameter> is interpreted as the first layer to be cleared and <parameter>depth</parameter> is the number
            of layers to clear. Cube map textures are treated as an array of six slices in the z-dimension,
            where the value of <parameter>zoffset</parameter> is interpreted as specifying the cube map face
            for the corresponding layer and <parameter>depth</parameter> is the number of faces to clear.
            For cube map array textures, <parameter>zoffset</parameter> is the first layer-face to clear,
            and <parameter>depth</parameter> is the number of layer-faces to clear. Each layer-face is
            translated into an array layer and a cube map face as described in the OpenGL Specification.
        </para>
        <para>
            Negative values of <parameter>xoffset</parameter>, <parameter>yoffset</parameter>, and <parameter>zoffset</parameter> correspond to the coordinates of
            border texels. Taking
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">ws</mml:mi></mml:math>
            </inlineequation>,
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">hs</mml:mi></mml:math>
            </inlineequation>,
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">ds</mml:mi></mml:math>
            </inlineequation>,
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">wb</mml:mi></mml:math>
            </inlineequation>,
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">hb</mml:mi></mml:math>
            </inlineequation>, and
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">db</mml:mi></mml:math>
            </inlineequation> to be
            the specified <parameter>width</parameter>, <parameter>height</parameter>, <parameter>depth</parameter>, and the border width, border height, and border
            depth of the texel array and taking
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math>
            </inlineequation>,
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math>
            </inlineequation>,
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math>
            </inlineequation>,
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math>
            </inlineequation>,
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math>
            </inlineequation>, and
            <inlineequation>
                <mml:math><mml:mi mathvariant="italic">d</mml:mi></mml:math>
            </inlineequation>
            to be the <parameter>xoffset</parameter>, <parameter>yoffset</parameter>,
            <parameter>zoffset</parameter>, <parameter>width</parameter>, <parameter>height</parameter>, and <parameter>depth</parameter> argument values,
            any of the following relationships generates a <constant>GL_INVALID_OPERATION</constant> error:
            <itemizedlist>
                <listitem>
                    <informalequation>
                        <mml:math>
                            <mml:mrow>
                                    <mml:mtext>x</mml:mtext>
                                    <mml:mo>&lt;</mml:mo>
                                    <mml:msub>
                                            <mml:mtext>w</mml:mtext>
                                            <mml:mtext>b</mml:mtext>
                                    </mml:msub>
                            </mml:mrow>
                        </mml:math>
                    </informalequation>
                </listitem>

                <listitem>
                    <informalequation>
                        <mml:math>
                            <mml:mrow>
                                <mml:mtext mathvariant="italic">x</mml:mtext>
                                <mml:mo>+</mml:mo>
                                <mml:mtext mathvariant="italic">w</mml:mtext>
                                <mml:mo>&gt;</mml:mo>
                                <mml:msub>
                                    <mml:mtext mathvariant="italic">w</mml:mtext>
                                    <mml:mtext mathvariant="italic">s</mml:mtext>
                                </mml:msub>
                                <mml:mo>-</mml:mo>
                                <mml:msub>
                                    <mml:mtext mathvariant="italic">w</mml:mtext>
                                    <mml:mtext mathvariant="italic">b</mml:mtext>
                                </mml:msub>
                            </mml:mrow>
                        </mml:math>
                    </informalequation>
                </listitem>

                <listitem>
                    <informalequation>
                        <mml:math>
                            <mml:mrow>
                                <mml:mtext mathvariant="italic">y</mml:mtext>
                                <mml:mo>&lt;</mml:mo>
                                <mml:mo>-</mml:mo>
                                <mml:msub>
                                    <mml:mtext mathvariant="italic">h</mml:mtext>
                                    <mml:mtext mathvariant="italic">b</mml:mtext>
                                </mml:msub>
                            </mml:mrow>
                        </mml:math>
                    </informalequation>
                </listitem>

                <listitem>
                    <informalequation>
                        <mml:math>
                            <mml:mrow>
                                <mml:mtext mathvariant="italic">y</mml:mtext>
                                <mml:mo>+</mml:mo>
                                <mml:mtext mathvariant="italic">h</mml:mtext>
                                <mml:mo>&gt;</mml:mo>
                                <mml:msub>
                                    <mml:mtext mathvariant="italic">h</mml:mtext>
                                    <mml:mtext mathvariant="italic">s</mml:mtext>
                                </mml:msub>
                                <mml:mo>-</mml:mo>
                                <mml:msub>
                                    <mml:mtext mathvariant="italic">h</mml:mtext>
                                    <mml:mtext mathvariant="italic">b</mml:mtext>
                                </mml:msub>
                            </mml:mrow>
                        </mml:math>
                    </informalequation>
                </listitem>

                <listitem>
                    <informalequation>
                        <mml:math>
                            <mml:mrow>
                                <mml:mtext mathvariant="italic">z</mml:mtext>
                                <mml:mo>&lt;</mml:mo>
                                <mml:mo>-</mml:mo>
                                <mml:msub>
                                    <mml:mtext mathvariant="italic">d</mml:mtext>
                                    <mml:mtext mathvariant="italic">b</mml:mtext>
                                </mml:msub>
                            </mml:mrow>
                        </mml:math>
                    </informalequation>
                </listitem>

                <listitem>
                    <informalequation>
                        <mml:math>
                            <mml:mrow>
                                <mml:mtext mathvariant="italic">z</mml:mtext>
                                <mml:mo>+</mml:mo>
                                <mml:mtext mathvariant="italic">d</mml:mtext>
                                <mml:mo>&gt;</mml:mo>
                                <mml:msub>
                                    <mml:mtext mathvariant="italic">d</mml:mtext>
                                    <mml:mtext mathvariant="italic">s</mml:mtext>
                                </mml:msub>
                                <mml:mo>-</mml:mo>
                                <mml:msub>
                                    <mml:mtext mathvariant="italic">d</mml:mtext>
                                    <mml:mtext mathvariant="italic">b</mml:mtext>
                                </mml:msub>
                            </mml:mrow>
                        </mml:math>
                    </informalequation>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            For texture types that do not have certain dimensions, this command treats those
            dimensions as having a size of 1. For example, to clear a portion of a two-dimensional
            texture, use <parameter>zoffset</parameter> equal to zero and <parameter>depth</parameter> equal to one.
        </para>
        <para>
            <parameter>format</parameter> and <parameter>type</parameter> specify the format and type of the
            source data and are interpreted as they are for <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>.
            Textures with a base internal format of <constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_STENCIL_INDEX</constant>, or <constant>GL_DEPTH_STENCIL</constant>
            require depth component, stencil, or depth-stencil component data respectively.
            Textures with other base internal formats require RGBA formats. Textures with integer
            internal formats require integer data.
        </para>
        <para>
            <parameter>data</parameter> is a pointer to an array of between one and four components of texel
            data that will be used as the source for the constant fill value. The elements of
            data are converted by the GL into the internal format of the texture image (that
            was specified when the level was defined by any of the <function>glTexImage*</function>, <function>glTexStorage*</function>
            or <function>glCopyTexImage*</function> commands), and then
            used to fill the specified range of the destination texture level. If <parameter>data</parameter> is <constant>NULL</constant>, then
            the pointer is ignored and the sub-range of the texture image is filled with zeros. If
            texture is a multisample texture, all the samples in a texel are cleared to the value
            specified by data.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            <function>glClearTexSubImage</function> is available only if the GL version is 4.4 or greater.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>texture</parameter> is zero or not the
            name of an existing texture object.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>texture</parameter> is a buffer texture.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>texture</parameter> has a compressed
            internal format.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if the base internal format is
            <constant>GL_DEPTH_COMPONENT</constant> and <parameter>format</parameter> is not <constant>GL_DEPTH_COMPONENT</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if the base internal format is
            <constant>GL_DEPTH_STENCIL</constant> and <parameter>format</parameter> is not <constant>GL_DEPTH_STENCIL</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if the base internal format is
            <constant>GL_STENCIL_INDEX</constant> and <parameter>format</parameter> is not <constant>GL_STENCIL_INDEX</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if the base internal format is
            <constant>GL_RGBA</constant> and <parameter>format</parameter> is <constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_STENCIL_INDEX</constant>, or <constant>GL_DEPTH_STENCIL</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if the internal format is integer and <parameter>format</parameter> does not specify integer data.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if the internal format is not
            integer and <parameter>format</parameter> specifies integer data.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> error is generated if the <parameter>xoffset</parameter>, <parameter>yoffset</parameter>, <parameter>zoffset</parameter>,
            <parameter>width</parameter>, <parameter>height</parameter>, and <parameter>depth</parameter> parameters (or combinations thereof) specify a region that falls outside the
            defined texture image array (including border, if any).
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glGetInternalformat</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glClearTexImage</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexStorage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 2013 Khronos Group.
            This material may be distributed subject to the terms and conditions set forth in
            the Open Publication License, v 1.0, 8 June 1999.
            <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
        </para>
    </refsect1>
</refentry>