cgmath Documentation

cgmath treats vectors as column matrices (column vectors). When performing transformations, the matrix must be placed on the left of the vector.

Consequently, the library implements the multiplication operator for Matrix * Vector, but it does not implement Vector * Matrix.

To use swizzle operators (familiar to GPU programmers), you must enable the swizzle feature in your Cargo.toml or via the command line.

Enabling this feature increases the library size by approximately 0.6MB, but unused operators will be optimized away by the compiler in release mode when linked statically.

A Quaternion<S> represents a rotation in 3D space using a scalar part s and a vector part v (Vector3<S>). It is marked as #[repr(C)] for compatibility. Quaternions can be constructed from individual components, from a scalar and a vector, or converted from Euler angles.

pub struct Quaternion<S> {
    pub v: Vector3<S>,
    pub s: S,
}

In cgmath, Points represent fixed positions in affine space. They are distinct from Vectors because points have no length or direction; they only represent a specific location.

Supported types:

• Point1<S>: A point in 1-dimensional space.
• Point2<S>: A point in 2-dimensional space.
• Point3<S>: A point in 3-dimensional space.

All point types are marked as #[repr(C)] and support common traits like Copy, Clone, PartialEq, and Hash.

The Rotation trait defines a generic interface for transformations that create circular motion and preserve at least one point in space. It is implemented by types like Basis2 and Basis3.

Key capabilities include:

• Creating rotations via look_at (direction and up vector) or between_vectors (shortest rotation between two unit vectors).
• Transforming vectors via rotate_vector and points via rotate_point.
• Reversing a rotation using invert().

cgmath uses a trait-based API to organize mathematical operations by their properties. The primary traits are:

• VectorSpace: Main operators for vectors, quaternions, and matrices.
• MetricSpace: Types with a distance function.
• InnerSpace: Types with a dot (inner) product (e.g., vectors or quaternions), used for magnitude and normalization.
• EuclideanSpace: Represents points in euclidean space with an associated space of displacement vectors.
• Matrix: Common operations for matrices of arbitrary dimensions.
• SquareMatrix: Operations specific to matrices where rows equal columns.
• Array: Contiguous, indexable arrays (specifically for vectors).
• ElementWise: Element-wise arithmetic operations (addition, subtraction, multiplication, division, and remainder).

To avoid importing mathematical traits individually, use the prelude module. This provides access to the core traits required for vector, matrix, and quaternion operations, such as VectorSpace, MetricSpace, InnerSpace, and EuclideanSpace.

use cgmath::prelude::*;

When type inference is difficult—such as when declaring uniforms for graphics libraries like glium—you can use the cgmath::conv module to convert cgmath types into fixed-length arrays. This is a cleaner alternative to using Into::<[T; N]>::into(value) directly.

use cgmath::{Matrix4, Point2};
use cgmath::prelude::*;
use cgmath::conv::*;

let point = Point2::new(1, 2);
let matrix = Matrix4::from_scale(2.0);

// Using conv functions for cleaner syntax in macros or assignments
let point_array = array2(point);
let matrix_array = array4x4(matrix);

If the serde feature is enabled, Decomposed<V, R> implements Serialize and Deserialize. The data is represented as a struct with three fields:

• scale
• rot
• disp