NAME

POLYLINE SET 3 WITH DATA - creates a 3D polyline set structure element that includes colour and shading data

SYNOPSIS

C Syntax

void

ppolyline_set3_data ( vflag, colr_type, npl, vdata )

Pint                vflag;        data per vertex flag
Pint                colr_type;   colour type
Pint                npl;         number of polylines in the set
Pline_vdata_list3   * vdata;     per line vertex data list

FORTRAN Syntax

SUBROUTINE pplsd3 ( VFLAG, COLTYP, NPL, PLARR, NV, COORDS, IVCOLR, VCOLR, IMPL )

INTEGER      VFLAG              data per vertex flag
INTEGER      COLTYP             colour type
INTEGER      NPL                number of point lists
INTEGER      PLARR(NPL)         array of end indices for point lists
INTEGER      NV                 number of vertices
REAL         COORDS(3,NV)       array of vertex coordinates
INTEGER      IVCOLR(NV)         array of indirect vertex colours
REAL         VCOLR(3,NV)        array of vertex colours
REAL         IMPL(* )           implementation defined vertex data

Required PHIGS Operating States

(PHOP, * ,STOP, * )

DESCRIPTION

Purpose

POLYLINE SET 3 WITH DATA creates a 3D polyline set primitive with colour and shading data.

A 3D polyline with data primitive is a set of connected lines in a 3D space defined by a series of Modeling Coordinate (MC) points. The element can optionally specify colour information for each vertex of the primitive.

This is a SunPHIGS Extension function based on PHIGS PLUS and is not part of the PHIGS standard.

C Input Parameters

vflag

The data per vertex flag specifies the available data for each vertex of the primitive.

0   PVERT_COORD              Coordinates Specified
1   PVERT_COORD_COLOUR       Coordinates and Colours Specified

colr_type

The colour type for specified vertex colours.

0   PINDIRECT         Indirect
1   PMODEL_RGB        Red, Green, and Blue

                2   PMODEL_CIELUV     CIE Colour Model
                3   PMODEL_HSV        Hue, Saturation, and Value
                4   PMODEL_HLS        Hue, Lightness, and Saturation

npl

The number of polylines in the set.

vdata

A pointer to an array of npl Pline_vdata_list3 structures that specifies the list of vertices and optionally associated colour information. Pline_vdata_list3 is defined in phigs.h as follows:

