218 lines
6.1 KiB
Plaintext
218 lines
6.1 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 begin.gl
|
|
.ds Xs 5437 8 begin.gl
|
|
.TH GLBEGIN 3G
|
|
.SH NAME
|
|
.B "glBegin, glEnd
|
|
\- delimit the vertices of a primitive or a group of like primitives
|
|
|
|
.SH C SPECIFICATION
|
|
void \f3glBegin\fP(
|
|
GLenum \fImode\fP )
|
|
.nf
|
|
.fi
|
|
|
|
.EQ
|
|
delim $$
|
|
.EN
|
|
.SH PARAMETERS
|
|
.TP \w'\f2mode\fP\ \ 'u
|
|
\f2mode\fP
|
|
Specifies the primitive or primitives that will be created from vertices
|
|
presented between \%\f3glBegin\fP and the subsequent \%\f3glEnd\fP.
|
|
Ten symbolic constants are accepted:
|
|
\%\f3GL_POINTS\fP,
|
|
\%\f3GL_LINES\fP,
|
|
\%\f3GL_LINE_STRIP\fP,
|
|
\%\f3GL_LINE_LOOP\fP,
|
|
\%\f3GL_TRIANGLES\fP,
|
|
\%\f3GL_TRIANGLE_STRIP\fP,
|
|
\%\f3GL_TRIANGLE_FAN\fP,
|
|
\%\f3GL_QUADS\fP,
|
|
\%\f3GL_QUAD_STRIP\fP, and
|
|
\%\f3GL_POLYGON\fP.
|
|
.SH C SPECIFICATION
|
|
void \f3glEnd\fP( void )
|
|
.nf
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
\%\f3glBegin\fP and \%\f3glEnd\fP delimit the vertices that define a primitive or
|
|
a group of like primitives.
|
|
\%\f3glBegin\fP accepts a single argument that specifies in which of ten ways the
|
|
vertices are interpreted.
|
|
Taking $n$ as an integer count starting at one,
|
|
and $N$ as the total number of vertices specified,
|
|
the interpretations are as follows:
|
|
.TP 23
|
|
\%\f3GL_POINTS\fP
|
|
Treats each vertex as a single point.
|
|
Vertex $n$ defines point $n$.
|
|
$N$ points are drawn.
|
|
.TP
|
|
\%\f3GL_LINES\fP
|
|
Treats each pair of vertices as an independent line segment.
|
|
Vertices $2n^-^1$ and $2n$ define line $n$.
|
|
$N/2$ lines are drawn.
|
|
.TP
|
|
\%\f3GL_LINE_STRIP\fP
|
|
Draws a connected group of line segments from the first vertex
|
|
to the last.
|
|
Vertices $n$ and $n~+~1$ define line $n$.
|
|
$N^-^1$ lines are drawn.
|
|
.TP
|
|
\%\f3GL_LINE_LOOP\fP
|
|
Draws a connected group of line segments from the first vertex
|
|
to the last,
|
|
then back to the first.
|
|
Vertices $n$ and $n~+~1$ define line $n$.
|
|
The last line, however, is defined by vertices $N$ and $1$.
|
|
$N$ lines are drawn.
|
|
.TP
|
|
\%\f3GL_TRIANGLES\fP
|
|
Treats each triplet of vertices as an independent triangle.
|
|
Vertices $3n^-^2$, $3n^-^1$, and $3n$ define triangle $n$.
|
|
$N/3$ triangles are drawn.
|
|
.BP
|
|
.TP
|
|
\%\f3GL_TRIANGLE_STRIP\fP
|
|
Draws a connected group of triangles. One triangle is defined for each
|
|
vertex presented after the first two vertices. For odd $n$, vertices
|
|
$n$, $n~+~1$, and $n~+~2$ define triangle $n$. For even $n$, vertices
|
|
$n~+~1$, $n$, and $n~+~2$ define triangle $n$. $N^-^2$ triangles are
|
|
drawn.
|
|
.TP
|
|
\%\f3GL_TRIANGLE_FAN\fP
|
|
Draws a connected group of triangles.
|
|
One triangle is defined for each vertex presented after the first two vertices.
|
|
Vertices $1$,
|
|
$n~+~1$,
|
|
and $n~+~2$ define triangle $n$.
|
|
$N^-^2$ triangles are drawn.
|
|
.TP
|
|
\%\f3GL_QUADS\fP
|
|
Treats each group of four vertices as an independent quadrilateral.
|
|
Vertices $4n^-^3$, $4n^-^2$, $4n^-^1$, and $4n$
|
|
define quadrilateral $n$.
|
|
$N/4$ quadrilaterals are drawn.
|
|
.TP
|
|
\%\f3GL_QUAD_STRIP\fP
|
|
Draws a connected group of quadrilaterals.
|
|
One quadrilateral is defined for each pair of vertices presented
|
|
after the first pair.
|
|
Vertices $2n^-^1$, $2n$, $2n~+~2$, and $2n~+~1$ define quadrilateral $n$.
|
|
$N/2^-^1$ quadrilaterals are drawn.
|
|
Note that the order in which vertices are used to construct a quadrilateral
|
|
from strip data is different from that used with independent data.
|
|
.TP
|
|
\%\f3GL_POLYGON\fP
|
|
Draws a single,
|
|
convex polygon.
|
|
Vertices $1$ through $N$ define this polygon.
|
|
.P
|
|
Only a subset of GL commands can be used between \%\f3glBegin\fP and \%\f3glEnd\fP.
|
|
The commands are
|
|
\%\f3glVertex\fP,
|
|
\%\f3glColor\fP,
|
|
\%\f3glIndex\fP,
|
|
\%\f3glNormal\fP,
|
|
\%\f3glTexCoord\fP,
|
|
\%\f3glEvalCoord\fP,
|
|
\%\f3glEvalPoint\fP,
|
|
\%\f3glArrayElement\fP,
|
|
\%\f3glMaterial\fP, and
|
|
\%\f3glEdgeFlag\fP.
|
|
Also,
|
|
it is acceptable to use
|
|
\%\f3glCallList\fP or
|
|
\%\f3glCallLists\fP to execute
|
|
display lists that include only the preceding commands.
|
|
If any other GL command is executed between \%\f3glBegin\fP and \%\f3glEnd\fP,
|
|
the error flag is set and the command is ignored.
|
|
.P
|
|
Regardless of the value chosen for \f2mode\fP,
|
|
there is no limit to the number of vertices that can be defined
|
|
between \%\f3glBegin\fP and \%\f3glEnd\fP.
|
|
Lines,
|
|
triangles,
|
|
quadrilaterals,
|
|
and polygons that are incompletely specified are not drawn.
|
|
Incomplete specification results when either too few vertices are
|
|
provided to specify even a single primitive or when an incorrect multiple
|
|
of vertices is specified. The incomplete primitive is ignored; the rest are drawn.
|
|
.P
|
|
The minimum specification of vertices
|
|
for each primitive is as follows:
|
|
1 for a point,
|
|
2 for a line,
|
|
3 for a triangle,
|
|
4 for a quadrilateral,
|
|
and 3 for a polygon.
|
|
Modes that require a certain multiple of vertices are
|
|
\%\f3GL_LINES\fP (2),
|
|
\%\f3GL_TRIANGLES\fP (3),
|
|
\%\f3GL_QUADS\fP (4),
|
|
and \%\f3GL_QUAD_STRIP\fP (2).
|
|
.SH ERRORS
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2mode\fP is set to an unaccepted value.
|
|
.P
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glBegin\fP is executed between a
|
|
\%\f3glBegin\fP
|
|
and the corresponding execution of \%\f3glEnd\fP.
|
|
.P
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glEnd\fP is executed without being
|
|
preceded by a \%\f3glBegin\fP.
|
|
.P
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if a command other than
|
|
\%\f3glVertex\fP,
|
|
\%\f3glColor\fP,
|
|
\%\f3glIndex\fP,
|
|
\%\f3glNormal\fP,
|
|
\%\f3glTexCoord\fP,
|
|
\%\f3glEvalCoord\fP,
|
|
\%\f3glEvalPoint\fP,
|
|
\%\f3glArrayElement\fP,
|
|
\%\f3glMaterial\fP,
|
|
\%\f3glEdgeFlag\fP,
|
|
\%\f3glCallList\fP, or
|
|
\%\f3glCallLists\fP is executed between
|
|
the execution of \%\f3glBegin\fP and the corresponding
|
|
execution \%\f3glEnd\fP.
|
|
.P
|
|
Execution of
|
|
\%\f3glEnableClientState\fP,
|
|
\%\f3glDisableClientState\fP,
|
|
\%\f3glEdgeFlagPointer\fP,
|
|
\%\f3glTexCoordPointer\fP,
|
|
\%\f3glColorPointer\fP,
|
|
\%\f3glIndexPointer\fP,
|
|
\%\f3glNormalPointer\fP,
|
|
.br
|
|
\%\f3glVertexPointer\fP,
|
|
\%\f3glInterleavedArrays\fP, or
|
|
\%\f3glPixelStore\fP is not allowed after a call to \%\f3glBegin\fP and before
|
|
the corresponding call to \%\f3glEnd\fP,
|
|
but an error may or may not be generated.
|
|
.SH SEE ALSO
|
|
\%\f3glArrayElement(3G)\fP,
|
|
\%\f3glCallList(3G)\fP,
|
|
\%\f3glCallLists(3G)\fP,
|
|
\%\f3glColor(3G)\fP,
|
|
\%\f3glEdgeFlag(3G)\fP,
|
|
\%\f3glEvalCoord(3G)\fP,
|
|
.br
|
|
\%\f3glEvalPoint(3G)\fP,
|
|
\%\f3glIndex(3G)\fP,
|
|
\%\f3glMaterial(3G)\fP,
|
|
\%\f3glNormal(3G)\fP,
|
|
\%\f3glTexCoord(3G)\fP,
|
|
\%\f3glVertex(3G)\fP
|
|
|
|
|