<?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="glBindFramebuffer">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>2005</year>
                <holder>Sams Publishing</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glBindFramebuffer</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glBindFramebuffer</refname>
        <refpurpose>bind a named framebuffer object</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glBindFramebuffer</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLuint <parameter>framebuffer</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specifies the target to which the framebuffer object is bound.
                    The symbolic constant must be
                    <constant>GL_FRAMEBUFFER</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>framebuffer</parameter></term>
            <listitem>
                <para>
                    Specifies the name of a framebuffer object.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glBindFramebuffer</function> lets you create or use a named framebuffer object. Calling <function>glBindFramebuffer</function> with
            <parameter>target</parameter> set to <constant>GL_FRAMEBUFFER</constant>
            and <parameter>framebuffer</parameter> set to the name
            of the new framebuffer object binds the framebuffer object name.
            When a framebuffer object is bound, the previous binding
            is automatically broken.
        </para>
        <para>
            Framebuffer object names are unsigned integers. The value zero is reserved to represent the default framebuffer
            provided by the windowing system. Framebuffer object names and the corresponding framebuffer object contents are local to
            the shared object space of the current GL rendering context.
        </para>
        <para>
            You may use <citerefentry><refentrytitle>glGenFramebuffers</refentrytitle></citerefentry> to generate a set of new framebuffer object names.
        </para>
        <para>
            The state of a framebuffer object immediately after it is first bound is
            three attachment points (<constant>GL_COLOR_ATTACHMENT0</constant>,
            <constant>GL_DEPTH_ATTACHMENT</constant>, and 
            <constant>GL_STENCIL_ATTACHMENT</constant>) each with 
            <constant>GL_NONE</constant> as the object type.
        </para>
        <para>
            While a non-zero framebuffer object name is bound, GL operations on
            target <constant>GL_FRAMEBUFFER</constant> affect the bound framebuffer
            object, and queries of target <constant>GL_FRAMEBUFFER</constant> or of
            framebuffer details such as <constant>GL_DEPTH_BITS</constant>
            return state from the bound framebuffer object. While framebuffer object 
            name zero is bound, as in the initial state, attempts to modify or query
            state on target <constant>GL_FRAMEBUFFER</constant> generates an 
            <constant>GL_INVALID_OPERATION</constant> error.
        </para>
        <para>
            While a non-zero framebuffer object name is bound, all rendering to the
            framebuffer (with <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>
            and <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>)
            and reading from the framebuffer (with 
            <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
            or <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>)
            use the images attached to the application-created framebuffer object rather than the default
            window-system-provided framebuffer.
        </para>
        <para>
            Application created framebuffer objects (i.e. those with a non-zero name)
            differ from the default window-system-provided framebuffer in a few
            important ways. First, they have modifiable attachment points for
            a color buffer, a depth buffer, and a stencil buffer to which framebuffer
            attachable images may be attached and detached. Second, the size and format of the
            attached images are controlled entirely within the GL and are not
            affected by window-system events, such as pixel format selection,
            window resizes, and display mode changes. Third, when rendering to or
            reading from an application created framebuffer object, the pixel
            ownership test always succeeds (i.e. they own all their pixels). Fourth,
            there are no visible color buffer bitplanes, only a single &quot;off-screen&quot;
            color image attachment, so there is no sense of front and back buffers
            or swapping. Finally, there is no multisample buffer, so the value of 
            the implementation-dependent state variables 
            <constant>GL_SAMPLES</constant> and <constant>GL_SAMPLE_BUFFERS</constant>
            are both zero for application created framebuffer objects.
        </para>
        <para>
            A framebuffer object binding created with <function>glBindFramebuffer</function> remains active until a different
            framebuffer object name is bound, or until the bound framebuffer object is
            deleted with <citerefentry><refentrytitle>glDeleteFramebuffers</refentrytitle></citerefentry>.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            Queries of implementation-dependent pixel depths and related state are
            derived from the currently bound framebuffer object.  These include
            <constant>GL_RED_BITS</constant>, <constant>GL_GREEN_BITS</constant>, 
            <constant>GL_BLUE_BITS</constant>, <constant>GL_ALPHA_BITS</constant>, 
            <constant>GL_DEPTH_BITS</constant>, <constant>GL_STENCIL_BITS</constant>, 
            <constant>GL_IMPLEMENTATION_COLOR_READ_TYPE</constant>, 
            <constant>GL_IMPLEMENTATION_COLOR_READ_FORMAT</constant>,
            <constant>GL_SAMPLES</constant>, and <constant>GL_SAMPLE_BUFFERS</constant>.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_FRAMEBUFFER</constant>.
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_FRAMEBUFFER_BINDING</constant>
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glDeleteFramebuffers</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glFramebufferRenderbuffer</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glFramebufferTexture2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glGenFramebuffers</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glGetFramebufferAttachmentParameteriv</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glIsFramebuffer</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 2008 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>
