mirror of https://github.com/mosra/magnum.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
170 lines
8.1 KiB
170 lines
8.1 KiB
/* |
|
This file is part of Magnum. |
|
|
|
Copyright © 2010, 2011, 2012, 2013, 2014 |
|
Vladimír Vondruš <mosra@centrum.cz> |
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a |
|
copy of this software and associated documentation files (the "Software"), |
|
to deal in the Software without restriction, including without limitation |
|
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
|
and/or sell copies of the Software, and to permit persons to whom the |
|
Software is furnished to do so, subject to the following conditions: |
|
|
|
The above copyright notice and this permission notice shall be included |
|
in all copies or substantial portions of the Software. |
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
|
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
|
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
|
DEALINGS IN THE SOFTWARE. |
|
*/ |
|
|
|
namespace Magnum { |
|
/** @page types Type system |
|
@brief Type aliases, naming and compatibility with OpenGL and GLSL types. |
|
|
|
- Previous page: @ref platform |
|
- Next page: @ref matrix-vector |
|
|
|
The root @ref Magnum namespace defines a few aliases for essential types. See |
|
its documentation for more information about usage with CMake. |
|
|
|
@section types-builtin Builtin types |
|
|
|
%Magnum provides typedefs for builtin integral and floating-point arithmetic |
|
types to ensure portability (e.g. @ref Int is *always* 32bit), maintain |
|
consistency and reduce confusion (e.g. `std::int32_t`, `int` and `GLint` all |
|
refer to the same type). |
|
|
|
| %Magnum type | Size | Equivalent GLSL type | |
|
| ------------------ | -------------- | -------------------- | |
|
| @ref UnsignedByte | 8bit unsigned | | |
|
| @ref Byte | 8bit signed | | |
|
| @ref UnsignedShort | 16bit unsigned | | |
|
| @ref Short | 16bit signed | | |
|
| @ref UnsignedInt | 32bit unsigned | `uint` | |
|
| @ref Int | 32bit signed | `int` | |
|
| @ref UnsignedLong | 64bit unsigned | | |
|
| @ref Long | 64bit signed | | |
|
| @ref Float | 32bit | `float` | |
|
| @ref Double | 64bit | `double` | |
|
|
|
Types not meant to be used in arithmetic (such as `bool` or `std::size_t`) or |
|
types which cannot be directly passed to GLSL shaders (such as `long double`) |
|
have no typedefs. |
|
|
|
Types from the above table are then used to define other types. All following |
|
types are aliases of corresponding types in @ref Math namespace. No suffix |
|
after type name means @ref Float underlying type, `ui` means @ref UnsignedInt |
|
underlying type, `i` is @ref Int underlying type and `d` is for @ref Double |
|
underlying type. |
|
|
|
@section types-matrix Matrix/vector types |
|
|
|
| %Magnum vector type | Equivalent GLSL type | |
|
| ---------------------------------------------- | ------------------------- | |
|
| @ref Vector2, @ref Vector3, @ref Vector4 | `vec2`, `vec3`, `vec4` | |
|
| @ref Vector2ui, @ref Vector3ui, @ref Vector4ui | `uvec2`, `uvec3`, `uvec4` | |
|
| @ref Vector2i, @ref Vector3i, @ref Vector4i | `ivec2`, `ivec3`, `ivec4` | |
|
| @ref Vector2d, @ref Vector3d, @ref Vector4d | `dvec2`, `dvec3`, `dvec4` | |
|
|
|
| %Magnum matrix type | Equivalent GLSL type | |
|
| ---------------------------------------------------------------- | ------------------------------------ | |
|
| @ref Matrix2x2 or @ref Matrix2x2d | `mat2`/`mat2x2` or `dmat2`/`dmat2x2` | |
|
| @ref Matrix3 / @ref Matrix3x3 or @ref Matrix3d / @ref Matrix3x3d | `mat3`/`mat3x3` or `dmat3`/`dmat3x3` | |
|
| @ref Matrix4 / @ref Matrix4x4 or @ref Matrix4d / @ref Matrix4x4d | `mat4`/`mat4x4` or `dmat4`/`dmat4x4` | |
|
| @ref Matrix2x3 or @ref Matrix2x3d | `mat2x3` or `dmat2x3` | |
|
| @ref Matrix3x2 or @ref Matrix3x2d | `mat3x2` or `dmat3x2` | |
|
| @ref Matrix2x4 or @ref Matrix2x4d | `mat2x4` or `dmat2x4` | |
|
| @ref Matrix4x2 or @ref Matrix4x2d | `mat4x2` or `dmat4x2` | |
|
| @ref Matrix3x4 or @ref Matrix3x4d | `mat3x4` or `dmat3x4` | |
|
| @ref Matrix4x3 or @ref Matrix4x3d | `mat4x3` or `dmat4x3` | |
|
|
|
Any super- or sub-class of the same size and underlying type can be used |
|
equivalently (e.g. @ref Math::Vector or @ref Color3 instead of @ref Vector3). |
|
|
|
@section types-binary Binary representation |
|
|
|
Scalar types with GLSL equivalent are verified to be exactly the same as |
|
corresponding `GL*` types. Matrix and vector classes have the same binary |
|
representation as corresponding array of numeric values without any additional |
|
data or padding (e.g. `sizeof(Vector3i) == sizeof(Int[3])`), all matrices are |
|
stored in column-major order. |
|
|
|
This means that all scalar, matrix and vector types can be used directly for |
|
filling GPU buffers and textures without any need for data extraction or |
|
conversion. For convenience all vector and matrix classes provide |
|
@ref Math::RectangularMatrix::data() "data()" function, which returns pointer |
|
to the internal data array. |
|
|
|
@section types-special Special types |
|
|
|
%Magnum has special type for strongly-typed representation of angles, namely |
|
the @ref Deg and @ref Rad classes (or @ref Degd and @ref Radd with @ref Double |
|
as underlying type). Their only purpose is to avoid common degree-vs-radian |
|
bugs (i.e. entering degree value where radians should be) and make the |
|
conversion between these two representations easier. They are just a tiny |
|
`inline` `constexpr` wrapper around the native type and they support all |
|
meaningful numeric operations, so using them won't have any performance or |
|
usability impact in practice. |
|
|
|
These classes are *not* implicitly constructible or convertible from/to |
|
@ref Float or @ref Double, you have to either construct/convert them explicitly |
|
or use custom `_degf`/`_deg` and `_radf`/`_rad` literals: |
|
@code |
|
//Deg a = 60.0f // error, no implicit conversion from Float |
|
Deg a = 60.0_degf; // okay |
|
|
|
Float b = 3.2831853f; |
|
auto tau = Rad{b} + 3.0_radf; |
|
Radd pi = 3.141592653589793_rad; |
|
|
|
//Double c = pi; // error, no implicit conversion to Double |
|
auto c = Double{pi}; // okay |
|
@endcode |
|
|
|
They can be implicitly converted to each other, but conversion to different |
|
underlying type is *explicit* to avoid precision loss (or, on the other hand, |
|
unnecessarily high precision) during computations: |
|
@code |
|
Rad d = 60.0_degf; // 1.0471976f |
|
auto e = Degd{pi}; // 180.0 |
|
|
|
//Rad f = pi; // error, no implicit conversion of underlying types |
|
auto f = Rad{pi}; // 3.141592654f |
|
@endcode |
|
|
|
These classes are used exclusively in all functions taking and returning angles |
|
-- trigonometry, angle computation, rotating transformation etc. Thanks to |
|
implicit conversion you can seamlessly use either radians or degrees without |
|
any need to care about what input the function expects: |
|
@code |
|
Float a = Math::sin(1.32457_radf); |
|
Complex b = Complex::rotation(60.0_degf); |
|
@endcode |
|
|
|
@section types-other Other types |
|
|
|
Other types, which don't have their GLSL equivalent, are: |
|
|
|
- @ref Complex or @ref Complexd, @ref DualComplex or @ref DualComplexd |
|
- @ref Quaternion or @ref Quaterniond, @ref DualQuaternion or |
|
@ref DualQuaterniond |
|
- @ref Range1D / @ref Range2D / @ref Range3D, @ref Range1Di / @ref Range2Di / |
|
@ref Range3Di or @ref Range1Dd / @ref Range2Dd / @ref Range3Dd |
|
|
|
These types can be used in GLSL either by extracting values from their |
|
underlying structure or converting them to types supported by GLSL (e.g. |
|
quaternion to matrix). |
|
|
|
For your convenience, there is also alias for class with often used constants |
|
-- @ref Constants or @ref Constantsd. |
|
|
|
- Previous page: @ref platform |
|
- Next page: @ref matrix-vector |
|
*/ |
|
}
|
|
|