kgeom_primitive *
kgeom_new_primitive(int type)
none
A geometry primitive contains geometric data which
describes a shape in space. Lines, triangles, and
spheres, are all considered to be geometric
primitives. Each "type" of primitive is actually
represented by a distinct structure; these structures
have been unioned into a common
kgeom_primitive
structure.
The type of primitive is declared on instantiation, as in this example :
kgeom_primitive *prim;
prim = kgeom_new_primitive(KGEOM_POLYLINE_CONNECTED);
The type of primitive is tracked in a type field
which is common to all the primitive structures. It
can always be accessed as prim->type
from any
primitive structure.
For a complete description of all the types of geometry primitives, see the kgeom_primitive man page, or consult the Data Services Manual : Programming Services Volume II
Note that a geometry primitive is not limited to a single instance of a shape. For example, a single spheres primitive can contain many spheres and a single polyline primitive can contain many lines.
The data within a primitive consists of several components; the predominate component which actually defines the size and position of the geometry is the location data. The location data consists of a list of vertices. The number of these vertices is a specified by a field within the primitive and is a defining characteristic for most geometry primitives.
Additional components which may be present in a geometry primitive are color, normals, or texture coordinates. All components except for the location component are optional in any given geometry primitive.
Most the fields of a geometry primitive are pointers to allocated arrays which contain these components. The size of these arrays is implied from the number of vertices present in the geometry primitive, and the presentation characteristics (layout, location_dim, texture_coord_dim, and has_alpha) set in the associated geometry object. Most data within a geometry primitive will be floating point.
Geometric data is always stored "elements first", with the vectors forming the leading dimension of the array. For example, 3D location vertices will be stored in the order XYZXYZXYZ...
The number of location vertices is by definition the number of vertices in the primitive. The size of each vertex will be determined by the location_dim field of the associated object.
The number of color and normal vectors will be a function of the number of vertices, but will vary depending on the primitive and the layout field of associated geometry object. For example, a disjoint polyline primitive will have 1 color per vertex for a KPER_VERTEX layout, but will have 1 color per line for a KPER_LINE primitive.
The size of each color vector will either be 3 (for RGB), of 4 (for RGBa) if the has_alpha field of the associated object is TRUE. The size of each normal vector will match the size of location_dim field in the associated object.
If texture coordinate vectors are present, the number of texture coordinates must match the number of vertices in the primitive. The size of each texture coordinate will be determined by the texture_coord_dim field of the associated object.
If the modeling_space field of the associated object is set to KNDC_SPACE, the location data will be interpreted as normalized device coordinates and thus should range between 0.0 and 1.0.
Color data is represented by RGB vectors with three floats determining the red, green, and blue intensity. These numbers should range from 0.0 to 1.0, with 1.0 implying maximum intensity. If an alpha component is present it will determine the transparency of the primitive. It also should range from 0.0 to 1.0, with 0.0 implying that the primitive is totally transparent, and 1.0 implying that the primitive is totally opaque.
Since the fields of a geometry primitive vary from type to type, we must specify the type of primitive we are working with in order to access the components of the primitive structure. For example, if we had a spheres primitive, we would have to do the following to access the specific sphere fields :
kgeom_primitive *prim;
prim = kgeom_new_primitive(KGEOM_SPHERES);
// specify that we want 45 spheres
prim->spheres.nverts = 45;
This can alternatively be done by casting the structure to its specific primitive type as follows :
kgeom_spheres *s;
s = (kgeom_spheres *) kgeom_new_primitive(KGEOM_SPHERES);
// specify that we want 45 spheres
s->nverts = 45;
Primitives can be cast to any type at any time, but
you should be sure that you cast back to the general
kgeom_primitive *
type before passing a
specific primitive into any functions which take a
primitive argument.
none
none
$DATASERV/objects/library/kgeom/src/primitive.c