upstream-man-pages/man2/xhtml/glDrawRangeElements.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?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" /><title>glDrawRangeElements</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glDrawRangeElements"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glDrawRangeElements — render primitives from array data</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">glDrawRangeElements</b>(</code></td><td>GLenum  </td><td><var class="pdparam">mode</var>, </td></tr><tr><td> </td><td>GLuint  </td><td><var class="pdparam">start</var>, </td></tr><tr><td> </td><td>GLuint  </td><td><var class="pdparam">end</var>, </td></tr><tr><td> </td><td>GLsizei  </td><td><var class="pdparam">count</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">type</var>, </td></tr><tr><td> </td><td>const GLvoid *  </td><td><var class="pdparam">indices</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>mode</code></em></span></dt><dd><p>
   4                     Specifies what kind of primitives to render.
   5                     Symbolic constants
   6                     <code class="constant">GL_POINTS</code>,
   7                     <code class="constant">GL_LINE_STRIP</code>,
   8                     <code class="constant">GL_LINE_LOOP</code>,
   9                     <code class="constant">GL_LINES</code>,
  10                     <code class="constant">GL_TRIANGLE_STRIP</code>,
  11                     <code class="constant">GL_TRIANGLE_FAN</code>,
  12                     <code class="constant">GL_TRIANGLES</code>,
  13                     <code class="constant">GL_QUAD_STRIP</code>,
  14                     <code class="constant">GL_QUADS</code>,
  15                     and <code class="constant">GL_POLYGON</code> are accepted.
  16                 </p></dd><dt><span class="term"><em class="parameter"><code>start</code></em></span></dt><dd><p>
  17                     Specifies the minimum array index contained in <em class="parameter"><code>indices</code></em>.
  18                 </p></dd><dt><span class="term"><em class="parameter"><code>end</code></em></span></dt><dd><p>
  19                     Specifies the maximum array index contained in <em class="parameter"><code>indices</code></em>.
  20                 </p></dd><dt><span class="term"><em class="parameter"><code>count</code></em></span></dt><dd><p>
  21                     Specifies the number of elements to be rendered.
  22                 </p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p>
  23                     Specifies the type of the values in <em class="parameter"><code>indices</code></em>. Must be one of
  24                     <code class="constant">GL_UNSIGNED_BYTE</code>, <code class="constant">GL_UNSIGNED_SHORT</code>, or
  25                     <code class="constant">GL_UNSIGNED_INT</code>.
  26                 </p></dd><dt><span class="term"><em class="parameter"><code>indices</code></em></span></dt><dd><p>
  27                     Specifies a pointer to the location where the indices are stored.
  28                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  29             <code class="function">glDrawRangeElements</code> is a restricted form of <a class="citerefentry" href="glDrawElements.xml"><span class="citerefentry"><span class="refentrytitle">glDrawElements</span></span></a>. <em class="parameter"><code>mode</code></em>, <em class="parameter"><code>start</code></em>, <em class="parameter"><code>end</code></em>,
  30             and <em class="parameter"><code>count</code></em> match the corresponding arguments to <a class="citerefentry" href="glDrawElements.xml"><span class="citerefentry"><span class="refentrytitle">glDrawElements</span></span></a>, with
  31             the additional constraint that all values in the arrays <em class="parameter"><code>count</code></em> must lie
  32             between <em class="parameter"><code>start</code></em> and <em class="parameter"><code>end</code></em>, inclusive.
  33         </p><p>
  34             Implementations denote recommended maximum amounts of vertex and
  35             index data,
  36             which may be queried by calling <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument
  37             <code class="constant">GL_MAX_ELEMENTS_VERTICES</code> and <code class="constant">GL_MAX_ELEMENTS_INDICES</code>.
  38             If
  39             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  40
  41                 <mml:mrow>
  42                     <mml:mi mathvariant="italic">end</mml:mi>
  43                     <mml:mo>-</mml:mo>
  44                     <mml:mi mathvariant="italic">start</mml:mi>
  45                     <mml:mo>+</mml:mo>
  46                     <mml:mn>1</mml:mn>
  47                 </mml:mrow>
  48             </mml:math>
  49             is greater than the value of
  50             <code class="constant">GL_MAX_ELEMENTS_VERTICES</code>, or if <em class="parameter"><code>count</code></em> is greater than the value of
  51             <code class="constant">GL_MAX_ELEMENTS_INDICES</code>, then the call may operate at reduced
  52             performance.  There is no requirement that all vertices in the range
  53             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  54
  55                 <mml:mfenced open="[" close="]">
  56                     <mml:mi mathvariant="italic">start</mml:mi>
  57                     <mml:mi mathvariant="italic">end</mml:mi>
  58                 </mml:mfenced>
  59             </mml:math>
  60             be referenced.  However, the implementation may
  61             partially process unused vertices, reducing performance from what could
  62             be achieved with an optimal index set.
  63         </p><p>
  64             When <code class="function">glDrawRangeElements</code> is called, it uses <em class="parameter"><code>count</code></em> sequential elements from an
  65             enabled array, starting at <em class="parameter"><code>start</code></em> to construct a sequence of
  66             geometric primitives. <em class="parameter"><code>mode</code></em> specifies what kind of primitives are
  67             constructed, and how the array elements construct these primitives. If
  68             more than one array is enabled, each is used. If
  69             <code class="constant">GL_VERTEX_ARRAY</code> is not enabled, no geometric primitives are
  70             constructed.
  71         </p><p>
  72             Vertex attributes that are modified by <code class="function">glDrawRangeElements</code> have an
  73             unspecified value after <code class="function">glDrawRangeElements</code> returns. For example, if
  74             <code class="constant">GL_COLOR_ARRAY</code> is enabled, the value of the current color is
  75             undefined after <code class="function">glDrawRangeElements</code> executes. Attributes that aren't
  76             modified maintain their previous values.
  77         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
  78             <code class="function">glDrawRangeElements</code> is available only if the GL version is 1.2 or greater.
  79         </p><p>
  80             <code class="function">glDrawRangeElements</code> is included in display lists. If <code class="function">glDrawRangeElements</code> is entered into a
  81             display list,
  82             the necessary array data (determined by the array pointers and
  83             enables) is also
  84             entered into the display list. Because the array pointers and
  85             enables are client-side state, their values affect display lists
  86             when the lists are created, not when the lists are executed.
  87         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
  88             It is an error for indices to lie outside the range
  89             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  90
  91                 <mml:mfenced open="[" close="]">
  92                     <mml:mi mathvariant="italic">start</mml:mi>
  93                     <mml:mi mathvariant="italic">end</mml:mi>
  94                 </mml:mfenced>
  95             </mml:math>,
  96             but implementations may not check for this situation. Such indices
  97             cause implementation-dependent behavior.
  98         </p><p>
  99             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>mode</code></em> is not an accepted value.
 100         </p><p>
 101             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>count</code></em> is negative.
 102         </p><p>
 103             <code class="constant">GL_INVALID_VALUE</code> is generated if
 104             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 105
 106                 <mml:mrow>
 107                     <mml:mi mathvariant="italic">end</mml:mi>
 108                     <mml:mo>&lt;</mml:mo>
 109                     <mml:mi mathvariant="italic">start</mml:mi>
 110                 </mml:mrow>
 111             </mml:math>.
 112         </p><p>
 113             <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to an
 114             enabled array or the element array and the buffer object's data store is currently mapped.
 115         </p><p>
 116             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glDrawRangeElements</code> is executed between
 117             the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> and the corresponding <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 118         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 119             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_MAX_ELEMENTS_VERTICES</code>
 120         </p><p>
 121             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_MAX_ELEMENTS_INDICES</code>
 122         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 123             <a class="citerefentry" href="glArrayElement.xml"><span class="citerefentry"><span class="refentrytitle">glArrayElement</span></span></a>,
 124             <a class="citerefentry" href="glColorPointer.xml"><span class="citerefentry"><span class="refentrytitle">glColorPointer</span></span></a>,
 125             <a class="citerefentry" href="glDrawArrays.xml"><span class="citerefentry"><span class="refentrytitle">glDrawArrays</span></span></a>,
 126             <a class="citerefentry" href="glDrawElements.xml"><span class="citerefentry"><span class="refentrytitle">glDrawElements</span></span></a>,
 127             <a class="citerefentry" href="glEdgeFlagPointer.xml"><span class="citerefentry"><span class="refentrytitle">glEdgeFlagPointer</span></span></a>,
 128             <a class="citerefentry" href="glGetPointerv.xml"><span class="citerefentry"><span class="refentrytitle">glGetPointerv</span></span></a>,
 129             <a class="citerefentry" href="glIndexPointer.xml"><span class="citerefentry"><span class="refentrytitle">glIndexPointer</span></span></a>,
 130             <a class="citerefentry" href="glInterleavedArrays.xml"><span class="citerefentry"><span class="refentrytitle">glInterleavedArrays</span></span></a>,
 131             <a class="citerefentry" href="glNormalPointer.xml"><span class="citerefentry"><span class="refentrytitle">glNormalPointer</span></span></a>,
 132             <a class="citerefentry" href="glSecondaryColorPointer.xml"><span class="citerefentry"><span class="refentrytitle">glSecondaryColorPointer</span></span></a>,
 133             <a class="citerefentry" href="glTexCoordPointer.xml"><span class="citerefentry"><span class="refentrytitle">glTexCoordPointer</span></span></a>,
 134             <a class="citerefentry" href="glVertexPointer.xml"><span class="citerefentry"><span class="refentrytitle">glVertexPointer</span></span></a>
 135         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 136             Copyright <span class="trademark"></span>© 1991-2006
 137             Silicon Graphics, Inc. This document is licensed under the SGI
 138             Free Software B License. For details, see
 139             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 140         </p></div></div></body></html>