2013-08-26 05:08:25 +00:00
|
|
|
# cgmath-rs
|
2012-11-01 05:58:36 +00:00
|
|
|
|
2016-08-17 13:03:39 +00:00
|
|
|
[](https://travis-ci.org/brendanzab/cgmath)
|
2016-09-05 19:01:27 +00:00
|
|
|
[](https://docs.rs/cgmath)
|
2015-10-02 05:28:04 +00:00
|
|
|
[](https://crates.io/crates/cgmath)
|
2016-08-17 13:03:39 +00:00
|
|
|
[](https://github.com/brendanzab/cgmath/blob/master/LICENSE)
|
2015-10-02 05:28:04 +00:00
|
|
|
[](https://crates.io/crates/cgmath)
|
2016-09-14 13:00:44 +00:00
|
|
|
[](https://gitter.im/brendanzab/cgmath)
|
2015-09-20 05:42:10 +00:00
|
|
|
|
2013-08-26 05:08:25 +00:00
|
|
|
A linear algebra and mathematics library for computer graphics.
|
2013-08-27 11:12:42 +00:00
|
|
|
|
2013-09-03 05:13:10 +00:00
|
|
|
The library provides:
|
|
|
|
|
|
2014-10-23 08:30:33 +00:00
|
|
|
- vectors: `Vector2`, `Vector3`, `Vector4`
|
|
|
|
|
- square matrices: `Matrix2`, `Matrix3`, `Matrix4`
|
|
|
|
|
- a quaternion type: `Quaternion`
|
|
|
|
|
- rotation matrices: `Basis2`, `Basis3`
|
2013-09-17 09:02:28 +00:00
|
|
|
- angle units: `Rad`, `Deg`
|
2013-09-20 06:45:51 +00:00
|
|
|
- points: `Point2`, `Point3`
|
2013-09-17 09:02:28 +00:00
|
|
|
- perspective projections: `Perspective`, `PerspectiveFov`, `Ortho`
|
2014-10-23 08:30:33 +00:00
|
|
|
- spatial transformations: `AffineMatrix3`, `Transform3`
|
2013-09-03 05:13:10 +00:00
|
|
|
|
2013-09-17 09:02:28 +00:00
|
|
|
Not all of the functionality has been implemented yet, and the existing code
|
|
|
|
|
is not fully covered by the testsuite. If you encounter any mistakes or
|
|
|
|
|
omissions please let me know by posting an issue, or even better: send me a
|
|
|
|
|
pull request with a fix.
|
|
|
|
|
|
2016-04-09 16:44:23 +00:00
|
|
|
## Conventions
|
|
|
|
|
|
|
|
|
|
cgmath interprets its vectors as column matrices (also known as "column
|
|
|
|
|
vectors"), meaning when transforming a vector with a matrix, the matrix goes
|
2016-08-17 13:03:39 +00:00
|
|
|
on the left. This is reflected in the fact that cgmath implements the
|
2016-04-09 16:44:23 +00:00
|
|
|
multiplication operator for Matrix * Vector, but not Vector * Matrix.
|
|
|
|
|
|
2017-10-01 21:23:07 +00:00
|
|
|
## Features
|
|
|
|
|
|
|
|
|
|
### Swizzling
|
|
|
|
|
This library offers an optional feature called
|
|
|
|
|
["swizzling"](https://en.wikipedia.org/wiki/Swizzling_(computer_graphics))
|
|
|
|
|
widely familiar to GPU programmers. To enable swizzle operators, pass the
|
|
|
|
|
`--features="swizzle"` option to cargo. Enabling this feature will increase
|
|
|
|
|
the size of the cgmath library by approximately 0.6MB. This isn't an
|
|
|
|
|
issue if the library is linked in the "normal" way by adding cgmath as a
|
|
|
|
|
dependency in Cargo.toml, which will link cgmath statically so all unused
|
|
|
|
|
swizzle operators will be optimized away by the compiler in release mode.
|
|
|
|
|
|
|
|
|
|
#### Example
|
|
|
|
|
If we have
|
|
|
|
|
```rust
|
|
|
|
|
let v = Vector3::new(1.0, 2.0, 3.0);
|
|
|
|
|
```
|
|
|
|
|
then `v.xyxz()` produces a
|
|
|
|
|
```rust
|
|
|
|
|
Vector4 { x: 1.0, y: 2.0, z: 1.0, w: 3.0 }
|
|
|
|
|
```
|
|
|
|
|
and `v.zy()` produces a
|
|
|
|
|
```rust
|
|
|
|
|
Vector2 { x: 3.0, y: 2.0 }
|
|
|
|
|
```
|
|
|
|
|
|
2013-09-03 05:13:10 +00:00
|
|
|
## Limitations
|
|
|
|
|
|
|
|
|
|
cgmath is _not_ an n-dimensional library and is aimed at computer graphics
|
|
|
|
|
applications rather than general linear algebra. It only offers the 2, 3, and
|
2016-05-02 22:45:29 +00:00
|
|
|
4 dimensional structures that are more than enough for most computer graphics
|
2013-09-03 05:13:10 +00:00
|
|
|
applications. This design decision was made in order to simplify the
|
2016-05-02 22:45:29 +00:00
|
|
|
implementation (Rust cannot parameterize over constants at compile time), and to
|
2014-01-27 05:11:20 +00:00
|
|
|
make dimension-specific optimisations easier in the future.
|
2013-09-03 05:13:10 +00:00
|
|
|
|
|
|
|
|
## Contributing
|
|
|
|
|
|
|
|
|
|
Pull requests are most welcome, especially in the realm of performance
|
|
|
|
|
enhancements and fixing any mistakes I may have made along the way. Unit tests
|
|
|
|
|
and benchmarks are also required, so help on that front would be most
|
2013-09-17 09:02:28 +00:00
|
|
|
appreciated.
|
2013-09-21 08:09:15 +00:00
|
|
|
|
|
|
|
|
## Support
|
|
|
|
|
|
|
|
|
|
Contact `bjz` on irc.mozilla.org [#rust](http://mibbit.com/?server=irc.mozilla.org&channel=%23rust)
|
|
|
|
|
and [#rust-gamedev](http://mibbit.com/?server=irc.mozilla.org&channel=%23rust-gamedev),
|
2015-12-23 19:03:49 +00:00
|
|
|
or [post an issue](https://github.com/bjz/cgmath/issues/new) on Github.
|
