 # 3d vectors

3.1.0

A utility library implementing 2D, 3D, and 4D vector functionality.

## About 3d-vectors

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 non-modifying 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 `single-float`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 :3d-vectors)
(use-package :3d-vectors)
``````

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)
``````

3d-vectors 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 lower-level 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 single-field accessors, there's multi-field 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 `single-float`s ensure, you can add `:3d-vectors-double-floats` to `*features*` and recompile the library `(asdf:compile-system :3d-vectors :force T)`. Similarly, if you want to switch back to `single-float`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

• 3d-matrices for Matrix operations in conjunction with this library.

3.1.0
Nicolas Hafner
Artistic

## Definition Index

• ### 3D-VECTORS

• ORG.SHIRAKUMO.FLARE.VECTOR
No documentation provided.
• EXTERNAL CONSTANT

#### +VW4+

Source
`Constant vector for the 4D unit in W direction.`
• EXTERNAL CONSTANT

#### +VX+

Source
`Constant vector for the 3D unit in X direction.`
• EXTERNAL CONSTANT

#### +VX2+

Source
`Constant vector for the 2D unit in X direction.`
• EXTERNAL CONSTANT

#### +VX3+

Source
`Constant vector for the 3D unit in X direction.`
• EXTERNAL CONSTANT

#### +VX4+

Source
`Constant vector for the 4D unit in X direction.`
• EXTERNAL CONSTANT

#### +VY+

Source
`Constant vector for the 3D unit in Y direction.`
• EXTERNAL CONSTANT

#### +VY2+

Source
`Constant vector for the 2D unit in Y direction.`
• EXTERNAL CONSTANT

#### +VY3+

Source
`Constant vector for the 3D unit in Y direction.`
• EXTERNAL CONSTANT

#### +VY4+

Source
`Constant vector for the 4D unit in Y direction.`
• EXTERNAL CONSTANT

#### +VZ+

Source
`Constant vector for the 3D unit in Z direction.`
• EXTERNAL CONSTANT

#### +VZ3+

Source
`Constant vector for the 3D unit in Z direction.`
• EXTERNAL CONSTANT

#### +VZ4+

Source
`Constant vector for the 4D unit in Z direction.`
• EXTERNAL STRUCTURE

#### VEC2

Source
`A two-dimensional vector with X and Y fields.`
• EXTERNAL STRUCTURE

#### VEC3

Source
`A three-dimensional vector with X, Y, and Z fields.`
• EXTERNAL STRUCTURE

#### VEC4

Source
`A four-dimensional vector with X, Y, Z, and W fields.`
• EXTERNAL TYPE-DEFINITION

#### VEC

Source
`Either a vec2, vec3, or vec4.`
• EXTERNAL FUNCTION

#### NV*

• VAL
• &REST
• VALS
Source
`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
Source
`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
Source
`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
Source
`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
Source
`Performs ABS on each component of the vector and stores back the results.`
• EXTERNAL FUNCTION

#### NVCLAMP

• LOWER
• VEC
• UPPER
Source
`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
Source
`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
Source
`Performs MOD on each component of the vector and stores back the results.`
• EXTERNAL FUNCTION

#### NVORDER

• V
• X
• &OPTIONAL
• Y
• Z
• W
Source
No documentation provided.
• EXTERNAL FUNCTION

#### NVROT

• V
• AXIS
• PHI
Source
```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
Source
```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
Source
`Scales the vector to be of the specified length.`
• EXTERNAL FUNCTION

#### NVUNIT

• VEC
Source
`Normalizes the vector into its unit form by the 2-norm.`
• EXTERNAL FUNCTION

#### V*

• VAL
• &REST
• VALS
Source
`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
Source
`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
Source
`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
Source
`Returns the dot product of the two vectors.`
• EXTERNAL FUNCTION

#### V/

• VAL
• &REST
• VALS
Source
`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
Source
`This is the same as /=, but testing all vector fields simultaneously.`
• EXTERNAL FUNCTION

#### V1+

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

#### V1-

• V
Source
`Same as 1-, but returns a new vector with each component decreased by 1.`
• EXTERNAL FUNCTION

#### V1NORM

• V
Source
`Returns the taxicab/1-norm of the vector.`
• EXTERNAL FUNCTION

#### V2NORM

• V
Source
`Returns the euclidean/2-norm of the vector.`
• EXTERNAL FUNCTION

#### V<

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

#### V<=

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

#### V=

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

#### V>

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

#### V>=

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

#### VABS

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

#### VANGLE

• A
• B
Source
`Returns the angle between two vectors.`
• EXTERNAL FUNCTION

#### VC

• A
• B
Source
```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
Source
`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
Source
`Creates a copy of the vector.`
• EXTERNAL FUNCTION

