Our own aliases for builtin types.

It seems like a bad idea, but it will:

 * Improve portability, as `Int` will be always 32bit.
 * Improve readability, as `std::int32_t` is just plain ugly and too
   complicated to write.
 * Improve consistency and reduce confusion, as it's not good to mix
   `int`, `std::int32_t`, `GLint`, `khronos_int_t` and whatnot in one
   codebase.
 * Possibly reduce compilation time, because including all ~35k lines
   worth of GL headers just for one GLfloat typedef is even worse than
   now forbidden #include <iostream> in headers.

doc/features.dox

@@ -2,10 +2,11 @@ namespace Magnum {
 /** @page features Feature overview
 @brief Fundamental principles and design goals
 
-- @subpage matrix-vector - @copybrief matrix-vector
+- @subpage types -- @copybrief types
-- @subpage transformations - @copybrief transformations
+- @subpage matrix-vector -- @copybrief matrix-vector
-- @subpage scenegraph - @copybrief scenegraph
+- @subpage transformations -- @copybrief transformations
-- @subpage collision-detection - @copybrief collision-detection
+- @subpage scenegraph -- @copybrief scenegraph
-- @subpage debug-tools - @copybrief debug-tools
+- @subpage collision-detection -- @copybrief collision-detection
+- @subpage debug-tools -- @copybrief debug-tools
 */
 }

doc/types.dox

