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

98 lines
3.0 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 drawarray
.ds Xs 55233 5 drawarrays.gl
.TH GLDRAWARRAYS 3G
.SH NAME
.B "glDrawArrays
\- render primitives from array data
.SH C SPECIFICATION
void \f3glDrawArrays\fP(
GLenum \fImode\fP,
.nf
.ta \w'\f3void \fPglDrawArrays( 'u
GLint \fIfirst\fP,
GLsizei \fIcount\fP )
.fi
.EQ
delim $$
.EN
.SH PARAMETERS
.TP \w'\fIfirst\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
\f2first\fP
Specifies the starting index in the enabled arrays.
.TP
\f2count\fP
Specifies the number of indices to be rendered.
.SH DESCRIPTION
\%\f3glDrawArrays\fP specifies multiple geometric primitives
with very few subroutine calls. Instead of calling a GL procedure
to pass each individual vertex, normal, texture coordinate, edge
flag, or color, you can prespecify
separate arrays of vertices, normals, and colors and use them to
construct a sequence of primitives with a single
call to \%\f3glDrawArrays\fP.
.P
When \%\f3glDrawArrays\fP is called, it uses \f2count\fP sequential elements from each
enabled array to construct a sequence of geometric primitives,
beginning with element \f2first\fP. \f2mode\fP specifies what kind of
primitives are constructed, and how the array elements
construct those primitives. If \%\f3GL_VERTEX_ARRAY\fP is not enabled, no
geometric primitives are generated.
.P
Vertex attributes that are modified by \%\f3glDrawArrays\fP have an
unspecified value after \%\f3glDrawArrays\fP returns. For example, if
\%\f3GL_COLOR_ARRAY\fP is enabled, the value of the current color is
undefined after \%\f3glDrawArrays\fP executes. Attributes that aren't
modified remain well defined.
.SH NOTES
\%\f3glDrawArrays\fP is available only if the GL version is 1.1 or greater.
.P
\%\f3glDrawArrays\fP is included in display lists. If \%\f3glDrawArrays\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 \%\f3glDrawArrays\fP is executed between
the execution of \%\f3glBegin\fP and the corresponding \%\f3glEnd\fP.
.SH SEE ALSO
\%\f3glArrayElement(3G)\fP,
\%\f3glColorPointer(3G)\fP,
\%\f3glDrawElements(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