.\"#ident "%W%" %G%
.\"
.\" #
.\" # 
.\" # Permission to use, copy, modify, and distribute this material for
.\" # any purpose and without fee is hereby granted, provided that the
.\" # above copyright notice and this permission notice appear in all
.\" # copies, and that the name of Kubota Graphics not be used in
.\" # advertising or publicity pertaining to this material.  
.\" # 
.\" # KUBOTA GRAPHICS Corporation MAKES NO REPRESENTATIONS ABOUT THE ACCURACY
.\" # OR SUITABILITY OF THIS MATERIAL FOR ANY PURPOSE.  IT IS PROVIDED
.\" # "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING THE
.\" # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" # PURPOSE AND KUBOTA GRAPHICS CORPORATION DISCLAIMS ALL WARRANTIES,
.\" # EXPRESS OR IMPLIED.
.\" #
.\"
.\" Process this file by using the command
.\"             dpx.dieqn FILENAME
.\" which is identical to /techp/bin/dpx, but with the references
.\" to 'eqn' replaced by references to 'dieqn'
.so /usr/local/lib/dpx/macros/local_macros/local.me
.PN 443
.ds BT \\*(Dd Reference Manual
.ds CT \*(Dd Vertex Types
.ds h1 5
.L1 "D" OR\h'5p'\v'-8p'\(aa\v'8p'\h'-5p' "" "\h'-\w'\(aa'u'E 
.L2 V ERTEX
.L3 T YPES
.CH FIVE
.EQ 
delim $$
.EN
.rs
.sp -2v
For most \*(Dd primitives you provide
vertex data when you create an object.
In addition to the vertex locations which define the shape of
the object, you can provide information about vertex normals,
vertex colors, and \f2uv\fP and \f2uvw\fP texture coordinates. 
This additional information is used by \*(Dd for shading and
texture mapping.
.sp -.25v
.lp
Usually all the vertex data is provided in a single array 
and a vertex type parameter specifies which type of information
is supplied for each vertex.
For variable data primitives (\f2DoVar- <DOV->\fP functions)
the vertex information is split up
into several arrays, and the vertex type parameter is not used.
Some primitive objects, such as \f2DoPrimSurf <DOPMS>\fP objects,
do not use vertex data at all.
.sp -.25v
.lp
A vertex type consists of a base vertex
type, optionally combined with a texture coordinate specification.
The following sections discuss these components of the vertex type.
.sp -.5v
.H1 "Base Vertex Type 
.rs
.sp -.25v
All vertex arrays must include at least vertex locations.
The base vertex type specifies whether the array also includes vertex
normals or vertex colors.
The following table lists the possible base values:
.sp .5v
.TS
cp9  s | cp9
cp9 cp9 | lp9.
Value of \f2vertextype\fP	Vertex Information Supplied
_
\f2DcLoc\fP	\f2<DCL>\fP	Only the vertex location
\f2DcLocNrm\fP	\f2<DCLN>\fP	The vertex location and vertex normal 
\f2DcLocClr\fP	\f2<DCLC>\fP	The vertex location and vertex color 
\f2DcLocNrmClr\fP	\f2<DCLNC>\fP	The vertex location, vertex normal, and vertex color	
.TE
.lp
If \f2DcLoc\fP <\f2DCL\fP> is specified, three
floating point values (x, y, z)
must be supplied for each vertex.  
If other vertex information is included in the array, all the
values for a single vertex are stored consecutively in the array.
\f2DcLocNrm\fP <\f2DCLN\fP> and \f2DcLocClr\fP <\f2DCLC\fP>
require three additional values for vertex normals and vertex
colors, respectively.  
(Assuming a color model that
requires three components per vertex.)
\f2DcLocNrmClr\fP <\f2DCLNC\fP>
requires nine floating point values for each vertex, where
the vertex normal triple comes before the vertex color triple
in the array.
Vertex normals \f2must\fP be unit vectors (of length one).
Normals that are not unit vectors produce improper shading.
.sp -.5v
.H1 "Vertex Types that Contain Texture Information
.rs
.sp -.25v
The \*(Dd functions \f2DsTextureUVCount\fP <\f2DSTUVC\fP> and
\f2DsTextureUVWCount\fP <\f2DSTWC\fP> are used in conjunction
with a base vertex type to specify a new vertex type
that includes \f2uv\fP and/or \f2uvw\fP coordinates.
.sp -.25v
.lp
You can obtain the new vertex type by bitwise \f2or\fP'ing
any of the base vertex values with the values
returned from the above named functions.
Both \f2DsTextureUVCount\fP
<\f2DSTUVC\fP> and \f2DsTextureUVWCount\fP <\f2DSTWC\fP> take a
parameter, \f2count\fP, which specifies how many sets of \f2uv\fP
or \f2uvw\fP coordinates are specified for each vertex in the vertex list.
.sp -.25v
.lp
As an example, consider the following vertex type specification
within a \f2DoTriangleList <DOTRIL>\fP function:
.(m
DoTriangleList(DcRGB, DcLocClr | DsTextureUVCount(2), 
		tricnt, vert)

DOTRIL(DCRGB, IOR(DCLC,DSTUVC(2)), TRICNT, VERT)
.)m
In this function, the vertex type specifies that each vertex
is defined by ten real values (DtReal in C, REAL*8 or REAL*4 
in \*(Fo):
.nf

	an ordered triple specifying the vertex position
	an ordered triple specifying the red, green, and blue values
	two ordered pairs specifying \f2uv\fP coordinates

.fi
If the value of \f2tricnt\fP in this example were fifteen, the
array \f2vert\fP would contain ~ 10 ~ times ~ 15 ~ = ~ 150$ values.
.lp
A vertex type may specify both \f2uv\fP and \f2uvw\fP coordinates.
Associated vertex arrays must list \f2uv\fP data before \f2uvw\fP data.
.lp
Other examples of vertex arrays can be found in Chapter 4
of the \f2\*(Dd Programmer's Guide\fP.
