VERTEX_FORMAT(3G)

NAME

vertex_format − set vertex list format for polygons and polylines

SYNOPSIS

C Syntax:

void vertex_format(fildes,coord,use,rgb,normals,order);
int fildes,coord,use,rgb,normals,order;

FORTRAN77 Syntax:

subroutine vertex_format(fildes,coord,use,rgb,normals,order)
integer *4 fildes,coord,use,rgb,normals,order

Pascal Syntax:

procedure vertex_format(fildes,coord,use,rgb,normals,order:integer);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by open when an I/O path to a graphics device is opened.

coord Set the number of extra coordinates supplied with each polygon, polyline and polymarker vertex.

use Sets the number of extra coordinates to be used for color determination. Allowable values are 0, 1 or 3.

rgb If TRUE (1) and coord is 3, the extra coordinates are interpreted as red, green, and blue values. Otherwise, the extra coordinates are interpreted as the x, y, z normal to that polygon vertex.

normals If TRUE (1), it is assumed that the first entry in the vertex list of each polygon3d call is a normal to that polygon.

order If order is CLOCKWISE (0), polygon vertices are assumed to be arranged in a clockwise format.
If order is COUNTER_CLOCKWISE (1), they are assumed to be counter-clockwise.
The clockwise/counter-clockwise direction is defined in terms of viewing from the outside of the object, looking in from a left-handed coordinate system.

Discussion

The coord parameter determines how many extra coordinates Starbase accepts for each vertex in polyline, polymarker, polygon, and partial_polygon procedures (extra coordinates are those coordinates that are in addition to x/y, x/y/z, x/y/flag, or x/y/z/flag). Setting coord to a value larger than use provides a means for placing application-dependent data or color-determining data in the vertex list.

By setting use to:

0 All extra coordinates are ignored. Polylines are drawn in the current line color.

• With shading off, polygons are filled with the current fill color.

• With shading on, polygons are filled with the current fill color modified by the light source equations given in surface_model. This value produces constant (sometimes called faceted) shading.

1 The coord parameter must be 1 or greater and either CMAP_MONOTONIC or CMAP_FULL must have been specified in shade_mode. For polylines, an intensity is given for each vertex, and the intensity times the line color is linearly interpolated between vertices.

• With shading off, polygons use an intensity value per vertex to linearly interpolate the intensity times the fill color in the filled area.

• With shading on, the color of a polygon vertex is fill color multiplied by the intensity value which is then modified by the light source equations. The color at each pixel is linearly interpolated from the vertex values.

3 If nonzero, the coord parameter must be 3 or greater and either CMAP_MONOTONIC or CMAP_FULL must have been specified with shade_mode. For polylines a red, green, and blue value is given for each vertex and the colors are linearly interpolated between vertices. Note that if use is 3, the extra coordinates will always be treated as RGB values for polylines, even if rgb is FALSE. Normals per vertex are only used for filled polygons.

If the coord parameter is nonzero, move/draw flags in the vertex data are found after all extra coordinates (used and not used).

• With shading off, polygons use a red, green and blue value per vertex to linearly interpolate the colors in the filled area.

• With shading on and rgb TRUE (1), the color of a polygon vertex is the red, green and blue color triplet modified by the light source equations. The color at each pixel is linearly interpolated from the vertex values.

• With shading on and rgb FALSE (0), the color of a polygon vertex is the fill color modified by the light source equations using the 3 extra coordinates supplied as the x, y, z normal to the vertex. The color at each pixel is linearly interpolated from the vertex values to produce smooth (Gouraud) shading.

Note that the color determinations described above for polygons apply only to the fill colors used. Polygon edges are always drawn using the current perimeter color.

When normals is FALSE (0), the light source equations either generate a normal to the polygon (by taking the cross product of the two vectors described by the first 3 vertices of a polygon list of vertices) or use the normals supplied with each vertex. If back-facing cull is on then a normal will always be generated. Note that since the normal is calculated using the first three polygon vertices, the vertices must not be colinear nor very close to each other. Also, the calculated normal may lead to unusual results if the vertices form a concave section of the polygon or if the polygon is non-planar. During partial polygon calls, the normal calculations use the first three vertices of the first partial polygon. There must be at least three vertices in the first partial/full polygon or the calculations will be incorrect.

When normals is TRUE (1), the light source equations will either use the normal supplied at the beginning of each call to polygon3d or use the normal-per-vertex if supplied. If back-facing cull is on, the normal supplied at the beginning of the polygon is used to determine whether to render the polygon.

Normals only occur in the vertex list of polygon3d calls. They are not expected in partial_polygon3d, partial_polygon2d, or polygon2d calls.

The order parameter is needed when polygon normals are generated. If an object is made of polygons, the vertices of all the polygons must be given in either a clockwise or counter-clockwise direction in order for light sources and back-facing cull to work correctly.

When using a right-handed coordinate system, the sense of CLOCKWISE and COUNTER_CLOCKWISE are reversed, meaning that direction is determined from the inside of an object looking out. A right-handed coordinate system is obtainable by pushing an identity matrix onto the matrix stack with the z-scale term set to −1. Spline surface generation is also affected by the current vertex_format. If coord = 3, use = 3, and rgb = FALSE (normals per vertex), spline surface generation produces normals per vertex with smooth (Gouraud) shading. In all other cases, constant (or faceted) shading is used for spline surfaces. Spline surfaces also use the current interior_style which must be set to INT_SOLID before any shading can occur.

For performance reasons, rgb data in vertex lists is not checked for validity. These values should range from 0.0 to 1.0. If they are not in this range, device-dependent behavior will result.

DEFAULTS

coord = 0, use = 0, rgb = TRUE (1), normals = FALSE (0), order = COUNTER_CLOCKWISE (1).

Museum

Related Articles