POLYHEDRON 3 WITH DATA(3P+) — MISC. REFERENCE MANUAL PAGES

NAME

POLYHEDRON 3 WITH DATA − creates a 3D polyhedron structure element that includes colour and shading data

SYNOPSIS

C Syntax

void
ppolyhedron3data ( fflag, eflag, vflag, colour_model, nfa, fdata, edata, vlist, vdata )
Pintfflag;data per facet flag
Pinteflag;data per edge flag
Pintvflag;data per vertex flag
Pintcolour_model;colour type
Pintnfa;number of facets (fill area sets)
Pfacetdataarr3∗fdata;facet data list
Pedgedatalstlst∗edata; facet edge list
Pintlstlst∗vlist;vertex indices
Pfacetvdatalst3∗vdata; vertex data array list

FORTRAN Syntax

SUBROUTINE pphed3 ( FFLAG, EFLAG, VFLAG, COLMOD, NFA, IFCOLR, FCOLR, FNORM,
NB, FARR, VFARR, EDARR, NV, COORDS, IVCOLR, VCOLR, VNORM, IMPL )
INTEGERFFLAGdata per facet flag
INTEGEREFLAGdata per edge flag
INTEGERVFLAGdata per vertex flag
INTEGERCOLMODcolour model
INTEGERNFAnumber of facets (fill area sets)
INTEGERIFCOLR(NFA)array of indirect facet colours
REALFCOLR(3,NFA)array of facet colours
REALFNORM(3,NFA)array of facet normals
INTEGERNB(NFA)array of bounds (fill areas) per facet
INTEGERFARR(∗)array of end indices per facet
INTEGERVFARR(∗)array of vertex indices per facet
INTEGEREDARR(∗)array of edge data (PON/POFF)
INTEGERNVnumber of vertices
REALCOORDS(3,NV)array of vertex coordinates
INTEGERIVCOLR(NV)array of indirect vertex colours
REALVCOLR(3,NV)array of vertex colours
REALVNORM(3,NV)array of vertex normals
REALIMPL(∗)implementation defined vertex data

Required PHIGS Operating States

(PHOP, ∗, STOP, ∗)

DESCRIPTION

Purpose

POLYHEDRON 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+ and is not part of the PHIGS standard.

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

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

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 specifies the colour type for specified vertex colours.

0PINDIRECTColour Index Specified
1PRGBRed, Green, and Blue
2PCIECIE Colour Model
3PHSVHue, Saturation, and Value
4PHLSHue, Lightness, and Saturation

nfaThe number of facets. Each facet is one fill area set.

fdataA pointer, to a Pfacetdataarr3 structure, that specifies the colour and/or normal information for each facet. Pfacetdataarr3 is defined as:

typedef union {
Pcoval∗colours;/∗ array (nfa) of colours ∗/
Pvector3∗normals;/∗ array (nfa) of normals ∗/
Pconorm3∗conorms; /∗ array (nfa) of colours and normals ∗/
/∗ implementation dependent types can go here ∗/
} Pfacetdataarr3;

Pcoval is defined as:

typedef union {
Pintindex;/∗ index in workstation colour bundle table ∗/
Pcobundldirect;/∗ direct colour components ∗/
} Pcoval;

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

Pcobundl is defined as:

typedef struct {
Pfloatx;/∗ red, hue, etc ∗/
Pfloaty;/∗ green, saturation, lightness, etc ∗/
Pfloatz;/∗ blue, value, saturation, etc ∗/
} Pcobundl;

Pvector3 is defined as:

typedef struct {
Pfloatx;/∗ x magnitude ∗/
Pfloaty;/∗ y magnitude ∗/
Pfloatz;/∗ z magnitude ∗/
} Pvector3;

Pconorm3 is defined as:

typedef struct {
Pcovalcolour;/∗ colour ∗/
Pvector3normal;/∗ normal ∗/
} Pconorm3;

Pcoval and Pvector3 are defined above.

edataA pointer to an array (nfa) of Pedgedatalstlst structures. Each Pedgedatalstlst structure specifies the edge data list for the corresponding facet (fill area set). Each Pedgedatalst structure contains a list of edge flags for a single bound in a facet. The first element of the Pedgedataarr edge data array contains the information pertaining to the edge which 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. Pedgedatalstlst (edge data for a single fill area set) is defined as:

typedef struct {
Pintnumber;/∗ number of Pedgedatalsts (bounds) in list ∗/
Pedgedatalst∗edgelst;/∗ list of edge data list ∗/
} Pedgedatalstlst;

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

