NAME

SET OF FILL AREA SET 3 WITH DATA − create a 3D set of fill area set 3 with data structure element that includes colour and shading data

SYNOPSIS

C Syntax

void
pset_of_fill_area_set3_data ( fflag, eflag, vflag, colour_model, num_sets, fdata, edata, vlist, vdata )
Pintfflag;data per facet  flag
Pinteflag;data per edge flag
Pintvflag;data per vertex flag
Pintcolour_model;colour model
Pintnum_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

Required PHIGS Operating States

(PHOP, ∗, STOP, ∗)

DESCRIPTION

Purpose

SET OF FILL AREA SET 3 WITH DATA creates a set of fill area set 3 primitive with colour and shading data. 

It 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. 

C Input Parameters

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

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

0PFACET_NONENo Facet Data Specified
1PFACET_COLOURFacet Colours Specified
2PFACET_NORMALFacet Normals Specified
3PFACET_COLOUR_NORMALFacet Normals and Colours Specified

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

0PEDGE_NONENo Edge Data Specified
1PEDGE_VISIBILITYEdge Visibility Flags Specified

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

0PVERT_COORDCoordinates Specified
1PVERT_COORD_COLOURCoordinates and Vertex Colours Specified
2PVERT_COORD_NORMALCoordinates and Vertex Normals Specified
3PVERT_COORD_COLOUR_NORMALCoordinates, Vertex Colours, and Vertex Normals Specified

colour_model
The colour model for specified vertex colours.

0PINDIRECTColour Index Specified
1PMODEL_RGB Red, Green, and Blue
2PMODEL_CIELUV CIE Colour Model
3PMODEL_HSV Hue, Saturation, and Value
4PMODEL_HLS Hue, Lightness, and Saturation

num_sets
The number of facets.  Each facet is one fill area set.

fdataA pointer to a Pfacet_data_arr3 structure that specifies the 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 {
Pintind;/∗ index in workstation colour bundle table ∗/
Pcolr_repdirect; /∗ direct colour components ∗/
} Pcoval;

When colour model is PINDIRECT, index is used; otherwise direct is used. 

Pcolr_rep is defined in phigs.h as follows:

typedef union {
Prgbrgb;/∗ Red Green Blue colour specification ∗/
Pcieluvcieluv;/∗ CIE L∗U∗V∗ colour specification ∗/
Phlshls;/∗ Hue Lightness Saturation colour specification ∗/
Phsvhsv;/∗ Hue Saturation Value colour specification ∗/
Pdataunsupp;/∗ Colour in unsupported colour model ∗/
} Pcolr_rep

Prgb is defined in phigs.h as follows:

typedef struct {
Pfloatred;/∗ red, hue, etc ∗/
Pfloatgreen;/∗ green, saturation, lightness, etc ∗/
Pfloatblue;/∗ blue, value, saturation, etc ∗/
} Prgb;

Pcieluv is defined in phigs.h as follows:

typedef struct {
Pfloatcieluv_x;/∗ x coefficient ∗/
Pfloatcieluv_y;/∗ y coefficient ∗/
Pfloatcieluv_y_lum; /∗ y luminance ∗/
} Pcieluv;

Phls is defined in phigs.h as follows:

typedef struct {
Pfloathue;/∗ hue ∗/
Pfloatlightness;/∗ lightness ∗/
Pfloatsatur;/∗ saturation ∗/
} Phls;

Phsv is defined in phigs.h as follows:

typedef struct {
Pfloathue;/∗ hue ∗/
Pfloatsatur;/∗ saturation ∗/
Pfloatvalue;/∗ value ∗/
} Phsv;

Pdata is defined in phigs.h as follows:

typedef struct {
size_tsize;/∗ size of data ∗/
char∗data/∗ pointer to data ∗/
} Pdata;

Pconorm3 is defined as:

typedef struct {
Pcovalcolr; /∗ colour ∗/
Pvec3norm;/∗ unit normal ∗/
} Pconorm3;

Pcoval is defined above.  Pvec3 is defined as:

typedef struct {
Pfloatdelta_x;/∗ x magnitude ∗/
Pfloatdelta_y;/∗ y magnitude ∗/
Pfloatdelta_z;/∗ z magnitude ∗/
} Pvec3;

edataA 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 {
Pintnum_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 {
Pintnum_edges;/∗ number of edges ∗/
Pedge_data_arredgedata;/∗ 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;

vlistA 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 {
Pintnum_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 {
Pintnum_ints;/∗ number of Pints in list ∗/
Pint∗ints;/∗ list of integers ∗/

} Pint_list;

vdataA 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 {
Pintnum_vertices;/∗ number of vertices ∗/
Pfacet_vdata_arr3vertex_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 {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
Pfloatz;/∗ z coordinate ∗/
} Ppoint3;

Pptco3 is defined as:

typedef struct {
Ppoint3point;/∗ point coordinates ∗/
Pcovalcolr;/∗ colour ∗/
} Pptco3;

Ppoint3 and Pcoval are defined above. 

Pptnorm3 is defined as:

typedef struct {
Ppoint3point;/∗ point coordinates ∗/
Pvec3norm;/∗ unit normal ∗/
} Pptnorm3;

Ppoint3 and Pvec3 are defined above. 

Pptconorm3 is defined as:

typedef struct {
Ppoint3point;/∗ point coordinates ∗/
Pcovalcolr;/∗ colour ∗/
Pvec3norm;/∗ unit normal ∗/
} Pptconorm3;

Ppoint3, Pcoval, and Pvec3 are defined above. 

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 it 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 set 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 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 colourinterior colour index ASF
back interior colourback interior colour ASF
interior styleinterior style ASF
back interior styleback interior style ASF
interior style indexinterior style index ASF
back interior style indexback interior style index ASF
interior shading methodinterior shading method ASF
back interior shading methodback interior shading method ASF
interior reflectance equation interior reflectance equation ASF
back interior reflectance equationback interior reflectance equation ASF
area propertiesarea properties ASF
back area propertiesback area properties ASF
interior index
edge colouredge colour ASF
edge flagedge flag ASF
edgetypeedgetype ASF
edgewidth scale factoredgewidth scale factor ASF
edge index
face distinguishing mode
face culling mode
depth cue index
light source state
name set

ERRORS

005Ignoring function, function requires state (PHOP, ∗, STOP, ∗)

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

513Ignoring function, inconsistent edge flag specification. 

SEE ALSO

FILL AREA SET 3 WITH DATA (3P+)
INTRO PHIGS PLUS (3P+)

September 02, 1992