spline_torus(3G)

NAME

spline_torus − draw a torus using a spline surface

SYNOPSIS

C Syntax:

void spline_torus(fildes,min_rad,maj_rad,x,y,z,
dirx,diry,dirz,refx,refy,refz);
int fildes;
float min_rad,maj_rad,x,y,z,dirx,diry,dirz,refx,refy,refz;

FORTRAN77 Syntax:

subroutine spline_torus(fildes,min_rad,maj_rad,x,y,z,
dirx,diry,dirz,refx,refy,refz)
integer*4 fildes
float min_rad,maj_rad,x,y,z,dirx,diry,dirz,refx,refy,refz

Pascal Syntax:

procedure spline_torus(fildes:integer;min_rad,maj_rad,
x,y,z,dirx,diry,dirz,refx,refy,refz:real);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.

min_rad Radius of the circle that is swept around the major radius of the torus to form the torus surface.

maj_rad Radius of the circle about which the torus is constructed.

x,y,z Position of the torus center in modelling coordinates.

dirx,diry,dirz Defines the direction vector, anchored at (x,y,z), of the torus’ central axis

refx,refy,refz Defines a direction that determines the (u,v) origin of the torus’ spline surface.

Discussion

spline_torus draws a torus (donut) shaped rational spline surface. The torus is drawn by first centering a circle with a radius of maj_rad at (x,y,z) and then sweeping around it a second circle of radius min_rad. The first circle is drawn perpendicular to the central axis of the torus. The second circle is centered on the edge of the first, and is always contained in the plane formed by its own centerpoint and the central axis. The equator of the torus is described by a circle with a radius of maj_rad − 0.5(min_rad) that is centered at (x,y,z) and coplanar with the maj_rad circle.

The torus’s central axis runs through (x,y,z) in the direction defined by (dirx,diry,dirz). The (dirx,diry,dirz) direction vector need not be normalized to unit length.

spline_torus converts these parameters into a 9×9 (quadratic, quadratic) control-point matrix that defines a sixteen-patch (4×4) spline surface. The (u,v) origin and the orientation of this spline surface are determined by the reference direction (refx,refy,refz). The reference direction need not be normalized and need not be perpendicular to the central axis. The (u,v) origin of the torus is the point on the equator closest to (refx,refy,refz). The u axis maps in a right-hand fashion from the origin, where u=0.0, proceeding around the equator to u=1.0. The v axis maps from v=0.0 at the equator and proceeds down and around the minor radius of the torus: through v=0.25 at the bottom of the torus, v=0.5 at the outside, v=0.75 at the top, and ending at v=1.0 back inside at the equator.

In cases where the precise orientation of the (u,v) space does not matter, (if trimming curves are not used, for example), (refx,refy,refz) can be arbitrarily set. For fastest performance, set (refx,refy,refz) to (0.0,0.0,0.0).

If (refx,refy,refz) is set either to (0.0,0.0,0.0) or is parallel to the axis, and trim curves are used, a reference point of (1.0,0.0,0.0) is set relative to a central axis direction of (0.0,0.0,1.0). The transformation from (0.0,0.0,1.0) to the central axis also transforms the default reference direction to its new orientation.

spline_torus handles degenerate “apple” forms of the torus that occur when min_rad is larger than maj_rad by creating and rendering all overlapping surfaces inside the torus.

Because the torus is rendered as a spline surface, it is subject to all conditions set by the user with functions such as vertex_format, curve_resolution, trimming_curve, etc. A vertex_format of CLOCKWISE (0) is used to display the outside of the surface, while COUNTER_CLOCKWISE (1) displays the inner surface. spline_torus sets its own u and v knot vectors, ignoring any existing Starbase knot vectors. Existing Starbase knot vectors are saved when spline_torus is called and restored after the call.

NOTES

This primitive command can be used with all global and non-global rendering modes.

Starbase texture mapping may be applied to spline tori. The mapping of textures onto the torus is determined by the (u,v) mapping of the spline surface on the torus.

The Starbase ray tracer is optimized for the smooth shaded torus, as it uses the algebraic form to render the object. A torus which is passed to the ray tracer without smooth shading (no normals per vertex), will be treated by the ray tracer as an ordinary spline surface, which requires a slower and more memory-intensive rendering.

ERRORS

Invalid file descriptor.
maj_rad less than 0.0.
min_rad less than or equal to 0.0.
dirx, diry, and dirz all equal to 0.0.

Museum

Related Articles