G3dVector.mesa
Copyright Ó 1984, 1992 by Xerox Corporation. All rights reserved.
Bloomenthal, July 15, 1992 6:26 pm PDT
Andrew Glassner February 14, 1991 9:02 am PST
DIRECTORY G3dBasic, G3dMatrix;
G3dVector: CEDAR DEFINITIONS
~ BEGIN
Type Declarations
Box:    TYPE ~ G3dBasic.Box;
Pair:    TYPE ~ G3dBasic.Pair;
Triple:   TYPE ~ G3dBasic.Triple;
Quad:    TYPE ~ G3dBasic.Quad;
Ray:    TYPE ~ G3dBasic.Ray;
TripleSequence: TYPE ~ G3dBasic.TripleSequence;
Matrix:   TYPE ~ G3dMatrix.Matrix;
NearSegment:   TYPE ~ RECORD [
point:        Triple ¬ [],    -- point on 3d segment
inside:       BOOL ¬ FALSE,   -- true iff point inside segment
w0, w1:       REAL ¬ 0.0    -- point = w0*p0+w1*p1
];
origin:   Triple ~ G3dBasic.origin;
Basic Operations on a Single Vector
Null: PROC [v: Triple] RETURNS [BOOL];
Returns TRUE iff v is the origin.
Negate: PROC [v: Triple] RETURNS [Triple];
Vector negation: return -v.
Unit: PROC [v: Triple] RETURNS [Triple];
Vector normalization: return v/|v|.
Mul: PROC [v: Triple, s: REAL] RETURNS [Triple];
Vector scalar multiplication: return s*v.
Div: PROC [v: Triple, s: REAL] RETURNS [Triple];
Vector scalar division: return v/s; division not performed if s = 0.
Abs: PROC [v: Triple] RETURNS [Triple];
Return the absolute values of v's components.
Basic Operations on Two Vectors
Add: PROC [v1, v2: Triple] RETURNS [Triple];
Vector additon: return v1+v2.
Sub: PROC [v1, v2: Triple] RETURNS [Triple];
Vector subtraction: return v1-v2.
Equal: PROC [v1, v2: Triple, epsilon: REAL ¬ 0.001] RETURNS [BOOL];
Returns TRUE iff v1 = v2, to within epsilon.
Dot: PROC [v1, v2: Triple] RETURNS [REAL];
Vector dot product: return v1.v2.
Cross: PROC [v1, v2: Triple] RETURNS [Triple];
Right handed vector cross product: v1 v2.
Midpoint: PROC [v1, v2: Triple] RETURNS [Triple];
Return 0.5*(v1+v2).
Interp: PROC [t: REAL, v1, v2: Triple] RETURNS [Triple];
Return v1+t(v2-v1).
InterpQuad: PROC [t: REAL, v1, v2: Quad] RETURNS [Quad];
Return v1+t(v2-v1).
Combine: PROC [v1: Triple, s1: REAL, v2: Triple, s2: REAL] RETURNS [Triple];
Return s1*v1+s2*v2.
ScaleRay: PROC [ray: Ray, d: REAL] RETURNS [Triple];
Return l.base+d*l.axis.
MulVectors: PROC [v1, v2: Triple] RETURNS [Triple];
Return v1*v2.
DivVectors: PROC [v1, v2: Triple] RETURNS [Triple];
Return v1/v2; component division not performed if v2 component = 0.
Basic Operations on Sequence of Vectors
UnitizeSequence: PROC [triples: TripleSequence];
Unitize the sequence of vectors.
NegateSequence: PROC [triples: TripleSequence];
Negate the sequence of vectors.
MinMaxSequence: PROC [triples: TripleSequence] RETURNS [Box];
Return the bounding triples of the sequence.
Length and Distance Operations
Length: PROC [v: Triple] RETURNS [REAL];
Vector length: return SqRt[v.v] = |v|.
Square: PROC [v: Triple] RETURNS [REAL];
Vector length squared: return |v||v| (same as Dot[v, v]).
Distance: PROC [p1, p2: Triple] RETURNS [REAL];
Distance between two points.
SquareDistance: PROC [p1, p2: Triple] RETURNS [REAL];
Distance squared between two points.
SameLength: PROC [v1, v2: Triple] RETURNS [Triple];
Return v2 adjusted to be same magnitude as v1.
SetVectorLength: PROC [v: Triple, length: REAL] RETURNS [Triple];
Return v adjusted to be of magnitude length.
Directional Tests
Collinear: PROC [p1, p2, p3: Triple, epsilon: REAL ¬ 0.01] RETURNS [BOOL];
Return TRUE iff the three points are colinear, to within epsilon.
VecsCoplanar: PROC [v1, v2, v3: Triple, epsilon: REAL ¬ 0.005] RETURNS [BOOL];
Return TRUE iff the three vectors are coplanar.
PointsCoplanar: PROC [p1, p2, p3, p4: Triple, epsilon: REAL ¬ 0.005] RETURNS [BOOL];
Return TRUE iff the four points are coplanar, ie., all within epsilon distance of a plane.
Parallel: PROC [v1, v2: Triple, epsilon: REAL ¬ 0.005] RETURNS [BOOL];
Return TRUE iff the two vectors are parallel, to within epsilon.
Perpendicular: PROC [v1, v2: Triple, epsilon: REAL ¬ 0.005] RETURNS [BOOL];
Return TRUE iff the two vectors are perpendicular, to within epsilon.
FrontFacing: PROC [vector, base: Triple, view: Matrix] RETURNS [BOOL];
Return TRUE iff the transformed vector is front-facing (the z component < 0).
This is useful for culling back-facing polygons; view may or may not contain perspective.
FrontFacingNoPerspective: PROC [vector: Triple, view: Matrix] RETURNS [BOOL];
Return TRUE iff the transformed vector is front-facing (the z component < 0).
This is useful for culling back-facing polygons if the view does not contain perspective.
FrontFacingWithPerspective: PROC [vector, base: Triple, invView: Matrix] RETURNS [BOOL];
Transform world space plane to view space and test z component of normal:
invView is the INVERSE of the actual world-to-view matrix.
Return TRUE iff the transformed vector is front-facing (the z component < 0).
This is useful for culling back-facing polygons if the view does contain perspective.
Nearness Operations
NearnessAccelerator: PROC [p0, p1: Triple] RETURNS [Quad];
Return the 3d accelerator for computing nearest point on the p0-p1 segment.
NearestToSegment: PROC [p0, p1, q: Triple, acc: Quad ¬ [0, 0, 0, 0]] RETURNS [NearSegment];
Return the triple on line segment p0p1 nearest to q.
If acc # [0, 0, 0, 0], the calculation of NearSegment is accelerated.
NearestToLine: PROC [line: Ray, q: Triple] RETURNS [Triple];
Return point closest to q on line.
PointOnLine: PROC [p: Triple, line: Ray, epsilon: REAL ¬ 0.005] RETURNS [BOOL];
Return TRUE iff p is within epsilon of the line.
NearestToSequence: PROC [p: Triple, points: TripleSequence] RETURNS [index: NAT];
Return index such that points[index] is nearest to p.
DistanceBetween2Lines: PUBLIC PROC [line1, line2: Ray] RETURNS [REAL];
Return the distance of the closest approach of two lines.
ClosestApproach2Lines: PROC [line1, line2: Ray] RETURNS [p1, p2: Triple];
Return a point on line1 and a point on line2 that are the closest approaches of the two lines.
Presumes line1.axis and line2.axis are unitized.
Results are undefined if line1 and line2 are parallel.
Simple Geometric Operations
V90: PROC [v0, v1: Triple, unitize: BOOL ¬ TRUE] RETURNS [Triple];
Return vector orthogonal to v0 and in plane of v0 and v1; v0 and v1 presumed unitized.
Ortho: PROC [v: Triple, crosser: Triple ¬ [0.0, 0.0, 1.0]] RETURNS [Triple];
Return a vector orthonormal to both v and crosser and of the same magnitude as v; if v =
crosser, an arbitrary crosser is chosen.
RotateAbout: PROC [v, axis: Triple, a: REAL, degrees: BOOL ¬ TRUE] RETURNS [Triple];
Return v rotated around axis by a.
Polar/Cartesian Coordinates
PolarFromCartesian: PROC [cartesian: Triple] RETURNS [Triple];
Return the polar equivalent of the input cartesian vector.
The returned triple's x, y, and z fields correspond to longitude, lattitude, and magnitude.
CartesianFromPolar: PROC [polar: Triple] RETURNS [Triple];
The input triple's x, y, and z fields correspond to longitude, lattitude, and magnitude.
Return the cartesian equivalent of the input polar vector.
Longitude and lattitude are in degrees.
Miscellany
Clip: PROC [p: Triple, box: Box] RETURNS [Triple];
Return a point clipped to box.
Average: PUBLIC PROC [triples: TripleSequence] RETURNS [Triple];
Return the average of the TripleSequence.
Project: PROC [v1, v2: Triple] RETURNS [Triple];
Return the vector projection of v1 onto v2.
CosineBetween: PROC [v0, v1: Triple, unitize: BOOL ¬ FALSE] RETURNS [REAL];
Return the cosine of the angle between the two vectors. Iff unitize, do so to v0 and v1.
AngleBetween: PROC [v0, v1: Triple, degrees: BOOL ¬ TRUE, unitize: BOOL ¬ FALSE]
RETURNS [REAL];
Return the angle (in degrees if degrees TRUE, else in radians) between the two vectors.
Iff unitize, do so to v0 and v1.
END.