path: root/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/begin.gl

_C_ License Applicability. Except to the extent portions of this file are
_C_ made subject to an alternative license as permitted in the SGI Free
_C_ Software License B, Version 1.1 (the "License"), the contents of this
_C_ file are subject only to the provisions of the License. You may not use
_C_ this file except in compliance with the License. You may obtain a copy
_C_ of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
_C_ Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
_C_ 
_C_ http://oss.sgi.com/projects/FreeB
_C_ 
_C_ Note that, as provided in the License, the Software is distributed on an
_C_ "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
_C_ DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
_C_ CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
_C_ PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
_C_ 
_C_ Original Code. The Original Code is: OpenGL Sample Implementation,
_C_ Version 1.2.1, released January 26, 2000, developed by Silicon Graphics,
_C_ Inc. The Original Code is Copyright (c) 1991-2000 Silicon Graphics, Inc.
_C_ Copyright in any portions created by third parties is as indicated
_C_ elsewhere herein. All Rights Reserved.
_C_ 
_C_ Additional Notice Provisions: The application programming interfaces
_C_ established by SGI in conjunction with the Original Code are The
_C_ OpenGL(R) Graphics System: A Specification (Version 1.2.1), released
_C_ April 1, 1999; The OpenGL(R) Graphics System Utility Library (Version
_C_ 1.3), released November 4, 1998; and OpenGL(R) Graphics with the X
_C_ Window System(R) (Version 1.3), released October 19, 1998. This software
_C_ was created using the OpenGL(R) version 1.2.1 Sample Implementation
_C_ published by SGI, but has not been independently verified as being
_C_ compliant with the OpenGL(R) version 1.2.1 Specification.
_C_
_C_ The first character in this file must be an '_'!
_C_ Anything on a line after _C_ is ignored
_define(_filters,tbl|eqn)_C_
_header(Begin,delimit the vertices of a primitive or a group of like primitives)
_names(Begin)
.EQ
delim $$
.EN
.SH PARAMETERS
_phead(_param1)
Specifies the primitive or primitives that will be created from vertices
presented between _cmnd(Begin) and the subsequent _cmnd(End).
Ten symbolic constants are accepted:
_const(POINTS),
_const(LINES),
_const(LINE_STRIP),
_const(LINE_LOOP),
_const(TRIANGLES),
_const(TRIANGLE_STRIP),
_const(TRIANGLE_FAN),
_const(QUADS),
_const(QUAD_STRIP), and
_const(POLYGON).
_names(End)
.SH DESCRIPTION
_cmnd(Begin) and _cmnd(End) delimit the vertices that define a primitive or
a group of like primitives.
_cmnd(Begin) 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
_const(POINTS)
Treats each vertex as a single point.
Vertex $n$ defines point $n$.
$N$ points are drawn.
.TP
_const(LINES)
Treats each pair of vertices as an independent line segment.
Vertices $2n^-^1$ and $2n$ define line $n$.
$N/2$ lines are drawn.
.TP
_const(LINE_STRIP)
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
_const(LINE_LOOP)
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
_const(TRIANGLES)
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
_const(TRIANGLE_STRIP)
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
_const(TRIANGLE_FAN)
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
_const(QUADS)
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
_const(QUAD_STRIP)
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
_const(POLYGON)
Draws a single,
convex polygon.
Vertices $1$ through $N$ define this polygon.
.P
Only a subset of GL commands can be used between _cmnd(Begin) and _cmnd(End).
The commands are
_cmnd(Vertex),
_cmnd(Color),
_cmnd(Index),
_cmnd(Normal),
_cmnd(TexCoord),
_cmnd(EvalCoord),
_cmnd(EvalPoint),
_cmnd(ArrayElement),
_cmnd(Material), and
_cmnd(EdgeFlag).
Also,
it is acceptable to use
_cmnd(CallList) or
_cmnd(CallLists) to execute
display lists that include only the preceding commands.
If any other GL command is executed between _cmnd(Begin) and _cmnd(End),
the error flag is set and the command is ignored.
.P
Regardless of the value chosen for _param1(1),
there is no limit to the number of vertices that can be defined
between _cmnd(Begin) and _cmnd(End).
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
_const(LINES) (2),
_const(TRIANGLES) (3),
_const(QUADS) (4),
and _const(QUAD_STRIP) (2).
.SH ERRORS
_const(INVALID_ENUM) is generated if _param1(1) is set to an unaccepted value.
.P
_const(INVALID_OPERATION) is generated if _cmnd(Begin) is executed between a 
_cmnd(Begin)
and the corresponding execution of _cmnd(End).
.P
_const(INVALID_OPERATION) is generated if _cmnd(End) is executed without being
preceded by a _cmnd(Begin).
.P
_const(INVALID_OPERATION) is generated if a command other than
_cmnd(Vertex),
_cmnd(Color),
_cmnd(Index),
_cmnd(Normal),
_cmnd(TexCoord),
_cmnd(EvalCoord),
_cmnd(EvalPoint),
_cmnd(ArrayElement),
_cmnd(Material),
_cmnd(EdgeFlag),
_cmnd(CallList), or
_cmnd(CallLists) is executed between
the execution of _cmnd(Begin) and the corresponding
execution _cmnd(End).
.P
Execution of 
_cmnd(EnableClientState),
_cmnd(DisableClientState),
_cmnd(EdgeFlagPointer),
_cmnd(TexCoordPointer),
_cmnd(ColorPointer),
_cmnd(IndexPointer),
_cmnd(NormalPointer),
.br
_cmnd(VertexPointer),
_cmnd(InterleavedArrays), or
_cmnd(PixelStore) is not allowed after a call to _cmnd(Begin) and before
the corresponding call to _cmnd(End),
but an error may or may not be generated.
.SH SEE ALSO
_cmnd(ArrayElement),
_cmnd(CallList),
_cmnd(CallLists),
_cmnd(Color),
_cmnd(EdgeFlag),
_cmnd(EvalCoord),
.br
_cmnd(EvalPoint),
_cmnd(Index),
_cmnd(Material),
_cmnd(Normal),
_cmnd(TexCoord),
_cmnd(Vertex)