NAME

dcpartial_polygon, dcpolygon, intpartial_polygon2d, intpolygon2d, partial_polygon2d, partial_polygon3d, polygon2d, polygon3d, partial_polygon_with_data3d, polygon_with_data3d − defines a polygonal region to be filled and/or edged, or defines a group of polygon vertices that begins as subpolygon or non-edged boundary. 

SYNOPSIS

C Syntax:

void dcpartial_polygon(fildes,clist,numverts,flags,closure);
int fildes,numverts,flags,closure,clist[];

void dcpolygon(fildes,clist,numverts,flags);
int fildes,numverts,flags;
int clist[];

void intpartial_polygon2d(fildes,clist,numverts,flags,closure);
int fildes,numverts,flags,closure,clist[];

void intpolygon2d(fildes,clist,numverts,flags);
int fildes,numverts,flags,clist[];

void partial_polygon2d(fildes,clist,numverts,flags,closure);
int fildes,numverts,flags,closure;
float clist[];

void partial_polygon3d(fildes,clist,numverts,flags,closure);
int fildes, numverts,flags,closure;
float clist[];

void polygon2d(fildes,clist,numverts,flags);
int fildes,numverts,flags;
float clist[];

void polygon3d(fildes,clist,numverts,flags);
int fildes,numverts,flags;
float clist[];

void partial_polygon_with_data3d(fildes,clist,numverts,numcoord,vertex_flags,
facet_flags,closure);
int fildes, numverts,numcoord,vertex_flags,facet_flags,closure;
float clist[];

void polygon_with_data3d(fildes,clist,numverts,numcoord,vertex_flags,
facet_flags);
int fildes,numverts,numcoord,vertex_flags,facet_flags;
float clist[];

FORTRAN77 Syntax:

subroutine dcpartial_polygon(fildes,clist,numverts,flags,closure)
integer*4 fildes,numverts,flags,closure
integer*4 clist(numverts*(2+flags))

subroutine dcpolygon(fildes,clist,numverts,flags)
integer*4 fildes,numverts,flags
integer*4 clist(numverts*(2+flags))

subroutine intpartial_polygon2d(fildes,clist,numverts,flags,closure)
integer*4 fildes,numverts,flags,closure,clist(numverts*(2+flags))

subroutine intpolygon2d(fildes,clist,numverts,flags)
integer*4 fildes,numverts,flags,clist(numverts*(2+flags))

subroutine partial_polygon2d(fildes,clist,numverts,flags,closure)
integer*4 fildes,numverts,flags,closure
real clist(numverts*(2+flags))

subroutine partial_polygon3d(fildes,clist,numverts,flags,closure)
integer*4 fildes,numverts,flags,closure
real clist(numverts*(3+flags))

subroutine polygon2d(fildes,clist,numverts,flags)
integer*4 fildes,numverts,flags
real clist(numverts*(2+flags))

subroutine polygon3d(fildes,clist,numverts,flags)
integer*4 fildes,numverts,flags
real clist(numverts*(3+flags))

subroutine partial_polygon_with_data3d(fildes,clist,numverts,numcoord,
vertex_flags,facet_flags,closure)
integer*4 fildes,numverts,numcoord,vertex_flags,facet_flags,closure
real clist(numverts*(3+numcoord))

subroutine polygon_with_data3d(fildes,clist,numverts,numcoord,vertex_flags,
facet_flags)
integer*4 fildes,numverts,numcoord,vertex_flags,facet_flags
real clist(numverts*(3+numcoord))

Pascal Syntax:

procedure dcpartial_polygon(fildes:integer; var clist:array[lo..hi:integer] of integer; numverts,flags,closure:integer);

procedure dcpolygon(fildes:integer; var clist:array[lo..hi:integer] of integer; numverts,flags:integer);

procedure intpartial_polygon2d(fildes:integer; var clist:array[lo..hi:integer] of integer; numverts,flags,closure:integer);

procedure intpolygon2d(fildes:integer; var clist:array[lo..hi:integer] of integer; numverts,flags:integer);

