polyhedron_with_data(3G)
NAME
polyhedron_with_data − defines a series of polygonal regions (facets) to be filled and/or edged. The vertices of each polygonal region are selected by indexing into a shared vertex list.
SYNOPSIS
C Syntax:
void polyhedron_with_data ( fildes, clist, numverts, numcoord,
vertex_flags, ilist, flist, numfacetsets, facet_flags );
int fildes, numverts, numcoord, vertex_flags, numfacetsets,
facet_flags, ilist[];
float clist[], flist[];
FORTRAN77 Syntax:
subroutine polyhedron_with_data ( fildes, clist, numverts,
numcoord, vertex_flags, ilist, flist, numfacetsets, facet_flags )
integer*4 fildes, numverts, numcoord, vertex_flags,
numfacetsets, facet_flags, ilist (*)
real clist ( numverts*( 3+numcoord )) ), flist (*)
Pascal Syntax:
procedure polyhedron_with_data ( fildes: integer;
var clist: array[lo..hi:integer] of real;
numverts, numcoord, vertex_flags: integer;
var ilist: array[lo..hi:integer] of integer;
var flist: array[lo..hi:integer] of real;
numfacetsets, facet_flags: integer );
DESCRIPTION
Input Parameters
fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.
clist Real array containing the vertex data list (coordinate data and optional vertex data).
numverts Number of vertices in the clist array.
numcoord The number of extra coordinates in the vertex data. This includes the data specified in vertex_flags.
vertex_flags Word containing flags indicating contents of clist array. The flags can be bitwise ORed together.
ilist Integer array containing the sets of facet vertex indices lists (and optional move/draw flags).
flist Real array containing the sets of facet data lists (optional facet colors and facet normals).
numfacetsets Number of facet sets defined in the ilist and flist arrays.
facet_flags Word containing flags indicating contents of ilist and flist arrays. The flags can be bitwise ORed together.
The following table describes the vertex flags which can be ORed together, their expected order, and indicates (YES) for flags that are utilized, (OK) for flags that may be present but are ignored, and (NO) for flags that must not be present (error condition):
| Vertex Flag | Description | |
| NULL | None of the extra data is to be used for rendering | YES |
| VERTEX_INTENSITY | A single intensity value | YES |
| VERTEX_COLOR | An (r, g, b) triple at the vertex | YES |
| VERTEX_NORMAL | An (nx, ny, nz) normal at the vertex | YES |
| TEXTURE_MAP | A coordinate (u, v) into a texture map | YES |
| VERTEX_BLEND | A blending factor for combination with existing pixels | YES |
| ILLUMINATION | Illumination factors for each light source | YES |
| DEFORMATION | Complex deformation factors for each axis | YES |
| CONTOURING | Front- and back-facing scalar contouring values per vertex | YES |
| MD_FLAGS | A move/draw flag | YES |
The following table describes the facet flags which can be ORed together, their expected order, and indicates (YES) for flags that are utilized, (OK) for flags that may be present but are ignored, and (NO) for flags that must not be present (error condition):
| Facet Flag | Description | |
| NULL | No facet flags are provided | YES |
| FACET_COLOR | RGB color triad is supplied in flist for each facet | YES |
| FACET_NORMAL | Normal vector supplied in flist for each facet | YES |
| EDGE_FLAG | Edge visibility flag | YES |
| CLOCKWISE | Facet vertices arranged clockwise format (front-face) | YES |
| COUNTER_CLOCKWISE | Facet vertices arranged in counter clockwise format | YES |
| UNIT_NORMALS | Vertex and facet normal vectors are normalized | YES |
Discussion
This primitive provides a method to specify a set of polygons (or facets) using shared vertex data. Despite the name of this primitive, the facets need not form a closed surface.
The vertex data list, clist, is an array containing vertex definitions. Each vertex definition consists of X, Y, Z coordinates and, optionally, vertex intensity, texture map coordinates, vertex color, vertex normal data, vertex blending factor, deformation, contouring and application-dependent data. Unlike the polygon calls, this vertex data does not include support for move/draw flags.
Move/draw flags can be supplied as part of the facet vertex indices lists (ilist). The presence of these optional data is determined by the status of vertex_flags.
All of the vertex_flags flags may be specified alone or in any combination, except VERTEX_COLOR ORed with VERTEX_INTENSITY.
ILLUMINATION specifies that data is present containing 4-bit illumination factors for light sources. As a default, there are two words of data which allows for factors for 16 light sources. The amount of data used for illumination may be changed via the ILLUMINATION_ENABLE gescape. Each of these factors has a range of 0 (0%) to 15 (100%) and indicate the amount of light directly available or indirectly available from each light source. The four least significant bits of the first word contains the factor for light source zero, the next four bits the factor for light source one, and so on. The four least significant bits of the second word contains the factor for light source eight, the next four bits the factor for light source nine and so on. These factors are used to generate soft shadows.
DEFORMATION specifies that complex deformation values are present. Whether to use the real or imaginary portion of the deformation factor/deformation values product and the deformation factor (df + dfi below) are specified in the deformation_mode procedure. The per vertex deformation values are in the following order: fx, fy, fz, fxi, fyi, fzi. Prior to processing the polygon all of the vertices are deformed by the following calculations:
x = x + (df + dfi) × (fx + fxi)
y = y + (df + dfi) × (fy + fyi)
z = z + (df + dfi) × (fz + fzi)
CONTOURING specifies that two floating point scalar values per vertex are present. The first scalar value is used for contouring front-facing facets and the second scalar value is used for contouring back-facing facets. If contouring is enabled via contour_enable, each scalar value is mapped to an RGB value through use of the contour table defined with define_contour_table. Contouring is supported for triangular or quadrilateral facets using the polyhedron_with_data primitive. Triangular or quadrilateral facets are rendered with: contoured lines if CONTOUR_LINE contouring is specified through contour_enable, with solid contoured bands if CONTOUR_SOLID contouring is specified, or with shaded contoured bands if CONTOUR_SHADED contouring is enabled. Move/draw flags can be included per vertex index in each facet if EDGE_FLAG is specified. In this way, complex contoured polygonal images can be constructed by using polyhedron_with_data and specifying which edges should be drawn. When facets are contoured, the current interior style is superseded by the contour. The VERTEX_INTENSITY, VERTEX_COLOR, and TEXTURE_MAP vertex data are ignored when contouring. Likewise, FACET_COLOR facet data is ignored when contouring. Facets consisting of more than four vertices will be rendered in the current interior style without contouring.
The sequence of these data types are fixed. The expected sequence is in the same order as the vertex_flags are listed above. Any additional application-dependent data is assumed to be last and is specified by providing a value of numcoord greater than the number of coordinates used by the data types specified in vertex_flags. The value numcoord specifies the total number of optional coordinates for each vertex (the number of coordinates beyond the standard X, Y, and Z). The maximum number of vertices supported is device-dependent.
As an example, if a vertex_flags of TEXTURE_MAP | VERTEX_BLEND is specified, and numcoord is set to 6, then x, y, z, u, v, blend, ad, ad, ad would be the composition of each vertex, where ad indicates Application-Dependent data not used for rendering.
This list of vertices is implicitly indexed from 0 to numverts-1. These vertices are referenced by index in the facet vertex lists.
The facet vertex indices list, ilist, is an array containing sets of facet definitions in the form of lists of vertices indexed into clist. Each set of facet definitions consists of a number of facets count followed by the facet definitions. Each facet definition consists of a vertex count, a list of vertex indices and, optionally, edge move/draw flags (with each vertex index). The use of edge flags is determined by the presence of EDGE_FLAG in facet_flags. The format of ilist is shown in the table below.
NOTE: This routine (polyhedron_with_data) has a unique fill algorithm. All facets in any given facet set are filled as if they are located in the same X-Y plane. This can be used to create holes in the object, similar to those create by partial_polygon_with_data3d by making a facet set containing a facet and the hole in that facet. To fill all surfaces according to their X, Y, and Z values, set each numfacets(n) = 1, which makes every facet into its own facet set.
cbp10 s cb |cb cb |cb l l. facet_flags in ilist data format _ _
The sense of the CLOCKWISE/COUNTER_CLOCKWISE direction of facet vertices is determined by the presence of the CLOCKWISE or COUNTER_CLOCKWISE flag in facet_flags. If neither flag is present, the facet vertices are assumed clockwise. (If both flags are present, the vertices will be assumed counter clockwise).
Each list of vertex indices forms a facet. A boundary of a facet (polygonal region) is defined by connecting each indexed vertex to its successor in the vertex list. If the last vertex indexed does not close the facet (i.e., is not the same vertex as the first vertex indexed), a boundary is added between the first and last vertices. Whether an edge is drawn on this boundary is determined by the move/draw flag associated with the last vertex (if present) and the current interior style.
There is no limit to the number of facet sets you can have, or the number of vertices per facet. The only requirement for facets within a single facet set is that they all must be coplanar.
Each facet is filled and/or outlined according to current interior style, fill color and perimeter attributes. As with all output primitives, it is affected by the current drawing mode and write enable.
If move/draw flags are present, each vertex index is followed by a move/draw flag. Each move/draw flag applies to the edge between the vertex it follows and the previous vertex. Each facet edge can be either a drawn boundary or a non-drawn boundary, depending on the value of the corresponding move/draw flag and whether or not interior_style is set to be edged. If the indicator is non-zero (draw) and interior_style is set to edged, the boundary is drawn. Otherwise, it is not drawn. Non-drawn boundaries simply define the edges of the filled area.
The facet data list, flist, is an array containing optional facet data. Each facet definition can include a facet color or facet color index, and a facet normal. The presence of this optional data is determined by the status of facet_flags. The sequence of these data types is fixed. The format of flist is as shown in the table below. If none of the these optional data are present, then the flist value may be null.
| FACET_FLAGS in flist data format | ||
| FACET_COLOR | FACET_NORMAL | FACET_NORMAL |
| r(1, 1) | nx(1, 1) | r(1, 1) |
| g(1, 1) | ny(1, 1) | g(1, 1) |
| b(1, 1) | nz(1, 1) | b(1, 1) |
| r(1, 2) | nx(1, 2) | nx(1, 1) |
| g(1, 2) | ny(1, 2) | ny(1, 1) |
| b(1, 2) | nz(1, 2) | nz(1, 1) |
| . | . | . |
| . | . | . |
| r(1, numfacets(1)) | nx(1, numfacets(1)) | r(1, numfacets(1)) |
| g(1, numfacets(1)) | ny(1, numfacets(1)) | g(1, numfacets(1)) |
| b(1, numfacets(1)) | nz(1, numfacets(1)) | b(1, numfacets(1)) |
| . | . | . |
| . | . | . |
| r(2, 1) | nx(2, 1) | r(2, 1) |
| g(2, 1) | ny(2, 1) | g(2, 1) |
| b(2, 1) | nz(2, 1) | b(2, 1) |
| r(2, 2) | nx(2, 2) | nx(2, 1) |
| g(2, 2) | ny(2, 2) | ny(2, 1) |
| b(2, 2) | nz(2, 2) | nz(2, 1) |
| . | . | . |
| . | . | . |
| r(N, numfacets(N)) | nx(N, numfacets(N)) | r(N, numfacets(N)) |
| g(N, numfacets(N)) | ny(N, numfacets(N)) | g(N, numfacets(N)) |
| b(N, numfacets(N)) | nz(N, numfacets(N)) | b(N, numfacets(N)) |
Where N is the value of numfacetsets (the number of facet sets).
If facet_flags includes FACET_COLOR, then an RGB color specification is expected in the facet data (as shown above). The fill color will be set to the specified color prior to drawing each facet. The effect of this is identical to calling fill_color prior to drawing a discrete polygon.
If facet_flags includes FACET_NORMAL, then a normal specification is expected in the facet data for each facet (as shown below). These normals will be used for back-face cull computations and light source equations (if normals per vertex are not supplied).
If facet_flags is ORed with UNIT_NORMALS then facet normals (and any vertex normals) will be assumed to be normalized to a magnitude of 1.0 in model coordinates. Providing normalized surface normals within the data (and using this flag) will cause the Starbase program to execute more quickly, since the normalization calculation will not be required during rendering.
For performance reasons, color data in vertex and facet lists and blend data in the vertex list are not checked for validity. If the color and blend values are not in the expected ranges, device-dependent behavior will result.
SEE ALSO
define_texture(3G), deformation_mode(3G), drawing_mode(3G), fill_color(3G), interior_style(3G), perimeter_color(3G), perimeter_repeat_length(3G), perimeter_type(3G), polygon(3G), texture_index(3G), texture_viewport(3G), texture_window(3G), write_enable(3G).
Hewlett-Packard Company — November 03, 1994