NAME

FILL AREA SET 3 WITH DATA - creates a 3D fill area set structure element that includes colour and shading data

SYNOPSIS

C Syntax

void

pfill_area_set3_data ( fflag, eflag, vflag, colr_type, fdata, nfa, edata, vdata )

Pint                 fflag;        what data is specified per facet
Pint                 eflag;        what data is specified per edge
Pint                 vflag;        what data is specified per vertex
Pint                 colr_type;   colour type
Pfacet_data3         * fdata;     facet data
Pint                 nfa;         number of fill areas in the set
Pedge_data_list      * edata;     edge data list
Pfacet_vdata_list3   * vdata;     facet vertex data list

FORTRAN Syntax

SUBROUTINE pfasd3 ( FFLAG, EFLAG, VFLAG, COLTYP, IFCOLR, FCOLR, FNORM, NFA, FARR, NV, EDARR, 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      IFCOLR             indirect facet colour
REAL         FCOLR(3)           array of facet colour
REAL         FNORM(3)           array of facet normals
INTEGER      NFA                number of fill areas
INTEGER      FARR(NFA)          array of fill area end indices
INTEGER      NV                 number of vertices
INTEGER      EDARR(NV)          array of edge data (PON/POFF)
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

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

The FILL AREA SET 3 WITH DATA is a set of closed polygonal areas defined by a series of three-dimensional Modelling Coordinate points. You can specify a geometric normal for the entire fill area, and specify colour/normal information for each vertex in addition to point coordinates. The added data is used when applying lighting, shading, face

distinguishing, and face culling.

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

C Input Parameters

fflag

The data per facet flag specifies the available data for the entire fill area set.

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

eflag

The data per edge flag specifies the available information for each edge.

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

colr_type

The colour type for specified facet and/or vertex colours.

                0   PINDIRECT         Colour Index Specified
                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

fdata

A pointer to a Pfacet_data3 structure that specifies the fill area and optionally associated colour information. Pfacet_data3 is defined as follows:

typedef union {

Pcoval          colr;           /* colour * /
Pvec3           normal;         /* unit normal* /
Pconorm3        conorm;         /* colour and normal * /

} Pfacet_data3;

coval is defined as:

typedef union {

Pint

ind;

/* index in workstation colour

bundle table * /

Pcolr_rep

direct;

/* direct colour components * /

} Pcoval;

Pcolr_rep is defined as:

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;

Phsv is defined in phigs.h as follows:

typedef struct {

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

} Phsv;

Phls is defined in phigs.h as follows:

typedef struct {

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

} Phls;

Pdata is defined in phigs.h as follows:

typedef struct {

size_t

size;

/* size of data * /

char

* data

/* pointer to data * /

} Pdata;

Pvec3 is defined in phigs.h as follows:

typedef struct {

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

} Pvec3;

Pconorm3 is defined in phigs.h as follows:

typedef struct {

Pcoval          colr;           /* colour * /
Pvec3           norm;           /* normal * /

} Pconorm3;

Pcoval and Pvec3 are defined above.

nfa

The number of fill areas in the set.

edata

A pointer to an array (nfa) of Pedge_data_list structures that specifies the edge data. Pedge_data_list 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;

vdata

A pointer to an array (nfa) of Pfacet_vdata_list3 structures that specifies each fill area in the set and optionally associated colour 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 types can go here * /

} 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 anc Pcoval are defined above. Pptnorm3 is defined in phigs.h as follows: typedef struct {

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

} Pptnorm3;

Ppoint3 and Pvec3 are defined above. Pptconorm3 is defined in phigs.h as follows:

typedef struct {

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

} Pptconorm3;

/* point with colour and

normal * /

Ppoint3, Pcoval, and Pvec3 are defined above.

FORTRAN Input Parameters

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

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

set. 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. 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 vertex colours are 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

IFCOLR

An integer value, which is an index into the workstation colour table for determining the colour of the facet. This value is unused if FFLAG is set to either PFNONE or PFNORM or if COLTYP is greater than zero.

FCOLR(3)

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) = Red, Hue, and so on

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

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

FNORM(3)

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) = x Magnitude

FNORM(2) = y Magnitude

FNORM(3) = z Magnitude

NFA

The number of fill areas in the fill area set.

FARR(NFA)

An array of integers containing the end indices the COORDS array for each polygon in the fill area set.

NV

The number of points used to define the fill area set.

EDARR(NV)

An array of integers containing edge visibility data. The possible values for each element of the array are:

0

POFF

1

PON

COORDS(3,NV)

An array of reals containing the x, y and z coordinates of the fill area 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 to 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 if 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 type is not currently used.

Execution

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

When the structure is traversed, FILL AREA SET 3 WITH DATA draws an implicitly closed polygonal area with multiple boundaries. SunPHIGS Extensions implicitly closes the area by extending each fill area boundary from the last point to the first point. Fill areas can be empty, hollow, shaded, or filled with a color, pattern, or hatch. The interior of the primitive is defined by the odd winding rule. The FILL AREA SET 3 WITH DATA element can specify the facet color and normal vector as well as colours and normal vectors for each vertex. These colours and normal vectors are used in conjunction with the current lighting and depth cueing attributes to colour and shade the primitive. Note that

unexpected lighting effects result if the supplied normals are not of unit length. See INTRO (3PP) for a complete description of these values.

The application should insure that the fill area set points are coplanar. Display of noncoplanar fill area set is device-dependent. FILL AREA SET 3 WITH DATA elements containing fewer than three vertices can be created, but are ignored during structure traversal.

Attributes Applied

The attributes listed below are used to display the FILL AREA SET 3 WITH DATA primitive when the structure is traversed. The Aspect Source Flags (ASFs) describe 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, * )

900

Storage overflow has occurred in PHIGS

2004

FORTRAN-specific Binding Error -- Ignoring function, input parameter size out of range

SEE ALSO

INTRO (3PP)

SET OF FILL AREA SET 3 WITH DATA (3PP)

FILL AREA SET 3 (3P)