euclid/
lib.rs

1// Copyright 2013 The Servo Project Developers. See the COPYRIGHT
2// file at the top-level directory of this distribution.
3//
4// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
5// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
7// option. This file may not be copied, modified, or distributed
8// except according to those terms.
9
10#![cfg_attr(feature = "unstable", feature(fn_must_use))]
11#![cfg_attr(not(test), no_std)]
12
13//! A collection of strongly typed math tools for computer graphics with an inclination
14//! towards 2d graphics and layout.
15//!
16//! All types are generic over the scalar type of their component (`f32`, `i32`, etc.),
17//! and tagged with a generic Unit parameter which is useful to prevent mixing
18//! values from different spaces. For example it should not be legal to translate
19//! a screen-space position by a world-space vector and this can be expressed using
20//! the generic Unit parameter.
21//!
22//! This unit system is not mandatory and all Typed* structures have an alias
23//! with the default unit: `UnknownUnit`.
24//! for example ```Point2D<T>``` is equivalent to ```TypedPoint2D<T, UnknownUnit>```.
25//! Client code typically creates a set of aliases for each type and doesn't need
26//! to deal with the specifics of typed units further. For example:
27//!
28//! ```rust
29//! use euclid::*;
30//! pub struct ScreenSpace;
31//! pub type ScreenPoint = TypedPoint2D<f32, ScreenSpace>;
32//! pub type ScreenSize = TypedSize2D<f32, ScreenSpace>;
33//! pub struct WorldSpace;
34//! pub type WorldPoint = TypedPoint3D<f32, WorldSpace>;
35//! pub type ProjectionMatrix = TypedTransform3D<f32, WorldSpace, ScreenSpace>;
36//! // etc...
37//! ```
38//!
39//! All euclid types are marked `#[repr(C)]` in order to facilitate exposing them to
40//! foreign function interfaces (provided the underlying scalar type is also `repr(C)`).
41//!
42//! Components are accessed in their scalar form by default for convenience, and most
43//! types additionally implement strongly typed accessors which return typed ```Length``` wrappers.
44//! For example:
45//!
46//! ```rust
47//! # use euclid::*;
48//! # pub struct WorldSpace;
49//! # pub type WorldPoint = TypedPoint3D<f32, WorldSpace>;
50//! let p = WorldPoint::new(0.0, 1.0, 1.0);
51//! // p.x is an f32.
52//! println!("p.x = {:?} ", p.x);
53//! // p.x is a Length<f32, WorldSpace>.
54//! println!("p.x_typed() = {:?} ", p.x_typed());
55//! // Length::get returns the scalar value (f32).
56//! assert_eq!(p.x, p.x_typed().get());
57//! ```
58
59#[cfg(feature = "serde")]
60#[macro_use]
61extern crate serde;
62
63#[cfg(feature = "mint")]
64pub extern crate mint;
65#[macro_use]
66extern crate euclid_macros;
67extern crate num_traits;
68#[cfg(test)]
69extern crate rand;
70#[cfg(test)]
71use std as core;
72
73pub use box2d::{TypedBox2D, Box2D};
74pub use length::Length;
75pub use scale::TypedScale;
76pub use transform2d::{Transform2D, TypedTransform2D};
77pub use transform3d::{Transform3D, TypedTransform3D};
78pub use point::{Point2D, Point3D, TypedPoint2D, TypedPoint3D, point2, point3};
79pub use vector::{TypedVector2D, TypedVector3D, Vector2D, Vector3D, vec2, vec3};
80pub use vector::{BoolVector2D, BoolVector3D, bvec2, bvec3};
81pub use homogen::HomogeneousVector;
82
83pub use rect::{rect, Rect, TypedRect};
84pub use rigid::{RigidTransform3D, TypedRigidTransform3D};
85pub use box3d::{box3d, Box3D, TypedBox3D};
86pub use translation::{TypedTranslation2D, TypedTranslation3D};
87pub use rotation::{Angle, Rotation2D, Rotation3D, TypedRotation2D, TypedRotation3D};
88pub use side_offsets::{SideOffsets2D, TypedSideOffsets2D};
89pub use size::{Size2D, TypedSize2D, size2};
90pub use trig::Trig;
91
92#[macro_use]
93mod macros;
94
95pub mod approxeq;
96pub mod approxord;
97mod box2d;
98mod homogen;
99pub mod num;
100mod length;
101mod point;
102mod rect;
103mod rigid;
104mod rotation;
105mod scale;
106mod side_offsets;
107mod size;
108mod transform2d;
109mod transform3d;
110mod translation;
111mod trig;
112mod vector;
113mod box3d;
114
115/// The default unit.
116#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
117pub struct UnknownUnit;
118
119/// Temporary alias to facilitate the transition to the new naming scheme
120#[deprecated]
121pub type Matrix2D<T> = Transform2D<T>;
122
123/// Temporary alias to facilitate the transition to the new naming scheme
124#[deprecated]
125pub type TypedMatrix2D<T, Src, Dst> = TypedTransform2D<T, Src, Dst>;
126
127/// Temporary alias to facilitate the transition to the new naming scheme
128#[deprecated]
129pub type Matrix4D<T> = Transform3D<T>;
130
131/// Temporary alias to facilitate the transition to the new naming scheme
132#[deprecated]
133pub type TypedMatrix4D<T, Src, Dst> = TypedTransform3D<T, Src, Dst>;
134
135/// Temporary alias to facilitate the transition to the new naming scheme
136#[deprecated]
137pub type ScaleFactor<T, Src, Dst> = TypedScale<T, Src, Dst>;
138
139/// Temporary alias to facilitate the transition to the new naming scheme
140#[deprecated]
141pub use Angle as Radians;
euclid/lib.rs

euclid/
lib.rs