typedef struct {
Pintnumber;/∗ number of edges ∗/
Pedgedataarredgedata;/∗ edge data ∗/
} Pedgedatalst;

Pedgedataarr is defined as: typedef union { Pedgef∗edges; /∗ array of edge flags ∗/

/∗ implementation dependent data ∗/ } Pedgedataarr;

Pedgef is defined as:

typedef enum {
PEDGE_OFF,
PEDGE_ON
} Pedgef;

vlistA pointer, to an array (nfa) of Pintlstlst structures. Each Pintlstlst structure specifies the integer list for the corresponding facet (fill area set). Each Pintlst structure contains the indices into the vertex data which specify a single bound of each facet. Pintlstlst (bounds for a single fill area set) is defined as:

typedef struct {
Pintnumber;/∗ number of Pintlsts in list ∗/
Pintlst∗ils;/∗ list of integer lists ∗/
} Pintlstlst;

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

typedef struct {
Pintnumber;/∗ number of Pints in list ∗/
Pint∗integers;/∗ list of integers ∗/

} Pintlst;

vdataA pointer, to a Pfacetvdatalst3 structure, that specifies the polyhedron vertices and optionally associated colour and normal information. Pfacetvdatalst3 is defined as:

typedef struct {
Pintnumber;/∗ number of vertices ∗/
Pfacetvdataarr3vertexdata; /∗ facet vertex data ∗/
} Pfacetvdatalst3;

Pfacetvdataarr3 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 ∗/
} Pfacetvdataarr3;

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 ∗/
Pcovalcolour;/∗ colour ∗/
} Pptco3;

Ppoint3 is defined above. Pcoval is defined as:

typedef union {
Pintindex;/∗ index in workstation colour bundle table ∗/
Pcobundldirect;/∗ direct colour components ∗/
} Pcoval;

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

Pcobundl is defined as:

typedef struct {
Pfloatx;/∗ red, hue, etc ∗/
Pfloaty;/∗ green, saturation, lightness, etc ∗/
Pfloatz;/∗ blue, value, saturation, etc ∗/
} Pcobundl;

Pptnorm3 is defined as:

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

Ppoint3 is defined above. Pvector3 is defined as:

typedef struct {
Pfloatx;/∗ x magnitude ∗/
Pfloaty;/∗ y magnitude ∗/
Pfloatz;/∗ z magnitude ∗/
} Pvector3;

Pptconorm3 is defined as:

typedef struct {
Ppoint3point;/∗ point coordinates ∗/
Pcovalcolour;/∗ colour ∗/
Pvector3normal; /∗ normal ∗/
} Pptconorm3;

Ppoint3, Pcoval, and Pvector3 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 each facet (fill area set) in the polyhedron. The possible values are:

0PFNONENo Facet Data Specified
1PFCLRFacet Colour Specified
2PFNORMFacet Normal Specified
3PFCLRNFacet 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:

0PEDNONo Edge Data Specified
1PEDVISEdge Visibility Flags Specified

VFLAG
The data per vertex flag indicates the information specified with each vertex of the primitive. The possible values are:

0PVCOORCoordinates Only
1PVCLRCoordinates and Colours
2PVNORMCoordinates and Normals
3PVCLRNCoordinates, Colours, and Normals

COLMOD
The colour model. 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 COLMOD is set to one of the following:

0PINDIRColour Index Specified
1PRGBRed, Green, and Blue
2PCIECIE Colour Model
3PHSVHue, Saturation, and Value
4PHLSHue, Lightness, and Saturation

NFAThe 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 COLMOD 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 COLMOD is equal to zero.

FCOLR(1,f) = Red, Hue, etc.
FCOLR(2,f) = Green, Saturation, Lightness, etc.
FCOLR(3,f) = Blue, Value, Saturation, etc.

FNORM(3,NFA)
An array of reals containing the 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 indicies 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:

0POFFOff
1PONOn

NVThe 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 COLMOD 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 COLMOD is equal to zero.

VCOLR(1,v) = Red, Hue, etc.
VCOLR(2,v) = Green, Saturation, Lightness, etc.
VCOLR(3,v) = Blue, Value, Saturation, etc.

VNORM(3,NV)
An array of reals containing the 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 POLYHEDRON 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 POLYHEDRON 3 WITH DATA element.

When the structure is traversed, POLYHEDRON 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.

POLYHEDRON 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 POLYHEDRON 3 WITH DATA element can specify the colour and normal vector of each facet, as well as colour and normal vectors for each vertex.

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 POLYHEDRON 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 index 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,∗)

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

900Storage overflow has occurred in PHIGS

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

Museum