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