upstream-doc/man4/glBeginQuery.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glBeginQuery">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2005</year>
   9                 <holder>Sams Publishing</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glBeginQuery</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glBeginQuery</refname>
  17         <refpurpose>delimit the boundaries of a query object</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glBeginQuery</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLuint <parameter>id</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27     </refsynopsisdiv>
  28     <!-- eqn: ignoring delim $$ -->
  29     <refsect1 id="parameters"><title>Parameters</title>
  30         <variablelist>
  31         <varlistentry>
  32             <term><parameter>target</parameter></term>
  33             <listitem>
  34                 <para>
  35                     Specifies the target type of query object established between
  36                     <function>glBeginQuery</function> and the subsequent <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry>.
  37                     The symbolic constant must be one of <constant>GL_SAMPLES_PASSED</constant>, <constant>GL_ANY_SAMPLES_PASSED</constant>,
  38                     <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant>,
  39                     <constant>GL_PRIMITIVES_GENERATED</constant>, <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>, or
  40                     <constant>GL_TIME_ELAPSED</constant>.
  41                 </para>
  42             </listitem>
  43         </varlistentry>
  44         <varlistentry>
  45             <term><parameter>id</parameter></term>
  46             <listitem>
  47                 <para>
  48                     Specifies the name of a query object.
  49                 </para>
  50             </listitem>
  51         </varlistentry>
  52         </variablelist>
  53     </refsect1>
  54     <refsynopsisdiv><title>C Specification</title>
  55         <funcsynopsis>
  56             <funcprototype>
  57                 <funcdef>void <function>glEndQuery</function></funcdef>
  58                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  59             </funcprototype>
  60         </funcsynopsis>
  61     </refsynopsisdiv>
  62     <!-- eqn: ignoring delim $$ -->
  63     <refsect1 id="parameters2"><title>Parameters</title>
  64         <variablelist>
  65         <varlistentry>
  66             <term><parameter>target</parameter></term>
  67             <listitem>
  68                 <para>
  69                     Specifies the target type of query object to be concluded.
  70                     The symbolic constant must be one of <constant>GL_SAMPLES_PASSED</constant>, <constant>GL_ANY_SAMPLES_PASSED</constant>,
  71                     <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant>,
  72                     <constant>GL_PRIMITIVES_GENERATED</constant>, <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>, or
  73                     <constant>GL_TIME_ELAPSED</constant>.
  74                 </para>
  75             </listitem>
  76         </varlistentry>
  77         </variablelist>
  78     </refsect1>
  79     <refsect1 id="description"><title>Description</title>
  80         <para>
  81             <function>glBeginQuery</function> and <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry> delimit the
  82             boundaries of a query object.  <parameter>query</parameter> must be a name previously returned from a call to
  83             <citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>. If a query object with name <parameter>id</parameter>
  84             does not yet exist it is created with the type determined by <parameter>target</parameter>. <parameter>target</parameter> must
  85             be one of <constant>GL_SAMPLES_PASSED</constant>, <constant>GL_ANY_SAMPLES_PASSED</constant>, <constant>GL_PRIMITIVES_GENERATED</constant>,
  86             <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>, or <constant>GL_TIME_ELAPSED</constant>. The behavior of the query
  87             object depends on its type and is as follows.
  88         </para>
  89         <para>
  90             If <parameter>target</parameter> is <constant>GL_SAMPLES_PASSED</constant>, <parameter>id</parameter> must be an unused name,
  91             or the name of an existing occlusion query object.
  92             When <function>glBeginQuery</function> is executed, the query object's samples-passed counter is reset to 0.  Subsequent
  93             rendering will increment the counter for every sample that passes the depth test.  If the value of <constant>GL_SAMPLE_BUFFERS</constant>
  94             is 0, then the samples-passed count is incremented by 1 for each fragment. If the value of <constant>GL_SAMPLE_BUFFERS</constant>
  95             is 1, then the samples-passed count is incremented by the number of samples whose coverage bit is set. However, implementations, at their
  96             discression may instead increase the samples-passed count by the value of <constant>GL_SAMPLES</constant> if any sample in the fragment
  97             is covered. When <function>glEndQuery</function>
  98             is executed, the samples-passed counter is assigned to the query object's result value.  This value can be queried by
  99             calling <citerefentry><refentrytitle>glGetQueryObject</refentrytitle></citerefentry> with <parameter>pname</parameter>
 100             <constant>GL_QUERY_RESULT</constant>.
 101         </para>
 102         <para>
 103             If <parameter>target</parameter> is <constant>GL_ANY_SAMPLES_PASSED</constant> or <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant>,
 104             <parameter>id</parameter> must be an unused name, or the name of an existing boolean occlusion query object.
 105             When <function>glBeginQuery</function> is executed, the query object's samples-passed flag is reset to <constant>GL_FALSE</constant>.
 106             Subsequent rendering causes the flag to be set to <constant>GL_TRUE</constant> if any sample passes the depth test in the case of <constant>GL_ANY_SAMPLES_PASSED</constant>,
 107             or if the implementation determines that any sample might pass the depth test in the case of <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant>.
 108             The implementation may be able to provide a more efficient test in the case of <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant>
 109             if some false positives are acceptable to the application.  When
 110             <function>glEndQuery</function> is executed, the samples-passed flag is assigned to the query object's result value.  This value can
 111             be queried by calling <citerefentry><refentrytitle>glGetQueryObject</refentrytitle></citerefentry> with <parameter>pname</parameter>
 112             <constant>GL_QUERY_RESULT</constant>.
 113         </para>
 114         <para>
 115             If <parameter>target</parameter> is <constant>GL_PRIMITIVES_GENERATED</constant>, <parameter>id</parameter> must be an unused
 116             name, or the name of an existing primitive query object previously bound to the <constant>GL_PRIMITIVES_GENERATED</constant> query binding.
 117             When <function>glBeginQuery</function> is executed, the query object's primitives-generated counter is reset to 0.  Subsequent
 118             rendering will increment the counter once for every vertex that is emitted from the geometry shader, or from the vertex shader if
 119             no geometry shader is present.  When <function>glEndQuery</function> is executed, the primitives-generated counter is assigned to
 120             the query object's result value.  This value can be queried by calling <citerefentry><refentrytitle>glGetQueryObject</refentrytitle></citerefentry> with <parameter>pname</parameter>
 121             <constant>GL_QUERY_RESULT</constant>.
 122         </para>
 123         <para>
 124             If <parameter>target</parameter> is <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>, <parameter>id</parameter> must be
 125             an unused name, or the name of an existing primitive query object previously bound to the <constant>GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</constant>
 126             query binding. When <function>glBeginQuery</function> is executed, the query object's primitives-written counter is reset to 0.  Subsequent
 127             rendering will increment the counter once for every vertex that is written into the bound transform feedback buffer(s).  If transform feedback
 128             mode is not activated between the call to <function>glBeginQuery</function> and <function>glEndQuery</function>, the counter will not be
 129             incremented.  When <function>glEndQuery</function> is executed, the primitives-written counter is assigned to
 130             the query object's result value.  This value can be queried by calling <citerefentry><refentrytitle>glGetQueryObject</refentrytitle></citerefentry> with <parameter>pname</parameter>
 131             <constant>GL_QUERY_RESULT</constant>.
 132         </para>
 133         <para>
 134             If <parameter>target</parameter> is <constant>GL_TIME_ELAPSED</constant>, <parameter>id</parameter> must be
 135             an unused name, or the name of an existing timer query object previously bound to the <constant>GL_TIME_ELAPSED</constant>
 136             query binding. When <function>glBeginQuery</function> is executed, the query object's time counter is reset to 0.  When <function>glEndQuery</function>
 137             is executed, the elapsed server time that has passed since the call to <function>glBeginQuery</function> is written into the query object's
 138             time counter.  This value can be queried by calling <citerefentry><refentrytitle>glGetQueryObject</refentrytitle></citerefentry> with <parameter>pname</parameter>
 139             <constant>GL_QUERY_RESULT</constant>.
 140         </para>
 141         <para>
 142             Querying the <constant>GL_QUERY_RESULT</constant> implicitly flushes the GL pipeline until the rendering delimited by the
 143             query object has completed and the result is available.  <constant>GL_QUERY_RESULT_AVAILABLE</constant> can be queried to
 144             determine if the result is immediately available or if the rendering is not yet complete.
 145         </para>
 146     </refsect1>
 147     <refsect1 id="notes"><title>Notes</title>
 148         <para>
 149             If the query target's count exceeds the maximum value representable in the number of available bits, as reported by
 150             <citerefentry><refentrytitle>glGetQueryiv</refentrytitle></citerefentry> with <parameter>target</parameter> set to the
 151             appropriate query target and <parameter>pname</parameter>
 152             <constant>GL_QUERY_COUNTER_BITS</constant>, the count becomes undefined.
 153         </para>
 154         <para>
 155             An implementation may support 0 bits in its counter, in which case query results are always undefined
 156             and essentially useless.
 157         </para>
 158         <para>
 159             When <constant>GL_SAMPLE_BUFFERS</constant> is 0, the samples-passed counter of an occlusion query will increment once for each
 160             fragment that passes the depth test.  When <constant>GL_SAMPLE_BUFFERS</constant> is 1, an implementation may either increment
 161             the samples-passed counter individually for each sample of a fragment that passes the depth test, or it may choose to increment
 162             the counter for all samples of a fragment if any one of them passes the depth test.
 163         </para>
 164         <para>
 165             The query targets <constant>GL_ANY_SAMPLES_PASSED</constant>, and <constant>GL_TIME_ELAPSED</constant> are availale only if
 166             the GL version is 3.3 or higher.
 167         </para>
 168         <para>
 169             The query target <constant>GL_ANY_SAMPLES_PASSED_CONSERVATIVE</constant> is available only of the GL version is 4.3 or higher.
 170         </para>
 171     </refsect1>
 172     <refsect1 id="errors"><title>Errors</title>
 173         <para>
 174             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the accepted tokens.
 175         </para>
 176         <para>
 177             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glBeginQuery</function> is executed while
 178             a query object of the same <parameter>target</parameter> is already active.
 179         </para>
 180         <para>
 181             <constant>GL_INVALID_OPERATION</constant> is generated if <citerefentry><refentrytitle>glEndQuery</refentrytitle></citerefentry>
 182             is executed when a query object of the same <parameter>target</parameter> is not active.
 183         </para>
 184         <para>
 185             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is 0.
 186         </para>
 187         <para>
 188             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is the name of an already active query object.
 189         </para>
 190         <para>
 191             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> refers to an existing query object whose type
 192             does not does not match <parameter>target</parameter>.
 193         </para>
 194     </refsect1>
 195     <refsect1 id="seealso"><title>See Also</title>
 196         <para>
 197             <citerefentry><refentrytitle>glDeleteQueries</refentrytitle></citerefentry>,
 198             <citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>,
 199             <citerefentry><refentrytitle>glGetQueryiv</refentrytitle></citerefentry>,
 200             <citerefentry><refentrytitle>glGetQueryObject</refentrytitle></citerefentry>,
 201             <citerefentry><refentrytitle>glIsQuery</refentrytitle></citerefentry>
 202         </para>
 203     </refsect1>
 204     <refsect1 id="Copyright"><title>Copyright</title>
 205         <para>
 206             Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
 207             Copyright <trademark class="copyright"></trademark> 2010-2012 Khronos Group.
 208             This material may be distributed subject to the terms and conditions set forth in
 209             the Open Publication License, v 1.0, 8 June 1999.
 210             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 211         </para>
 212     </refsect1>
 213 </refentry>