From 963faea23da66b1bde5326840d7993a3813076f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 3 Jan 2023 12:06:13 +0100 Subject: [PATCH] Shaders: doc++ --- src/Magnum/Shaders/DistanceFieldVectorGL.h | 19 +-- src/Magnum/Shaders/FlatGL.h | 70 ++++++----- src/Magnum/Shaders/MeshVisualizerGL.h | 134 ++++++++++++--------- src/Magnum/Shaders/PhongGL.h | 75 +++++++----- src/Magnum/Shaders/VectorGL.h | 19 +-- src/Magnum/Shaders/VertexColorGL.h | 25 ++-- 6 files changed, 191 insertions(+), 151 deletions(-) diff --git a/src/Magnum/Shaders/DistanceFieldVectorGL.h b/src/Magnum/Shaders/DistanceFieldVectorGL.h index d4d84af9f..0ccda624a 100644 --- a/src/Magnum/Shaders/DistanceFieldVectorGL.h +++ b/src/Magnum/Shaders/DistanceFieldVectorGL.h @@ -134,8 +134,8 @@ template class MAGNUM_SHADERS_EXPORT DistanceFieldVector * @brief Vertex position * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2" in 2D, @ref Magnum::Vector3 "Vector3" - * in 3D. + * @relativeref{Magnum,Vector2} in 2D, @relativeref{Magnum,Vector3} in + * 3D. */ typedef typename GenericGL::Position Position; @@ -143,7 +143,7 @@ template class MAGNUM_SHADERS_EXPORT DistanceFieldVector * @brief 2D texture coordinates * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2". + * @relativeref{Magnum,Vector2}. */ typedef typename GenericGL::TextureCoordinates TextureCoordinates; @@ -191,11 +191,12 @@ template class MAGNUM_SHADERS_EXPORT DistanceFieldVector * and adds the value from @ref setDrawOffset() with the * @glsl gl_DrawID @ce builtin, which makes draws submitted via * @ref GL::AbstractShaderProgram::draw(const Containers::Iterable&) - * pick up per-draw parameters directly, without having to rebind - * the uniform buffers or specify @ref setDrawOffset() before each - * draw. In a non-multidraw scenario, @glsl gl_DrawID @ce is - * @cpp 0 @ce, which means a shader with this flag enabled can be - * used for regular draws as well. + * and related APIs pick up per-draw parameters directly, without + * having to rebind the uniform buffers or specify + * @ref setDrawOffset() before each draw. In a non-multidraw + * scenario, @glsl gl_DrawID @ce is @cpp 0 @ce, which means a + * shader with this flag enabled can be used for regular draws as + * well. * @requires_gl46 Extension @gl_extension{ARB,uniform_buffer_object} * and @gl_extension{ARB,shader_draw_parameters} * @requires_es_extension OpenGL ES 3.0 and extension @@ -217,7 +218,7 @@ template class MAGNUM_SHADERS_EXPORT DistanceFieldVector * @brief Flags * @m_since{2020,06} * - * @see @ref flags() + * @see @ref flags(), @ref Configuration::setFlags() */ typedef Containers::EnumSet Flags; #else diff --git a/src/Magnum/Shaders/FlatGL.h b/src/Magnum/Shaders/FlatGL.h index 8d1e364da..5fd70a0da 100644 --- a/src/Magnum/Shaders/FlatGL.h +++ b/src/Magnum/Shaders/FlatGL.h @@ -263,8 +263,8 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief Vertex position * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2" in 2D, @ref Magnum::Vector3 "Vector3" - * in 3D. + * @relativeref{Magnum,Vector2} in 2D, @relativeref{Magnum,Vector3} in + * 3D. */ typedef typename GenericGL::Position Position; @@ -272,7 +272,7 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief 2D texture coordinates * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2". Used only if @ref Flag::Textured is + * @relativeref{Magnum,Vector2}. Used only if @ref Flag::Textured is * set. */ typedef typename GenericGL::TextureCoordinates TextureCoordinates; @@ -302,8 +302,9 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief Joint ids * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4ui. - * Used only if @ref perVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4ui}. Used only if + * @ref perVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -316,8 +317,9 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief Weights * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4. - * Used only if @ref perVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4}. Used only if + * @ref perVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -330,8 +332,9 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief Secondary joint ids * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4ui. - * Used only if @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4ui}. Used only if + * @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -344,8 +347,9 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief Secondary weights * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4. - * Used only if @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4}. Used only if + * @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -360,8 +364,9 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief (Instanced) object ID * @m_since{2020,06} * - * @ref shaders-generic "Generic attribute", @ref Magnum::UnsignedInt. - * Used only if @ref Flag::InstancedObjectId is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,UnsignedInt}. Used only if + * @ref Flag::InstancedObjectId is set. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Object ID output requires integer support in * shaders, which is not available in OpenGL ES 2.0. @@ -375,9 +380,9 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief (Instanced) transformation matrix * @m_since{2020,06} * - * @ref shaders-generic "Generic attribute", @ref Magnum::Matrix3 in - * 2D, @ref Magnum::Matrix4 in 3D. Used only if - * @ref Flag::InstancedTransformation is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Matrix3} in 2D, @relativeref{Magnum,Matrix4} in + * 3D. Used only if @ref Flag::InstancedTransformation is set. * @requires_gl33 Extension @gl_extension{ARB,instanced_arrays} * @requires_gles30 Extension @gl_extension{ANGLE,instanced_arrays}, * @gl_extension{EXT,instanced_arrays} or @@ -391,8 +396,9 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief (Instanced) texture offset * @m_since{2020,06} * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector2. Use - * either this or the @ref TextureOffsetLayer attribute. Used only if + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector2}. Use either this or the + * @ref TextureOffsetLayer attribute. Used only if * @ref Flag::InstancedTextureOffset is set. * @requires_gl33 Extension @gl_extension{ARB,instanced_arrays} * @requires_gles30 Extension @gl_extension{ANGLE,instanced_arrays}, @@ -408,11 +414,11 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @brief (Instanced) texture offset and layer * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector3, with - * the last component interpreted as an integer. Use either this or the - * @ref TextureOffset attribute. First two components used only if - * @ref Flag::InstancedTextureOffset is set, third component only if - * @ref Flag::TextureArrays is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector3}, with the last component interpreted as + * an integer. Use either this or the @ref TextureOffset attribute. + * First two components used only if @ref Flag::InstancedTextureOffset + * is set, third component only if @ref Flag::TextureArrays is set. * @requires_gl33 Extension @gl_extension{EXT,texture_array} and * @gl_extension{ARB,instanced_arrays} * @requires_gles30 Texture arrays are not available in OpenGL ES 2.0. @@ -423,8 +429,9 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: enum: UnsignedInt { /** - * Color shader output. Present always, expects three- or - * four-component floating-point or normalized buffer attachment. + * Color shader output. @ref shaders-generic "Generic output", + * present always. Expects three- or four-component floating-point + * or normalized buffer attachment. * @m_since{2019,10} */ ColorOutput = GenericGL::ColorOutput, @@ -603,11 +610,12 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * and adds the value from @ref setDrawOffset() with the * @glsl gl_DrawID @ce builtin, which makes draws submitted via * @ref GL::AbstractShaderProgram::draw(const Containers::Iterable&) - * pick up per-draw parameters directly, without having to rebind - * the uniform buffers or specify @ref setDrawOffset() before each - * draw. In a non-multidraw scenario, @glsl gl_DrawID @ce is - * @cpp 0 @ce, which means a shader with this flag enabled can be - * used for regular draws as well. + * and related APIs pick up per-draw parameters directly, without + * having to rebind the uniform buffers or specify + * @ref setDrawOffset() before each draw. In a non-multidraw + * scenario, @glsl gl_DrawID @ce is @cpp 0 @ce, which means a + * shader with this flag enabled can be used for regular draws as + * well. * @requires_gl46 Extension @gl_extension{ARB,uniform_buffer_object} * and @gl_extension{ARB,shader_draw_parameters} * @requires_es_extension OpenGL ES 3.0 and extension @@ -669,7 +677,7 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: /** * @brief Flags * - * @see @ref flags() + * @see @ref flags(), @ref Configuration::setFlags() */ typedef Containers::EnumSet Flags; #else diff --git a/src/Magnum/Shaders/MeshVisualizerGL.h b/src/Magnum/Shaders/MeshVisualizerGL.h index e6580ef42..cafc87ed3 100644 --- a/src/Magnum/Shaders/MeshVisualizerGL.h +++ b/src/Magnum/Shaders/MeshVisualizerGL.h @@ -216,7 +216,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * @brief Vertex position * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2". + * @relativeref{Magnum,Vector2}. */ typedef typename GenericGL2D::Position Position; @@ -230,7 +230,8 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * @brief Joint ids * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4ui. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4ui}. * Used only if @ref perVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which @@ -244,8 +245,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * @brief Weights * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4. - * Used only if @ref perVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4}. Used only if + * @ref perVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -258,8 +260,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * @brief Secondary joint ids * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4ui. - * Used only if @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4ui}. Used only if + * @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -272,8 +275,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * @brief Secondary weights * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4. - * Used only if @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4}. Used only if + * @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -283,11 +287,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua typedef GenericGL3D::SecondaryWeights SecondaryWeights; #endif - /** - * @brief Vertex index - * - * See @ref MeshVisualizerGL3D::VertexIndex for more information. - */ + /** @copydoc MeshVisualizerGL3D::VertexIndex */ typedef GL::Attribute<4, Float> VertexIndex; #ifndef MAGNUM_TARGET_GLES2 @@ -295,8 +295,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * @brief (Instanced) object ID * @m_since{2020,06} * - * @ref shaders-generic "Generic attribute", @ref Magnum::UnsignedInt. - * Used only if @ref Flag::InstancedObjectId is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,UnsignedInt}. Used only if + * @ref Flag::InstancedObjectId is set. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Object ID output requires integer support in * shaders, which is not available in OpenGL ES 2.0. @@ -310,8 +311,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * @brief (Instanced) transformation matrix * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Matrix3. - * Used only if @ref Flag::InstancedTransformation is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Matrix3}. Used only if + * @ref Flag::InstancedTransformation is set. * @requires_gl33 Extension @gl_extension{ARB,instanced_arrays} * @requires_gles30 Extension @gl_extension{ANGLE,instanced_arrays}, * @gl_extension{EXT,instanced_arrays} or @@ -499,11 +501,12 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * and combines the value from @ref setDrawOffset() with the * @glsl gl_DrawID @ce builtin, which makes draws submitted via * @ref GL::AbstractShaderProgram::draw(const Containers::Iterable&) - * pick up per-draw parameters directly, without having to rebind - * the uniform buffers or specify @ref setDrawOffset() before each - * draw. In a non-multidraw scenario, @glsl gl_DrawID @ce is - * @cpp 0 @ce, which means a shader with this flag enabled can be - * used for regular draws as well. + * and related APIs pick up per-draw parameters directly, without + * having to rebind the uniform buffers or specify + * @ref setDrawOffset() before each draw. In a non-multidraw + * scenario, @glsl gl_DrawID @ce is @cpp 0 @ce, which means a + * shader with this flag enabled can be used for regular draws as + * well. * @requires_gl46 Extension @gl_extension{ARB,uniform_buffer_object} * and @gl_extension{ARB,shader_draw_parameters} * @requires_es_extension OpenGL ES 3.0 and extension @@ -547,7 +550,11 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua #endif }; - /** @brief Flags */ + /** + * @brief Flags + * + * @see @ref flags(), @ref Configuration::setFlags() + */ typedef Containers::EnumSet Flags; /** @@ -1641,7 +1648,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief Vertex position * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector3 "Vector3". + * @relativeref{Magnum,Vector3}. */ typedef typename GenericGL3D::Position Position; @@ -1650,7 +1657,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @m_since{2020,06} * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector3 "Vector3". Use either this or the @ref Tangent4 + * @relativeref{Magnum,Vector3}. Use either this or the @ref Tangent4 * attribute. Used only if @ref Flag::TangentDirection is enabled. */ typedef typename GenericGL3D::Tangent Tangent; @@ -1660,7 +1667,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @m_since{2020,06} * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector4 "Vector4". Use either this or the @ref Tangent + * @relativeref{Magnum,Vector4}. Use either this or the @ref Tangent * attribute. Used only if @ref Flag::TangentDirection or * @ref Flag::BitangentFromTangentDirection is enabled. */ @@ -1671,7 +1678,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @m_since{2020,06} * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector3 "Vector3". Use either this or the @ref Tangent4 + * @relativeref{Magnum,Vector3}. Use either this or the @ref Tangent4 * attribute. Used only if @ref Flag::BitangentDirection is enabled. */ typedef typename GenericGL3D::Bitangent Bitangent; @@ -1681,7 +1688,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @m_since{2020,06} * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector3 "Vector3". Used only if + * @relativeref{Magnum,Vector3}. Used only if * @ref Flag::NormalDirection is enabled. */ typedef typename GenericGL3D::Normal Normal; @@ -1692,7 +1699,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @m_since_latest * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2". Used only if + * @relativeref{Magnum,Vector2}. Used only if * @ref Flag::ObjectIdTexture is enabled. * @requires_gl33 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Object ID input requires integer support in @@ -1708,8 +1715,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief Joint ids * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4ui. - * Used only if @ref perVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4ui}. Used only if + * @ref perVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -1722,8 +1730,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief Weights * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4. - * Used only if @ref perVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4}. Used only if + * @ref perVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -1736,8 +1745,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief Secondary joint ids * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4ui. - * Used only if @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4ui}. Used only if + * @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -1750,8 +1760,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief Secondary weights * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4. - * Used only if @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4}. Used only if + * @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -1764,7 +1775,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua /** * @brief Vertex index * - * @ref Magnum::Float "Float", used only in OpenGL < 3.1 and OpenGL ES + * @relativeref{Magnum,Float}, used only in OpenGL < 3.1 and OpenGL ES * 2.0 if @ref Flag::Wireframe is enabled. This attribute (modulo 3) * specifies index of given vertex in triangle, i.e. @cpp 0.0f @ce for * first, @cpp 1.0f @ce for second, @cpp 2.0f @ce for third. In OpenGL @@ -1784,8 +1795,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief (Instanced) object ID * @m_since{2020,06} * - * @ref shaders-generic "Generic attribute", @ref Magnum::UnsignedInt. - * Used only if @ref Flag::InstancedObjectId is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,UnsignedInt}. Used only if + * @ref Flag::InstancedObjectId is set. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Object ID output requires integer support in * shaders, which is not available in OpenGL ES 2.0. @@ -1799,8 +1811,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief (Instanced) transformation matrix * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Matrix4. - * Used only if @ref Flag::InstancedTransformation is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Matrix4}. Used only if + * @ref Flag::InstancedTransformation is set. * @requires_gl33 Extension @gl_extension{ARB,instanced_arrays} * @requires_gles30 Extension @gl_extension{ANGLE,instanced_arrays}, * @gl_extension{EXT,instanced_arrays} or @@ -1815,8 +1828,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief (Instanced) normal matrix * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Matrix3x3. - * Used only if @ref Flag::InstancedTransformation and at least one of + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Matrix3x3}. Used only if + * @ref Flag::InstancedTransformation and at least one of * @ref Flag::TangentDirection, @ref Flag::BitangentDirection or * @ref Flag::NormalDirection is set. * @requires_gl33 Extension @gl_extension{ARB,geometry_shader4} and @@ -1834,8 +1848,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief (Instanced) texture offset for an object ID texture * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector2. Used - * only if @ref Flag::InstancedTextureOffset is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector2}. Used only if + * @ref Flag::InstancedTextureOffset is set. * @requires_gl33 Extension @gl_extension{EXT,gpu_shader4} and * @gl_extension{ARB,instanced_arrays} * @requires_gles30 Object ID input requires integer support in @@ -1849,11 +1864,11 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @brief (Instanced) texture offset and layer for an object ID texture * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector3, with - * the last component interpreted as an integer. Use either this or the - * @ref TextureOffset attribute. First two components used only if - * @ref Flag::InstancedTextureOffset is set, third component only if - * @ref Flag::TextureArrays is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector3}, with the last component interpreted as + * an integer. Use either this or the @ref TextureOffset attribute. + * First two components used only if @ref Flag::InstancedTextureOffset + * is set, third component only if @ref Flag::TextureArrays is set. * @requires_gl33 Extension @gl_extension{EXT,gpu_shader4}, * @gl_extension{EXT,texture_array} and * @gl_extension{ARB,instanced_arrays} @@ -2161,11 +2176,12 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * and combines the value from @ref setDrawOffset() with the * @glsl gl_DrawID @ce builtin, which makes draws submitted via * @ref GL::AbstractShaderProgram::draw(const Containers::Iterable&) - * pick up per-draw parameters directly, without having to rebind - * the uniform buffers or specify @ref setDrawOffset() before each - * draw. In a non-multidraw scenario, @glsl gl_DrawID @ce is - * @cpp 0 @ce, which means a shader with this flag enabled can be - * used for regular draws as well. + * and related APIs pick up per-draw parameters directly, without + * having to rebind the uniform buffers or specify + * @ref setDrawOffset() before each draw. In a non-multidraw + * scenario, @glsl gl_DrawID @ce is @cpp 0 @ce, which means a + * shader with this flag enabled can be used for regular draws as + * well. * @requires_gl46 Extension @gl_extension{ARB,uniform_buffer_object} * and @gl_extension{ARB,shader_draw_parameters} * @requires_es_extension OpenGL ES 3.0 and extension @@ -2229,7 +2245,11 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua #endif }; - /** @brief Flags */ + /** + * @brief Flags + * + * @see @ref flags(), @ref Configuration::setFlags() + */ typedef Containers::EnumSet Flags; /** diff --git a/src/Magnum/Shaders/PhongGL.h b/src/Magnum/Shaders/PhongGL.h index b6cc2af60..97918090f 100644 --- a/src/Magnum/Shaders/PhongGL.h +++ b/src/Magnum/Shaders/PhongGL.h @@ -360,7 +360,7 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief Vertex position * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector3 "Vector3". + * @relativeref{Magnum,Vector3}. */ typedef GenericGL3D::Position Position; @@ -368,7 +368,7 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief Normal direction * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector3 "Vector3". Used only if @ref lightCount() isn't + * @relativeref{Magnum,Vector3}. Used only if @ref lightCount() isn't * @cpp 0 @ce. */ typedef GenericGL3D::Normal Normal; @@ -378,7 +378,7 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @m_since{2019,10} * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector3 "Vector3". Use either this or the @ref Tangent4 + * @relativeref{Magnum,Vector3}. Use either this or the @ref Tangent4 * attribute. If only a three-component attribute is used and * @ref Flag::Bitangent is not enabled, it's the same as if * @ref Tangent4 was specified with the fourth component always being @@ -393,7 +393,7 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @m_since_latest * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector4 "Vector4". Use either this or the @ref Tangent + * @relativeref{Magnum,Vector4}. Use either this or the @ref Tangent * attribute. If @ref Flag::Bitangent is set, the fourth component is * ignored and bitangents are taken from the @ref Bitangent attribute * instead. Used only if @ref Flag::NormalTexture is set and @@ -407,7 +407,7 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @m_since_latest * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector3 "Vector3". Use either this or the @ref Tangent4 + * @relativeref{Magnum,Vector3}. Use either this or the @ref Tangent4 * attribute. Used only if both @ref Flag::NormalTexture and * @ref Flag::Bitangent are set and @ref lightCount() isn't @cpp 0 @ce. * @see @ref Shaders-PhongGL-normal-mapping @@ -418,7 +418,7 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief 2D texture coordinates * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2", used only if at least one of + * @relativeref{Magnum,Vector2}, used only if at least one of * @ref Flag::AmbientTexture, @ref Flag::DiffuseTexture and * @ref Flag::SpecularTexture is set. */ @@ -449,8 +449,9 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief Joint ids * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4ui. - * Used only if @ref perVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4ui}. Used only if + * @ref perVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -463,8 +464,9 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief Weights * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4. - * Used only if @ref perVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4}. Used only if + * @ref perVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -477,8 +479,9 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief Secondary joint ids * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4ui. - * Used only if @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4ui}. Used only if + * @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -491,8 +494,9 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief Secondary weights * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector4. - * Used only if @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector4}. Used only if + * @ref secondaryPerVertexJointCount() isn't @cpp 0 @ce. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Skinning requires integer support in shaders, which * is not available in OpenGL ES 2.0. @@ -507,8 +511,9 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief (Instanced) object ID * @m_since{2020,06} * - * @ref shaders-generic "Generic attribute", @ref Magnum::UnsignedInt. - * Used only if @ref Flag::InstancedObjectId is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,UnsignedInt}. Used only if + * @ref Flag::InstancedObjectId is set. * @requires_gl30 Extension @gl_extension{EXT,gpu_shader4} * @requires_gles30 Object ID output requires integer support in * shaders, which is not available in OpenGL ES 2.0. @@ -522,8 +527,9 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief (Instanced) transformation matrix * @m_since{2020,06} * - * @ref shaders-generic "Generic attribute", @ref Magnum::Matrix4. - * Used only if @ref Flag::InstancedTransformation is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Matrix4}. Used only if + * @ref Flag::InstancedTransformation is set. * @requires_gl33 Extension @gl_extension{ARB,instanced_arrays} * @requires_gles30 Extension @gl_extension{ANGLE,instanced_arrays}, * @gl_extension{EXT,instanced_arrays} or @@ -537,8 +543,9 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief (Instanced) normal matrix * @m_since{2020,06} * - * @ref shaders-generic "Generic attribute", @ref Magnum::Matrix3x3. - * Used only if @ref Flag::InstancedTransformation is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Matrix3x3}. Used only if + * @ref Flag::InstancedTransformation is set. * @requires_gl33 Extension @gl_extension{ARB,instanced_arrays} * @requires_gles30 Extension @gl_extension{ANGLE,instanced_arrays}, * @gl_extension{EXT,instanced_arrays} or @@ -552,8 +559,9 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief (Instanced) texture offset * @m_since{2020,06} * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector2. Used - * only if @ref Flag::InstancedTextureOffset is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector2}. Used only if + * @ref Flag::InstancedTextureOffset is set. * @requires_gl33 Extension @gl_extension{ARB,instanced_arrays} * @requires_gles30 Extension @gl_extension{ANGLE,instanced_arrays}, * @gl_extension{EXT,instanced_arrays} or @@ -568,11 +576,11 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief (Instanced) texture offset and layer * @m_since_latest * - * @ref shaders-generic "Generic attribute", @ref Magnum::Vector3, with - * the last component interpreted as an integer. Use either this or the - * @ref TextureOffset attribute. First two components used only if - * @ref Flag::InstancedTextureOffset is set, third component only if - * @ref Flag::TextureArrays is set. + * @ref shaders-generic "Generic attribute", + * @relativeref{Magnum,Vector3}, with the last component interpreted as + * an integer. Use either this or the @ref TextureOffset attribute. + * First two components used only if @ref Flag::InstancedTextureOffset + * is set, third component only if @ref Flag::TextureArrays is set. * @requires_gl33 Extension @gl_extension{EXT,texture_array} and * @gl_extension{ARB,instanced_arrays} * @requires_gles30 Texture arrays are not available in OpenGL ES 2.0. @@ -797,11 +805,12 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * and adds the value from @ref setDrawOffset() with the * @glsl gl_DrawID @ce builtin, which makes draws submitted via * @ref GL::AbstractShaderProgram::draw(const Containers::Iterable&) - * pick up per-draw parameters directly, without having to rebind - * the uniform buffers or specify @ref setDrawOffset() before each - * draw. In a non-multidraw scenario, @glsl gl_DrawID @ce is - * @cpp 0 @ce, which means a shader with this flag enabled can be - * used for regular draws as well. + * and related APIs pick up per-draw parameters directly, without + * having to rebind the uniform buffers or specify + * @ref setDrawOffset() before each draw. In a non-multidraw + * scenario, @glsl gl_DrawID @ce is @cpp 0 @ce, which means a + * shader with this flag enabled can be used for regular draws as + * well. * @requires_gl46 Extension @gl_extension{ARB,uniform_buffer_object} * and @gl_extension{ARB,shader_draw_parameters} * @requires_es_extension OpenGL ES 3.0 and extension @@ -895,7 +904,7 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { /** * @brief Flags * - * @see @ref flags() + * @see @ref flags(), @ref Configuration::setFlags() */ typedef Containers::EnumSet Flags; diff --git a/src/Magnum/Shaders/VectorGL.h b/src/Magnum/Shaders/VectorGL.h index a88600c90..341957db7 100644 --- a/src/Magnum/Shaders/VectorGL.h +++ b/src/Magnum/Shaders/VectorGL.h @@ -128,8 +128,8 @@ template class MAGNUM_SHADERS_EXPORT VectorGL: public GL * @brief Vertex position * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2" in 2D, @ref Magnum::Vector3 "Vector3" - * in 3D. + * @relativeref{Magnum,Vector2} in 2D, @relativeref{Magnum,Vector3} in + * 3D. */ typedef typename GenericGL::Position Position; @@ -137,7 +137,7 @@ template class MAGNUM_SHADERS_EXPORT VectorGL: public GL * @brief 2D texture coordinates * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2". + * @relativeref{Magnum,Vector2}. */ typedef typename GenericGL::TextureCoordinates TextureCoordinates; @@ -185,11 +185,12 @@ template class MAGNUM_SHADERS_EXPORT VectorGL: public GL * and adds the value from @ref setDrawOffset() with the * @glsl gl_DrawID @ce builtin, which makes draws submitted via * @ref GL::AbstractShaderProgram::draw(const Containers::Iterable&) - * pick up per-draw parameters directly, without having to rebind - * the uniform buffers or specify @ref setDrawOffset() before each - * draw. In a non-multidraw scenario, @glsl gl_DrawID @ce is - * @cpp 0 @ce, which means a shader with this flag enabled can be - * used for regular draws as well. + * and related APIs pick up per-draw parameters directly, without + * having to rebind the uniform buffers or specify + * @ref setDrawOffset() before each draw. In a non-multidraw + * scenario, @glsl gl_DrawID @ce is @cpp 0 @ce, which means a + * shader with this flag enabled can be used for regular draws as + * well. * @requires_gl46 Extension @gl_extension{ARB,uniform_buffer_object} * and @gl_extension{ARB,shader_draw_parameters} * @requires_es_extension OpenGL ES 3.0 and extension @@ -211,7 +212,7 @@ template class MAGNUM_SHADERS_EXPORT VectorGL: public GL * @brief Flags * @m_since{2020,06} * - * @see @ref flags() + * @see @ref flags(), @ref Configuration::setFlags() */ typedef Containers::EnumSet Flags; #else diff --git a/src/Magnum/Shaders/VertexColorGL.h b/src/Magnum/Shaders/VertexColorGL.h index ec86062c3..c0a81e577 100644 --- a/src/Magnum/Shaders/VertexColorGL.h +++ b/src/Magnum/Shaders/VertexColorGL.h @@ -27,7 +27,7 @@ */ /** @file - * @brief Class @ref Magnum::Shaders::VertexColorGL + * @brief Class @ref Magnum::Shaders::VertexColorGL, typedef @ref Magnum::Shaders::VertexColorGL2D, @ref Magnum::Shaders::VertexColorGL3D * @m_since_latest */ @@ -63,9 +63,9 @@ the mesh in an identity transformation. Use @image html shaders-vertexcolor.png width=256px This shader is equivalent to @ref FlatGL with @ref FlatGL::Flag::VertexColor -enabled; the 3D version of this shader is equivalent to @ref PhongGL with -@ref PhongGL::Flag::VertexColor enabled. In both cases this implementation is -much simpler and thus likely also faster. +enabled or to @ref PhongGL with zero lights and @ref PhongGL::Flag::VertexColor +enabled. However, the implementation is much simpler and thus likely also +faster. Alpha / transparency is supported by the shader implicitly, but to have it working on the framebuffer, you need to enable @@ -121,8 +121,8 @@ template class MAGNUM_SHADERS_EXPORT VertexColorGL: publ * @brief Vertex position * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector2 "Vector2" in 2D @ref Magnum::Vector3 "Vector3" - * in 3D. + * @relativeref{Magnum,Vector2} in 2D, @relativeref{Magnum,Vector3} in + * 3D. */ typedef typename GenericGL::Position Position; @@ -178,11 +178,12 @@ template class MAGNUM_SHADERS_EXPORT VertexColorGL: publ * and adds the value from @ref setDrawOffset() with the * @glsl gl_DrawID @ce builtin, which makes draws submitted via * @ref GL::AbstractShaderProgram::draw(const Containers::Iterable&) - * pick up per-draw parameters directly, without having to rebind - * the uniform buffers or specify @ref setDrawOffset() before each - * draw. In a non-multidraw scenario, @glsl gl_DrawID @ce is - * @cpp 0 @ce, which means a shader with this flag enabled can be - * used for regular draws as well. + * and related APIs pick up per-draw parameters directly, without + * having to rebind the uniform buffers or specify + * @ref setDrawOffset() before each draw. In a non-multidraw + * scenario, @glsl gl_DrawID @ce is @cpp 0 @ce, which means a + * shader with this flag enabled can be used for regular draws as + * well. * @requires_gl46 Extension @gl_extension{ARB,uniform_buffer_object} * and @gl_extension{ARB,shader_draw_parameters} * @requires_es_extension OpenGL ES 3.0 and extension @@ -204,7 +205,7 @@ template class MAGNUM_SHADERS_EXPORT VertexColorGL: publ * @brief Flags * @m_since{2020,06} * - * @see @ref flags() + * @see @ref flags(), @ref Configuration::setFlags() */ typedef Containers::EnumSet Flags; #else