xenocara/doc/gl-docs/GL/gl/drawelements.3gl
2006-11-29 17:00:35 +00:00

106 lines
3.3 KiB
Plaintext

'\" te
'\"! tbl|eqn | mmdoc
'\"macro stdmacro
.ds Vn Version 1.2
.ds Dt 24 September 1999
.ds Re Release 1.2.1
.ds Dp Jan 14 18:30
.ds Dm 01 draweleme
.ds Xs 17577 5 drawelements.gl
.TH GLDRAWELEMENTS 3G
.SH NAME
.B "glDrawElements
\- render primitives from array data
.SH C SPECIFICATION
void \f3glDrawElements\fP(
GLenum \fImode\fP,
.nf
.ta \w'\f3void \fPglDrawElements( 'u
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
\f2count\fP
Specifies the number of elements to be rendered.
.TP
\f2type\fP
Specifies the type of the values in \f2indices\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
\%\f3glDrawElements\fP specifies multiple geometric primitives
with very few subroutine calls. Instead of calling a GL function
to pass each individual vertex, normal, texture coordinate, edge
flag, or color, you can prespecify
separate arrays of vertices, normals, and so on and use them to
construct a sequence of primitives with a single
call to \%\f3glDrawElements\fP.
.P
When \%\f3glDrawElements\fP is called, it uses \f2count\fP sequential elements from an
enabled array, starting at \f2indices\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 \%\f3glDrawElements\fP have an
unspecified value after \%\f3glDrawElements\fP returns. For example, if
\%\f3GL_COLOR_ARRAY\fP is enabled, the value of the current color is
undefined after \%\f3glDrawElements\fP executes. Attributes that aren't
modified maintain their previous values.
.SH NOTES
\%\f3glDrawElements\fP is available only if the GL version is 1.1 or greater.
.P
\%\f3glDrawElements\fP is included in display lists. If \%\f3glDrawElements\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
\%\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_OPERATION\fP is generated if \%\f3glDrawElements\fP is executed between
the execution of \%\f3glBegin\fP and the corresponding \%\f3glEnd\fP.
.SH SEE ALSO
\%\f3glArrayElement(3G)\fP,
\%\f3glColorPointer(3G)\fP,
\%\f3glDrawArrays(3G)\fP,
\%\f3glDrawRangeElements(3G)\fP,
\%\f3glEdgeFlagPointer(3G)\fP,
\%\f3glGetPointerv(3G)\fP,
\%\f3glIndexPointer(3G)\fP,
\%\f3glInterleavedArrays(3G)\fP,
\%\f3glNormalPointer(3G)\fP,
\%\f3glTexCoordPointer(3G)\fP,
\%\f3glVertexPointer(3G)\fP