magnum/doc/types.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013 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

@section types-builtin Builtin types

%Magnum provides typedefs for builtin integral and floating-point arithmetic
types to ensure portability (e.g. 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 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 Matrix2 or @ref Matrix2d     | `mat2`/`mat2x2` or `dmat2`/`dmat2x2` |
| @ref Matrix3 or @ref Matrix3d     | `mat3`/`mat3x3` or `dmat3`/`dmat3x3` |
| @ref Matrix4 or @ref Matrix4d     | `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. Math::Vector or Color3 instead of @ref Vector3).

@section types-other Other types

Other types, which don't have their GLSL equivalent, are:

 - @ref Rectangle, @ref Rectanglei or @ref Rectangled
 - @ref Complex or @ref Complexd, @ref DualComplex or @ref DualComplexd
 - @ref Quaternion or @ref Quaterniond, @ref DualQuaternion or @ref DualQuaterniond

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.

*/
}