From 6220f24f0b2bacae73d512954be59c96e4e2ecdb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 27 Feb 2013 16:35:24 +0100 Subject: [PATCH] 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 in headers. --- doc/features.dox | 11 +- doc/types.dox | 72 +++++++++++++ src/AbstractShaderProgram.h | 66 ++++-------- src/CMakeLists.txt | 1 + src/Magnum.h | 206 +++++++++++++++++++++++++++--------- src/Types.h | 45 ++++++++ 6 files changed, 302 insertions(+), 99 deletions(-) create mode 100644 doc/types.dox create mode 100644 src/Types.h diff --git a/doc/features.dox b/doc/features.dox index 0a084a3bc..137c52c9a 100644 --- a/doc/features.dox +++ b/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 transformations - @copybrief transformations -- @subpage scenegraph - @copybrief scenegraph -- @subpage collision-detection - @copybrief collision-detection -- @subpage debug-tools - @copybrief debug-tools +- @subpage types -- @copybrief types +- @subpage matrix-vector -- @copybrief matrix-vector +- @subpage transformations -- @copybrief transformations +- @subpage scenegraph -- @copybrief scenegraph +- @subpage collision-detection -- @copybrief collision-detection +- @subpage debug-tools -- @copybrief debug-tools */ } diff --git a/doc/types.dox b/doc/types.dox new file mode 100644 index 000000000..bce7c53ef --- /dev/null +++ b/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). + +*/ +} diff --git a/src/AbstractShaderProgram.h b/src/AbstractShaderProgram.h index 53b69ce6c..c38b7de4a 100644 --- a/src/AbstractShaderProgram.h +++ b/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>", - @ref Math::Vector "Math::Vector<3, GLfloat>" and - @ref Math::Vector "Math::Vector<4, GLfloat>". - -- `mat2`, `mat3` and `mat4` is @ref Math::Matrix "Math::Matrix<2, GLfloat>", - @ref Math::Matrix "Math::Matrix<3, GLfloat>" and - @ref Math::Matrix "Math::Matrix<4, GLfloat>". - -- `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 +See @ref types for more information, only types with GLSL equivalent can be used +(and their super- or subclasses with the same size and underlying type). + +@requires_gl30 %Extension @extension{EXT,gpu_shader4} is required when using + integer attributes (i.e. UnsignedInt, Int, Vector2ui, Vector2i, Vector3ui, + Vector3i, Vector4ui and Vector4i) or unsigned integer uniforms. (i.e. + UnsignedInt, Vector2ui, Vector3ui and Vector4ui). +@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>", - @ref Math::Vector "Math::Vector<3, GLdouble>" and - @ref Math::Vector "Math::Vector<4, GLdouble>", `dmat2`, `dmat3` and `dmat4` - is @ref Math::Matrix "Math::Matrix<2, GLdouble>", - @ref Math::Matrix "Math::Matrix<3, GLdouble>" and - @ref Math::Matrix "Math::Matrix<4, GLdouble>", `dmat2x3`, `dmat3x2`, - `dmat2x4`, `dmat4x2`, `dmat3x4`, `dmat4x3` is - @ref Math::RectangularMatrix "Math::RectangularMatrix<2, 3, GLdouble>", - @ref Math::RectangularMatrix "Math::RectangularMatrix<3, 2, GLdouble>", - @ref Math::RectangularMatrix "Math::RectangularMatrix<2, 4, GLdouble>", - @ref Math::RectangularMatrix "Math::RectangularMatrix<4, 2, GLdouble>", - @ref Math::RectangularMatrix "Math::RectangularMatrix<3, 4, GLdouble>" and - @ref Math::RectangularMatrix "Math::RectangularMatrix<4, 3, GLdouble>". - @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. +@requires_gl40 %Extension @extension{ARB,gpu_shader_fp64} is required when + using double uniforms (i.e. Double, Vector2d, Vector3d, Vector4d, Matrix2d, + Matrix3d, Matrix4d, Matrix2x3d, Matrix3x2d, Matrix2x4d, Matrix4x2d, + Matrix3x4d and Matrix4x3d). +@requires_gl41 %Extension @extension{ARB,vertex_attrib_64bit} is required when + using double attributes (i.e. Double, Vector2d, Vector3d, Vector4d, Matrix2d, + Matrix3d, Matrix4d, Matrix2x3d, Matrix3x2d, Matrix2x4d, Matrix4x2d, + Matrix3x4d and Matrix4x3d). +@requires_gl Double attributes and uniforms are not available in OpenGL ES. + +@requires_gles30 Non-square matrix attributes and uniforms (i.e. Matrix2x3, + Matrix3x2, Matrix2x4, Matrix4x2, Matrix3x4 and Matrix4x3) are not available + in OpenGL ES 2.0. @section AbstractShaderProgram-performance-optimization Performance optimizations diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 56b94d28d..136a082dc 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -78,6 +78,7 @@ set(Magnum_HEADERS Swizzle.h Texture.h Timeline.h + Types.h magnumVisibility.h) diff --git a/src/Magnum.h b/src/Magnum.h index 0fdb9e711..862b2b14d 100644 --- a/src/Magnum.h +++ b/src/Magnum.h @@ -19,10 +19,10 @@ * @brief Basic definitions and forward declarations for Magnum namespace */ -#include #include #include "Math/Math.h" +#include "Types.h" #include "magnumConfigure.h" @@ -53,10 +53,10 @@ namespace Magnum { namespace Math { template struct Constants; - constexpr Rad operator "" _rad(long double); - constexpr Rad operator "" _radf(long double); - constexpr Deg operator "" _deg(long double); - constexpr Deg operator "" _degf(long double); + constexpr Rad operator "" _rad(long double); + constexpr Rad operator "" _radf(long double); + constexpr Deg operator "" _deg(long double); + constexpr Deg 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 Vector2; +typedef Math::Vector2 Vector2; /** @brief Three-component float vector */ -typedef Math::Vector3 Vector3; +typedef Math::Vector3 Vector3; /** @brief Four-component float vector */ -typedef Math::Vector4 Vector4; +typedef Math::Vector4 Vector4; + +/** @brief Two-component unsigned integer vector */ +typedef Math::Vector2 Vector2ui; + +/** @brief Three-component unsigned integer vector */ +typedef Math::Vector3 Vector3ui; + +/** @brief Four-component unsigned integer vector */ +typedef Math::Vector4 Vector4ui; /** @brief Two-component signed integer vector */ -typedef Math::Vector2 Vector2i; +typedef Math::Vector2 Vector2i; /** @brief Three-component signed integer vector */ -typedef Math::Vector3 Vector3i; +typedef Math::Vector3 Vector3i; /** @brief Four-component signed integer vector */ -typedef Math::Vector4 Vector4i; +typedef Math::Vector4 Vector4i; -/** @brief Two-component unsigned integer vector */ -typedef Math::Vector2 Vector2ui; +/** @brief 2x2 float matrix */ +typedef Math::Matrix<2, Float> Matrix2; -/** @brief Three-component unsigned integer vector */ -typedef Math::Vector3 Vector3ui; +/** @brief 3x3 float matrix */ +typedef Math::Matrix3 Matrix3; -/** @brief Four-component unsigned integer vector */ -typedef Math::Vector4 Vector4ui; +/** @brief 4x4 float matrix */ +typedef Math::Matrix4 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 Complex; + +/** @brief Float dual complex number */ +typedef Math::DualComplex DualComplex; + +/** @brief Float quaternion */ +typedef Math::Quaternion Quaternion; + +/** @brief Float dual quaternion */ +typedef Math::DualQuaternion DualQuaternion; + +/** @brief Float constants */ +typedef Math::Constants Constants; + +/** @brief Angle in float degrees */ +typedef Math::Deg Deg; + +/** @brief Angle in float radians */ +typedef Math::Rad Rad; + +/** @brief Float rectangle */ +typedef Math::Geometry::Rectangle Rectangle; + +/** @brief Signed integer rectangle */ +typedef Math::Geometry::Rectangle 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 Vector2d; +typedef Math::Vector2 Vector2d; /** @brief Three-component double vector */ -typedef Math::Vector3 Vector3d; +typedef Math::Vector3 Vector3d; /** @brief Four-component double vector */ -typedef Math::Vector4 Vector4d; -#endif +typedef Math::Vector4 Vector4d; -/** @brief 3x3 float matrix */ -typedef Math::Matrix3 Matrix3; +/** @brief 2x2 double matrix */ +typedef Math::Matrix<2, Double> Matrix2d; -/** @brief 4x4 float matrix */ -typedef Math::Matrix4 Matrix4; - -#ifndef MAGNUM_TARGET_GLES /** @brief 3x3 double matrix */ -typedef Math::Matrix3 Matrix3d; +typedef Math::Matrix3 Matrix3d; /** @brief 4x4 double matrix */ -typedef Math::Matrix4 Matrix4d; -#endif +typedef Math::Matrix4 Matrix4d; -/** @brief %Complex number */ -typedef Math::Complex Complex; +/** @brief Double matrix with 2 columns and 3 rows */ +typedef Math::RectangularMatrix<2, 3, Double> Matrix2x3d; -/** @brief %Dual complex number */ -typedef Math::DualComplex DualComplex; +/** @brief Double matrix with 3 columns and 2 rows */ +typedef Math::RectangularMatrix<3, 2, Double> Matrix3x2d; -/** @brief %Quaternion */ -typedef Math::Quaternion Quaternion; +/** @brief Double matrix with 2 columns and 4 rows */ +typedef Math::RectangularMatrix<2, 4, Double> Matrix2x4d; -/** @brief %Dual quaternion */ -typedef Math::DualQuaternion DualQuaternion; +/** @brief Double matrix with 4 columns and 2 rows */ +typedef Math::RectangularMatrix<4, 2, Double> Matrix4x2d; -/** @brief Floating-point constants */ -/* Using float instead of GLfloat to not break KDevelop autocompletion */ -typedef Math::Constants Constants; +/** @brief Double matrix with 3 columns and 4 rows */ +typedef Math::RectangularMatrix<3, 4, Double> Matrix3x4d; -/** @brief Angle in single-precision degrees */ -typedef Math::Deg Deg; +/** @brief Double matrix with 4 columns and 3 rows */ +typedef Math::RectangularMatrix<4, 3, Double> Matrix4x3d; -/** @brief Angle in single-precision radians */ -typedef Math::Rad Rad; +/** @brief Double complex number */ +typedef Math::Complex Complexd; -/** @brief Floating-point rectangle */ -typedef Math::Geometry::Rectangle Rectangle; +/** @brief Double dual complex number */ +typedef Math::DualComplex DualComplexd; -/** @brief Integer rectangle */ -typedef Math::Geometry::Rectangle Rectanglei; +/** @brief Double quaternion */ +typedef Math::Quaternion Quaterniond; + +/** @brief Double dual quaternion */ +typedef Math::DualQuaternion DualQuaterniond; + +/** @brief Double constants */ +typedef Math::Constants Constantsd; + +/** @brief Angle in double degrees */ +typedef Math::Deg Degd; + +/** @brief Angle in double radians */ +typedef Math::Rad Radd; + +/** @brief Double rectangle */ +typedef Math::Geometry::Rectangle Rectangled; + +/*@}*/ +#endif /* Using angle literals from Math namespace */ using Math::operator "" _deg; diff --git a/src/Types.h b/src/Types.h new file mode 100644 index 000000000..ee76b421f --- /dev/null +++ b/src/Types.h @@ -0,0 +1,45 @@ +#ifndef Magnum_Types_h +#define Magnum_Types_h +/* + Copyright © 2010, 2011, 2012 Vladimír Vondruš + + 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 + +#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