Opentk/Source/Bind/Specifications/Docs/ES31/glBeginQuery.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="glBeginQuery">
    <info>
        <copyright>
            <year>2005</year>
            <holder>Sams Publishing</holder>
        </copyright>
        <copyright>
            <year>2010-2014</year>
            <holder>Khronos Group</holder>
        </copyright>
    </info>
    <refmeta>
        <refentrytitle>glBeginQuery</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glBeginQuery</refname>
        <refpurpose>delimit the boundaries of a query object</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glBeginQuery</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLuint <parameter>id</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glEndQuery</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 xml:id="parameters"><title>Parameters for <function>glBeginQuery</function></title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specifies the target type of query object established between
                    <function>glBeginQuery</function> and the subsequent <function>glEndQuery</function>.
                    The symbolic constant must be one of <constant>GL_ANY_SAMPLES_PASSED</constant>, <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant>,
                    or <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>id</parameter></term>
            <listitem>
                <para>
                    Specifies the name of a query object.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 xml:id="parameters2"><title>Parameters for <function>glEndQuery</function></title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specifies the target type of query object to be concluded.
                    The symbolic constant must be one of <constant>GL_ANY_SAMPLES_PASSED</constant>, <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant>,
                    or <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 xml:id="description"><title>Description</title>
        <para>
            <function>glBeginQuery</function> and <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry> delimit the
            boundaries of a query object.  <parameter>query</parameter> must be a name previously returned from a call to
            <citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>. If a query object with name <parameter>id</parameter>
            does not yet exist it is created with the type determined by <parameter>target</parameter>. <parameter>target</parameter> must
            be one of <constant>GL_ANY_SAMPLES_PASSED</constant>, <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant>,
            or <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>. The behavior of the query
            object depends on its type and is as follows.
        </para>
        <para>
            If <parameter>target</parameter> is <constant>GL_ANY_SAMPLES_PASSED</constant>, <parameter>id</parameter> must be an unused name,
            or the name of an existing boolean occlusion query object.
            When <function>glBeginQuery</function> is executed, the query object's samples-passed flag is reset to <constant>GL_FALSE</constant>.
            Subsequent rendering causes the flag to be set to <constant>GL_TRUE</constant> if any sample passes the depth test.  When
            <function>glEndQuery</function> is executed, the samples-passed flag is assigned to the query object's result value.  This value can
            be queried by calling <citerefentry><refentrytitle>glGetQueryObjectuiv</refentrytitle></citerefentry> with <parameter>pname</parameter>
            <constant>GL_QUERY_RESULT</constant>.
        </para>
        <para>
            If <parameter>target</parameter> is <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant>, <parameter>id</parameter> must be an unused name,
            or the name of an existing boolean occlusion query object.
            When <function>glBeginQuery</function> is executed, the query object's samples-passed flag is reset to <constant>GL_FALSE</constant>.
            Subsequent rendering causes the flag to be set to <constant>GL_TRUE</constant> if any sample passes the depth test.  The implementation
            may choose to use a less precision version of the test, which can additionally set the samples-passed flag to <constant>GL_TRUE</constant>
            in some other implementation-dependent cases. When <function>glEndQuery</function> is executed, the samples-passed flag is assigned to
            the query object's result value.  This value can be queried by calling <citerefentry><refentrytitle>glGetQueryObjectuiv</refentrytitle></citerefentry>
            with <parameter>pname</parameter> <constant>GL_QUERY_RESULT</constant>.
        </para>
        <para>
            If <parameter>target</parameter> is <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>, <parameter>id</parameter> must be
            an unused name, or the name of an existing primitive query object previously bound to the <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>
            query binding. When <function>glBeginQuery</function> is executed, the query object's primitives-written counter is reset to 0.  Subsequent
            rendering will increment the counter once for every vertex that is written into the bound transform feedback buffer(s).  If transform feedback
            mode is not activated between the call to <function>glBeginQuery</function> and <function>glEndQuery</function>, the counter will not be
            incremented.  When <function>glEndQuery</function> is executed, the primitives-written counter is assigned to
            the query object's result value.  This value can be queried by calling <citerefentry><refentrytitle>glGetQueryObjectuiv</refentrytitle></citerefentry> with <parameter>pname</parameter>
            <constant>GL_QUERY_RESULT</constant>.
        </para>
    </refsect1>
    <refsect1 xml:id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the accepted tokens.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <function>glBeginQuery</function> is executed while
            a query object of the same <parameter>target</parameter> is already active. Note: <constant>GL_ANY_SAMPLES_PASSED</constant>
            and <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant> alias to the same target for the purposes of this error.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <function>glEndQuery</function>
            is executed when a query object of the same <parameter>target</parameter> is not active.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is 0.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> not a name returned from a previous call to
            <function>glGenQueries</function>, or if such a name has since been deleted with <function>glDeleteQueries</function>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is the name of an already active query object.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> refers to an existing query object whose type
            does not does not match <parameter>target</parameter>.
        </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><function>glBeginQuery</function></entry>
                        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='es30']/*)"/>
                    </row>
                    <row>
                        <entry><function>glEndQuery</function></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>glDeleteQueries</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glGetQueryiv</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glGetQueryObjectuiv</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glIsQuery</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 xml:id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"/> 2005 Addison-Wesley.
            Copyright <trademark class="copyright"/> 2010-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>