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=
"glDrawRangeElements">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glDrawRangeElements
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glDrawRangeElements
</refname>
17 <refpurpose>render primitives from array data
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glDrawRangeElements
</function></funcdef>
23 <paramdef>GLenum
<parameter>mode
</parameter></paramdef>
24 <paramdef>GLuint
<parameter>start
</parameter></paramdef>
25 <paramdef>GLuint
<parameter>end
</parameter></paramdef>
26 <paramdef>GLsizei
<parameter>count
</parameter></paramdef>
27 <paramdef>GLenum
<parameter>type
</parameter></paramdef>
28 <paramdef>const GLvoid *
<parameter>indices
</parameter></paramdef>
32 <!-- eqn: ignoring delim $$ -->
33 <refsect1 id=
"parameters"><title>Parameters
</title>
36 <term><parameter>mode
</parameter></term>
39 Specifies what kind of primitives to render.
41 <constant>GL_POINTS
</constant>,
42 <constant>GL_LINE_STRIP
</constant>,
43 <constant>GL_LINE_LOOP
</constant>,
44 <constant>GL_LINES
</constant>,
45 <constant>GL_TRIANGLE_STRIP
</constant>,
46 <constant>GL_TRIANGLE_FAN
</constant>,
47 <constant>GL_TRIANGLES
</constant>,
48 <constant>GL_QUAD_STRIP
</constant>,
49 <constant>GL_QUADS
</constant>,
50 and
<constant>GL_POLYGON
</constant> are accepted.
55 <term><parameter>start
</parameter></term>
58 Specifies the minimum array index contained in
<parameter>indices
</parameter>.
63 <term><parameter>end
</parameter></term>
66 Specifies the maximum array index contained in
<parameter>indices
</parameter>.
71 <term><parameter>count
</parameter></term>
74 Specifies the number of elements to be rendered.
79 <term><parameter>type
</parameter></term>
82 Specifies the type of the values in
<parameter>indices
</parameter>. Must be one of
83 <constant>GL_UNSIGNED_BYTE
</constant>,
<constant>GL_UNSIGNED_SHORT
</constant>, or
84 <constant>GL_UNSIGNED_INT
</constant>.
89 <term><parameter>indices
</parameter></term>
92 Specifies a pointer to the location where the indices are stored.
98 <refsect1 id=
"description"><title>Description
</title>
100 <function>glDrawRangeElements
</function> is a restricted form of
<citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>.
<parameter>mode
</parameter>,
<parameter>start
</parameter>,
<parameter>end
</parameter>,
101 and
<parameter>count
</parameter> match the corresponding arguments to
<citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>, with
102 the additional constraint that all values in the arrays
<parameter>count
</parameter> must lie
103 between
<parameter>start
</parameter> and
<parameter>end
</parameter>, inclusive.
106 Implementations denote recommended maximum amounts of vertex and
108 which may be queried by calling
<citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
109 <constant>GL_MAX_ELEMENTS_VERTICES
</constant> and
<constant>GL_MAX_ELEMENTS_INDICES
</constant>.
111 <inlineequation><mml:math>
112 <!-- eqn: end - start + 1:-->
114 <mml:mi mathvariant=
"italic">end
</mml:mi>
116 <mml:mi mathvariant=
"italic">start
</mml:mi>
120 </mml:math></inlineequation>
121 is greater than the value of
122 <constant>GL_MAX_ELEMENTS_VERTICES
</constant>, or if
<parameter>count
</parameter> is greater than the value of
123 <constant>GL_MAX_ELEMENTS_INDICES
</constant>, then the call may operate at reduced
124 performance. There is no requirement that all vertices in the range
125 <inlineequation><mml:math>
126 <!-- eqn: [start, end]:-->
127 <mml:mfenced open=
"[" close=
"]">
128 <mml:mi mathvariant=
"italic">start
</mml:mi>
129 <mml:mi mathvariant=
"italic">end
</mml:mi>
131 </mml:math></inlineequation>
132 be referenced. However, the implementation may
133 partially process unused vertices, reducing performance from what could
134 be achieved with an optimal index set.
137 When
<function>glDrawRangeElements
</function> is called, it uses
<parameter>count
</parameter> sequential elements from an
138 enabled array, starting at
<parameter>start
</parameter> to construct a sequence of
139 geometric primitives.
<parameter>mode
</parameter> specifies what kind of primitives are
140 constructed, and how the array elements construct these primitives. If
141 more than one array is enabled, each is used. If
142 <constant>GL_VERTEX_ARRAY
</constant> is not enabled, no geometric primitives are
146 Vertex attributes that are modified by
<function>glDrawRangeElements
</function> have an
147 unspecified value after
<function>glDrawRangeElements
</function> returns. For example, if
148 <constant>GL_COLOR_ARRAY
</constant> is enabled, the value of the current color is
149 undefined after
<function>glDrawRangeElements
</function> executes. Attributes that aren't
150 modified maintain their previous values.
153 <refsect1 id=
"notes"><title>Notes
</title>
155 <function>glDrawRangeElements
</function> is available only if the GL version is
1.2 or greater.
158 <function>glDrawRangeElements
</function> is included in display lists. If
<function>glDrawRangeElements
</function> is entered into a
160 the necessary array data (determined by the array pointers and
162 entered into the display list. Because the array pointers and
163 enables are client-side state, their values affect display lists
164 when the lists are created, not when the lists are executed.
167 <refsect1 id=
"errors"><title>Errors
</title>
169 It is an error for indices to lie outside the range
170 <inlineequation><mml:math>
171 <!-- eqn: [start, end]:-->
172 <mml:mfenced open=
"[" close=
"]">
173 <mml:mi mathvariant=
"italic">start
</mml:mi>
174 <mml:mi mathvariant=
"italic">end
</mml:mi>
176 </mml:math></inlineequation>,
177 but implementations may not check for this situation. Such indices
178 cause implementation-dependent behavior.
181 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>mode
</parameter> is not an accepted value.
184 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>count
</parameter> is negative.
187 <constant>GL_INVALID_VALUE
</constant> is generated if
188 <inlineequation><mml:math>
189 <!-- eqn: end < start:-->
191 <mml:mi mathvariant=
"italic">end
</mml:mi>
192 <mml:mo><</mml:mo>
193 <mml:mi mathvariant=
"italic">start
</mml:mi>
195 </mml:math></inlineequation>.
198 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to an
199 enabled array or the element array and the buffer object's data store is currently mapped.
202 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glDrawRangeElements
</function> is executed between
203 the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry> and the corresponding
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
206 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
208 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_MAX_ELEMENTS_VERTICES
</constant>
211 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_MAX_ELEMENTS_INDICES
</constant>
214 <refsect1 id=
"seealso"><title>See Also
</title>
216 <citerefentry><refentrytitle>glArrayElement
</refentrytitle></citerefentry>,
217 <citerefentry><refentrytitle>glColorPointer
</refentrytitle></citerefentry>,
218 <citerefentry><refentrytitle>glDrawArrays
</refentrytitle></citerefentry>,
219 <citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>,
220 <citerefentry><refentrytitle>glEdgeFlagPointer
</refentrytitle></citerefentry>,
221 <citerefentry><refentrytitle>glGetPointerv
</refentrytitle></citerefentry>,
222 <citerefentry><refentrytitle>glIndexPointer
</refentrytitle></citerefentry>,
223 <citerefentry><refentrytitle>glInterleavedArrays
</refentrytitle></citerefentry>,
224 <citerefentry><refentrytitle>glNormalPointer
</refentrytitle></citerefentry>,
225 <citerefentry><refentrytitle>glSecondaryColorPointer
</refentrytitle></citerefentry>,
226 <citerefentry><refentrytitle>glTexCoordPointer
</refentrytitle></citerefentry>,
227 <citerefentry><refentrytitle>glVertexPointer
</refentrytitle></citerefentry>
230 <refsect1 id=
"Copyright"><title>Copyright
</title>
232 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
233 Silicon Graphics, Inc. This document is licensed under the SGI
234 Free Software B License. For details, see
235 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.