From c26075427b293dff3b8c4cc3cd863f3924d97e92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 12 Jul 2018 02:38:43 +0200 Subject: [PATCH] Doxygen. Doxygen IS BROKEN BEYOND REPAIR. I introduced *strong* enum with values, in a subnamespace, that have the same name as completely unrelated typedefs. Guess what?! It breaks ALL LINKS TO THOSE TYPEDEFS! **EVERYWHERE!!!** --- src/Magnum/GL/AbstractShaderProgram.h | 47 +++++++++++++++++---------- src/Magnum/GL/Attribute.h | 21 +++++++----- src/Magnum/Math/Range.h | 3 +- src/Magnum/Shaders/AbstractVector.h | 8 +++-- src/Magnum/Shaders/Flat.h | 10 +++--- src/Magnum/Shaders/Generic.h | 7 ++-- src/Magnum/Shaders/MeshVisualizer.h | 3 +- src/Magnum/Shaders/Phong.h | 13 +++++--- src/Magnum/Shaders/VertexColor.h | 5 +-- 9 files changed, 71 insertions(+), 46 deletions(-) diff --git a/src/Magnum/GL/AbstractShaderProgram.h b/src/Magnum/GL/AbstractShaderProgram.h index 3ca69d00b..7a5af4e9d 100644 --- a/src/Magnum/GL/AbstractShaderProgram.h +++ b/src/Magnum/GL/AbstractShaderProgram.h @@ -363,30 +363,41 @@ used (and their super- or subclasses with the same size and underlying type). See also @ref Attribute::DataType enum for additional type options. @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} is required when using - integer attributes (i.e. @ref UnsignedInt, @ref Int, @ref Vector2ui, - @ref Vector2i, @ref Vector3ui, @ref Vector3i, @ref Vector4ui and - @ref Vector4i) or unsigned integer uniforms (i.e. @ref UnsignedInt, - @ref Vector2ui, @ref Vector3ui and @ref Vector4ui). + integer attributes (i.e. @ref Magnum::UnsignedInt "UnsignedInt", + @ref Magnum::Int "Int", @ref Magnum::Vector2ui "Vector2ui", + @ref Magnum::Vector2i "Vector2i", @ref Magnum::Vector3ui "Vector3ui", + @ref Magnum::Vector3i "Vector3i", @ref Magnum::Vector4ui "Vector4ui" and + @ref Magnum::Vector4i "Vector4i") or unsigned integer uniforms (i.e. + @ref Magnum::UnsignedInt "UnsignedInt", @ref Magnum::Vector2ui "Vector2ui", + @ref Magnum::Vector3ui "Vector3ui" and @ref Magnum::Vector4ui "Vector4ui"). @requires_gl40 Extension @gl_extension{ARB,gpu_shader_fp64} is required when - using double uniforms (i.e. @ref Magnum::Double "Double", @ref Vector2d, - @ref Vector3d, @ref Vector4d, @ref Matrix2x2d, @ref Matrix3x3d, - @ref Matrix4x4d, @ref Matrix2x3d, @ref Matrix3x2d, @ref Matrix2x4d, - @ref Matrix4x2d, @ref Matrix3x4d and @ref Matrix4x3d). + using double uniforms (i.e. @ref Magnum::Double "Double", + @ref Magnum::Vector2d "Vector2d", @ref Magnum::Vector3d "Vector3d", + @ref Magnum::Vector4d "Vector4d", @ref Magnum::Matrix2x2d "Matrix2x2d", + @ref Magnum::Matrix3x3d "Matrix3x3d", @ref Magnum::Matrix4x4d "Matrix4x4d", + @ref Magnum::Matrix2x3d "Matrix2x3d", @ref Magnum::Matrix3x2d "Matrix3x2d", + @ref Magnum::Matrix2x4d "Matrix2x4d", @ref Magnum::Matrix4x2d "Matrix4x2d", + @ref Magnum::Matrix3x4d "Matrix3x4d" and @ref Magnum::Matrix4x3d "Matrix4x3d"). @requires_gl41 Extension @gl_extension{ARB,vertex_attrib_64bit} is required when - using double attributes (i.e. @ref Magnum::Double "Double", @ref Vector2d, - @ref Vector3d, @ref Vector4d, @ref Matrix2x2d, @ref Matrix3x3d, - @ref Matrix4x4d, @ref Matrix2x3d, @ref Matrix3x2d, @ref Matrix2x4d, - @ref Matrix4x2d, @ref Matrix3x4d and @ref Matrix4x3d). + using double attributes (i.e. @ref Magnum::Double "Double", + @ref Magnum::Vector2d "Vector2d", @ref Magnum::Vector3d "Vector3d", + @ref Magnum::Vector4d "Vector4d", @ref Magnum::Matrix2x2d "Matrix2x2d", + @ref Magnum::Matrix3x3d "Matrix3x3d", @ref Magnum::Matrix4x4d "Matrix4x4d", + @ref Magnum::Matrix2x3d "Matrix2x3d", @ref Magnum::Matrix3x2d "Matrix3x2d", + @ref Magnum::Matrix2x4d "Matrix2x4d", @ref Magnum::Matrix4x2d "Matrix4x2d", + @ref Magnum::Matrix3x4d "Matrix3x4d" and @ref Magnum::Matrix4x3d "Matrix4x3d"). @requires_gles30 Integer attributes, unsigned integer uniforms and non-square - matrix attributes and uniforms (i.e. @ref Matrix2x3, @ref Matrix3x2, - @ref Matrix2x4, @ref Matrix4x2, @ref Matrix3x4 and @ref Matrix4x3) are not - available in OpenGL ES 2.0. + matrix attributes and uniforms (i.e. @ref Magnum::Matrix2x3 "Matrix2x3", + @ref Magnum::Matrix3x2 "Matrix3x2", @ref Magnum::Matrix2x4 "Matrix2x4", + @ref Magnum::Matrix4x2 "Matrix4x2", @ref Magnum::Matrix3x4 "Matrix3x4" and + @ref Magnum::Matrix4x3 "Matrix4x3") are not available in OpenGL ES 2.0. @requires_gl Double attributes and uniforms are not available in OpenGL ES or WebGL. @requires_webgl20 Integer attributes, unsigned integer uniforms and non-square - matrix attributes and uniforms (i.e. @ref Matrix2x3, @ref Matrix3x2, - @ref Matrix2x4, @ref Matrix4x2, @ref Matrix3x4 and @ref Matrix4x3) are not - available in WebGL 1.0. + matrix attributes and uniforms (i.e. @ref Magnum::Matrix2x3 "Matrix2x3", + @ref Magnum::Matrix3x2 "Matrix3x2", @ref Magnum::Matrix2x4 "Matrix2x4", + @ref Magnum::Matrix4x2 "Matrix4x2", @ref Magnum::Matrix3x4 "Matrix3x4" and + @ref Magnum::Matrix4x3 "Matrix4x3") are not available in WebGL 1.0. @section GL-AbstractShaderProgram-performance-optimization Performance optimizations diff --git a/src/Magnum/GL/Attribute.h b/src/Magnum/GL/Attribute.h index d0fe8f9f0..07c993c21 100644 --- a/src/Magnum/GL/Attribute.h +++ b/src/Magnum/GL/Attribute.h @@ -48,12 +48,13 @@ is vertex attribute location, number between @cpp 0 @ce and should always have vertex attribute with location @cpp 0 @ce. Template parameter @p T is the type which is used for shader attribute, e.g. -@ref Vector4i for @glsl ivec4 @ce. DataType is type of passed data when adding -vertex buffers to mesh. By default it is the same as type used in shader (e.g. -@ref DataType::Int for @ref Vector4i). It's also possible to pass integer data -to floating-point shader inputs. In this case you may want to normalize the -values (e.g. color components from @cpp 0 @ce -- @cpp 255 @ce to @cpp 0.0f @ce --- @cpp 1.0f @ce) --- see @ref DataOption::Normalized. +@ref Magnum::Vector4i "Vector4i" for @glsl ivec4 @ce. DataType is type of +passed data when adding vertex buffers to mesh. By default it is the same as +type used in shader (e.g. @ref DataType::Int for @ref Magnum::Vector4i "Vector4i"). +It's also possible to pass integer data to floating-point shader inputs. In +this case you may want to normalize the values (e.g. color components from +@cpp 0 @ce -- @cpp 255 @ce to @cpp 0.0f @ce -- @cpp 1.0f @ce) --- see +@ref DataOption::Normalized. Only some types are allowed as attribute types, see @ref GL-AbstractShaderProgram-types for more information. @@ -265,7 +266,8 @@ template class Attribute { * @brief Constructor * @param components Component count * @param dataType Type of passed data. Default is the same as - * type used in shader (e.g. @ref DataType::Int for @ref Vector4i). + * type used in shader (e.g. @ref DataType::Int for + * @ref Magnum::Vector4i "Vector4i"). * @param dataOptions Data options. Default is no options. */ constexpr Attribute(Components components, DataType dataType = Implementation::Attribute::DefaultDataType, DataOptions dataOptions = DataOptions()): _components(components), _dataType(dataType), _dataOptions(dataOptions) {} @@ -273,11 +275,12 @@ template class Attribute { /** * @brief Constructor * @param dataType Type of passed data. Default is the same as - * type used in shader (e.g. @ref DataType::Int for @ref Vector4i). + * type used in shader (e.g. @ref DataType::Int for + * @ref Magnum::Vector4i "Vector4i"). * @param dataOptions Data options. Default is no options. * * Component count is set to the same value as in type used in shader - * (e.g. @ref Components::Three for @ref Vector3). + * (e.g. @ref Components::Three for @ref Magnum::Vector3 "Vector3"). */ constexpr Attribute(DataType dataType = Implementation::Attribute::DefaultDataType, DataOptions dataOptions = DataOptions()): _components(Implementation::Attribute::DefaultComponents), _dataType(dataType), _dataOptions(dataOptions) {} diff --git a/src/Magnum/Math/Range.h b/src/Magnum/Math/Range.h index 66a82bf1b..c8a3e7758 100644 --- a/src/Magnum/Math/Range.h +++ b/src/Magnum/Math/Range.h @@ -58,7 +58,8 @@ template class Range { /** * @brief Underlying vector type * - * `T` in 1D, @ref Vector2 in 2D, @ref Vector3 in 3D. + * `T` in 1D, @ref Math::Vector2 "Vector2" in 2D, + * @ref Math::Vector3 "Vector3" in 3D. */ typedef typename Implementation::RangeTraits::Type VectorType; diff --git a/src/Magnum/Shaders/AbstractVector.h b/src/Magnum/Shaders/AbstractVector.h index 69e664fce..007a9671c 100644 --- a/src/Magnum/Shaders/AbstractVector.h +++ b/src/Magnum/Shaders/AbstractVector.h @@ -45,15 +45,17 @@ template class AbstractVector: public GL::AbstractShader /** * @brief Vertex position * - * @ref shaders-generic "Generic attribute", @ref Vector2 in 2D, - * @ref Vector3 in 3D. + * @ref shaders-generic "Generic attribute", + * @ref Magnum::Vector2 "Vector2" in 2D, @ref Magnum::Vector3 "Vector3" + * in 3D. */ typedef typename Generic::Position Position; /** * @brief 2D texture coordinates * - * @ref shaders-generic "Generic attribute", @ref Vector2. + * @ref shaders-generic "Generic attribute", + * @ref Magnum::Vector2 "Vector2". */ typedef typename Generic::TextureCoordinates TextureCoordinates; diff --git a/src/Magnum/Shaders/Flat.h b/src/Magnum/Shaders/Flat.h index 9e9d83ac2..8be0055fa 100644 --- a/src/Magnum/Shaders/Flat.h +++ b/src/Magnum/Shaders/Flat.h @@ -90,16 +90,18 @@ template class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab /** * @brief Vertex position * - * @ref shaders-generic "Generic attribute", @ref Vector2 in 2D, - * @ref Vector3 in 3D. + * @ref shaders-generic "Generic attribute", + * @ref Magnum::Vector2 "Vector2" in 2D, @ref Magnum::Vector3 "Vector3" + * in 3D. */ typedef typename Generic::Position Position; /** * @brief 2D texture coordinates * - * @ref shaders-generic "Generic attribute", @ref Vector2. Used only if - * @ref Flag::Textured is set. + * @ref shaders-generic "Generic attribute", + * @ref Magnum::Vector2 "Vector2". Used only if @ref Flag::Textured is + * set. */ typedef typename Generic::TextureCoordinates TextureCoordinates; diff --git a/src/Magnum/Shaders/Generic.h b/src/Magnum/Shaders/Generic.h index 787adf3ee..5d5c4d334 100644 --- a/src/Magnum/Shaders/Generic.h +++ b/src/Magnum/Shaders/Generic.h @@ -49,21 +49,22 @@ template struct Generic { /** * @brief Vertex position * - * @ref Vector2 in 2D and @ref Vector3 in 3D. + * @ref Magnum::Vector2 "Vector2" in 2D and @ref Magnum::Vector3 "Vector3" + * in 3D. */ typedef GL::Attribute<0, T> Position; /** * @brief 2D texture coordinates * - * @ref Vector2. + * @ref Magnum::Vector2 "Vector2". */ typedef GL::Attribute<1, Vector2> TextureCoordinates; /** * @brief Vertex normal * - * @ref Vector3, defined only in 3D. + * @ref Magnum::Vector3 "Vector3", defined only in 3D. */ typedef GL::Attribute<2, Vector3> Normal; diff --git a/src/Magnum/Shaders/MeshVisualizer.h b/src/Magnum/Shaders/MeshVisualizer.h index eb965c28d..89df8f440 100644 --- a/src/Magnum/Shaders/MeshVisualizer.h +++ b/src/Magnum/Shaders/MeshVisualizer.h @@ -108,7 +108,8 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizer: public GL::AbstractShaderProgram { /** * @brief Vertex position * - * @ref shaders-generic "Generic attribute", @ref Vector3. + * @ref shaders-generic "Generic attribute", + * @ref Magnum::Vector3 "Vector3". */ typedef GL::Attribute<0, Vector3> Position; diff --git a/src/Magnum/Shaders/Phong.h b/src/Magnum/Shaders/Phong.h index 3e3a6a7fb..ef3e63225 100644 --- a/src/Magnum/Shaders/Phong.h +++ b/src/Magnum/Shaders/Phong.h @@ -93,23 +93,26 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram { /** * @brief Vertex position * - * @ref shaders-generic "Generic attribute", @ref Vector3. + * @ref shaders-generic "Generic attribute", + * @ref Magnum::Vector3 "Vector3". */ typedef Generic3D::Position Position; /** * @brief Normal direction * - * @ref shaders-generic "Generic attribute", @ref Vector3. + * @ref shaders-generic "Generic attribute", + * @ref Magnum::Vector3 "Vector3". */ typedef Generic3D::Normal Normal; /** * @brief 2D texture coordinates * - * @ref shaders-generic "Generic attribute", @ref Vector2, used only if - * at least one of @ref Flag::AmbientTexture, @ref Flag::DiffuseTexture - * and @ref Flag::SpecularTexture is set. + * @ref shaders-generic "Generic attribute", + * @ref Magnum::Vector2 "Vector2", used only if at least one of + * @ref Flag::AmbientTexture, @ref Flag::DiffuseTexture and + * @ref Flag::SpecularTexture is set. */ typedef Generic3D::TextureCoordinates TextureCoordinates; diff --git a/src/Magnum/Shaders/VertexColor.h b/src/Magnum/Shaders/VertexColor.h index c30253689..395fd0104 100644 --- a/src/Magnum/Shaders/VertexColor.h +++ b/src/Magnum/Shaders/VertexColor.h @@ -66,8 +66,9 @@ template class MAGNUM_SHADERS_EXPORT VertexColor: public /** * @brief Vertex position * - * @ref shaders-generic "Generic attribute", @ref Vector2 in 2D, - * @ref Vector3 in 3D. + * @ref shaders-generic "Generic attribute", + * @ref Magnum::Vector2 "Vector2" in 2D @ref Magnum::Vector3 "Vector3" + * in 3D. */ typedef typename Generic::Position Position;