@@ -0,0 +1,72 @@
+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 `dmat3`/`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 or @ref Rectanglei
+ - @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).
+
+*/
+}

src/AbstractShaderProgram.h

@@ -219,53 +219,29 @@ mesh.draw();
 
 @section AbstractShaderProgram-types Mapping between GLSL and Magnum types
 
-- `vec2`, `vec3` and `vec4` is @ref Math::Vector "Math::Vector<2, GLfloat>",
+See @ref types for more information, only types with GLSL equivalent can be used
-  @ref Math::Vector "Math::Vector<3, GLfloat>" and
+(and their super- or subclasses with the same size and underlying type).
-  @ref Math::Vector "Math::Vector<4, GLfloat>".
+
-
+@requires_gl30 %Extension @extension{EXT,gpu_shader4} is required when using
-- `mat2`, `mat3` and `mat4` is @ref Math::Matrix "Math::Matrix<2, GLfloat>",
+    integer attributes (i.e. UnsignedInt, Int, Vector2ui, Vector2i, Vector3ui,
-  @ref Math::Matrix "Math::Matrix<3, GLfloat>" and
+    Vector3i, Vector4ui and Vector4i) or unsigned integer uniforms. (i.e.
-  @ref Math::Matrix "Math::Matrix<4, GLfloat>".
+    UnsignedInt, Vector2ui, Vector3ui and Vector4ui).
-
+@requires_gles30 Integer attributes and unsigned integer uniforms are not
-- `mat2x3`, `mat3x2`, `mat2x4`, `mat4x2`, `mat3x4`, `mat4x3` is
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<2, 3, GLfloat>",
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<3, 2, GLfloat>",
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<2, 4, GLfloat>",
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<4, 2, GLfloat>",
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<3, 4, GLfloat>" and
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<4, 3, GLfloat>".
-
-- `ivec2`, `ivec3` and `ivec4` is @ref Math::Vector "Math::Vector<2, GLint>",
-  @ref Math::Vector "Math::Vector<3, GLint>" and
-  @ref Math::Vector "Math::Vector<4, GLint>", `uvec2`, `uvec3` and `uvec4` is
-  @ref Math::Vector "Math::Vector<2, GLuint>",
-  @ref Math::Vector "Math::Vector<3, GLuint>" and
-  @ref Math::Vector "Math::Vector<4, GLuint>".
-  @requires_gl30 %Extension @extension{EXT,gpu_shader4} (for integer attributes
-    and unsigned integer uniforms)
-  @requires_gles30 Integer attributes and unsigned integer uniforms are not
     available in OpenGL ES 2.0.
 
-- `dvec2`, `dvec3` and `dvec4` is @ref Math::Vector "Math::Vector<2, GLdouble>",
+@requires_gl40 %Extension @extension{ARB,gpu_shader_fp64} is required when
-  @ref Math::Vector "Math::Vector<3, GLdouble>" and
+    using double uniforms (i.e. Double, Vector2d, Vector3d, Vector4d, Matrix2d,
-  @ref Math::Vector "Math::Vector<4, GLdouble>", `dmat2`, `dmat3` and `dmat4`
+    Matrix3d, Matrix4d, Matrix2x3d, Matrix3x2d, Matrix2x4d, Matrix4x2d,
-  is @ref Math::Matrix "Math::Matrix<2, GLdouble>",
+    Matrix3x4d and Matrix4x3d).
-  @ref Math::Matrix "Math::Matrix<3, GLdouble>" and
+@requires_gl41 %Extension @extension{ARB,vertex_attrib_64bit} is required when
-  @ref Math::Matrix "Math::Matrix<4, GLdouble>", `dmat2x3`, `dmat3x2`,
+    using double attributes (i.e. Double, Vector2d, Vector3d, Vector4d, Matrix2d,
-  `dmat2x4`, `dmat4x2`, `dmat3x4`, `dmat4x3` is
+    Matrix3d, Matrix4d, Matrix2x3d, Matrix3x2d, Matrix2x4d, Matrix4x2d,
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<2, 3, GLdouble>",
+    Matrix3x4d and Matrix4x3d).
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<3, 2, GLdouble>",
+@requires_gl Double attributes and uniforms are not available in OpenGL ES.
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<2, 4, GLdouble>",
+
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<4, 2, GLdouble>",
+@requires_gles30 Non-square matrix attributes and uniforms (i.e. Matrix2x3,
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<3, 4, GLdouble>" and
+    Matrix3x2, Matrix2x4, Matrix4x2, Matrix3x4 and Matrix4x3) are not available
-  @ref Math::RectangularMatrix "Math::RectangularMatrix<4, 3, GLdouble>".
+    in OpenGL ES 2.0.
-  @requires_gl41 %Extension @extension{ARB,vertex_attrib_64bit} (for double
-    attributes)
-  @requires_gl Double attributes are not available in OpenGL ES.
-
-Only types listed here (and their subclasses and specializations, such as
-@ref Matrix3 or Color4) can be used for setting uniforms and specifying
-vertex attributes.
 
 @section AbstractShaderProgram-performance-optimization Performance optimizations
 

src/CMakeLists.txt

@@ -78,6 +78,7 @@ set(Magnum_HEADERS
     Swizzle.h
     Texture.h
     Timeline.h
+    Types.h
 
     magnumVisibility.h)
 

src/Magnum.h

@@ -19,10 +19,10 @@
  * @brief Basic definitions and forward declarations for Magnum namespace
  */
 
-#include <cstdint>
 #include <corradeConfigure.h>
 
 #include "Math/Math.h"
+#include "Types.h"
 
 #include "magnumConfigure.h"
 
@@ -53,10 +53,10 @@ namespace Magnum {
 namespace Math {
     template<class T> struct Constants;
 
-    constexpr Rad<double> operator "" _rad(long double);
+    constexpr Rad<Double> operator "" _rad(long double);
-    constexpr Rad<float> operator "" _radf(long double);
+    constexpr Rad<Float> operator "" _radf(long double);
-    constexpr Deg<double> operator "" _deg(long double);
+    constexpr Deg<Double> operator "" _deg(long double);
-    constexpr Deg<float> operator "" _degf(long double);
+    constexpr Deg<Float> operator "" _degf(long double);
 }
 
 /* Bring debugging facility from Corrade::Utility namespace */
@@ -65,85 +65,193 @@ using Corrade::Utility::Warning;
 using Corrade::Utility::Error;
 #endif
 
+/** @{ @name Basic type definitions
+
+See @ref types for more information.
+*/
+
+/** @brief Unsigned byte (8bit) */
+typedef std::uint8_t UnsignedByte;
+
+/** @brief Signed byte (8bit) */
+typedef std::int8_t Byte;
+
+/** @brief Unsigned short (16bit) */
+typedef std::uint16_t UnsignedShort;
+
+/** @brief Signed short (16bit) */
+typedef std::int16_t Short;
+
+/** @brief Unsigned int (32bit) */
+typedef std::uint32_t UnsignedInt;
+
+/** @brief Signed int (32bit) */
+typedef std::int32_t Int;
+
+/** @brief Unsigned long (64bit) */
+typedef std::uint64_t UnsignedLong;
+
+/** @brief Signed long (64bit) */
+typedef std::int64_t Long;
+
+/** @brief Float (32bit) */
+typedef float Float;
+
 /** @brief Two-component float vector */
-typedef Math::Vector2<GLfloat> Vector2;
+typedef Math::Vector2<Float> Vector2;
 
 /** @brief Three-component float vector */
-typedef Math::Vector3<GLfloat> Vector3;
+typedef Math::Vector3<Float> Vector3;
 
 /** @brief Four-component float vector */
-typedef Math::Vector4<GLfloat> Vector4;
+typedef Math::Vector4<Float> Vector4;
+
+/** @brief Two-component unsigned integer vector */
+typedef Math::Vector2<UnsignedInt> Vector2ui;
+
+/** @brief Three-component unsigned integer vector */
+typedef Math::Vector3<UnsignedInt> Vector3ui;
+
+/** @brief Four-component unsigned integer vector */
+typedef Math::Vector4<UnsignedInt> Vector4ui;
 
 /** @brief Two-component signed integer vector */
-typedef Math::Vector2<GLint> Vector2i;
+typedef Math::Vector2<Int> Vector2i;
 
 /** @brief Three-component signed integer vector */
-typedef Math::Vector3<GLint> Vector3i;
+typedef Math::Vector3<Int> Vector3i;
 
 /** @brief Four-component signed integer vector */
-typedef Math::Vector4<GLint> Vector4i;
+typedef Math::Vector4<Int> Vector4i;
 
-/** @brief Two-component unsigned integer vector */
+/** @brief 2x2 float matrix */
-typedef Math::Vector2<GLuint> Vector2ui;
+typedef Math::Matrix<2, Float> Matrix2;
 
-/** @brief Three-component unsigned integer vector */
+/** @brief 3x3 float matrix */
-typedef Math::Vector3<GLuint> Vector3ui;
+typedef Math::Matrix3<Float> Matrix3;
 
-/** @brief Four-component unsigned integer vector */
+/** @brief 4x4 float matrix */
-typedef Math::Vector4<GLuint> Vector4ui;
+typedef Math::Matrix4<Float> Matrix4;
+
+/** @brief Float matrix with 2 columns and 3 rows */
+typedef Math::RectangularMatrix<2, 3, Float> Matrix2x3;
+
+/** @brief Float matrix with 3 columns and 2 rows */
+typedef Math::RectangularMatrix<3, 2, Float> Matrix3x2;
+
+/** @brief Float matrix with 2 columns and 4 rows */
+typedef Math::RectangularMatrix<2, 4, Float> Matrix2x4;
+
+/** @brief Float matrix with 4 columns and 2 rows */
+typedef Math::RectangularMatrix<4, 2, Float> Matrix4x2;
+
+/** @brief Float matrix with 3 columns and 4 rows */
+typedef Math::RectangularMatrix<3, 4, Float> Matrix3x4;
+
+/** @brief Float matrix with 4 columns and 3 rows */
+typedef Math::RectangularMatrix<4, 3, Float> Matrix4x3;
+
+/** @brief Float complex number */
+typedef Math::Complex<Float> Complex;
+
+/** @brief Float dual complex number */
+typedef Math::DualComplex<Float> DualComplex;
+
+/** @brief Float quaternion */
+typedef Math::Quaternion<Float> Quaternion;
+
+/** @brief Float dual quaternion */
+typedef Math::DualQuaternion<Float> DualQuaternion;
+
+/** @brief Float constants */
+typedef Math::Constants<Float> Constants;
+
+/** @brief Angle in float degrees */
+typedef Math::Deg<Float> Deg;
+
+/** @brief Angle in float radians */
+typedef Math::Rad<Float> Rad;
+
+/** @brief Float rectangle */
+typedef Math::Geometry::Rectangle<Float> Rectangle;
+
+/** @brief Signed integer rectangle */
+typedef Math::Geometry::Rectangle<Int> Rectanglei;
+
+/*@}*/
 
 #ifndef MAGNUM_TARGET_GLES
+/** @{ @name Double-precision types
+
+See @ref types for more information.
+@requires_gl Only single-precision types are available in OpenGL ES.
+*/
+
+/** @brief Double (64bit) */
+typedef double Double;
+
 /** @brief Two-component double vector */
-typedef Math::Vector2<GLdouble> Vector2d;
+typedef Math::Vector2<Double> Vector2d;
 
 /** @brief Three-component double vector */
-typedef Math::Vector3<GLdouble> Vector3d;
+typedef Math::Vector3<Double> Vector3d;
 
 /** @brief Four-component double vector */
-typedef Math::Vector4<GLdouble> Vector4d;
+typedef Math::Vector4<Double> Vector4d;
-#endif
 
-/** @brief 3x3 float matrix */
+/** @brief 2x2 double matrix */
-typedef Math::Matrix3<GLfloat> Matrix3;
+typedef Math::Matrix<2, Double> Matrix2d;
 
-/** @brief 4x4 float matrix */
-typedef Math::Matrix4<GLfloat> Matrix4;
-
-#ifndef MAGNUM_TARGET_GLES
 /** @brief 3x3 double matrix */
-typedef Math::Matrix3<GLdouble> Matrix3d;
+typedef Math::Matrix3<Double> Matrix3d;
 
 /** @brief 4x4 double matrix */
-typedef Math::Matrix4<GLdouble> Matrix4d;
+typedef Math::Matrix4<Double> Matrix4d;
-#endif
 
-/** @brief %Complex number */
+/** @brief Double matrix with 2 columns and 3 rows */
-typedef Math::Complex<GLfloat> Complex;
+typedef Math::RectangularMatrix<2, 3, Double> Matrix2x3d;
 
-/** @brief %Dual complex number */
+/** @brief Double matrix with 3 columns and 2 rows */
-typedef Math::DualComplex<GLfloat> DualComplex;
+typedef Math::RectangularMatrix<3, 2, Double> Matrix3x2d;
 
-/** @brief %Quaternion */
+/** @brief Double matrix with 2 columns and 4 rows */
-typedef Math::Quaternion<GLfloat> Quaternion;
+typedef Math::RectangularMatrix<2, 4, Double> Matrix2x4d;
 
-/** @brief %Dual quaternion */
+/** @brief Double matrix with 4 columns and 2 rows */
-typedef Math::DualQuaternion<GLfloat> DualQuaternion;
+typedef Math::RectangularMatrix<4, 2, Double> Matrix4x2d;
 
-/** @brief Floating-point constants */
+/** @brief Double matrix with 3 columns and 4 rows */
-/* Using float instead of GLfloat to not break KDevelop autocompletion */
+typedef Math::RectangularMatrix<3, 4, Double> Matrix3x4d;
-typedef Math::Constants<float> Constants;
 
-/** @brief Angle in single-precision degrees */
+/** @brief Double matrix with 4 columns and 3 rows */
-typedef Math::Deg<float> Deg;
+typedef Math::RectangularMatrix<4, 3, Double> Matrix4x3d;
 
-/** @brief Angle in single-precision radians */
+/** @brief Double complex number */
-typedef Math::Rad<float> Rad;
+typedef Math::Complex<Double> Complexd;
 
-/** @brief Floating-point rectangle */
+/** @brief Double dual complex number */
-typedef Math::Geometry::Rectangle<GLfloat> Rectangle;
+typedef Math::DualComplex<Double> DualComplexd;
 
-/** @brief Integer rectangle */
+/** @brief Double quaternion */
-typedef Math::Geometry::Rectangle<GLint> Rectanglei;
+typedef Math::Quaternion<Double> Quaterniond;
+
+/** @brief Double dual quaternion */
+typedef Math::DualQuaternion<Double> DualQuaterniond;
+
+/** @brief Double constants */
+typedef Math::Constants<Double> Constantsd;
+
+/** @brief Angle in double degrees */
+typedef Math::Deg<Double> Degd;
+
+/** @brief Angle in double radians */
+typedef Math::Rad<Double> Radd;
+
+/** @brief Double rectangle */
+typedef Math::Geometry::Rectangle<Double> Rectangled;
+
+/*@}*/
+#endif
 
 /* Using angle literals from Math namespace */
 using Math::operator "" _deg;

src/Types.h

@@ -0,0 +1,45 @@
+#ifndef Magnum_Types_h
+#define Magnum_Types_h
+/*
+    Copyright © 2010, 2011, 2012 Vladimír Vondruš <mosra@centrum.cz>
+
+    This file is part of Magnum.
+
+    Magnum is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License version 3
+    only, as published by the Free Software Foundation.
+
+    Magnum is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    GNU Lesser General Public License version 3 for more details.
+*/
+
+/** @file
+ * @brief Declarations of built-in types
+ */
+
+#include <cstdint>
+
+#include "magnumConfigure.h"
+
+namespace Magnum {
+
+/* Documented in Magnum.h */
+typedef std::uint8_t UnsignedByte;
+typedef std::int8_t Byte;
+typedef std::uint16_t UnsignedShort;
+typedef std::int16_t Short;
+typedef std::uint32_t UnsignedInt;
+typedef std::int32_t Int;
+typedef std::uint64_t UnsignedLong;
+typedef std::int64_t Long;
+typedef float Float;
+
+#ifndef MAGNUM_TARGET_GLES
+typedef double Double;
+#endif
+
+}
+
+#endif