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_LINE_STRIP_ADJACENCY
</constant>,
46 <constant>GL_LINES_ADJACENCY
</constant>,
47 <constant>GL_TRIANGLE_STRIP
</constant>,
48 <constant>GL_TRIANGLE_FAN
</constant>,
49 <constant>GL_TRIANGLES
</constant>,
50 <constant>GL_TRIANGLE_STRIP_ADJACENCY
</constant> and
51 <constant>GL_TRIANGLES_ADJACENCY
</constant>
57 <term><parameter>start
</parameter></term>
60 Specifies the minimum array index contained in
<parameter>indices
</parameter>.
65 <term><parameter>end
</parameter></term>
68 Specifies the maximum array index contained in
<parameter>indices
</parameter>.
73 <term><parameter>count
</parameter></term>
76 Specifies the number of elements to be rendered.
81 <term><parameter>type
</parameter></term>
84 Specifies the type of the values in
<parameter>indices
</parameter>. Must be one of
85 <constant>GL_UNSIGNED_BYTE
</constant>,
<constant>GL_UNSIGNED_SHORT
</constant>, or
86 <constant>GL_UNSIGNED_INT
</constant>.
91 <term><parameter>indices
</parameter></term>
94 Specifies a pointer to the location where the indices are stored.
100 <refsect1 id=
"description"><title>Description
</title>
102 <function>glDrawRangeElements
</function> is a restricted form of
<citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>.
<parameter>mode
</parameter>,
<parameter>start
</parameter>,
<parameter>end
</parameter>,
103 and
<parameter>count
</parameter> match the corresponding arguments to
<citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>, with
104 the additional constraint that all values in the arrays
<parameter>count
</parameter> must lie
105 between
<parameter>start
</parameter> and
<parameter>end
</parameter>, inclusive.
108 Implementations denote recommended maximum amounts of vertex and
110 which may be queried by calling
<citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
111 <constant>GL_MAX_ELEMENTS_VERTICES
</constant> and
<constant>GL_MAX_ELEMENTS_INDICES
</constant>.
113 <inlineequation><mml:math>
114 <!-- eqn: end - start + 1: -->
116 <mml:mi mathvariant=
"italic">end
</mml:mi>
118 <mml:mi mathvariant=
"italic">start
</mml:mi>
122 </mml:math></inlineequation>
123 is greater than the value of
124 <constant>GL_MAX_ELEMENTS_VERTICES
</constant>, or if
<parameter>count
</parameter> is greater than the value of
125 <constant>GL_MAX_ELEMENTS_INDICES
</constant>, then the call may operate at reduced
126 performance. There is no requirement that all vertices in the range
127 <inlineequation><mml:math>
128 <!-- eqn: [start, end]: -->
129 <mml:mfenced open=
"[" close=
"]">
130 <mml:mi mathvariant=
"italic">start
</mml:mi>
131 <mml:mi mathvariant=
"italic">end
</mml:mi>
133 </mml:math></inlineequation>
134 be referenced. However, the implementation may
135 partially process unused vertices, reducing performance from what could
136 be achieved with an optimal index set.
139 When
<function>glDrawRangeElements
</function> is called, it uses
<parameter>count
</parameter> sequential elements from an
140 enabled array, starting at
<parameter>start
</parameter> to construct a sequence of
141 geometric primitives.
<parameter>mode
</parameter> specifies what kind of primitives are
142 constructed, and how the array elements construct these primitives. If
143 more than one array is enabled, each is used.
146 Vertex attributes that are modified by
<function>glDrawRangeElements
</function> have an
147 unspecified value after
<function>glDrawRangeElements
</function> returns. Attributes that aren't
148 modified maintain their previous values.
151 <refsect1 id=
"notes"><title>Notes
</title>
153 <constant>GL_LINE_STRIP_ADJACENCY
</constant>,
154 <constant>GL_LINES_ADJACENCY
</constant>,
155 <constant>GL_TRIANGLE_STRIP_ADJACENCY
</constant> and
156 <constant>GL_TRIANGLES_ADJACENCY
</constant>
157 are available only if the GL version is
3.2 or greater.
160 <refsect1 id=
"errors"><title>Errors
</title>
162 It is an error for indices to lie outside the range
163 <inlineequation><mml:math>
164 <!-- eqn: [start, end]: -->
165 <mml:mfenced open=
"[" close=
"]">
166 <mml:mi mathvariant=
"italic">start
</mml:mi>
167 <mml:mi mathvariant=
"italic">end
</mml:mi>
169 </mml:math></inlineequation>,
170 but implementations may not check for this situation. Such indices
171 cause implementation-dependent behavior.
174 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>mode
</parameter> is not an accepted value.
177 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>count
</parameter> is negative.
180 <constant>GL_INVALID_VALUE
</constant> is generated if
181 <inlineequation><mml:math>
182 <!-- eqn: end < start: -->
184 <mml:mi mathvariant=
"italic">end
</mml:mi>
185 <mml:mo><</mml:mo>
186 <mml:mi mathvariant=
"italic">start
</mml:mi>
188 </mml:math></inlineequation>.
191 <constant>GL_INVALID_OPERATION
</constant> is generated if a geometry shader is active and
<parameter>mode
</parameter>
192 is incompatible with the input primitive type of the geometry shader in the currently installed program object.
195 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to an
196 enabled array or the element array and the buffer object's data store is currently mapped.
199 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
201 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_MAX_ELEMENTS_VERTICES
</constant>
204 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_MAX_ELEMENTS_INDICES
</constant>
207 <refsect1 id=
"seealso"><title>See Also
</title>
209 <citerefentry><refentrytitle>glDrawArrays
</refentrytitle></citerefentry>,
210 <citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>,
211 <citerefentry><refentrytitle>glDrawElementsBaseVertex
</refentrytitle></citerefentry>
214 <refsect1 id=
"Copyright"><title>Copyright
</title>
216 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
217 Silicon Graphics, Inc. This document is licensed under the SGI
218 Free Software B License. For details, see
219 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.