3d vectors
3.1.0A utility library implementing 2D, 3D, and 4D vector functionality.
About 3dvectors
This is a library for vector math in 3D space. It contains most of the vector operations one would usually expect out of such a library and offers them both in nonmodifying and modifying versions where applicable. It also tries to be efficient where plausible. Each vector is made up of float
s, which by default are singlefloat
s, as they do not require value boxing on most modern systems and compilers. Despite the name of this library, 2D and 4D vectors are supported as well.
How To
Load it through ASDF or Quicklisp
(ql:quickload :3dvectors)
(usepackage :3dvectors)
Create a vector:
(vec 0 0 0)
Vectors always use float
s. Where sensible, operations should accept real
numbers for convenience. All vector operations are prefixed with a v
to allow importing the package without conflicts.
(v+ (vec 1 2 3) 4 5 6)
3dvectors implements pretty much all vector operations you might need, including comparators, dot and cross product, and rotation. There's also modifying variants of all operators, which have the same name, except they are prefixed by an n
.
(let ((v (vec 0 0 0)))
(nv* (nv+ v (vec 1 2 3)) 3)
v)
vec
s are dumpable, meaning you can insert them as literals into your code and they will be properly saved to and restored from a FASL.
The type vec
includes all three subtypes vec2
, vec3
, and vec4
. Each of the three also has its own accessors that are suffixed with the dimension number. While the standard vx
, vy
, vz
, and vw
will result in the lowerlevel variants through an etypecase
, it is usually a good idea to use vx2
etc if the type is already known to avoid unnecessary dispatch or branch elimination.
While most of the operations work on all three variants, you cannot intermix them. For example, (v+ (vec 1 2) (vec 1 2 3))
will signal an error. This is because it is often ambiguous and thus likely confusing as to what might happen in such a case. Should the result be upgraded to a vec3
or downgraded to a vec2
? In order to avoid this ambiguity, it is simply left up to you to ensure proper types.
One convenient way to switch around between the types and generally flip around the vector fields is swizzling: similar to the singlefield accessors, there's multifield readers that construct a new vector from the specified fields of the necessary length.
(vxy (vec 1 2 3)) ; => (vec2 1 2)
(vxy_ (vec 1 2)) ; => (vec3 1 2 0)
(vwwx (vec 1 2 3 4)) ; => (vec3 4 4 1)
The _
can be used anywhere within swizzle operators in order to pad the vector with a zero. You can also use the swizzle operators as accessors to set multiple fields of a vector at once.
If you require higher precision than singlefloat
s ensure, you can add :3dvectorsdoublefloats
to *features*
and recompile the library (asdf:compilesystem :3dvectors :force T)
. Similarly, if you want to switch back to singlefloat
s, you can remove the feature and recompile. Both at the same time is not supported as it would increase complexity in the library massively and make certain operations much slower.
Also See
 3dmatrices for Matrix operations in conjunction with this library.
System Information
Definition Index

3DVECTORS
 ORG.SHIRAKUMO.FLARE.VECTOR
No documentation provided.
EXTERNAL CONSTANT +VW4+
Constant vector for the 4D unit in W direction.

EXTERNAL CONSTANT +VX+
Constant vector for the 3D unit in X direction.

EXTERNAL CONSTANT +VX2+
Constant vector for the 2D unit in X direction.

EXTERNAL CONSTANT +VX3+
Constant vector for the 3D unit in X direction.

EXTERNAL CONSTANT +VX4+
Constant vector for the 4D unit in X direction.

EXTERNAL CONSTANT +VY+
Constant vector for the 3D unit in Y direction.

EXTERNAL CONSTANT +VY2+
Constant vector for the 2D unit in Y direction.

EXTERNAL CONSTANT +VY3+
Constant vector for the 3D unit in Y direction.

EXTERNAL CONSTANT +VY4+
Constant vector for the 4D unit in Y direction.

EXTERNAL CONSTANT +VZ+
Constant vector for the 3D unit in Z direction.

