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 gopen 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. Must be greater than or equal to use.

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

rgb Specifies if and where red, green and blue values are contained in each coordinate or if extra parameters are implied to be normals. Allowable values are 0, 1, or 4. 
 
Valid combinations (brackets [] mark optional data; AppDep = application dependent use):
 
 

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), vertices 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. 
 
If order is ORed with UNIT_NORMALS, then all geometric and vertex normal vectors are assumed to be normalized in modelling coordinates. 

Discussion

The coord parameter determines how many extra coordinates Starbase accepts for each vertex in non-integer interface 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).  Vertex format has no effect on intpolyline2d, intpolymarker2d, intpolygon2d, intpartial_polygon2d, intpolycircle, and intpolyrectangle. 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 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. Normals per vertex are only used for filled polygons.

• 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 equal one (1), the color of a polygon vertex is the red, green and blue color triplet located right after the x,y[,z] coordinates and modified by the light source equations.  The color at each pixel is linearly interpolated from the vertex values. 

• With shading on and rgb equal zero (0), the color of a polygon vertex is the fill color modified by the light source equations using the 3 extra coordinates located right after the x,y[,z] coordinates 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. 

• With shading on and rgb equal four (4), the color of a polygon vertex is the red, green and blue color triplet, starting in the fourth value after the z coordinate, modified by the light source equations.  The color at each pixel is linearly interpolated from the vertex values. 

6 If nonzero, the coord parameter must be 6 or greater and either CMAP_MONOTONIC or CMAP_FULL must have been specified with shade_mode. For polylines a red, green, blue, x_normal, y_normal and z_normal value is given for each vertex and the colors are linearly interpolated between vertices.  Note that if use is 6, the first three extra coordinates will always be treated as RGB values for polylines, even if rgb is four (4).  Normals per vertex are only used for filled polygons; they are ignored in polylines. 

• With shading off, polygons use a red, green and blue value per vertex to linearly interpolate the colors in the filled area.  These RGB values are assumed to be the first three extra coordinates. 

• With shading on and rgb equal one (1), the color of a polygon vertex is the red, green and blue color triplet, following the z coordinate value, modified by the light source equations.  The color at each pixel is linearly interpolated from the vertex values and specular highlights are added from the three extra coordinates following the blue color value which are the x,y,z normal to the vertex. 

• With shading on and rgb equal four (4), the color of a polygon vertex is the red, green and blue color triplet, starting at the fourth value after the z coordinate value, modified by the light source equations.  The color at each pixel is linearly interpolated from the vertex values and specular highlights are added from the three extra coordinates following the z coordinate value which are the x,y,z normal to the vertex. 

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

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 backfacing 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 neither 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 backfacing 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 polygon2d, intpolygon2d, partial_polygon2d, intpartial_polygon2d, or partial_polygon3d 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 backfacing 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. 

Providing normalized surface normals within the data and ORing the UNIT_NORMALS flag into the order parameter will cause the Starbase program to execute more quickly, since the normalization calculation will not be required during rendering. A normalized vector is a vector with a length of one unit. 

Spline surface generation is also affected by the current vertex_format. If coord = 3, use = 3, and rgb = 0 (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 for floating point calls (for example, polygon); for calls using DC values (for example, dcpolygon), the values should range from 0 to 32,000. If they are not in the correct range, device-dependent behavior will result. 

Performance is increased when coord is equal to use . 

DEFAULTS

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

SEE ALSO

backface_control(3G), hidden_surface(3G), shade_mode(3G), spline(3G), surface_model(3G), Starbase Graphics Techniques. 

Hewlett-Packard Company  —  HP-UX Release 9.10: April 1995