NAME

QUADRILATERAL MESH 3 WITH DATA - creates a 3D quadrilateral mesh structure element that includes colour and shading data

SYNOPSIS

C Syntax

void

pquad_mesh3_data ( fflag, vflag, colr_type, dim, fdata, vdata )

Pint                 fflag;        what data per fill facet is available
Pint                 vflag;        what data per vertex is available
Pint                 colr_type;   colour type
Pdims                * dim;       dimension of cells (in vertices)
Pfacet_data_arr3     * fdata;     facet data
Pfacet_vdata_arr3    * vdata;     vertex data

FORTRAN Syntax

SUBROUTINE pmed3 ( FFLAG, VFLAG, COLTYP, VROWS, VCOLS, IFCOLR, FCOLR, FNORM, COORDS, IVCOLR, VCOLR, VNORM, IMPL )

INTEGER      FFLAG                                   data per facet flag
INTEGER      VFLAG                                   data per vertex flag
INTEGER      COLTYP                                  colour type
INTEGER      VROWS                                   number of vertices along y axis
INTEGER      VCOLS                                   number of vertices along x axis
INTEGER      IFCOLR((VROWS-1)* (VCOLS-1))            array of indirect facet colours
REAL         FCOLR(3,((VROWS-1)* (VCOLS-1)))         array of facet colours
REAL         FNORM(3,((VROWS-1)* (VCOLS-1)))         array of facet normals
REAL         COORDS(3,VROWS* VCOLS)                  array of vertex coordinates
INTEGER      IVCOLR(VROWS* VCOLS)                    array of indirect vertex colours
REAL         VCOLR(3,VROWS* VCOLS)                   array of vertex colours
REAL         VNORM(3,VROWS* VCOLS)                   array of vertex normals
REAL         IMPL(* )                                implementation defined vertex
                                                     data

Required PHIGS Operating States

(PHOP, * ,STOP, * )

DESCRIPTION

Purpose

QUADRILATERAL MESH 3 WITH DATA creates a 3D quadrilateral mesh primitive with colour and shading data.

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 each quadrilateral of the quadrilateral mesh.

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

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

dim

A pointer to a Pint_size structure that specifies the number of vertices along the x and y coordinates. Pint_size is defined in phigs.h as follows:

typedef struct {

Pint  size_x;   /* number of vertices along the x axis * /
Pint  size_y;   /* number of vertices along the y axis * /

} Pint_size;

fdata

A pointer to a Pfacet_data_arr3 structure that specifies the colour and/or normal information for each facet. Note that number of facets = (size_x -1) * (size_y -1). Pfacet_data_arr3 is defined in phigs.h as follows:

typedef union {

Pcoval      * colrs;    /* array (size_x -1) * (size_y -1) of colours * /
Pvec3       * norms;    /* array (size_x -1) * (size_y -1) of unit
                           normals * /
Pconorm3 * conorms; /* array (size_x -1) * (size_y -1) of colours and
                           normals * /

} Pfacet_data_arr3;

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

Pvec3 is defined as:

typedef struct {

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

} Pvec3;

Pconorm3 is defined as:

typedef struct {

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

} Pconorm3;

Pcoval and Pvec3 are defined above.

vdata

A pointer to a Pfacet_vdata_arr3 structure that specifies the quadrilateral mesh vertices and optionally associated colour and normal information. Pfacet_vdata_arr3 is defined as:

typedef union {

Ppoint3      * points;     /* array of (size_x . size_y) of points * /
Pptco3       * ptcolrs;    /* array of (size_x . size_y) of points and
                              colours * /
Pptnorm3     * ptnorms;    /* array of (size_x . size_y) of points and
                              normals * /

Pptconorm3 * ptconorms; /* array of (size_x . size_y) 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 is defined above. Pcoval is defined as:

typedef union {

Pint

ind;

/* index in workstation colour bundle

table * /

Pcolr_rep

direct;

/* direct colour components * /

} Pcoval;

Pcolr_rep is 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

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

Note: The following arrays are row major: IFCOLR, FCOLR, FNORM, COORDS, IVCOLR, VCOLR, and VNORM.

FFLAG The data per facet flag indicates the information specified for each facet of the

quadrilateral mesh. 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

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   Indirect
1   PRGB     Red, Green, and Blue
2   PCIE     CIE Colour Model

3   PHSV     Hue, Saturation, and Value
4   PHLS     Hue, Lightness, and Saturation

VROWS The number of vertices along the y axis of the quadrilateral strip.

VCOLS The number of vertices along the x axis of the quadrilateral strip.

Note: The total number of vertices in the quadrilateral strip is the product of the number of vertices along the y axis and the number of vertices along the x axis (VROWS . VCOLS). The number of quadrilateral facets produced is (VROWS-1) . (VCOLS-1).

IFCOLR((VROWS-1)* (VCOLS-1))

An array of integers containing indices into the workstation colour table for each facet or quadrilateral. The number of facets is equal to (VROWS-1) . (VCOLS-1). This array is unused if FFLAG is set to either PFNONE or PFNORM or if COLTYP is greater than zero.

FCOLR(3,((VROWS-1)* (VCOLS-1)))

An array of reals containing the colours for each facet. The number of facets is equal to (VROWS-1) . (VCOLS-1). 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,((VROWS-1)* (VCOLS-1)))

An array of reals containing the unit normals for each facet. The number of facets is equal to (VROWS-1) . (VCOLS-1). 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

COORDS(3,VROWS* VCOLS)

An array of reals containing the x, y, and z coordinates of the quadrilaterals, where the data in each set of four neighboring array elements defines a quadrilateral.

COORDS(1 ,v)= x Coordinate

COORDS(2 ,v)= y Coordinate

COORDS(3 ,v)= z Coordinate

IVCOLR(VROWS* VCOLS)

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,VROWS* VCOLS)

An array of reals containing the colours for each vertex. This array is unused if VFLAG is set to either PVCOOR or PVERTCOORNORMAL 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,VROWS* VCOLS)

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(* )

Implementation defined vertex data.

Execution

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

When the structure is traversed, QUADRILATERAL MESH 3 WITH DATA generates a threedimensional mesh of (m-1) . (n -1) quadrilaterals from a two dimensional array of m . n vertices. Line segments form the boundary of each quadrilateral in the mesh. Each quadrilateral can be rendered empty, hollow, shaded, or filled with a colour, pattern, or hatch style. A nonplanar quadrilateral is decomposed into two triangles when its interior is rendered. A mesh with n < 2 or m < 2 vertices can be created, but is ignored during traversal.

QUADRILATERAL MESH 3 WITH DATA uses the same attributes as the FILL AREA SET 3 WITH DATA primitive.

The QUADRILATERAL MESH 3 WITH DATA element can specify the facet colour and normal vector of each quadrilateral in the mesh, 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: Unexpected lighting effects result when the supplied normals are not of unit length.

INTRO (3PP) describes how to use the output display attribute values.

Attributes Applied

The attributes listed below are used to display the QUADRILATERAL MESH 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, * )

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)