EXTERNAL CONSTANT +VZ3+
Constant vector for the 3D unit in Z direction.

EXTERNAL CONSTANT +VZ4+
Constant vector for the 4D unit in Z direction.

EXTERNAL STRUCTURE VEC2
A twodimensional vector with X and Y fields.

EXTERNAL STRUCTURE VEC3
A threedimensional vector with X, Y, and Z fields.

EXTERNAL STRUCTURE VEC4
A fourdimensional vector with X, Y, Z, and W fields.

EXTERNAL TYPEDEFINITION VEC
Either a vec2, vec3, or vec4.

EXTERNAL FUNCTION NV*
 VAL
 &REST
 VALS
Same as *, but modifies the first vector. Accepts REALs or VECs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION NV+
 VAL
 &REST
 VALS
Same as +, but modifies the first vector. Accepts REALs or VECs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION NV
 VAL
 &REST
 VALS
Same as , but modifies the first vector. Accepts REALs or VECs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION NV/
 VAL
 &REST
 VALS
Same as /, but modifies the first vector. Accepts REALs or VECs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION NVABS
 VEC
Performs ABS on each component of the vector and stores back the results.

EXTERNAL FUNCTION NVCLAMP
 LOWER
 VEC
 UPPER
Clamps the vector such that each field is within [LOWER, UPPER]. Accepts REALs or VECs as limits, where REALs are used for each component of the vector.

EXTERNAL FUNCTION NVLIMIT
 VEC
 LIMIT
Limits the vector such that each field is within [LIMIT, LIMIT]. Accepts a REAL or VEc for the limit, where a REAL is used for each component of the vector.

EXTERNAL FUNCTION NVMOD
 VEC
 DIVISOR
Performs MOD on each component of the vector and stores back the results.

EXTERNAL FUNCTION NVORDER
 V
 X
 &OPTIONAL
 Y
 Z
 W
No documentation provided. 
EXTERNAL FUNCTION NVROT
 V
 AXIS
 PHI
Rotates the 3D vector around AXIS by PHI rads. The axis has to be a unit vector. This operation does not work with 2D or 4D vectors.

EXTERNAL FUNCTION NVROTV
 A
 B
Rotates the 3D vector A around each axis by the amount in B. The rotations are performed in the order of X, Y, Z. Note that rotation in 3D space is not commutative, so this function might not perform the rotation as you expected if you need the rotation to happen in a different order. This operation does not work with 2D or 4D vectors. See NVROT.

EXTERNAL FUNCTION NVSCALE
 VEC
 LENGTH
Scales the vector to be of the specified length.

EXTERNAL FUNCTION NVUNIT
 VEC
Normalizes the vector into its unit form by the 2norm.

EXTERNAL FUNCTION V*
 VAL
 &REST
 VALS
Same as *, but always returns a vector. Accepts REALs or VECs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION V+
 VAL
 &REST
 VALS
Same as +, but always returns a vector. Accepts REALs or VECs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION V
 VAL
 &REST
 VALS
Same as , but always returns a vector. Accepts REALs or VECs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION V.
 A
 B
Returns the dot product of the two vectors.

EXTERNAL FUNCTION V/
 VAL
 &REST
 VALS
Same as /, but always returns a vector. Accepts REALs or VECs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION V/=
 VAL
 &REST
 VALS
This is the same as /=, but testing all vector fields simultaneously.

EXTERNAL FUNCTION V1+
 V
Same as 1+, but returns a new vector with each component increased by 1.

EXTERNAL FUNCTION V1
 V
Same as 1, but returns a new vector with each component decreased by 1.

EXTERNAL FUNCTION V1NORM
 V
Returns the taxicab/1norm of the vector.

EXTERNAL FUNCTION V2NORM
 V
Returns the euclidean/2norm of the vector.

EXTERNAL FUNCTION V<
 VAL
 &REST
 VALS
This is the same as <, but testing all vector fields simultaneously.

EXTERNAL FUNCTION V<=
 VAL
 &REST
 VALS
