NAME

SET OF FILL AREA SET 3 WITH DATA - creates a 3D polyhedron structure element that includes colour and shading data

SYNOPSIS

C Syntax

void

pset_of_fill_area_set3_data ( fflag, eflag, vflag, colr_type, num_sets, fdata, edata, vlist, vdata )

Pint                  fflag;         data per facet flag
Pint                  eflag;         data per edge flag
Pint                  vflag;         data per vertex flag
Pint                  colr_type;    colour type
Pint                  num_sets;     number of facets (fill area sets)
Pfacet_data_arr3      * fdata;      array of L({COLRV}{,NORM}) facet data
Pedge_data_list_list  * edata;      array of L(L(E)) edge data
Pint_list_list        * vlist;      array of L(L(I)) vertex indices
Pfacet_vdata_list3    * vdata;      array of L(P3,{COLRV}{,NORM}) facet vertex data

FORTRAN Syntax

SUBROUTINE psfsd3 ( FFLAG, EFLAG, VFLAG, COLTYP, NFA, IFCOLR, FCOLR, FNORM, NB, FARR, VFARR, EDARR, NV, COORDS, IVCOLR, VCOLR, VNORM, IMPL )

INTEGER      FFLAG              data per facet flag
INTEGER      EFLAG              data per edge flag
INTEGER      VFLAG              data per vertex flag
INTEGER      COLTYP             colour type
INTEGER      NFA                number of facets (fill area sets)
INTEGER      IFCOLR(NFA)        array of indirect facet colours
REAL         FCOLR(3,NFA)       array of facet colours
REAL         FNORM(3,NFA)       array of facet normals
INTEGER      NB(NFA)            array of bounds (fill areas) per facet
INTEGER      FARR(* )           array of end indices per facet
INTEGER      VFARR(* )          array of vertex indices per facet
INTEGER      EDARR(* )          array of edge data (PON/POFF)
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         VNORM(3,NV)        array of vertex normals
REAL         IMPL(* )           implementation defined vertex data

Required PHIGS Operating States

(PHOP, * ,STOP, * )

DESCRIPTION

Purpose

SET OF FILL AREA SET 3 WITH DATA creates a polyhedron primitive with colour and shading data.

A polyhedron generates a group of fill area sets (or facets) whose vertices are selected by indexing into a single list of vertices. If the facets share common vertices, the primitive can require less data than the corresponding collection of FILL AREA SET 3 WITH DATA primitives.

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

C Input Parameters

The following data types are predefined in phigs.h.

fflag

The data per facet flag specifies the available data for each facet in the set of fill area set 3.

                0   PFACET_NONE                 No Facet Data Specified
                1   PFACET_COLOUR               Facet Colours Specified
                2   PFACET_NORMAL               Facet Normals Specified
                3   PFACET_COLOUR_NORMAL        Facet Normals and Colours Specified

eflag

The data per edge flag specifies the available information for each edge of each facet in the set of fill area set 3.

                0   PEDGE_NONE         No Edge Data Specified
                1   PEDGE_VISIBILITY   Edge Visibility Flags Specified

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 Vertex
                                      Colours Specified
2   PVERT_COORD_NORMAL                Coordinates and Vertex
                                      Normals Specified
3   PVERT_COORD_COLOUR_NORMAL         Coordinates, Vertex Colours,
                                      and Vertex Normals Specified

colr_type

The colour type for specified vertex colour and/or norm information for each facet. Pfacet_data_arr3 is defined as:

