path: root/xc/unsupported/doc/PHIGS/man3/p348

.\"##
.\" $XConsortium: p348,v 5.1 91/02/16 09:43:48 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.\" 1. Substitute PHIGS+ function name (in CAPS) for "PNAME" in line below:
.ds pN SET OF FILL AREA SET 3 WITH DATA
.TH "\*(pN" 3P+ "29 February 1991"
.SH NAME
\*(pN \-
create a \s-23D\s+2 set of fill area set 3 with data structure element
that includes colour and shading data
.IX "PHIGS Extension Functions" "\*(pN"
.IX "Filled Area Primitives" "SET OF FILL AREA SET 3 WITH DATA"
.IX "Primitives, Filled Area Primitives" "SET OF FILL AREA SET 3 WITH DATA"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
.\" 6. Insert C syntax below
void
pset_of_fill_area_set3_data ( fflag, eflag, vflag, colour_model, num_sets, fdata, edata, vlist, vdata )
Pint	fflag;	\fIdata per facet  flag\fP
Pint	eflag;	\fIdata per edge flag\fP
Pint	vflag;	\fIdata per vertex flag\fP
Pint	colour_model;	\fIcolour model\fP
Pint	num_sets;	\fInumber of facets (fill area sets)\fP
Pfacet_data_arr3	*fdata;	\fIarray of L({COLRV}{,NORM}) facet data\fP
Pedge_data_list_list	*edata;	\fIarray of L(L(E)) edge data\fP
Pint_list_list	*vlist;	\fIarray of L(L(I)) vertex indices\fP
Pfacet_vdata_list3	*vdata;	\fIarray of L(P3,{COLRV}{,NORM}) facet vertex data\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET OF FILL AREA SET 3 WITH DATA\s+2 creates a set of 
fill area set 3 primitive with colour and shading data.  
.LP
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 \s-2FILL AREA SET 3 WITH DATA\s+2
primitives.
.\" .LP
.\" This is a \s-2PHIGS\s0 Extension function based on 
.\" \s-2PHIGS PLUS\s+2 and is not part of the 
.\" \s-2PHIGS\s+2 standard.
.SS C Input Parameters
All of the following data types are predefined in phigs.h.
.IP \fIfflag\fR
The data per facet flag specifies the available data for each facet
in the set of fill area set 3.
.sp
.nf
.ta .5i +\w'0     'u +\w'PFACET_COLOUR_NORMAL    'u
0	PFACET_NONE	\fINo Facet Data Specified\fP
1	PFACET_COLOUR	\fIFacet Colours Specified\fP
2	PFACET_NORMAL	\fIFacet Normals Specified\fP
3	PFACET_COLOUR_NORMAL	\fIFacet Normals and Colours Specified\fP
.sp
.fi
.IP \fIeflag\fR
The data per edge flag specifies the available information for
each edge of each facet
in the set of fill area set 3.
.sp
.nf
.ta .5i +\w'0     'u +\w'PEDGE_VISIBILITY     'u
0	PEDGE_NONE	\fINo Edge Data Specified\fP
1	PEDGE_VISIBILITY	\fIEdge Visibility Flags Specified\fP
.sp
.fi
.IP \fIvflag\fR
The data per vertex flag specifies the available data for
each vertex of the primitive.
.sp
.nf
.ta .5i +\w'0     'u +\w'PVERT_COORD_COLOUR_NORMAL     'u 
0	PVERT_COORD	\fICoordinates Specified\fP
1	PVERT_COORD_COLOUR	\fICoordinates and Vertex Colours Specified\fP
2	PVERT_COORD_NORMAL	\fICoordinates and Vertex Normals Specified\fP
3	PVERT_COORD_COLOUR_NORMAL	\fICoordinates, Vertex Colours, and Vertex Normals Specified\fP
.sp
.fi
.IP \fIcolour_model\fR
The colour model for specified vertex colours.
.nf
.ta .5i +\w'0     'u +\w'PINDIRECT     'u
0	PINDIRECT	\fIColour Index Specified\fP
1	PMODEL_RGB	\fIRed, Green, and Blue\fP
2	PMODEL_CIELUV	\fICIE Colour Model\fP
3	PMODEL_HSV	\fIHue, Saturation, and Value\fP
4	PMODEL_HLS	\fIHue, Lightness, and Saturation\fP
.sp
.fi
.IP \fInum_sets\fR
The number of facets.  Each facet is one fill area set.
.IP \fIfdata\fR
A pointer to a Pfacet_data_arr3 structure
that specifies the colour and/or norm information for each facet.
Pfacet_data_arr3 is defined as: 
.sp .2
.nf
.ta .5i +\w'Pconorm3     'u +\w'*conorms;     'u
.sp .2
typedef union {	
.sp .2	
	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 */
.sp .2
} Pfacet_data_arr3;
.IP
.fi	
Pcoval is defined as: 
.sp .2
.nf
.ta .5i +\w'Pcobundl     'u +\w'direct;     'u
.sp .2
typedef union {	
.sp .2
	Pint	ind;	/* index in workstation colour bundle table */
	Pcolr_rep	direct;	/* direct colour components */
.sp .2
} Pcoval;
.IP
.fi
When colour model is \s-2PINDIRECT\s+2, index is used; otherwise
direct is used.
.IP
.fi
Pcolr_rep is defined in phigs.h as follows:
.sp .2
.ta .5i +1i +1i
.nf
.sp .2
typedef union {
.sp .2
	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 */
.sp .2
} Pcolr_rep
.fi
.IP
Prgb is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	red;	/* red, hue, etc */
	Pfloat	green;	/* green, saturation, lightness, etc */
	Pfloat	blue;	/* blue, value, saturation, etc */
.sp .2
} Prgb;
.fi
.IP
Pcieluv is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	cieluv_x;	/* x coefficient */
	Pfloat	cieluv_y;	/* y coefficient */
	Pfloat	cieluv_y_lum;	/* y luminance */
