.\" @(#)PEXNURBSurface.3 1.5 95/03/24 SMI;
.so man3/pex.macs
.TH PEXNURBSurface 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXNURBSurface - Non-Uniform Rational B-spline Surface Primitive
.SH SYNTAX
.HP
void PEXNURBSurface\^(\^Display *\fIdisplay\fP\^, XID \fIresource_id\fP\^, PEXOCRequestType \fIreq_type\fP\^, int \fIrationality\fP\^, int \fIuorder\fP\^, int \fIvorder\fP\^, float *\fIuknots\fP\^, float *\fIvknots\fP\^, unsigned int \fIcol_count\fP\^, unsigned int \fIrow_count\fP\^, PEXArrayOfCoord \fIpoints\fP\^, unsigned int \fIcurve_count\fP\^, PEXListOfTrimCurve *\fItrim_curves\fP\^)
.SH PARAMETERS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.IP \fIresource_id\fP 1i
The resource identifier of the renderer or structure.
.IP \fIreq_type\fP 1i
The request type for the output command (
.B PEXOCRender,
.B PEXOCStore,
.B PEXOCRenderSingle
or
.B PEXOCStoreSingle
).
.IP \fIrationality\fP 1i
The type of B-spline surface, whether rational or non-rational
.B PEXRational
or
.B PEXNonRational
).
.IP \fIuorder\fP 1i
The order of the polynomial expression in the u direction.
.IP \fIvorder\fP 1i
The order of the polynomial expression in the v direction.
.IP \fIuknots\fP 1i
An array of floats specifying the B-spline curve knots in the u direction.
.IP \fIvknots\fP 1i
An array of floats specifying the B-spline curve knots in the v direction.
.IP \fIcol_count\fP 1i
The number of columns in the points array (number of points in the u direction).
.IP \fIrow_count\fP 1i
The number of rows in the points array (number of points in the v direction).
.IP \fIpoints\fP 1i
An array of points defining the B-spline surface.
.IP \fIcurve_count\fP 1i
The number of trimming curves.
.IP \fItrim_curves\fP 1i
A pointer to a list of trimming curves.
.SH RETURNS
.LP
None
.SH DESCRIPTION
.\" indexing
.IX PEXNURBSurface
.IX "Nurb" "PEXNURBSurface"
.LP
This function creates a non-uniform B-spline surface output primitive.
.LP
The surface is generated as a function of the parametric
variables u and v.
The u and v order must be positive integers and
indicate the order of the surface in each of the u and v parameter dimensions.
.BR PEXGetImpDepConstants (3)
can be called to determine
the largest supported value for surface u and v order.
The spline
shape is specified using two lists of knots in the parametric coordinate
space, plus an array of control points specified in
modeling coordinates.  The u and v knot
sequences must each form a non-decreasing sequence of numbers.
The column count indicates the number of control points in the u direction and
the row count indicates the number of control points in the v direction.
The control points are stored in the array in row-major order (i.e., the column
number varies fastest as vertices are stored in the array) and the rows
increase in the direction of increasing v.
The number of knots in the u direction is the sum of the order in the u
direction and column count.
The number of knots in the v direction is the sum of the order in the v
direction and row count.
The number of control points in each direction must be at least as large as the
corresponding order.
.LP
The minimum and maximum knot values define the range over
which the B-spline surface is evaluated in the u or v parametric direction,.
.LP
If the rationality is
.B PEXRational,
the control point list must be specified in
homogeneous (4D) modeling coordinates.  If rationality is
.B PEXNonRational,
the control point list must be specified in non-homogeneous (3D) modeling
coordinates.
.LP
In addition to the parametric bounds, a list of trimming loops may also
be specified.  Trimming loops serve to further restrict the region in
parametric coordinate space over which the surface is evaluated.
Each trimming loop is defined as a list of one or more B-spline trimming curves
that are connected head-to-tail.  Each trim curve is a completely specified
NURB curve, i.e. it is rational or non-rational, has its own order, etc.
The list must be explicitly closed so that the tail of the last curve
joins the head of the first.  Each trimming curve is parameterized
independently.  If there is floating point inaccuracy in closure or in
head-to-tail connectivity between curves, closure or connectivity will be
assumed.  Trimming loops are defined in the parameter space of the surface
and may not go outside the parameter space of the surface.
.LP
When no trimming
loops are specified, the rectangular parameter limits of the surface are
renderer as the edges of the surface based on the edge flag attribute.
.LP
Trimming loops define the region of the surface that is to be rendered based
on the following two rules:  (1) a point is in the portion of the surface to
be rendered if any ray projected from it to infinity has an odd number of
intersections with trimming loops, and (2) traveling in the direction of a
trimming loop, the portion of the surface to be trimmed away should be on
the right and the portion to be retained should be on the left.  In other
words, a loop defined in counter-clockwise order will cause the interior of
the loop to be retained and the exterior to be trimmed away.
A clockwise loop will cause the exterior of
the loop to be retained and the interior to be trimmed away.
If loops are
nested, they must alternate in direction.  In all cases, the outermost loop
must be counter-clockwise.  No trimming curve may intersect
itself and no trimming loop may intersect itself or any other trimming loop.
Trimming loops that do
not obey these rules will result in implementation-dependent behavior.
.LP
Each trimming curve has a visibility flag that controls its visibility
for the purposes of surface edge display.  Depending on the surface edge
attributes and the visibility flags associated with trimming curves, the
curves in trimming loops may be drawn as surface edges.
.LP
All attributes affecting the representation of fill area sets
also affect the representation of the non-unform B-spline surface
primitive.  In addition, the surface approximation
is used to determine how to
approximate the B-spline surface and the parametric surface characteristics
are used to specify the appearance of the surface.
.LP
If either of the specified surface orders are not supported, the output
primitive
is stored in a structure, but when rendered, the primitive
is ignored and has no visual effect.
.LP
Trimming curve specification must abide by the constraints of NURB curve
(e.g. number of control points at least as large as the order, non-decreasing
knot sequence, order plus number of controls points equals the number of
knots).
Also, the trim curve order must not be less than two.
.SH DATA STRUCTURES
.LP
.nf
typedef union {
	PEXCoord2D	*point_2d;
	PEXCoord	*point;
	PEXCoord4D	*point_4d;
.br
} PEXArrayOfCoord;	/* Pointer to array of points */
.sp
typedef struct {
	unsigned short		count;		/* number of curves */
	PEXTrimCurve		*curves;
.br
} PEXListOfTrimCurve;
.sp
typedef struct {
	PEXSwitch		visibility;		/* True or False */
	unsigned char		reserved;
	unsigned short		order;
	PEXCoordType		rationality;		/* PEXRational or PEXNonRational */
	PEXEnumTypeIndex	approx_method;	/* see PEXGetEnumTypeInfo */
	float			tolerance;
	float			tmin, tmax;
	PEXListOfFloat		knots;
	unsigned short		count;			/* number of control points */
	PEXArrayOfCoord	control_points;
.br
} PEXTrimCurve;
.sp
typedef  unsigned char	    PEXSwitch;
typedef  unsigned short	    PEXCoordType;
typedef  short		    PEXEnumTypeIndex;
.sp
typedef struct {
	unsigned short		count;		/* number of floats */
	float			*floats;
.br
} PEXListOfFloat;
.fi
.sp .5
See also
.B PEXlib.h.
.SH ERRORS
.TP
.SB BadPEXOutputCommand
The output command contains an invalid value.
.TP
.SB BadPEXRenderer
The specified renderer resource identifier is invalid.
.TP
.SB BadPEXStructure
The specified structure resource identifier is invalid.
.SH SEE ALSO
.LP
.nf
.BR PEXSetInteriorStyle (3)
.BR PEXSetInteriorStyleIndex (3)
.BR PEXSetSurfaceColorIndex (3)
.BR PEXSetSurfaceColor (3)
.BR PEXSetReflectionAttributes (3)
.BR PEXSetReflectionModel (3)
.BR PEXSetSurfaceInterpMethod (3)
.BR PEXSetBFInteriorStyle (3)
.BR PEXSetBFInteriorStyleIndex (3)
.BR PEXSetBFSurfaceColorIndex (3)
.BR PEXSetBFSurfaceColor (3)
.BR PEXSetBFReflectionAttributes (3)
.BR PEXSetBFReflectionModel (3)
.BR PEXSetBFSurfaceInterpMethod (3)
.BR PEXSetSurfaceApprox (3)
.BR PEXSetFacetCullingMode (3)
.BR PEXSetFacetDistinguishFlag (3)
.BR PEXSetPatternSize (3)
.BR PEXSetPatternAttributes (3)
.BR PEXSetPatternAttributes2D (3)
.BR PEXSetInteriorBundleIndex (3)
.BR PEXSetSurfaceEdgeFlag (3)
.BR PEXSetSurfaceEdgeType (3)
.BR PEXSetSurfaceEdgeWidth (3)
.BR PEXSetSurfaceEdgeColor (3)
.BR PEXSetSurfaceEdgeColorIndex (3)
.BR PEXSetEdgeBundleIndex (3)
.BR PEXSetParaSurfCharacteristics (3)
.BR PEXGetImpDepConstants (3)
.fi