#### VCOPY2

• INSTANCE
Source
`Creates a copy of a 2D vector.`
• EXTERNAL FUNCTION

#### VCOPY3

• INSTANCE
Source
`Creates a copy of a 3D vector.`
• EXTERNAL FUNCTION

#### VCOPY4

• INSTANCE
Source
`Creates a copy of a 4D vector.`
• EXTERNAL FUNCTION

#### VDISTANCE

• A
• B
Source
`Returns the distance from A to B.`
• EXTERNAL FUNCTION

#### VEC

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

#### VEC-P

• VEC
Source
`Returns T if the argument is a vector.`
• EXTERNAL FUNCTION

#### VEC2

• X
• Y
Source
`Constructs a 2D vector.`
• EXTERNAL FUNCTION

#### VEC2-P

• OBJECT
Source
`Returns T if the argument is of type vec2.`
• EXTERNAL FUNCTION

#### VEC2-RANDOM

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

#### VEC3

• X
• Y
• Z
Source
`Constructs a 3D vector.`
• EXTERNAL FUNCTION

#### VEC3-P

• OBJECT
Source
`Returns T if the argument is of type vec3.`
• EXTERNAL FUNCTION

#### VEC3-RANDOM

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

#### VEC4

• X
• Y
• Z
• W
Source
`Constructs a 3D vector.`
• EXTERNAL FUNCTION

#### VEC4-P

• OBJECT
Source
`Returns T if the argument is of type vec4.`
• EXTERNAL FUNCTION

#### VEC4-RANDOM

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

#### VINORM

• V
Source
`Returns the maximum-norm of the vector.`
• EXTERNAL FUNCTION

#### VLENGTH

• V
Source
`Returns the euclidean norm of the vector.`
• EXTERNAL FUNCTION

#### VLERP

• FROM
• TO
• N
Source
`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
Source
`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
Source
`Same as MAX, but testing all vector fields simultaneously.`
• EXTERNAL FUNCTION

#### VMIN

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

#### VMOD

• VEC
• DIVISOR
Source
`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
Source
```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
Source
`Returns the p-norm of the vector.`
• EXTERNAL FUNCTION

#### VROT

• V
• AXIS
• PHI
Source
```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
Source
```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
Source
`Returns a scaled vector of the specified length.`
• EXTERNAL FUNCTION

#### VUNIT

• A
Source
`Returns the unit vector form of the given vector by the 2-norm.`
• EXTERNAL FUNCTION

#### VW

• VEC
Source
`Returns the W component of the vector.`
• EXTERNAL FUNCTION

#### VW4

• VEC
Source
`Returns the W component of a 4D vector.`
• EXTERNAL FUNCTION

#### VX

• VEC
Source
`Returns the X component of the vector.`
• EXTERNAL FUNCTION

#### VX2

• VEC
Source
`Returns the X component of a 2D vector.`
• EXTERNAL FUNCTION

#### VX3

• VEC
Source
`Returns the X component of a 3D vector.`
• EXTERNAL FUNCTION

#### VX4

• VEC
Source
`Returns the X component of a 4D vector.`
• EXTERNAL FUNCTION

#### VY

• VEC
Source
`Returns the Y component of the vector.`
• EXTERNAL FUNCTION

#### VY2

• VEC
Source
`Returns the Y component of a 2D vector.`
• EXTERNAL FUNCTION

#### VY3

• VEC
Source
`Returns the Y component of a 3D vector.`
• EXTERNAL FUNCTION

#### VY4

• VEC
Source
`Returns the Y component of a 4D vector.`
• EXTERNAL FUNCTION

#### VZ

• VEC
Source
`Returns the Z component of the vector.`
• EXTERNAL FUNCTION

#### VZ3

• VEC
Source
`Returns the Z component of a 3D vector.`
• EXTERNAL FUNCTION

#### VZ4

• VEC
Source
`Returns the Z component of a 4D vector.`
• EXTERNAL MACRO

#### VAPPLY

• VEC
• OP
• &OPTIONAL
• X
• Y
• Z
• W
Source
`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
Source
`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
Source
`Decreases each field in the vector by DELTA.`
• EXTERNAL MACRO

#### VINCF

• V
• &OPTIONAL
• DELTA
Source
`Increases each field in the vector by DELTA.`
• EXTERNAL MACRO

#### VSETF

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

#### WITH-VEC

• X
• Y
• &OPTIONAL
• Z
• W
• VAL
• &BODY
• BODY
Source
```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

#### WITH-VEC2

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

#### WITH-VEC3

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

#### WITH-VEC4

• X
• Y
• Z
• W
• VAL
• &BODY
• BODY
Source
`Binds each component of the vector (or real) to the specified variable.`