This is the same as <=, but testing all vector fields simultaneously.

EXTERNAL FUNCTION V=
 VAL
 &REST
 VALS
This is the same as =, but testing all vector fields simultaneously.

EXTERNAL FUNCTION V>
 VAL
 &REST
 VALS
This is the same as >, but testing all vector fields simultaneously.

EXTERNAL FUNCTION V>=
 VAL
 &REST
 VALS
This is the same as >=, but testing all vector fields simultaneously.

EXTERNAL FUNCTION VABS
 VEC
Returns a vector with each component being the absolute value of the given vector's.

EXTERNAL FUNCTION VANGLE
 A
 B
Returns the angle between two vectors.

EXTERNAL FUNCTION VC
 A
 B
Returns the cross product of the two 3D vectors. This operation does not work with 2D or 4D vectors.

EXTERNAL FUNCTION VCLAMP
 LOWER
 VEC
 UPPER
Returns a clamped vector where each field is within [LOWER, UPPER]. Accepts REALs or VECs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION VCOPY
 VEC
Creates a copy of the vector.

EXTERNAL FUNCTION VCOPY2
 INSTANCE
Creates a copy of a 2D vector.

EXTERNAL FUNCTION VCOPY3
 INSTANCE
Creates a copy of a 3D vector.

EXTERNAL FUNCTION VCOPY4
 INSTANCE
Creates a copy of a 4D vector.

EXTERNAL FUNCTION VDISTANCE
 A
 B
Returns the distance from A to B.

EXTERNAL FUNCTION VEC
 X
 Y
 &OPTIONAL
 Z
 W
Creates a new vector of the appropriate size.

EXTERNAL FUNCTION VECP
 VEC
Returns T if the argument is a vector.

EXTERNAL FUNCTION VEC2
 X
 Y
Constructs a 2D vector.

EXTERNAL FUNCTION VEC2P
 OBJECT
Returns T if the argument is of type vec2.

EXTERNAL FUNCTION VEC2RANDOM
 LOWER
 UPPER
Constructs a 2D vector with random values according to the given bounds.

EXTERNAL FUNCTION VEC3
 X
 Y
 Z
Constructs a 3D vector.

EXTERNAL FUNCTION VEC3P
 OBJECT
Returns T if the argument is of type vec3.

EXTERNAL FUNCTION VEC3RANDOM
 LOWER
 UPPER
Constructs a 3D vector with random values according to the given bounds.

EXTERNAL FUNCTION VEC4
 X
 Y
 Z
 W
Constructs a 3D vector.

EXTERNAL FUNCTION VEC4P
 OBJECT
Returns T if the argument is of type vec4.

EXTERNAL FUNCTION VEC4RANDOM
 LOWER
 UPPER
Constructs a 4D vector with random values according to the given bounds.

EXTERNAL FUNCTION VINORM
 V
Returns the maximumnorm of the vector.

EXTERNAL FUNCTION VLENGTH
 V
Returns the euclidean norm of the vector.

EXTERNAL FUNCTION VLERP
 FROM
 TO
 N
Returns a vector where each field is linearly interpolated from the corresponding field in FROM to TO by N. Accepts a REAL or VEC for N, where REALs are used for each component of the vector.

EXTERNAL FUNCTION VLIMIT
 VEC
 LIMIT
Returns a limited vector where each field is within [LIMIT, LIMIT]. Accepts REALs or VEcs as arguments, where REALs are used for each component of the vector.

EXTERNAL FUNCTION VMAX
 VAL
 &REST
 VALS
Same as MAX, but testing all vector fields simultaneously.

EXTERNAL FUNCTION VMIN
 VAL
 &REST
 VALS
Same as MIN, but testing all vector fields simultaneously.

EXTERNAL FUNCTION VMOD
 VEC
 DIVISOR
Returns a vector with each component being the modulus of the given vector's against the divisor.

EXTERNAL FUNCTION VORDER
 V
 X
 &OPTIONAL
 Y
 Z
 W
