README
¶
VKM
VKM is a simple vector and matrix math package written in Go, inspired by glm, and targeting 3D graphics programing.
VKM is specifically targeted at 3D graphics and is NOT inteded to be an
all-purpose vector math or linear algebra package. It includes some variant types like Pt2 and
Vec3 for convenience, but the primary matrix math functions rely on homogenous 3D
vectors and points.
While this module can be used in any Go program wanting to work with 3D transformations, it was built to use with go-vk, a Go language binding for the Vulkan graphics API.
Usage
See the GoDoc for the full API.
VKM defines three primary types: Pt, Vec, and Matrix. All three are stored
in column-major order and are fundamentally arrays of [4]float32. (Note: this explicitly means static arrays and not
slices.)
We use float32, and not Go's default 64-bit floating point type, because Vulkan (generally) uses 32-bit
floats on the GPU. As a consequence, and rather than constantly forcing float32 type casts, VKM uses the chewxy/math32 package for float32 operations and constants.
Examples
Create a basic transformation
You can generate a simple tranformation with the NewMat__ variants:
import "github.com/bbredesen/vkm"
// ...
transVec := vkm.NewVec(-1, -2, -3)
transMat := vkm.NewMatTranslate(transVec)
Rotations are measured in radians by default, but each rotation function has a "Deg" variant to use degrees. Rotation angles will scale with the length of the axis vector, so be sure to normalize the vector first:
import "github.com/chewxy/math32"
// ...
axisVec := vkm.NewVec(1, 1, 1).Normalize()
aRotationMat := vkm.NewMatRotate(axisVec, math32.Pi)
Multiply arbitrary matricies and points or vectors
Matrix multiplication happens in the order written when you directly call
MultM, MultV, or MultP. The following code has the apparent
effect of rotating the world before translating:
transformMat := myTranslationMat.MultM(myRotationMat)
Create a "readable" transformation
Transformations can be chained, as long as you have a matrix to start from. In this example, we apply a translation of -5 in the X direction, rotate around the Y axis by 45 degrees counterclockwise, and then translate by +5 in the X direction:
transVec := NewVec(-5, 0, 0)
m := Identity().
Translate(transVec).
RotateYDeg(-45).
Translate(transVec.Invert())
When written in this form, we apply transformations in the order they are written. In practice, the code is actually right-multiplying each subsequent transformation, as in the previous example.
Performance Optimization TODO
All math in this library is currently writing in pure Go. Performance could benefit from using SIMD extensions on Intel/AMD CPUs, which will require writing those functions in assembly.
Documentation
¶
Overview ¶
Package vkm provides matrix math functions targeted at computer graphics. It was built for use with go-vk (https://github.com/bbredesen/go-vk), but should be appropriate for any graphics API expecting column-major matricies.
All matricies are 4x4. The Vec and Pt types are 4-component, homogenous column vectors. You can directly instantiate them via:
v := Vec{i, j, k, 0}
p := Pt{x, y, z, 1}
but it is recommended instead to call the New... functions to ensure that the fourth component is correctly set.
v := NewVec(i, j, k) p := NewPt(x, y, z)
Convenience "zero value" functions for the Origin, ZeroVec, and Identity matrix are included.
Additionally, standard transformation matricies are provided. You can either generate the matrix directly:
NewMatTranslate(transVector)
or you can apply a transformation to an existing matrix:
myMat.Translate(transVector)
Note that applied transformations are left-multiplied, so m.Translate(v) = T(v) x m, whereas calling MultM will right-multiply: m.MultM(t) = m x t.
Index ¶
- Variables
- type Mat
- func Camera(eye Pt, look Vec, up Vec) Mat
- func Identity() Mat
- func InvertedDepthPerspective(fov, aspect, near, far float32) Mat
- func LookAt(eye, focus Pt, up Vec) Mat
- func NewMatRotate(axis Vec, theta float32) Mat
- func NewMatRotateDeg(axis Vec, deg float32) Mat
- func NewMatRotateX(theta float32) Mat
- func NewMatRotateXDeg(deg float32) Mat
- func NewMatRotateY(theta float32) Mat
- func NewMatRotateYDeg(deg float32) Mat
- func NewMatRotateZ(theta float32) Mat
- func NewMatRotateZDeg(deg float32) Mat
- func NewMatScale(v Vec) Mat
- func NewMatTranslate(v Vec) Mat
- func OrthoProjection(width, height, near, far float32) Mat
- func Perspective(fov, aspect, near, far float32) Mat
- func PerspectiveDeg(fovDeg, aspect, near, far float32) Mat
- func (m Mat) ApproximatelyEquals(n Mat, precision float32) bool
- func (m *Mat) AsBytes() []byte
- func (m Mat) Determinant() float32
- func (m Mat) Equals(n Mat) bool
- func (m Mat) Inverse() Mat
- func (m Mat) MultM(n Mat) Mat
- func (m Mat) MultP(v Pt) Pt
- func (m Mat) MultV(v Vec) Vec
- func (m Mat) Rotate(axis Vec, theta float32) Mat
- func (m Mat) RotateDeg(axis Vec, deg float32) Mat
- func (m Mat) RotateX(theta float32) Mat
- func (m Mat) RotateXDeg(deg float32) Mat
- func (m Mat) RotateY(theta float32) Mat
- func (m Mat) RotateYDeg(deg float32) Mat
- func (m Mat) RotateZ(theta float32) Mat
- func (m Mat) RotateZDeg(deg float32) Mat
- func (m Mat) Scale(v Vec) Mat
- func (m Mat) Translate(v Vec) Mat
- func (m Mat) Transpose() Mat
- type Pt
- type Pt2
- type Pt3
- type Vec
- func (v Vec) Add(u Vec) Vec
- func (v Vec) Clone() Vec
- func (v Vec) Cross(u Vec) Vec
- func (v Vec) Dot(u Vec) float32
- func (v Vec) Invert() Vec
- func (v Vec) Length() float32
- func (v Vec) Normalize() Vec
- func (v Vec) RotateZ(theta float32) Vec
- func (v Vec) Scale(factor float32) Vec
- func (v Vec) SquareLength() float32
- func (v Vec) Sub(u Vec) Vec
- type Vec2
- type Vec3
Constants ¶
This section is empty.
Variables ¶
var ZeroPt = Origin
ZeroPt is a synonym for Origin()
Functions ¶
This section is empty.
Types ¶
type Mat ¶
type Mat [4]Vec
Mat is a column-major 4x4 matrix of float32s. Because it is fundamentally an array of arrays, elements can be directly addressed via double brackets: m[col][row]
func Camera ¶
Camera creates a view matrix from the provided eye location, pointed along the direction vector. Camera will continue to look "forward" as you move the eye point, while LookAt will change the look direction to continue pointing at the focus point as the eye moves around.
func InvertedDepthPerspective ¶
InvertedDepthPerspective generates a Vulkan perspective matrix with depth "reversed". This means that you must set DepthCompareOp to vk.COMPARE_OP_GREATER, and clear the depth buffer to zero, instead of one. The reason you might use this perspective over the "standard" perspecvtive matrix is for greater depth precision. Floating point numbers are more precise as you approach 1.0, and the persepctive matrix tends to compress verticies towards the near projection plane, hence closer to 1.0 in the depth buffer.
Parameters for this function have the same meaning as Perspective
func LookAt ¶
LookAt creates a view matrix from the provided eye and focus points, and an up vector. This function does NOT generate a persepctive matrix. Note that LookAt (and all projection helpers in this library) are based on Vulkan's clip space, which differs from OpenGL.
LookAt only orients the view from an arbitrary orientation down the positive Z axis. The up vector does not need to be orthagonal to the eye -> focus vector, but it cannot be parallel. Note that Vulkan's clip space is different than OpenGL: Z increases into the screen, Positive-Y is down the screen, and the clip boundaries are (-1 <= x <= 1, -1 <= y <= 1, 0 <= z <= 1).
func NewMatRotate ¶
NewMatRotate generates a rotation by theta radians around an arbitrary axis. Note that axis is assumed to be a unit vector. The rotation angle will be scaled by the length of the axis vector.
func NewMatRotateDeg ¶
NewMatRotateDeg generates a rotation by deg degrees around an arbitrary axis. Note that axis is assumed to be a unit vector. The rotation angle will be scaled by the length of the axis vector.
func NewMatRotateX ¶
NewMatRotateX generates a CCW rotation around the X axis by theta radians
func NewMatRotateXDeg ¶
NewMatRotateXDeg generates a CCW rotation around the X axis by deg degrees
func NewMatRotateY ¶
NewMatRotateY generates a CCW rotation around the Y axis by theta radians
func NewMatRotateYDeg ¶
NewMatRotateYDeg generates a CCW rotation around the Y axis by deg degrees
func NewMatRotateZ ¶
NewMatRotateZ generates a CCW rotation around the Z axis by theta radians
func NewMatRotateZDeg ¶
NewMatRotateZDeg generates a CCW rotation around the Z axis by deg degrees
func NewMatScale ¶
NewMatScale creates a scaling matrix using v. A negative value on any axis will create a reflection across that axis.
func NewMatTranslate ¶
NewMatTranslate generates a translation matrix using v. Note that the fourth component of v is ignored and that component of the matrix is set to 1.0
func OrthoProjection ¶
Ortho generates an orthogonal projection matrix.
func Perspective ¶
Perspective generates a perspective projection matrix for Vulkan. Note that in Vulkan, the standard z clipping space is in the range [0..1], and x/y in the range [-1..1] (or rather -w to +w).
aspect is the ratio of width divided by height
fov is the vertical field of view measured in radians
near and far are the near and far bounds of the frustum
func PerspectiveDeg ¶
PerspectiveDeg generates a perspective projection matrix. This version accepts the FOV angle in degrees. See Perspective.
func (Mat) ApproximatelyEquals ¶
ApproximatelyEquals returns true if m and n are equal component-for-component to within `precision`. Use this function if comparing two calculated matrices to determine if they are equal to within a reasonable precision.
func (Mat) Determinant ¶
func (Mat) Equals ¶
Equals returns true if m and n are exactly equal. Note that this function does not allow for "approximately equal" conditions, like many floating point comparison functions.
func (Mat) Inverse ¶
Inverse returns the inverse matrix of m, i.e. the matrix such that m.MultM(m.Inverse()) yields the identity matrix.
func (Mat) Rotate ¶
Rotate applies an arbitrary rotation measured in radian around the provided axis to m and returns the resulting matrix.
func (Mat) RotateDeg ¶
RotateDeg applies an arbitrary rotation measured in degrees around the provided axis to m and returns the resulting matrix.
func (Mat) RotateX ¶
RotateX applies a rotation around the X axis to m and returns the resulting matrix.
func (Mat) RotateXDeg ¶
RotateXDeg applies a rotation around the X axis to m and returns the resulting matrix.
func (Mat) RotateY ¶
RotateY applies a rotation around the Y axis to m and returns the resulting matrix.
func (Mat) RotateYDeg ¶
RotateYDeg applies a rotation around the Y axis to m and returns the resulting matrix.
func (Mat) RotateZ ¶
RotateZ applies a rotation around the Z axis to m and returns the resulting matrix.
func (Mat) RotateZDeg ¶
RotateZDeg applies a rotation around the Z axis to m and returns the resulting matrix.
type Pt ¶
type Pt Vec
Pt represents a homogenous 3d point (x, y, z, and w components)
func AsPt ¶
AsPt onverts a slice of float32 to a Pt. If the slice has more than four elements, only the first four will be copied.
func (Pt) EqualTo ¶
EqualTo determines if two points are (approximately) equal. If any component differs by more than 0.00001, then the two points are not "equal"
func (Pt) FlattenToXY ¶
func (Pt) Homogenize ¶
Homogenize on a Pt divides all components by the w coordinate
type Pt2 ¶
type Pt2 [2]float32
Pt2 is a 2d point (x and y components only), intended for use as texture coordinates.
func (Pt2) Homogenize ¶
Homogenize converts a Pt2 into a Pt, with z set to zero and the w component fixed to 1.0
type Pt3 ¶
type Pt3 Vec3
Pt3 is a 3d point (x, y, and z components)
func (Pt3) Homogenize ¶
Homogenize converts a Pt3 into a Pt, with the w component fixed to 1.0
type Vec ¶
type Vec [4]float32
Vec represents a homogenous 3d vector (i, j, k, and l components)
func AsVec ¶
AsVec converts a slice of float32 to a Vec. This function does not validate the input in any way, so if the slice has more than four elements, only the first four will be copied. If the slice has less than four elements, the remaining elements in the return value will be zeroes.
func (Vec) Add ¶
Add returns the sum of two vectors. Note that the w component from the input is ignored, and is clamped to zero on the output.
func (Vec) Cross ¶
Cross returns the cross product of v and u Note that the w component is ignored, though it should be zero for any homogenous vector
func (Vec) Dot ¶
Dot returns the dot product of v and u. Note that the w component is ignored, though it should be zero for any homogenous vector
func (Vec) Length ¶
Length is the length in 3D space of v. This function calculates a square root, making it relatively expensive. Use Vec.SquareLength instead if you are comparing two vectors, or comparing against a constant length.
func (Vec) SquareLength ¶
Calculates the dot product of v with itself, equal to the length of the vector squared. This is much more efficient than calling Length() if you are comparing the length of two vectors.
type Vec2 ¶
type Vec2 [2]float32
Vec2 is a 2d vector (i and j components)
func (Vec2) Homogenize ¶
Homogenize converts a Vec2 in to a Vec, with the k and l components fixed to 0.0
func (Vec2) Length ¶
Length is the length of v. This function calculates a square root, making it relatively expensive. Use Vec2.SquareLength instead if you are comparing two vectors, or comparing against a constant length.
func (Vec2) SquareLength ¶
type Vec3 ¶
type Vec3 [3]float32
Vec3 is a 3d vector (i, j, and k components)
func (Vec3) Homogenize ¶
Homogenize converts a Vec3 into a Vec, with the l component fixed to 0.0
func (Vec3) Length ¶
Length is the length in 3D space of v. This function calculates a square root, making it relatively expensive. Use Vec3.SquareLength instead if you are comparing two vectors, or comparing against a constant length.
Source Files