procedure partial_polygon2d(fildes:integer; var clist:array[lo..hi:integer] of real; numverts,flags,closure:integer);

procedure partial_polygon3d(fildes:integer; var clist:array[lo..hi:integer] of real; numverts,flags,closure:integer);

procedure polygon2d(fildes:integer; var clist:array[lo..hi:integer] of real; numverts,flags:integer);

procedure polygon3d(fildes:integer; var clist:array[lo..hi:integer] of real; numverts,flags:integer);

procedure partial_polygon_with_data3d(fildes:integer; var clist:array[lo..hi:integer] of real; numverts,numcoord,vertex_flags,facet_flags,closure:integer);

procedure polygon_with_data3d(fildes:integer; var clist:array[lo..hi:integer] of real; numverts,numcoord,vertex_flags,facet_flags:integer);

DESCRIPTION

Input Parameters

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

flags polygon: If set to FALSE (0), all edges are drawn if interior_style is set to be edged. 

partial_polygon: If FALSE (0), the first vertex represents a non-drawn boundary.  The remaining vertices represent drawn boundaries if interior_style is set to be edged. 

polygon and partial_polygon: If set to TRUE (1), each polygon edge can be either a drawn boundary or a non-drawn boundary, depending on the value of the corresponding move/draw indicator 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. 

clist Array of real or integer data with or without additional data and/or move/draw indicators embedded after each endpoint. 

numverts Number of polygon vertices in the clist array. If the value is less than zero, zero is substituted. 

numcoord the number of extra coordinates in the vertex data. This includes the data specified in vertex_flags. 

vertex_flags describes the definition of the vertex data. 

facet_flags describes the format of the polygon. 

closure partial_polygon: If TRUE (1), the polygon vertex list is non-empty, and the last subpolygon is not yet closed, a boundary is added to close that subpolygon within the boundary.  If the first polygon vertex in the partial polygon had a draw indicator, the closure boundary is drawn.  Otherwise, it is not drawn.  Partial_polygon then adds the vertices in clist to the polygon vertex list. 

Discussion

A boundary of a polygonal region is defined by connecting each vertex to its successor in the vertex list.  The polygon 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. 

Move/draw indicators occupy the same space as one coordinate (a single 32-bit value), and are interspersed with the coordinate data.  For polygon2d, partial_polygon2d, intpolygon2d, intpartial_polygon2d, dcpartial_polygon and dcpolygon each (x,y) pair of coordinates is followed by a move/draw indicator if flags is TRUE(1).  For polygon3d and partial_polygon3d each (x,y,z) triplet is followed by a move/draw indicator if flags is TRUE(1). 

Partial_polygon puts polygon vertices into an internal polygon data structure.  Only after a call is made to polygon, circle, polycircle, arc, ellipse, rectangle, or polyrectangle will the polygon be rendered.  Partial_polygon is most commonly used to create "holes" in polygons. 

Each entry in the clist can contain any number of coordinates.  The actual number depends on the coord parameter specified in vertex_format if using device coordinates or floating point coordinates.  vertex_format does not apply to intpolygon2d or intpartial_polygon2d .  The coord parameter can be used to skip over any extra coordinates following the usual 2, 3, or 4 that can be specified with this procedure.  Vertex move/draw flags follow the skipped extra coordinates. 

The use parameter specified in vertex_format determines whether any of the extra parameters are used to determine the color of the primitive.  The following list shows in what order the data is expected.  Any extra coordinates are skipped. 

use=0 For 2d,dc: x,y,...,(flag)
For 3d: x,y,z,...,(flag)

use=1 For 2d,dc: x,y,i,...,(flag)
For 3d: x,y,z,i,...,(flag)

use=3 For 2d,dc: x,y,a,b,c,...,(flag)
For 3d: x,y,z,a,b,c,...,(flag)

All extra parameters are ignored by some devices. 

Upon entry, the polygon vertex list is added to, not cleared.  The polygon list is then processed by filling all vertices in the list, and cleared upon exit.  The flag at the beginning (i.e., the first entry) of the clist for partial_polygon is used to create sub-polygons. 