Allows you to handily modify a vector by reordering its components. Each X/Y/Z argument can be one of 'X,'Y,'Z,'VX,'VY,'VZ,:X,:Y,:Z indicating the respective component, or NIL for 0.

EXTERNAL FUNCTION VPNORM
 V
 P
Returns the pnorm of the vector.

EXTERNAL FUNCTION VROT
 V
 AXIS
 PHI
Returns a 3D vector rotated around AXIS by PHI rads. The axis has to be a unit vector. This operation does not work with 2D or 4D vectors.

EXTERNAL FUNCTION VROTV
 A
 B
Returns a 3D vector of A rotated around each axis by the amount in B. The rotations are performed in the order of X, Y, Z. Note that rotation in 3D space is not commutative, so this function might not perform the rotation as you expected if you need the rotation to happen in a different order. This operation does not work with 2D or 4D vectors. See VROT.

EXTERNAL FUNCTION VSCALE
 A
 LENGTH
Returns a scaled vector of the specified length.

EXTERNAL FUNCTION VUNIT
 A
Returns the unit vector form of the given vector by the 2norm.

EXTERNAL FUNCTION VW
 VEC
Returns the W component of the vector.

EXTERNAL FUNCTION VW4
 VEC
Returns the W component of a 4D vector.

EXTERNAL FUNCTION VX
 VEC
Returns the X component of the vector.

EXTERNAL FUNCTION VX2
 VEC
Returns the X component of a 2D vector.

EXTERNAL FUNCTION VX3
 VEC
Returns the X component of a 3D vector.

EXTERNAL FUNCTION VX4
 VEC
Returns the X component of a 4D vector.

EXTERNAL FUNCTION VY
 VEC
Returns the Y component of the vector.

EXTERNAL FUNCTION VY2
 VEC
Returns the Y component of a 2D vector.

EXTERNAL FUNCTION VY3
 VEC
Returns the Y component of a 3D vector.

EXTERNAL FUNCTION VY4
 VEC
Returns the Y component of a 4D vector.

EXTERNAL FUNCTION VZ
 VEC
Returns the Z component of the vector.

EXTERNAL FUNCTION VZ3
 VEC
Returns the Z component of a 3D vector.

EXTERNAL FUNCTION VZ4
 VEC
Returns the Z component of a 4D vector.

EXTERNAL MACRO VAPPLY
 VEC
 OP
 &OPTIONAL
 X
 Y
 Z
 W
Applies OP to each applicable field of the vector plus the optional argument for each respective dimension, if given. Returns a new vector of the same type with the results in its fields.

EXTERNAL MACRO VAPPLYF
 VEC
 OP
 &OPTIONAL
 X
 Y
 Z
 W
Applies OP to each applicable field of the vector plus the optional argument for each respective dimension, if given. Returns the same vector with the results stored in its fields.

EXTERNAL MACRO VDECF
 V
 &OPTIONAL
 DELTA
Decreases each field in the vector by DELTA.

EXTERNAL MACRO VINCF
 V
 &OPTIONAL
 DELTA
Increases each field in the vector by DELTA.

EXTERNAL MACRO VSETF
 VEC
 X
 Y
 &OPTIONAL
 Z
 W
Similar to SETF, but requires as many values as the given vector has fields. Returns the modified vector.

EXTERNAL MACRO WITHVEC
 X
 Y
 &OPTIONAL
 Z
 W
 VAL
 &BODY
 BODY
Binds each component of the vector (or real) to the specified variable. If the vector does not have a particular field, the variable is initialized to 0 in the proper float format.

EXTERNAL MACRO WITHVEC2
 X
 Y
 VAL
 &BODY
 BODY
Binds each component of the vector (or real) to the specified variable.

EXTERNAL MACRO WITHVEC3
 X
 Y
 Z
 VAL
 &BODY
 BODY
Binds each component of the vector (or real) to the specified variable.

EXTERNAL MACRO WITHVEC4
 X
 Y
 Z
 W
 VAL
 &BODY
 BODY
Binds each component of the vector (or real) to the specified variable.