upstream-doc/man4/xhtml/glBeginQueryIndexed.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   3 <!-- saved from url=(0013)about:internet -->
   4 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="stylesheet" type="text/css" href="opengl-man.css" /><title>glBeginQueryIndexed, glEndQueryIndexed - OpenGL 4 Reference Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glBeginQueryIndexed"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glBeginQueryIndexed, glEndQueryIndexed — delimit the boundaries of a query object on an indexed target</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glBeginQueryIndexed</b>(</code></td><td>GLenum  </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLuint  </td><td><var class="pdparam">index</var>, </td></tr><tr><td> </td><td>GLuint  </td><td><var class="pdparam">id</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
   5                     Specifies the target type of query object established between
   6                     <code class="function">glBeginQueryIndexed</code> and the subsequent <a href="glEndQueryIndexed.xml"><span class="citerefentry"><span class="refentrytitle">glEndQueryIndexed</span></span></a>.
   7                     The symbolic constant must be one of <code class="constant">GL_SAMPLES_PASSED</code>, <code class="constant">GL_ANY_SAMPLES_PASSED</code>,
   8                     <code class="constant">GL_PRIMITIVES_GENERATED</code>, <code class="constant">GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</code>, or
   9                     <code class="constant">GL_TIME_ELAPSED</code>.
  10                 </p></dd><dt><span class="term"><em class="parameter"><code>index</code></em></span></dt><dd><p>
  11                     Specifies the index of the query target upon which to begin the query.
  12                 </p></dd><dt><span class="term"><em class="parameter"><code>id</code></em></span></dt><dd><p>
  13                     Specifies the name of a query object.
  14                 </p></dd></dl></div></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glEndQueryIndexed</b>(</code></td><td>GLenum  </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLuint  </td><td><var class="pdparam">index</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters2"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
  15                     Specifies the target type of query object to be concluded.
  16                     The symbolic constant must be one of <code class="constant">GL_SAMPLES_PASSED</code>, <code class="constant">GL_ANY_SAMPLES_PASSED</code>,
  17                     <code class="constant">GL_PRIMITIVES_GENERATED</code>, <code class="constant">GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</code>, or
  18                     <code class="constant">GL_TIME_ELAPSED</code>.
  19                 </p></dd><dt><span class="term"><em class="parameter"><code>index</code></em></span></dt><dd><p>
  20                     Specifies the index of the query target upon which to end the query.
  21                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  22             <code class="function">glBeginQueryIndexed</code> and <a href="glEndQueryIndexed.xml"><span class="citerefentry"><span class="refentrytitle">glEndQueryIndexed</span></span></a> delimit the
  23             boundaries of a query object.  <em class="parameter"><code>query</code></em> must be a name previously returned from a call to
  24             <a href="glGenQueries.xml"><span class="citerefentry"><span class="refentrytitle">glGenQueries</span></span></a>. If a query object with name <em class="parameter"><code>id</code></em>
  25             does not yet exist it is created with the type determined by <em class="parameter"><code>target</code></em>. <em class="parameter"><code>target</code></em> must
  26             be one of <code class="constant">GL_SAMPLES_PASSED</code>, <code class="constant">GL_ANY_SAMPLES_PASSED</code>, <code class="constant">GL_PRIMITIVES_GENERATED</code>,
  27             <code class="constant">GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</code>, or <code class="constant">GL_TIME_ELAPSED</code>. The behavior of the query
  28             object depends on its type and is as follows.
  29         </p><p>
  30             <em class="parameter"><code>index</code></em> specifies the index of the query target and must be between a <em class="parameter"><code>target</code></em>-specific
  31             maximum.
  32         </p><p>
  33             If <em class="parameter"><code>target</code></em> is <code class="constant">GL_SAMPLES_PASSED</code>, <em class="parameter"><code>id</code></em> must be an unused name,
  34             or the name of an existing occlusion query object.
  35             When <code class="function">glBeginQueryIndexed</code> is executed, the query object's samples-passed counter is reset to 0.  Subsequent
  36             rendering will increment the counter for every sample that passes the depth test.  If the value of <code class="constant">GL_SAMPLE_BUFFERS</code>
  37             is 0, then the samples-passed count is incremented by 1 for each fragment. If the value of <code class="constant">GL_SAMPLE_BUFFERS</code>
  38             is 1, then the samples-passed count is incremented by the number of samples whose coverage bit is set. However, implementations, at their
  39             discression may instead increase the samples-passed count by the value of <code class="constant">GL_SAMPLES</code> if any sample in the fragment
  40             is covered. When <code class="function">glEndQueryIndexed</code>
  41             is executed, the samples-passed counter is assigned to the query object's result value.  This value can be queried by
  42             calling <a href="glGetQueryObject.xml"><span class="citerefentry"><span class="refentrytitle">glGetQueryObject</span></span></a> with <em class="parameter"><code>pname</code></em>
  43             <code class="constant">GL_QUERY_RESULT</code>.
  44             When <em class="parameter"><code>target</code></em> is <code class="constant">GL_SAMPLES_PASSED</code>, <em class="parameter"><code>index</code></em> must be zero.
  45         </p><p>
  46             If <em class="parameter"><code>target</code></em> is <code class="constant">GL_ANY_SAMPLES_PASSED</code>, <em class="parameter"><code>id</code></em> must be an unused name,
  47             or the name of an existing boolean occlusion query object.
  48             When <code class="function">glBeginQueryIndexed</code> is executed, the query object's samples-passed flag is reset to <code class="constant">GL_FALSE</code>.
  49             Subsequent rendering causes the flag to be set to <code class="constant">GL_TRUE</code> if any sample passes the depth test.  When
  50             <code class="function">glEndQueryIndexed</code> is executed, the samples-passed flag is assigned to the query object's result value.  This value can
  51             be queried by calling <a href="glGetQueryObject.xml"><span class="citerefentry"><span class="refentrytitle">glGetQueryObject</span></span></a> with <em class="parameter"><code>pname</code></em>
  52             <code class="constant">GL_QUERY_RESULT</code>.
  53             When <em class="parameter"><code>target</code></em> is <code class="constant">GL_ANY_SAMPLES_PASSED</code>, <em class="parameter"><code>index</code></em> must be zero.
  54         </p><p>
  55             If <em class="parameter"><code>target</code></em> is <code class="constant">GL_PRIMITIVES_GENERATED</code>, <em class="parameter"><code>id</code></em> must be an unused
  56             name, or the name of an existing primitive query object previously bound to the <code class="constant">GL_PRIMITIVES_GENERATED</code> query binding.
  57             When <code class="function">glBeginQueryIndexed</code> is executed, the query object's primitives-generated counter is reset to 0.  Subsequent
  58             rendering will increment the counter once for every vertex that is emitted from the geometry shader to the stream given by <em class="parameter"><code>index</code></em>,
  59             or from the vertex shader if <em class="parameter"><code>index</code></em> is zero and no geometry shader is present.
  60             When <code class="function">glEndQueryIndexed</code> is executed, the primitives-generated counter for stream <em class="parameter"><code>index</code></em> is assigned to
  61             the query object's result value.  This value can be queried by calling <a href="glGetQueryObject.xml"><span class="citerefentry"><span class="refentrytitle">glGetQueryObject</span></span></a>
  62             with <em class="parameter"><code>pname</code></em> <code class="constant">GL_QUERY_RESULT</code>.
  63             When <em class="parameter"><code>target</code></em> is <code class="constant">GL_PRIMITIVES_GENERATED</code>, <em class="parameter"><code>index</code></em> must be
  64             less than the value of <code class="constant">GL_MAX_VERTEX_STREAMS</code>.
  65         </p><p>
  66             If <em class="parameter"><code>target</code></em> is <code class="constant">GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</code>, <em class="parameter"><code>id</code></em> must be
  67             an unused name, or the name of an existing primitive query object previously bound to the <code class="constant">GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</code>
  68             query binding. When <code class="function">glBeginQueryIndexed</code> is executed, the query object's primitives-written counter for the stream specified by
  69             <em class="parameter"><code>index</code></em> is reset to 0.  Subsequent rendering will increment the counter once for every vertex that is written into the bound
  70             transform feedback buffer(s) for stream <em class="parameter"><code>index</code></em>.  If transform feedback
  71             mode is not activated between the call to <code class="function">glBeginQueryIndexed</code> and <code class="function">glEndQueryIndexed</code>, the counter will not be
  72             incremented.  When <code class="function">glEndQueryIndexed</code> is executed, the primitives-written counter for stream <em class="parameter"><code>index</code></em> is assigned to
  73             the query object's result value.  This value can be queried by calling <a href="glGetQueryObject.xml"><span class="citerefentry"><span class="refentrytitle">glGetQueryObject</span></span></a> with <em class="parameter"><code>pname</code></em>
  74             <code class="constant">GL_QUERY_RESULT</code>.
  75             When <em class="parameter"><code>target</code></em> is <code class="constant">GL_TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN</code>, <em class="parameter"><code>index</code></em> must be
  76             less than the value of <code class="constant">GL_MAX_VERTEX_STREAMS</code>.
  77         </p><p>
  78             If <em class="parameter"><code>target</code></em> is <code class="constant">GL_TIME_ELAPSED</code>, <em class="parameter"><code>id</code></em> must be
  79             an unused name, or the name of an existing timer query object previously bound to the <code class="constant">GL_TIME_ELAPSED</code>
  80             query binding. When <code class="function">glBeginQueryIndexed</code> is executed, the query object's time counter is reset to 0.  When <code class="function">glEndQueryIndexed</code>
  81             is executed, the elapsed server time that has passed since the call to <code class="function">glBeginQueryIndexed</code> is written into the query object's
  82             time counter.  This value can be queried by calling <a href="glGetQueryObject.xml"><span class="citerefentry"><span class="refentrytitle">glGetQueryObject</span></span></a> with <em class="parameter"><code>pname</code></em>
  83             <code class="constant">GL_QUERY_RESULT</code>.
  84             When <em class="parameter"><code>target</code></em> is <code class="constant">GL_TIME_ELAPSED</code>, <em class="parameter"><code>index</code></em> must be zero.
  85         </p><p>
  86             Querying the <code class="constant">GL_QUERY_RESULT</code> implicitly flushes the GL pipeline until the rendering delimited by the
  87             query object has completed and the result is available.  <code class="constant">GL_QUERY_RESULT_AVAILABLE</code> can be queried to
  88             determine if the result is immediately available or if the rendering is not yet complete.
  89         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
  90             If the query target's count exceeds the maximum value representable in the number of available bits, as reported by
  91             <a href="glGetQueryiv.xml"><span class="citerefentry"><span class="refentrytitle">glGetQueryiv</span></span></a> with <em class="parameter"><code>target</code></em> set to the
  92             appropriate query target and <em class="parameter"><code>pname</code></em>
  93             <code class="constant">GL_QUERY_COUNTER_BITS</code>, the count becomes undefined.
  94         </p><p>
  95             An implementation may support 0 bits in its counter, in which case query results are always undefined
  96             and essentially useless.
  97         </p><p>
  98             When <code class="constant">GL_SAMPLE_BUFFERS</code> is 0, the samples-passed counter of an occlusion query will increment once for each
  99             fragment that passes the depth test.  When <code class="constant">GL_SAMPLE_BUFFERS</code> is 1, an implementation may either increment
 100             the samples-passed counter individually for each sample of a fragment that passes the depth test, or it may choose to increment
 101             the counter for all samples of a fragment if any one of them passes the depth test.
 102         </p><p>
 103             Calling <a href="glBeginQuery.xml"><span class="citerefentry"><span class="refentrytitle">glBeginQuery</span></span></a> or
 104             <a href="glEndQuery.xml"><span class="citerefentry"><span class="refentrytitle">glEndQuery</span></span></a> is equivalent to
 105             calling <a href="glBeginQueryIndexed.xml"><span class="citerefentry"><span class="refentrytitle">glBeginQueryIndexed</span></span></a> or
 106             <a href="glEndQueryIndexed.xml"><span class="citerefentry"><span class="refentrytitle">glEndQueryIndexed</span></span></a> with
 107             <em class="parameter"><code>index</code></em> set to zero, respectively.
 108         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 109             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>target</code></em> is not one of the accepted tokens.
 110         </p><p>
 111             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>index</code></em> is greater than the
 112             query target-specific maximum.
 113         </p><p>
 114             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glBeginQueryIndexed</code> is executed while
 115             a query object of the same <em class="parameter"><code>target</code></em> is already active.
 116         </p><p>
 117             <code class="constant">GL_INVALID_OPERATION</code> is generated if <a href="glEndQueryIndexed.xml"><span class="citerefentry"><span class="refentrytitle">glEndQueryIndexed</span></span></a>
 118             is executed when a query object of the same <em class="parameter"><code>target</code></em> is not active.
 119         </p><p>
 120             <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>id</code></em> is 0.
 121         </p><p>
 122             <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>id</code></em> is the name of an already active query object.
 123         </p><p>
 124             <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>id</code></em> refers to an existing query object whose type
 125             does not does not match <em class="parameter"><code>target</code></em>.
 126         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 127             <a href="glDeleteQueries.xml"><span class="citerefentry"><span class="refentrytitle">glDeleteQueries</span></span></a>,
 128             <a href="glBeginQuery.xml"><span class="citerefentry"><span class="refentrytitle">glBeginQuery</span></span></a>,
 129             <a href="glEndQuery.xml"><span class="citerefentry"><span class="refentrytitle">glEndQuery</span></span></a>,
 130             <a href="glGenQueries.xml"><span class="citerefentry"><span class="refentrytitle">glGenQueries</span></span></a>,
 131             <a href="glGetQueryiv.xml"><span class="citerefentry"><span class="refentrytitle">glGetQueryiv</span></span></a>,
 132             <a href="glGetQueryObject.xml"><span class="citerefentry"><span class="refentrytitle">glGetQueryObject</span></span></a>,
 133             <a href="glIsQuery.xml"><span class="citerefentry"><span class="refentrytitle">glIsQuery</span></span></a>
 134         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 135             Copyright <span class="trademark"></span>© 2010 Khronos Group.
 136             This material may be distributed subject to the terms and conditions set forth in
 137             the Open Publication License, v 1.0, 8 June 1999.
 138             <a href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>.
 139         </p></div></div></body></html>