typedef union {

Pcoval      * colrs;     /* array (num_sets) of colours * /
Pvec3       * norms;     /* array (num_sets) of unit normals * /
Pconorm3    * conorms;   /* array (num_sets) of colours and
                             normals * /
/* implementation-dependent types can go here * /

} Pfacet_data_arr3;

Pcoval is defined as:

typedef union {

Pint

ind;

/* index in workstation colour bundle

table * /

Pcolr_rep

direct;

/* direct colour components * /

} Pcoval;

When colour type is PINDIRECT, index 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 type* /

} 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;

Pconorm3 is defined as:

typedef struct {

Pcoval

colr;

/* colour * /

Pvec3

norm;

/* unit normal * /

} Pconorm3;

Pcoval is defined above. Pvec3 is defined as:

typedef struct {

Pfloat   delta_x;   /* x magnitude * /
Pfloat   delta_y;   /* y magnitude * /
Pfloat   delta_z;   /* z magnitude * /

} Pvec3;

edata

A pointer to an array (num_sets) of Pedge_data_list_list structures. Each Pedge_data_list_list structure specifies the edge data list for the corresponding facet (fill area set). Each Pedge_data_list structure contains a list of edge flags for a single bound in a facet. The first element of the Pedge_data_arr edge data array contains the information pertaining to the edge that falls between the first and second vertex index. The number of edges will be the same as the number of vertices in the vlist data structure. Pedge_data_list_list (edge data for a single fill area set) is defined as:

typedef struct {

Pint

num_lists;

/* number of Pedge_data_lists

(bounds) in list * /

Pedge_data_list

* edgelist;

/* list of edge data list * /

} Pedge_data_list_list;

Pedge_data_list (list of edges for one bound) is defined as:

typedef struct {

Pint              num_edges;    /* number of edges * /
Pedge_data_arr    edgedata;     /* edge data * /

} Pedge_data_list;

Pedge_data_arr is defined as:

typedef union {

Pedge_flag

* edges; /* array of edge flags * /

/* implementation-dependent data * /

} Pedge_data_arr;

Pedge_flag is defined as:

typedef enum {

PEDGE_OFF,

PEDGE_ON

} Pedge_flag;

vlist

A pointer to an array (num_sets) of Pint_list_list structures. Each Pint_list_list structure specifies the integer list for the corresponding facet (fill area set). Each Pint_list structure contains the indices into the vertex data that specify a single bound of each facet. Pint_list_list (bounds for a single fill area set) is defined as:

typedef struct {

Pint      num_lists;   /* number of Pint_lists in list * /
Pint_list * lists;     /* list of integer lists * /

} Pint_list_list;

Pint_list (vertex indices for all vertices in a single bound) is defined as:

typedef struct {

Pint  num_ints;    /* number of Pints in list * /
Pint  * ints;      /* list of integers * /

} Pint_list;

vdata

A pointer to a Pfacet_vdata_list3 structure that specifies the set of fill area set 3 vertices and optionally associated colour and norm information. Pfacet_vdata_list3 is defined as:

typedef struct {

Pint                num_vertices;    /* number of vertices * /
Pfacet_vdata_arr3   vertex_data;     /* facet vertex data * /

} Pfacet_vdata_list3;

Pfacet_vdata_arr3 is defined as:

typedef union {

Ppoint3       * points;      /* array of points * /
Pptco3        * ptcolrs;     /* array of points and colours * /
Pptnorm3      * ptnorms;     /* array of points and normals * /
Pptconorm3    * ptconorms;   /* array of points, colours,
                                 and normals * /
/* implementation-dependent data pointer * /

} Pfacet_vdata_arr3;

Ppoint3 is defined as:

typedef struct {

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

} Ppoint3;

Pptco3 is defined as:

typedef struct {

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

} Pptco3;

Ppoint3 and Pcoval are defined above.

Pptnorm3 is defined as:

typedef struct {

Ppoint3   point;   /* point coordinates * /
Pvec3     norm;    /* unit normal * /

} Pptnorm3;

Ppoint3 and Pvec3 are defined above.

Pptconorm3 is defined as:

typedef struct {

Ppoint3   point;   /* point coordinates * /
Pcoval    colr;    /* colour * /
Pvec3     norm;    /* unit normal * /

} Pptconorm3;

Ppoint3, Pcoval, and Pvec3 are defined above.

FORTRAN Input Parameters

The following data types are predefined in phigs77.h.

FFLAG The data per facet flag indicates the information specified for each facet (fill area

set) in the polyhedron. The possible values are:

0   PFNONE     No Facet Data Specified
1   PFCLR      Facet Colour Specified
2   PFNORM     Facet Normal Specified
3   PFCLRN     Facet Colour and Normal Specified

EFLAG The data per edge flag indicates the information specified for each edge of each

fill area set in the polyhedron. The possible values are:

0   PEDNO     No Edge Data Specified
1   PEDVIS    Edge Visibility Flags Specified

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
2   PVNORM     Coordinates and Normals
3   PVCLRN     Coordinates, Colours, and Normals

COLTYP

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

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

NFA

The number of facets or fill area sets in the polyhedron.

IFCOLR(NFA)

An array of integers containing indices into the workstation colour table for determining the colour of each facet. This array is unused if FFLAG is set to either PFNONE or PFNORM or if COLTYP is greater than zero.

FCOLR(3,NFA)

An array of reals containing the colours for the facet. This array is unused if FFLAG is set to either PFNONE or PFNORM or COLTYP is equal to zero.

FCOLR(1,f) = Red, Hue, and so on

FCOLR(2,f) = Green, Saturation, Lightness, and so on

FCOLR(3,f) = Blue, Value, Saturation, and so on

FNORM(3,NFA)

An array of reals containing the unit normals for the facet. This array is unused if FFLAG is set to either PFNONE or PFCLR.

FNORM(1,f) = x Magnitude

FNORM(2,f) = y Magnitude

FNORM(3,f) = z Magnitude

NB(NFA)

An array of integers containing the bounds (fill areas) for each facet in the polyhedron.

FARR(* )

An array of integers containing the end indices into the VFARR array for each fill area set in the polyhedron. The dimension of this array is equal to the sum of the bounds (fill areas) in the entire polyhedron (total number of elements in the NB

array).

VFARR(* )

An array of integers containing the vertex indices into the COORDS array which bound each fill area set in the polyhedron. The number of elements in the VFARR array may differ from the total number of vertices in the COORDS array.

EDARR(* )

An array of integers containing the edge visibility data. The first element of the edge data array contains the information pertaining to the edge which falls between vertex index one and vertex index two. The number of edges will be the same as the number of vertices in the VFARR array. For example, a polyhedron containing two facets, one a triangle with edges on, and one a square with edges off would appear as:

data edarr

/1 ,1 ,1 ,

+

0 ,0 ,0 ,0 /

The possible values for each element of the array are:

                0   POFF    Off
                1   PON     On

NV

The total number of points used to define the polyhedron.

COORDS(3,NV)

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

COORDS(1 ,v)= x Coordinate

COORDS(2 ,v)= y Coordinate

COORDS(3 ,v)= z Coordinate

IVCOLR(NV)

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

VCOLR(3,NV)

An array of reals containing the colours for each vertex. This array is unused if VFLAG is set to either PVCOOR or PVNORM or COLTYP is equal to zero.

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

VNORM(3,NV)

An array of reals containing the unit normals for each vertex. This array is unused if VFLAG is set to either PVCOOR or PVCLR.

VNORM(1 ,v)= x Magnitude

VNORM(2 ,v)= y Magnitude

VNORM(3 ,v)= z Magnitude

IMPL(* )

This implementation-defined data is not currently defined.

Execution

Depending on the edit mode, a SET OF FILL AREA 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 SET OF FILL AREA SET 3 WITH DATA element.

When the structure is traversed, SET OF FILL AREA SET 3 WITH DATA generates a group of implicitly closed facets. Each facet is rendered as a fill area set. The collection of facets need not be coplanar and need not necessarily form a closed surface. Vertices that define the facet contours are selected through an array of indices. Each array references specific coordinates from the vertex list. The odd winding rule defines the facet interior. The application should insure that each facet's points are coplanar. Non-coplanar facet display is device dependent. Facets containing fewer than three vertices can be created, but are ignored during structure traversal.

SET OF FILL AREA SET 3 WITH DATA uses the same attributes as the FILL AREA SET 3 WITH DATA structure element.

Vertex and facet colours and normals are used to calculate the polyhedron colour and shading. The SET OF FILL AREA SET 3 WITH DATA element can specify the colour and normal vector of each facet, as well as colour and normal vectors for each vertex. Note that unexpected lighting effects will result if the supplied normals are not of unit length.

Each polyhedron edge has an optional visibility flag to determine if that edge is rendered. There must be as many lists of edge visibility flags as there are lists of vertex indices, and corresponding lists must be the same length. The first edge visibility array entry controls edge visibility between the first two corresponding contour vertices. The last edge visibility array entry controls edge visibility between the last and the first vertices of the corresponding contour. If edge visibility flags are specified, an edge is displayed only when the EDGE FLAG attribute and the edge visibility flag are both ON. If edge visibility flags are not specified, no edges are displayed.

Attributes Applied

The attributes listed below are used to display the SET OF FILL AREA 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, using the appropriate index in the traversal state list and the corresponding bundled representation in the workstation state list.

interior colour

interior colour index ASF

back interior colour

back interior colour ASF

interior style

interior style ASF

back interior style

back interior style ASF

interior style index

interior style index ASF

back interior style index

back interior style index ASF

interior shading method

interior shading method ASF

back interior shading method

back interior shading method ASF

interior reflectance characteristics

interior reflectance characteristics ASF

back interior reflectance characteristics

back interior reflectance characteristics ASF

reflectance properties

reflectance properties ASF

back reflectance properties

back reflectance properties ASF

interior index

edge colour

edge colour index ASF

edge flag

edge flag ASF

edgetype

edgetype ASF

edgewidth scale factor

edgewidth scale factor ASF

edge index

face distinguishing mode

face culling mode

depth cue index

light source state

name set

ERRORS

005

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

619

Ignoring function, one or more of the vertex indices is out of range

900

Storage overflow has occurred in PHIGS

2004

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

SEE ALSO

FILL AREA SET 3 WITH DATA (3PP)

INTRO (3PP)