Opentk/Source/Bind/Specifications/Docs/ES31/glInvalidateSubFramebuffer.xml

<!DOCTYPE refentry [ <!ENTITY % mathent SYSTEM "math.ent"> %mathent; ]>

<!-- Converted by db4-upgrade version 1.1 -->

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="glInvalidateSubFramebuffer">
    <info>
        <copyright>
            <year>2012-2014</year>
            <holder>Khronos Group</holder>
        </copyright>
    </info>
    <refmeta>
        <refentrytitle>glInvalidateSubFramebuffer</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glInvalidateSubFramebuffer</refname>
        <refpurpose>Invalidate portions of the contents of attachments within a framebuffer</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glInvalidateSubFramebuffer</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLsizei <parameter>numAttachments</parameter></paramdef>
                <paramdef>const GLenum *<parameter>attachments</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>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 xml:id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specifies the target of the invalidate operation. Must be <constant>GL_FRAMEBUFFER</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>numAttachments</parameter></term>
            <listitem>
                <para>
                    Specifies how many attachments are supplied in the <parameter>attachments</parameter> list.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>attachments</parameter></term>
            <listitem>
                <para>
                    A list of <parameter>numAttachments</parameter> attachments to invalidate.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>x</parameter></term>
            <listitem>
                <para>
                    Specifies the left origin of the pixel rectangle to invalidate, with lower left hand corner at (0,0).
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>y</parameter></term>
            <listitem>
                <para>
                    Specifies the bottom origin of the pixel rectangle to invalidate, with lower left hand corner at (0,0).
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>width</parameter></term>
            <listitem>
                <para>
                    Specifies the width of the pixel rectangle to invalidate.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>height</parameter></term>
            <listitem>
                <para>
                    Specifies the height of the pixel rectangle to invalidate.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 xml:id="description"><title>Description</title>
        <para>
            <function>glInvalidateSubFramebuffer</function> signals to the
            GL that it need not preserve all pixels of a specified region of
            a bound framebuffer object. <parameter>attachments</parameter>
            contains a list of <parameter>numAttachments</parameter> to be
            invalidated. If an attachment is specified that does not exist
            in the bound framebuffer, it is ignored.
            <parameter>x</parameter>, <parameter>y</parameter>,
            <parameter>width</parameter> and <parameter>height</parameter>
            specify the bounds of the pixel rectangle to invalidate. Any of
            these pixels lying outside of the window allocated to the
            current GL context, or outside of the image attached to the
            currently bound framebuffer object, are ignored.
        </para>
        <para>
            If a framebuffer object is bound, then
            <parameter>attachments</parameter> may contain
            <constant>GL_COLOR_ATTACHMENTi</constant>,
            <constant>GL_DEPTH_ATTACHMENT</constant>, 
            <constant>GL_STENCIL_ATTACHMENT</constant>, and/or
            <constant>GL_DEPTH_STENCIL_ATTACHMENT</constant>. If the
            framebuffer object is not complete,
            <function>glInvalidateSubFramebuffer</function> may be ignored.
        </para>
        <para>
            If the default framebuffer is bound, then
            <parameter>attachments</parameter> may contain
            <constant>GL_COLOR</constant>, identifying the color buffer;
            <constant>GL_DEPTH</constant>, identifying the depth buffer;
            and/or <constant>GL_STENCIL</constant>, identifying the stencil
            buffer.
        </para>
    </refsect1>
    <refsect1 xml:id="notes"><title>Notes</title>
        <para>
            The intention of this function is to provide a hint to the GL
            implementation that there is no longer a need to preserve the
            contents of particular attachments of a framebuffer object, or
            the default framebuffer. It is possible, for example, to signal
            the intention that depth and or stencil data is no longer needed
            at the end of a scene, or that multisample color buffer data is
            no longer needed after a resolve through
            <citerefentry><refentrytitle>glBlitFramebuffer</refentrytitle></citerefentry>.
        </para>
    </refsect1>

    <refsect1 xml:id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_FRAMEBUFFER</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if
            <parameter>attachments</parameter> contains
            <constant>GL_COLOR_ATTACHMENTm</constant> and m is greater than
            or equal to the value of
            <constant>GL_MAX_COLOR_ATTACHMENTS</constant>.
        </para>
    </refsect1>
    <refsect1 xml:id="versions">
        <title>API Version Support</title>
        <informaltable>
            <tgroup cols="4" align="left">
                <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apifunchead.xml" xpointer="xpointer(/*/*)"/>
                <tbody>
                    <row>
                        <entry>glInvalidateSubFramebuffer</entry>
                        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='es30']/*)"/>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
    </refsect1>
    <refsect1 xml:id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glBindFramebuffer</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glBlitFramebuffer</refentrytitle></citerefentry>
            <citerefentry><refentrytitle>glFramebufferRenderbuffer</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glFramebufferTexture2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glFramebufferTextureLayer</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glInvalidateFramebuffer</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 xml:id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"/> 2014 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.
            <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://opencontent.org/openpub/">http://opencontent.org/openpub/</link>.
        </para>
    </refsect1>
</refentry>