glDrawRangeElements.3   [plain text]

'\" te  
'\"macro stdmacro
.ds Vn Version 1.2
.ds Dt 24 September 1999
.ds Re Release 1.2.1
.ds Dp May 22 14:45
.ds Dm 8 May 22 14:
.ds Xs 22158     7
.TH GLDRAWRANGEELEMENTS 3G
.SH NAME
.B "glDrawRangeElements
\- render primitives from array data

.SH C SPECIFICATION
void \f3glDrawRangeElements\fP(
GLenum \fImode\fP,
.nf
.ta \w'\f3void \fPglDrawRangeElements( 'u
	GLuint \fIstart\fP,
	GLuint \fIend\fP,
	GLsizei \fIcount\fP,
	GLenum \fItype\fP,
	const GLvoid \fI*indices\fP )
.fi

.EQ
delim $$
.EN
.SH PARAMETERS
.TP \w'\fIindices\fP\ \ 'u 
\f2mode\fP
Specifies what kind of primitives to render.
Symbolic constants
\%\f3GL_POINTS\fP,
\%\f3GL_LINE_STRIP\fP,
\%\f3GL_LINE_LOOP\fP,
\%\f3GL_LINES\fP,
\%\f3GL_TRIANGLE_STRIP\fP,
\%\f3GL_TRIANGLE_FAN\fP,
\%\f3GL_TRIANGLES\fP,
\%\f3GL_QUAD_STRIP\fP,
\%\f3GL_QUADS\fP,
and \%\f3GL_POLYGON\fP are accepted. 
.TP
\f2start\fP
Specifies the minimum array index contained in \f2indices\fP.
.TP
\f2end\fP
Specifies the maximum array index contained in \f2indices\fP.
.TP
\f2count\fP
Specifies the number of elements to be rendered.
.TP
\f2type\fP
Specifies the type of the values in \f2count\fP. Must be one of
\%\f3GL_UNSIGNED_BYTE\fP, \%\f3GL_UNSIGNED_SHORT\fP, or
\%\f3GL_UNSIGNED_INT\fP. 
.TP
\f2indices\fP
Specifies a pointer to the location where the indices are stored. 
.SH DESCRIPTION
\%\f3glDrawRangeElements\fP is a restricted form of \%\f3glDrawElements\fP. \f2mode\fP, \f2start\fP, \f2end\fP,
and \f2count\fP match the corresponding arguments to \%\f3glDrawElements\fP, with
the additional constraint that all values in the arrays \f2count\fP must lie
between \f2start\fP and \f2end\fP, inclusive.
.P
Implementations denote recommended maximum amounts of vertex and
.br
index data,
which may be queried by calling \%\f3glGet\fP with argument 
\%\f3GL_MAX_ELEMENTS_VERTICES\fP and \%\f3GL_MAX_ELEMENTS_INDICES\fP.
If $"end" ~-~ "start" ~+~ 1$ is greater than the value of
\%\f3GL_MAX_ELEMENTS_VERTICES\fP, or if \f2count\fP is greater than the value of
\%\f3GL_MAX_ELEMENTS_INDICES\fP, then the call may operate at reduced
performance.  There is no requirement that all vertices in the range
[\f2start\fP,\ \f2end\fP] be referenced.  However, the implementation may
partially process unused vertices, reducing performance from what could 
be achieved with an optimal index set.
.P
When \%\f3glDrawRangeElements\fP is called, it uses \f2start\fP sequential elements from an
enabled array, starting at \f2count\fP to construct a sequence of
geometric primitives. \f2mode\fP specifies what kind of primitives are
constructed, and how the array elements construct these primitives. If
more than one array is enabled, each is used. If
\%\f3GL_VERTEX_ARRAY\fP is not enabled, no geometric primitives are
constructed.
.P
Vertex attributes that are modified by \%\f3glDrawRangeElements\fP have an
unspecified value after \%\f3glDrawRangeElements\fP returns. For example, if
\%\f3GL_COLOR_ARRAY\fP is enabled, the value of the current color is
undefined after \%\f3glDrawRangeElements\fP executes. Attributes that aren't
modified maintain their previous values.
.SH NOTES
\%\f3glDrawRangeElements\fP is available only if the GL version is 1.2 or greater.
.P
\%\f3glDrawRangeElements\fP is included in display lists. If \%\f3glDrawRangeElements\fP is entered into a
display list, 
the necessary array data (determined by the array pointers and
enables) is also 
entered into the display list. Because the array pointers and
enables are client-side state, their values affect display lists
when the lists are created, not when the lists are executed.
.SH ERRORS
It is an error for indices to lie outside the range [\f2start\fP,\ \f2end\fP],
but implementations may not check for this situation. Such indices
cause implementation-dependent behavior.
.P
\%\f3GL_INVALID_ENUM\fP is generated if \f2mode\fP is not an accepted value.
.P
\%\f3GL_INVALID_VALUE\fP is generated if \f2count\fP is negative.
.P
\%\f3GL_INVALID_VALUE\fP is generated if \f2end\fP $<$ \f2start\fP.
.P
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glDrawRangeElements\fP is executed between
the execution of \%\f3glBegin\fP and the corresponding \%\f3glEnd\fP.
.SH ASSOCIATED GETS
\%\f3glGet\fP with argument \%\f3GL_MAX_ELEMENTS_VERTICES\fP
.P
\%\f3glGet\fP with argument \%\f3GL_MAX_ELEMENTS_INDICES\fP
.SH SEE ALSO 
\%\f3glArrayElement\fP,
\%\f3glColorPointer\fP,
\%\f3glDrawArrays\fP,
\%\f3glDrawElements\fP,
\%\f3glEdgeFlagPointer\fP,
\%\f3glGetPointerv\fP,
\%\f3glIndexPointer\fP,
\%\f3glInterleavedArrays\fP,
\%\f3glNormalPointer\fP,
\%\f3glTexCoordPointer\fP,
\%\f3glVertexPointer\fP