typedef struct {

Pint               num_vertices;    /* number of vertices * /
Pline_vdata_arr3   vertex_data;     /* line vertex data * /

} Pline_vdata_list3;

Pline_vdata_arr3 is defined in phigs.h as follows:

typedef union {

Ppoint3   * points;  /* array of points * /
Pptco3    * ptcolrs; /* array of points with colours * /
/* implementation-dependent data * /

}Pline_vdata_arr3;

Ppoint3 is defined in phigs.h as follows:

typedef struct {

Pfloat   x;   /* x coordinate * /
Pfloat   y;   /* y coordinate * /
Pfloat   z;   /* z coordinate * /

} Ppoint3;

Pptco3 is defined in phigs.h as follows:

typedef struct {

Ppoint3   point;  /* point coordinates * /
Pcoval    colr;   /* colour * /

} Pptco3;

Ppoint3 is defined above. Pcoval is defined in phigs.h as follows:

typedef union {

Pint

ind;

/* index in workstation colour bundle

table * /

Pcolr_rep

direct;

/* direct colour components * /

} Pcoval;

When colr_type is PINDIRECT, ind is used; otherwise, direct is used.

Pcolr_rep is defined in phigs.h as follows:

typedef union {

Prgb

rgb;

/* Red Green Blue colour

specification * /

Pcieluv

cieluv;

/* CIE L* U* V*

colour specification * /

Phls

hls;

/* Hue Lightness Saturation colour

specification * /

Phsv

hsv;

/* Hue Saturation Value colour

specification * /

Pdata

unsupp;

/* Colour in unsupported colour

model * /

} Pcolr_rep;

Prgb is defined in phigs.h as follows:

typedef struct {

Pfloat           red;            /* red, hue, and so on * /
Pfloat           green;          /* green, saturation, lightness,
                                   and so on * /
Pfloat           blue;           /* blue, value, saturation, and
                                   so on * /

} Prgb;

Pcieluv is defined in phigs.h as follows:

typedef struct {

Pfloat           cieluv_x;       /* x coefficient * /
Pfloat           cieluv_y;       /* y coefficient * /
Pfloat           cieluv_y_lum; /* y luminance * /

} Pcieluv;

Phls is defined in phigs.h as follows:

typedef struct {

Pfloat           hue;            /* hue * /
Pfloat           lightness;      /* lightness * /
Pfloat           satur;          /* saturation * /

} Phls;

Phsv is defined in phigs.h as follows:

typedef struct {

Pfloat           hue;            /* hue * /
Pfloat           satur;          /* saturation * /
Pfloat           value;          /* value * /

} Phsv;

Pdata is defined in phigs.h as follows:

typedef struct {

size_t          size;           /* size of data * /
char            * data          /* pointer to data * /

} Pdata;

FORTRAN Input Parameters

All of the following data types are predefined in phigs77.h.

VFLAG The data per vertex flag indicates the information specified with each vertex of

the primitive. The possible values are:

0   PVCOOR     Coordinates Only
1   PVCLR      Coordinates and Colours

COLTYP

The colour type. If the data per vertex flag (VFLAG) indicates that a colour per vertex is specified, then COLTYP is set to one of the following:

                0   PINDIR   Colour Index Specified
                1   PRGB     Red, Green, and Blue
                2   PCIE     CIE Colour Model
                3   PHSV     Hue, Saturation, and Value
                4   PHLS     Hue, Lightness, and Saturation

NPL

The number of point lists (polylines) in the polyline set.

PLARR(NPL)

An array of integers containing the end indices into the COORDS array for each point list in the polyline set.

NV

The number of points used to define the polyline set.

COORDS(3,NV)

An array of reals containing the x, y, and z coordinates of the polyline set.

COORDS(1 ,v)= x Coordinate

COORDS(2 ,v)= y Coordinate

COORDS(3 ,v)= z Coordinate

IVCOLR(NV)

An array of integers containing an index into the workstation colour table for each vertex. This array is unused if VFLAG is set to PVCOOR or if COLTYP is greater than zero.

VCOLR(3,NV)

An array of reals containing the colours for each vertex. This array is unused VFLAG is set to PVCOOR or COLTYP is equal to zero (PINDIR).

VCOLR(1 ,v)= Red, Hue, and so on

VCOLR(2 ,v)= Green, Saturation, Lightness, and so on

VCOLR(3 ,v)= Blue, Value, Saturation, and so on

IMPL(* )

This implementation defined data type is not currently used.

Execution

Depending on the edit mode, a POLYLINE SET 3 WITH DATA element is inserted into the open structure after the element pointer or replaces the element pointed to by the element pointer. In either case, the element pointer is updated to point to the newly created POLYLINE SET 3 WITH DATA element.

When the structure is traversed, POLYLINE SET 3 WITH DATA generates a set of unconnected polylines defined by a set of points. Each point sequence in the set generates connected line segments. Colour information for shading the line segments can be specified with each point as part of the primitive definition.

POLYLINE SET 3 WITH DATA elements containing less than two points can be created, but are ignored during structure traversal.

Attributes Applied

The attributes listed below are used to display the POLYLINE SET 3 WITH DATA primitive when the structure is traversed. The Aspect Source Flags (ASFs) tell where to access the output display attributes. These attributes can come directly from the traversal state list, or they can be accessed indirectly, by using the appropriate index in the traversal state list and the corresponding bundled representation in the workstation state list.

polyline colour

polyline colour index ASF

linewidth scale factor

linewidth scale factor ASF

linetype

linetype ASF

polyline shading method

polyline shading method ASF

polyline index

depth cue index

name set

ERRORS

005

Ignoring function, function requires state (PHOP, * ,STOP, * )

900

Storage overflow has occurred in PHIGS

2004

FORTRAN-specific binding error: ignoring function, input parameter size out of range

SEE ALSO

INTRO (3PP)

INQUIRE POLYLINE FACILITIES PLUS (3PP)

POLYLINE 3 (3P)