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

.\"##
.\" $XConsortium: p236,v 5.1 91/02/16 09:41:18 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.
.ds f \s-2NON-UNIFORM B-SPLINE SURFACE\s+2
.TH "NON-UNIFORM B-SPLINE SURFACE" 3P+ "29 February 1991"
.SH NAME
NON-UNIFORM B-SPLINE SURFACE \- create a non-uniform B-spline surface structure element
.IX "NURB functions" "NON-UNIFORM B-SPLINE SURFACE"
.IX "PHIGS Extension Functions" "NON-UNIFORM B-SPLINE SURFACE"
.IX "Filled Area Primitives" "NON-UNIFORM B-SPLINE SURFACE"
.IX "Primitives, Filled Area Primitives" "NON-UNIFORM B-SPLINE SURFACE"
.IX "Splines" "NON-UNIFORM B-SPLINE SURFACE"
.IX "Trimming Curve" "NON-UNIFORM B-SPLINE SURFACE"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
pnuni_bsp_surf ( uorder, vorder, uknots, vknots, rationality, grid, nloops, tloops )
Pint	uorder;	\fIU spline order\fP
Pint	vorder;	\fIV spline order\fP
Pfloat_list	*uknots;	\fIU knots\fP
Pfloat_list	*vknots;	\fIV knots\fP
Prational	rationality;	\fIrationality selector\fP
Ppoint_grid34	*grid;	\fIgrid of 3D or 4D control points\fP
Pint	nloops;	\fInumber of trim curve loops\fP
Ptrimcurve_list	*tloops;	\fItrim curve loops\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
\s-2NON-UNIFORM B-SPLINE SURFACE\s+2 
creates a structure element containing
the definition of a non-uniform
B-spline surface.
.SS C Input Parameters
.IP "\fIuorder, vorder\fP"
Order of the surface in the \fIu\fP and \fIv\fP dimensions, respectively.
.IP "\fIuknots, vknots\fP"
Pointers to Pfloat_list structures listing the knots for the \fIu\fP and
\fIv\fP dimensions of the surface.
Pfloat_list is defined in phigs.h as follows:
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pint	num_floats;	/* number of Pfloats in list */
	Pfloat	*floats;	/* list of floats */
.sp .2
} Pfloat_list;
.IP
.fi
.IP \fIrationality\fP
The rationality selector.  Prational is defined in phigs.h as follows:
.sp .2
.nf
.sp .2
typedef enum {
.sp .2
	PNON_RATIONAL = 0,
	PRATIONAL = 1
.sp .2
} Prational;
.IP
.fi
.IP \fIgrid\fP
Pointer to a Ppoint_grid34 structure containing the surface control points.
Ppoint_grid34 is defined in phigs.h as follows:
.sp .2
.nf
.ta .5i +.5i +.75i +.75i
.sp .2
typedef struct {			/* grid of 3D or 4D points, [u_dim] [v_dim] */
.sp .2
    Ppcs_dims	num_points;		/* number of points in each dimension */
    union {
	Ppoint3	*point3d;		/* array of 3D points */
	Ppoint4	*point4d;		/* array of 4D points */
    } points;
.sp .2
} Ppoint_grid34;
.IP
.fi
Ppcs_dims is defined in phigs.h as:
.sp .2
.nf
.ta .5i +\w'Pint     'u +\w'u_dim;     'u
.sp .2
typedef struct {
.sp .2
	Pint	u_dim;	/* dimension (number of divisions) along u */
	Pint	v_dim;	/* dimension (number of divisions) along v */
.sp .2
} Ppcs_dims;
.IP
.fi
Ppoint3 is defined in phigs.h 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
Ppoint4 is defined in phigs.h 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 */
	Pfloat	w;	/* w coordinate */
