diff --git a/src/lib.rs b/src/lib.rs index 3d7b997..73feed4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -13,19 +13,41 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! Computer graphics-centric math. +//! A low-dimensional linear algebra library, targeted at computer graphics. //! -//! This crate provides useful mathematical primitives and operations on them. -//! It is organized into one module per primitive. The core structures are -//! vectors and matrices. A strongly-typed interface is provided, to prevent -//! mixing units or violating mathematical invariants. +//! # Trait overview //! -//! Transformations are not usually done directly on matrices, but go through -//! transformation objects that can be converted to matrices. Rotations go -//! through the `Basis` types, which are guaranteed to be orthogonal matrices. -//! Despite this, one can directly create a limited rotation matrix using the -//! `look_at`, `from_angle`, `from_euler`, and `from_axis_angle` methods. -//! These are provided for convenience. +//! In order to make a clean, composable API, we divide operations into traits +//! that are roughly based on mathematical properties. The main ones that we +//! concern ourselves with are listed below: +//! +//! - `VectorSpace`: Specifies the main operators for vectors, quaternions, and +//! matrices. +//! - `InnerSpace`: For types that have a dot (or inner) product - ie. vectors or +//! quaternions. This also allows for the definition of operations that are +//! based on the dot product, like finding the magnitude or normalizing. +//! - `EuclideanSpace`: Points in euclidean space, with an associated space of +//! displacement vectors. +//! - `Matrix`: Common operations for matrices of arbitrary dimensions. +//! - `SquareMatrix`: A special trait for matrices where the number of columns +//! equal the number of rows. +//! +//! Other traits are included for practical convenience, for example: +//! +//! - `Array`: For contiguous, indexable arrays of elements, specifically +//! vectors. +//! - `ElementWise`: For element-wise addition, subtraction, multiplication, +//! division, and remainder operations. +//! +//! # The prelude +//! +//! Importing each trait individually can become a chore, so we provide a +//! `prelude` module to allow you to import the main trait all at once. For +//! example: +//! +//! ```rust +//! use cgmath::prelude::*; +//! ``` extern crate num as rust_num; extern crate rustc_serialize; diff --git a/src/matrix.rs b/src/matrix.rs index 08f550a..b6a3bb9 100644 --- a/src/matrix.rs +++ b/src/matrix.rs @@ -13,8 +13,6 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! Column major, square matrix types and traits. - use std::fmt; use std::mem; use std::ops::*; diff --git a/src/vector.rs b/src/vector.rs index 57bb110..6fb813c 100644 --- a/src/vector.rs +++ b/src/vector.rs @@ -13,80 +13,6 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! Types and traits for two, three, and four-dimensional vectors. -//! -//! ## Working with Vectors -//! -//! Vectors can be created in several different ways. There is, of course, the -//! traditional `new()` method, but unit vectors, zero vectors, and an one -//! vector are also provided: -//! -//! ```rust -//! use cgmath::{VectorSpace, Vector2, Vector3, Vector4, vec3}; -//! -//! assert_eq!(Vector2::new(1.0f64, 0.0f64), Vector2::unit_x()); -//! assert_eq!(vec3(0.0f64, 0.0f64, 0.0f64), Vector3::zero()); -//! ``` -//! -//! Vectors can be manipulated with typical mathematical operations (addition, -//! subtraction, element-wise multiplication, element-wise division, negation) -//! using the built-in operators. -//! -//! ```rust -//! use cgmath::{VectorSpace, Vector2, Vector3, Vector4}; -//! -//! let a: Vector2 = Vector2::new(3.0, 4.0); -//! let b: Vector2 = Vector2::new(-3.0, -4.0); -//! -//! assert_eq!(a + b, Vector2::zero()); -//! assert_eq!(-(a * 2.0), Vector2::new(-6.0, -8.0)); -//! -//! // As with Rust's `int` and `f32` types, Vectors of different types cannot -//! // be added and so on with impunity. The following will fail to compile: -//! // let c = a + Vector3::new(1.0, 0.0, 2.0); -//! -//! // Instead, we need to convert the Vector2 to a Vector3 by "extending" it -//! // with the value for the last coordinate: -//! let c: Vector3 = a.extend(0.0) + Vector3::new(1.0, 0.0, 2.0); -//! -//! // Similarly, we can "truncate" a Vector4 down to a Vector3: -//! let d: Vector3 = c + Vector4::unit_x().truncate(); -//! -//! assert_eq!(d, Vector3::new(5.0f64, 4.0f64, 2.0f64)); -//! ``` -//! -//! Vectors also provide methods for typical operations such as -//! [scalar multiplication](http://en.wikipedia.org/wiki/Scalar_multiplication), -//! [dot products](http://en.wikipedia.org/wiki/Dot_product), -//! and [cross products](http://en.wikipedia.org/wiki/Cross_product). -//! -//! ```rust -//! use cgmath::{VectorSpace, InnerSpace}; -//! use cgmath::{Vector2, Vector3, Vector4}; -//! -//! // All vectors implement the dot product as a method: -//! let a: Vector2 = Vector2::new(3.0, 6.0); -//! let b: Vector2 = Vector2::new(-2.0, 1.0); -//! assert_eq!(a.dot(b), 0.0); -//! -//! // But there is also a top-level function: -//! assert_eq!(a.dot(b), cgmath::dot(a, b)); -//! -//! // Cross products are defined for 3-dimensional vectors: -//! let e: Vector3 = Vector3::unit_x(); -//! let f: Vector3 = Vector3::unit_y(); -//! assert_eq!(e.cross(f), Vector3::unit_z()); -//! ``` -//! -//! Several other useful methods are provided as well. Vector fields can be -//! accessed using array syntax (i.e. `vector[0] == vector.x`), or by using -//! the methods provided by the [`Array`](../array/trait.Array.html) trait. -//! This trait also provides a `map()` method for applying arbitrary functions. -//! -//! The [`VectorSpace`](../trait.VectorSpace.html) trait presents the most -//! general features of the vectors, while [`InnerSpace`] -//! (../array/trait.InnerSpace.html) is more specific to Euclidean space. - use std::fmt; use std::mem; use std::ops::*;