.sp .2
} Pcieluv;
.fi
.IP
Phls is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.yp .2
	Pfloat	hue;	/* hue */
	Pfloat	lightness;	/* lightness */
	Pfloat	satur;	/* saturation */
.sp .2
} Phls;
.fi
.IP
Phsv is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	hue;	/* hue */
	Pfloat	satur;	/* saturation */
	Pfloat	value;	/* value */
.sp .2
} Phsv;
.fi
.IP
Pdata is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	size_t	size;	/* size of data */
	char	*data	/* pointer to data */
.sp .2
} Pdata;
.fi
.IP
Pconorm3 is defined as:
.sp .2
.nf
.ta .5i +\w'Pvec3     'u +\w'norm;     'u
.sp .2
typedef struct {
.sp .2
	Pcoval	colr;	/* colour */
	Pvec3	norm;	/* unit normal */
.sp .2
} Pconorm3;
.IP
.fi
Pcoval is defined above.
Pvec3 is defined as:
.sp .2
.nf
.ta .5i +\w'Pfloat     'u +\w'delta_y;     'u
.sp .2
typedef struct {
.sp .2
	Pfloat	delta_x;	/* x magnitude */
	Pfloat	delta_y;	/* y magnitude */
	Pfloat	delta_z;	/* z magnitude */
.sp .2
} Pvec3;
.fi
.IP \fIedata\fR
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:
.sp .4
.nf
.ta .5i +\w'Pedge_data_list     'u +\w'num_lists;     'u
typedef struct {
.sp .2
	Pint	num_lists;	/* number of Pedge_data_lists (bounds) in list */
	Pedge_data_list	*edgelist;	/* list of edge data list */
.sp .2
} Pedge_data_list_list;             		
.IP
.fi
Pedge_data_list (list of edges for one bound) is defined as:
.sp .2
.nf
.ta .5i +\w'Pedge_data_arr     'u +\w'num_edges;     'u
.sp .2
typedef struct {
.sp .2
	Pint	num_edges;	/* number of edges */
	Pedge_data_arr	edgedata;	/* edge data */
.sp .2
} Pedge_data_list;
.IP
.fi
Pedge_data_arr is defined as:
.ta .5i +\w'Pedge_flag     'u +\w'edges;     'u
.sp .4
typedef union {
.sp .2
	Pedge_flag	*edges;	/* array of edge flags */
.fi
	/* implementation-dependent data */  	
.sp .2
} Pedge_data_arr;
.IP
.fi
Pedge_flag is defined as:
.sp .2
.nf
.ta .5i +\w'PEDGE_OFF,     'u
.sp .2
typedef enum {
.sp .2
	PEDGE_OFF,
	PEDGE_ON
.sp .2
} Pedge_flag;
.fi
.IP \fIvlist\fR
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:
.sp .4
.nf
.ta .5i +\w'Pint_list     'u +\w'num_lists;     'u
typedef struct {
.sp .2
	Pint	num_lists;	/* number of Pint_lists in list */
	Pint_list	*lists;	/* list of integer lists */
.sp .2
} Pint_list_list;
.IP
.fi
Pint_list (vertex indices for all vertices in a single bound) is defined as:
.sp .2
.nf
.ta .5i +\w'Pint     'u +\w'num_ints;     'u
.sp .2
typedef struct {
.sp .2
	Pint	num_ints;	/* number of Pints in list */
	Pint	*ints;	/* list of integers */
.fi
.sp .2
} Pint_list;
.IP \fIvdata\fR
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: 
.nf
.ta .5i +\w'Pfacet_vdata_arr3     'u +\w'num_vertices;     'u
.sp .2
typedef struct {
.sp .2
	Pint	num_vertices;	/* number of vertices */
	Pfacet_vdata_arr3	vertex_data;	/* facet vertex data */
.sp .2
} Pfacet_vdata_list3;
.IP
.fi
Pfacet_vdata_arr3 is defined as:
.sp .2
.nf
.ta .5i +\w'Pptconorm3     'u +\w'*ptconorms;     'u
.sp .2
typedef union {	
.sp .2			
	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 */
.sp .2
} Pfacet_vdata_arr3;
.IP
.fi
Ppoint3 is defined as: 
.sp .2
.nf
.ta .5i +\w'Pfloat     'u +\w'x;     'u
.sp .2
typedef struct {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
	Pfloat	z;	/* z coordinate */
.sp .2
} Ppoint3;
.IP
.fi
Pptco3 is defined as:
.sp .2
.nf
.ta .5i +\w'Ppoint3     'u +\w'colour;     'u
.sp .2
typedef struct {	
.sp .2
	Ppoint3	point;	/* point coordinates */
	Pcoval	colr;	/* colour */
.sp .2
} Pptco3;
.IP
.fi
Ppoint3 and Pcoval are defined above.
.\" Pcoval is defined as:	 
.\" .sp .2
.\" .nf
.\" .ta .5i +\w'Pcolr_rep     'u +\w'direct;     'u
.\" .sp .2
.\" typedef union {	
.\" .sp .2
.\" 	Pint	ind;	/* index in workstation colour bundle table */
.\" 	Pcolr_rep	direct;	/* direct colour components */
.\" .sp .2
.\" } Pcoval;
.\" .IP
.\" .fi
.\" When colour model is \s-2PINDIRECT\s+2, index is used; otherwise
.\" direct is used.
.\" .IP
.\" .fi
.\" Pcolr_rep is defined as:
.\" .ta .5i +1i +1i
.\" .nf
.\" .sp .2
.\" typedef union {
.\" .sp .2
.\" 	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 */
.\" .sp .2
.\" } Pcolr_rep
.\" .fi
.\" .IP
.\" Prgb is defined in phigs.h as follows:
.\" .nf
.\" .ta .5i +1i +1i
.\" .sp .2
.\" typedef struct {
.\" .sp .2
.\" 	Pfloat	red;	/* red, hue, etc */
.\" 	Pfloat	green;	/* green, saturation, lightness, etc */
.\" 	Pfloat	blue;	/* blue, value, saturation, etc */
.\" .sp .2
.\" } Prgb;
.\" .fi
.\" .IP
.\" Pcieluv is defined in phigs.h as follows:
.\" .nf
.\" .ta .5i +1i +1i
.\" .sp .2
.\" typedef struct {
.\" .sp .2
.\" 	Pfloat	cieluv_x;	/* x coefficient */
.\" 	Pfloat	cieluv_y;	/* y coefficient */
.\" 	Pfloat	cieluv_y_lum;	/* y luminance */
.\" .sp .2
.\" } Pcieluv;
.\" .fi
.\" .IP
.\" Phls is defined in phigs.h as follows:
.\" .nf
.\" .ta .5i +1i +1i
.\" .sp .2
.\" typedef struct {
.\" .sp .2
.\" 	Pfloat	hue;	/* hue */
.\" 	Pfloat	lightness;	/* lightness */
.\" 	Pfloat	satur;	/* saturation */
.\" .sp .2
.\" } Phls;
.\" .fi
.\" .IP
.\" Phsv is defined in phigs.h as follows:
.\" .nf
.\" .ta .5i +1i +1i
.\" .sp .2
.\" typedef struct {
.\" .sp .2
.\" 	Pfloat	hue;	/* hue */
.\" 	Pfloat	satur;	/* saturation */
.\" 	Pfloat	value;	/* value */
.\" .sp .2
.\" } Phsv;
.\" .fi
.\" .IP
.\" Pdata is defined in phigs.h as follows:
.\" .nf
.\" .ta .5i +1i +1i
.\" .sp .2
.\" typedef struct {
.\" .sp .2
.\" 	size_t	size;	/* size of data */
.\" 	char	*data	/* pointer to data */
.\" .sp .2
.\" } Pdata;
.\" .fi
.IP
Pptnorm3 is defined as:
.sp .2
.nf
.ta .5i +\w'Ppoint3     'u +\w'norm;     'u
.sp .2
typedef struct {	
.sp .2
	Ppoint3	point;	/* point coordinates */
	Pvec3	norm;	/* unit normal */
.sp .2
} Pptnorm3;
.IP
.fi
Ppoint3 and Pvec3 are defined above.
.\" .sp .2
.\" .nf
.\" .ta .5i +\w'Pfloat     'u +\w'delta_y;     'u
.\" .sp .2
.\" typedef struct {
.\" .sp .2
.\" 	Pfloat	delta_x;	/* x magnitude */
.\" 	Pfloat	delta_y;	/* y magnitude */
.\" 	Pfloat	delta_z;	/* z magnitude */
.\" .sp .2
.\" } Pvec3;
.IP
.fi
Pptconorm3 is defined as: 
.sp .2
.nf
.ta .5i +\w'Ppoint3     'u +\w'norm;     'u
.sp .2
typedef struct {	
.sp .2
	Ppoint3	point;	/* point coordinates */
	Pcoval	colr;	/* colour */
	Pvec3	norm;	/* unit normal */
.sp .2
} Pptconorm3;
.IP
.fi
Ppoint3, Pcoval, and Pvec3 are defined above.
.SS Execution
Depending on the edit mode, a \s-2SET OF FILL AREA SET 3 WITH DATA\s+2
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 \s-2SET OF FILL AREA SET 3 WITH DATA\s+2 element.
.LP
When the structure is traversed, \s-2SET OF FILL AREA SET 3 WITH DATA\s+2
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.
.LP    
\s-2SET OF FILL AREA SET 3 WITH DATA\s+2 uses the same attributes as the
\s-2FILL AREA SET 3 WITH DATA\s+2 structure element. 
.LP
Vertex and facet colours and normals are used to calculate the set 
colour and shading. The \s-2SET OF FILL AREA SET 3 WITH DATA\s+2
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. 
.LP
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 \s-2EDGE FLAG\s+2 attribute and
the edge visibility flag are both \s-2ON\s+2. If edge visibility
flags are not specified, no edges are displayed. 
.SS Attributes Applied
The attributes listed below are used to display the
\s-2SET OF FILL AREA SET 3 WITH DATA\s+2 primitive when the structure is traversed. The Aspect Source 
Flags (\s-2ASF\s+2s) 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.
.sp 
.RS
.nf
.ta .5i +\w'back interior reflectance equation   'u 
.sp
interior colour			interior colour index \s-2ASF\s+2
back interior colour		back interior colour \s-2ASF\s+2
interior style			interior style \s-2ASF\s+2
back interior style		back interior style \s-2ASF\s+2
interior style index		interior style index \s-2ASF\s+2
back interior style index	back interior style index \s-2ASF\s+2
interior shading method		interior shading method \s-2ASF\s+2
back interior shading method	back interior shading method \s-2ASF\s+2
interior reflectance equation 	interior reflectance equation \s-2ASF\s+2
back interior reflectance equation	back interior reflectance equation \s-2ASF\s+2
area properties			area properties \s-2ASF\s+2
back area properties		back area properties \s-2ASF\s+2
interior index
edge colour			edge colour \s-2ASF\s+2
edge flag			edge flag \s-2ASF\s+2
edgetype			edgetype \s-2ASF\s+2
edgewidth scale factor		edgewidth scale factor \s-2ASF\s+2
edge index
face distinguishing mode
face culling mode
depth cue index
light source state
name set
.fi
.RE
.sp .2
.SH ERRORS
.IP 005
Ignoring function, function requires state 
(\s-2PHOP\s+2, \s-2*\s+2, \s-2STOP\s+2, \s-2*\s+2)
.IP 504
Ignoring function, one or more of the vertex indices is out
of range
.IP 513
Ignoring function, inconsistent edge flag specification.
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "FILL AREA SET 3 WITH DATA (3P+)"
.SM "INTRO PHIGS PLUS (3P+)"
.fi