.sp .2
} Ppoint4;
.IP
.fi
.IP \fInloops\fP
Number of trimming curve loops.
.IP \fItloops\fP
A pointer to an array of Ptrimcurve_list structures that specifies the trimming
curve loops. Each of these structures contains the specification of an
individual trimming curve loop (set of trimming curves).
Ptrimcurve_list is defined in phigs.h as:
.sp .2
.nf
.ta .5i +\w'Ptrimcurve     'u +\w'num_curves;     'u
.sp .2
typedef struct {
.sp .2
	Pint	num_curves;	/* number of trimming curves in list */
	Ptrimcurve	*curves;	/* list of curves */
.sp .2
N
} Ptrimcurve_list;
.IP
.fi
Ptrimcurve is defined in phigs.h as:
.sp .2
.nf
.ta .5i +\w'Ppoint_list23     'u +\w'tmin, tmax;     'u
.sp .2
typedef struct {
.sp .2
	Pedge_flag	visible;	/* curve visibility flag */
	Prational	rationality;	/* rationality */
	Pint	order;	/* curve order */
	Pint	approx_type	/* approximation type */
	Pfloat	approx_val	/* approximation value */
	Pfloat_list	knots;	/* curve knot vector */
	Pfloat	tmin, tmax;	/* curve parameter range */
	Ppoint_list23	cpts;	/* control points */
.sp .2
} Ptrimcurve;
.IP
.fi
Pedge_flag is defined in phigs.h as:
.sp .2
.nf
.sp .2
typedef enum {
.sp .2
	PEDGE_OFF,
	PEDGE_ON
.sp .2
} Pedge_flag;
.IP
.fi
Prational is defined in phigs.h as:
.sp .2
.nf
.sp .2
typedef enum {
.sp .2
	PNON_RATIONAL = 0,
	PRATIONAL = 1
.sp .2
} Prational;
.IP
.fi
Pfloat_list is defined in phigs.h as:
.sp .2
.nf
.ta .5i +\w'Pfloat     'u +\w'num_floats;     'u
typedef struct {
.sp .2
	Pint	num_floats;	/* number of Pfloats in list */
	Pfloat	*floats;	/* list of floats */
.sp .2
} Pfloat_list;
.IP
.fi
Ppoint_list23 is defined in phigs.h as:
.sp .2
.nf
.ta .5i +\w'} points;     'u +\w'Ppoint3     'u +\w'num_points	'u 
.sp .2
typedef struct {			 /* list of 2D or 3D points */
.sp .2
	Pint		num_points;		/* number of points */
	union {
		Ppoint	*point2d;		/* array of 2D points */
		Ppoint3	*point3d;		/* array of 3D points */
	} points;
.sp .2
} Ppoint_list23;
.IP
.fi
The \fIpoint3d\fR member of the points union is used if the
rationality member of Ptrimcurve is \s-2PRATIONAL\s+2;
otherwise, the \fIpoint2d\fR member is used.
Ppoint is defined in phigs.h 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 */
.sp .2
} Ppoint;
.IP
.fi
Ppoint3 is defined in phigs.h 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
.SS Execution
.LP
Depending on the edit mode, a \s-2NON-UNIFORM B-SPLINE SURFACE\s+2
element is either inserted into the open structure
after the element pointer, or replaces the element pointed at by the
element pointer.  The element pointer is then updated to point to this
\s-2NON-UNIFORM B-SPLINE SURFACE\s+2 structure element.
.LP
The surface \fIu\fP and \fIv\fP orders must be positive integers.
Surfaces of unsupported orders in either dimension will be displayed by
drawing the control grid; that is, the corresponding surface of order 2 in
both dimensions.
.LP
The \fIu\fP and \fIv\fP knots must each form a non-decreasing
sequence of numbers.
.LP
The \fIrationality selector\fP parameter may have the enumerated value
\fIRational\fP or \fINon-rational\fP.
When \fIRational\fP is specified, the control points must be specified as
4D homogeneous modelling coordinates. When \fINon-rational\fP is
specified, the control points are 3D \s-2PHIGS\s+2 modelling coordinates.
.LP
The number of control points in the \fIu\fP and \fIv\fP directions must be
at least as large as the corresponding order.  The number of control points
in each direction plus the corresponding spline order must be equal to the 
corresponding number of knots.
.LP
At structure traversal time, a \s-2NON-UNIFORM B-SPLINE SURFACE\s+2
primitive is drawn using the attributes that apply to
\s-2FILL AREA SET 3\s+2 primitives, plus
the extended interior attributes.  See
\s-2SET INTERIOR REPRESENTATION PLUS\s+2
for a listing of these.
.SS Trimming Curves
.LP
The surface parameter area to be rendered may be defined by trimming curves.
The trimming definition of a surface consists of a list of loops.
Each of these loops is a list of one or more trimming curves. Each
trimming curve is a non-uniform
rational B-spline curve defined in the 2D parameter space of the surface.
The curves of a loop connect in a head-to-tail fashion. Each loop must be
explicitly closed.
.LP
The restrictions on trimming curves are the same as those for
non-uniform B-spline curves, and are specified in the function
\s-2NON-UNIFORM B-SPLINE CURVE\s+2.
.LP
The trimming curves associated with a surface can touch each other only at their
end points. No other pair of trimming curves can connect at that same point. A
trimming curve cannot be self-touching or self-intersecting.
.LP
If trimming curves are specified, then they define the edges of the
surface.  Each trimming curve has a flag that controls its visibility.
These visibility flags have lower precedence than the edge flag
attribute and are ignored if the edge flag attribute is set to \s-2OFF\s+2.
.LP
\s-2PHIGS PLUS\s0 restricts trimming loops of a single surface
primitive to a certain canonical form. This form must redundantly
identify the interior parameter area in two different ways:
according to the odd winding
and the curve handedness rules.
.SS Attributes Applied
The attributes listed below are used to display the
\s-2NON-UNIFORM B-SPLINE SURFACE\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 pipline context,
or they can be accessed indirectly, using the appropriate index 
in the pipline context and the corresponding bundled 
representation in the PHIGS workstation state list.
.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 index \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
surface approximation criteria	surface approximation criteria \s-2ASF\s+2
trimming curve approximation criteria	trimming curve approximation criteria \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, *, STOP, *\s+2)
.IP 600
Ignoring function, not enough control points for specified order
.IP 601
Ignoring function, knot sequence is not non-decreasing
.IP 602
Ignoring function, order is inconsistent with number of knots and control
points specified
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET SURFACE APPROXIMATION CRITERIA (3P+)"
.SM "NON-UNIFORM B-SPLINE CURVE (3P+)"
.SM "SET INTERIOR REPRESENTATION PLUS (3P+)"
.SM "INQUIRE CURVE AND SURFACE FACILITIES (3P+)"
.fi