polyline(3G)

NAME

dcpolyline, intpolyline2d, polyline2d, polyline3d, polyline_with_data3d − move/draw between specified points

SYNOPSIS

C Syntax:

void dcpolyline(fildes,clist,numpts,flags);
int fildes,numpts,flags,clist[];

void intpolyline2d(fildes,clist,numpts,flags);
int fildes,numpts,flags,clist[];

void polyline2d(fildes,clist,numpts,flags);
int fildes,numpts,flags;
float clist[];

void polyline3d(fildes,clist,numpts,flags);
int fildes,numpts,flags;
float clist[];

void polyline_with_data3d(fildes,clist,numpts,numcoord,
vertex_flags);
int fildes,numpts,numcoord,vertex_flags;
float clist[];

FORTRAN77 Syntax:

subroutine dcpolyline(fildes,clist,numpts,flags)
integer*4 fildes,numpts,flags,clist(numpts*(2+flags))

subroutine intpolyline2d(fildes,clist,numpts,flags)
integer*4 fildes,numpts,flags,clist(numpts*(2+flags))

subroutine polyline2d(fildes,clist,numpts,flags)
integer*4 fildes,numpts,flags
real clist(numpts*(2+flags))

subroutine polyline3d(fildes,clist,numpts,flags)
integer*4 fildes,numpts,flags
real clist(numpts*(3+flags))

subroutine polyline_with_data3d(fildes,clist,numpts,numcoord,
vertex_flags)
integer*4 fildes,numpts,numcoord,vertex_flags
real clist(numpts*(3+flags))

Pascal Syntax:

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

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

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

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

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

DESCRIPTION

Input Parameters

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

clist Array of virtual device coordinate data, modelling coordinate data, or world coordinate data used by polyline2d, intpolyline2d, and polyline3d or device coordinate data used by dcpolyline. This data may contain extra coordinates and move/draw indicators embedded after each endpoint.

numpts Defines the number of endpoints in the clist array. If numpts is less than zero, zero is substituted. A numpts greater than 32767 is not allowed.

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

flags If set to FALSE (0), the first endpoint represents a move and subsequent endpoints represent draws.
If set to TRUE (1), the move/draw indicators define whether a move or draw is performed for the corresponding endpoints. For each endpoint, if the corresponding move/draw indicator is non-zero (draw), a line is drawn from the current position to the endpoint. Otherwise, the current position is simply updated to the position of the endpoint. vertex_flags describes the definition of the vertex data.

Discussion

Polyline draws a series of line segments in the current line_color and line_type. A color can be specified for each endpoint, and the specified color can override line_color (see vertex_format for details). As with all output primitives, polyline is affected by the current drawing_mode and write_enable.

The line type pattern is continuous throughout a polyline.

Each entry in the clist can contain any number of coordinates. The actual number depends on the coord parameter specified in vertex_format . 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. ( vertex_format does not apply to intpolyline2d .) The following shows 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)

The world-coordinate current pen position is not related to the device current pen position. When mixing the use of these coordinate systems, always make a move to a known pen position before executing a draw procedure.

The polyline_with_data3d procedure is similar to the polyline3d except that the vertex data format is specified in the procedure and is not derived from the vertex_format procedure.

For polyline_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 meaning of the inclusive OR parameters and the expected order of the data is:
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	No 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	OK
VERTEX_BLEND	Blending factor for combining with existing pixels	OK
ILLUMINATION	Illumination factors for each light source	OK
DEFORMATION	Complex deformation factors for each axis	YES
CONTOURING	Front/back facing scalar contouring values per vertex	NO
MD_FLAGS	A move/draw flag	YES

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, fxi, fy, fyi, fz, 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)W

All extra parameters may be ignored by some devices.

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.

For increased performance of small polylines (numpts < 10) macros can be used to generate in-line code for C. See "Polyline Macros" in Starbase Graphics Techniques − HP-UX Concepts and Tutorials.

Museum

Related Articles