The current position is updated to the first vertex in the first partial_polygon/polygon upon completion of the polygon. 

If per-polygon normal is set in vertex_format, the first vertex in polygon3d is used as a normal to that polygon, and the number of vertices in the clist should be numverts + 1.  The normal must contain the same number of coordinates as every other vertex (extra coordinates are ignored). 

If normals per polygon is specified in vertex_format, the normal is contained in the polygon vertex list; not in the partial_polygon list.  If a normal needs to be calculated, the first 3 points of the first partial_polygon are used.  The vertex list for the first partial polygon must contain at least 3 points or the normal cannot be calculated correctly. 

Integer operations are only available when using the INT_XFORM gopen mode. When in INT_XFORM mode, floating point operations are not available for that fildes. Floating point operations are the default, or can be specified with FLOAT_XFORM mode. For a list of integer operations, floating point operations and common operations see the starbase.3g manual page. 
The polygon_with_data3d and partial_polygon_with_data3d procedures are similar to the corresponding polygon3d and partial_polygon3d procedures except that the vertex data format is specified in the procedure and is not derived from the vertex_format procedure. 

For partial_polygon_with_data3d and polygon_with_data3d , each entry in the clist can contain any number of coordinates.  The actual number depends on the numcoord parameter.  How the additional data is to be used is specified with the vertex_flags parameter.  The additional data starts after the z coordinate and is assumed to be omitted if not specified. 
 
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):
 

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 gescape ILLUMINATION_BLEND.  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 backfacing facets.  If contouring is enabled via contour_enable, each scalar value is mapped to an r,g,b value through use of the contour table defined with define_contour_table.  Contouring is only supported for triangular or quadrilateral facets using the polyhedron_with_data or the polygon_with_data3d 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 if MD_FLAGS is specified.  In this way, complex contoured polygonal images can be constructed by using these primitives 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.  Facets consisting of more than four vertices will be rendered in the current interior style without contouring. 

All of the values may be specified alone and they may all be bitwise ORed in any combination except that VERTEX_INTENSITY and VERTEX_COLOR may not be present together.  If they are present together the procedure will generate an error and exit.  Additional data is assumed to be before the MD_FLAGS data if specified.  If the numcoord parameter specifies less data than is specified with the vertex_flags parameter, then an error is generated and the procedure exits. 

As an example, if a vertex_flags of TEXTURE_MAP | VERTEX_BLEND | MD_FLAGS is specified, and numcoord is set to 6, then x,y,z,u,v,blend,ad,ad,flag would be the composition of each vertex, where ad = application dependent data not used for rendering. 

The format of the polygon and additional data is specified by the facet_flags parameter. 

 
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):
 

 
The * indicates that both FACET_COLOR and FACET_NORMAL cannot be present
 
The clockwise/counter_clockwise direction of facet vertices is determined by the presence of the CLOCKWISE or COUNTER_CLOCKWISE flag[s].  If neither flag is present, the facet vertices are assumed clockwise.  (If both flags are present, the vertices are assumed to be counter clockwise).

If FACET_NORMAL is set in facet_flags the first vertex in polygon_with_data3d is used as a normal to that polygon, and the number of vertices in the clist should be numverts + 1.  The normal must contain the same number of coordinates as every other vertex (extra coordinates are ignored).  Facet normals are not contained in the partial_polygon_with_data3d clist. 

NOTE

Any Starbase call other than intpartial_polygon2d, intpartial_arc, intpartial_circle, partial_polygon2d, partial_polygon3d, partial_arc, partial_ellipse, or dcpartial_polygon, in the middle of a list of these procedure calls and before a call to arc, circle, polycircle, ellipse, polygon, rectangle, or polycircle produces unpredictable, device-dependent results. 

SEE ALSO

drawing_mode(3G),

contour_enable(3G), drawing_mode(3G), define_contour_table(3G), define_texture(3G), deformation_mod(3G), fill_color(3G), interior_style(3G), perimeter_color(3G), perimeter_repeat_length(3G), perimeter_type(3G), texture_index(3G), write_enable(3G), vertex_format(3G). 

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