diff --git a/src/Magnum/Shaders/DistanceFieldVector.h b/src/Magnum/Shaders/DistanceFieldVector.h index e6c72adc9..432f2f3db 100644 --- a/src/Magnum/Shaders/DistanceFieldVector.h +++ b/src/Magnum/Shaders/DistanceFieldVector.h @@ -88,11 +88,11 @@ struct DistanceFieldVectorDrawUniform { * References a particular material from a * @ref DistanceFieldVectorMaterialUniform array. Useful when an UBO with * more than one material is supplied or in a multi-draw scenario. Should - * be less than the material count passed to the - * @ref DistanceFieldVectorGL::DistanceFieldVectorGL(Flags, UnsignedInt, UnsignedInt) - * constructor, if material count is @cpp 1 @ce, this field is assumed to - * be @cpp 0 @ce and isn't even read by the shader. Default value is - * @cpp 0 @ce, meaning the first material gets used. + * be less than the material count passed to + * @ref DistanceFieldVectorGL::Configuration::setMaterialCount(), if + * material count is @cpp 1 @ce, this field is assumed to be @cpp 0 @ce and + * isn't even read by the shader. Default value is @cpp 0 @ce, meaning the + * first material gets used. */ /* This field is an UnsignedInt in the shader and materialId is extracted diff --git a/src/Magnum/Shaders/DistanceFieldVectorGL.h b/src/Magnum/Shaders/DistanceFieldVectorGL.h index 79306bec5..711501f55 100644 --- a/src/Magnum/Shaders/DistanceFieldVectorGL.h +++ b/src/Magnum/Shaders/DistanceFieldVectorGL.h @@ -98,11 +98,11 @@ buffer setup equivalent to the above would look like this: @snippet MagnumShaders-gl.cpp DistanceFieldVectorGL-ubo For a multidraw workflow enable @ref Flag::MultiDraw, supply desired material -and draw count in the @ref DistanceFieldVectorGL(Flags, UnsignedInt, UnsignedInt) -constructor and specify material references and texture offsets for every draw. -Texture arrays aren't currently supported for this shader. Besides that, the -usage is similar for all shaders, see @ref shaders-usage-multidraw for an -example. +and draw count via @ref Configuration::setMaterialCount() and +@relativeref{Configuration,setDrawCount()} and specify material references and +texture offsets for every draw. Texture arrays aren't currently supported for +this shader. Besides that, the usage is similar for all shaders, see +@ref shaders-usage-multidraw for an example. @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} for uniform buffers. @@ -156,7 +156,7 @@ template class MAGNUM_SHADERS_EXPORT DistanceFieldVector * @brief Flag * @m_since{2020,06} * - * @see @ref Flags, @ref flags() + * @see @ref Flags, @ref flags(), @ref Configuration::setFlags() */ enum class Flag: UnsignedByte { /** @@ -332,6 +332,8 @@ template class MAGNUM_SHADERS_EXPORT DistanceFieldVector /** * @brief Flags * @m_since{2020,06} + * + * @see @ref Configuration::setFlags() */ Flags flags() const { return _flags; } @@ -341,9 +343,10 @@ template class MAGNUM_SHADERS_EXPORT DistanceFieldVector * @m_since_latest * * Statically defined size of the - * @ref DistanceFieldVectorMaterialUniform uniform buffer. Has use only - * if @ref Flag::UniformBuffers is set. - * @see @ref bindMaterialBuffer() + * @ref DistanceFieldVectorMaterialUniform uniform buffer bound with + * @ref bindMaterialBuffer(). Has use only if @ref Flag::UniformBuffers + * is set. + * @see @ref Configuration::setMaterialCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -357,8 +360,11 @@ template class MAGNUM_SHADERS_EXPORT DistanceFieldVector * @ref TransformationProjectionUniform2D / * @ref TransformationProjectionUniform3D, * @ref DistanceFieldVectorDrawUniform and - * @ref TextureTransformationUniform uniform buffers. Has use only if + * @ref TextureTransformationUniform uniform buffers bound with + * @ref bindTransformationProjectionBuffer(), @ref bindDrawBuffer() and + * @ref bindTextureTransformationBuffer(). Has use only if * @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setDrawCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -647,6 +653,7 @@ template class DistanceFieldVectorGL::Config * @brief Set flags * * No flags are set by default. + * @see @ref DistanceFieldVectorGL::flags() */ Configuration& setFlags(Flags flags) { _flags = flags; @@ -668,7 +675,8 @@ template class DistanceFieldVectorGL::Config * is @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setDrawCount() + * @see @ref setFlags(), @ref setDrawCount(), + * @ref DistanceFieldVectorGL::materialCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. @@ -695,7 +703,8 @@ template class DistanceFieldVectorGL::Config * set via @ref setDrawOffset(). Default value is @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setMaterialCount() + * @see @ref setFlags(), @ref setMaterialCount(), + * @ref DistanceFieldVectorGL::drawCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. diff --git a/src/Magnum/Shaders/Flat.h b/src/Magnum/Shaders/Flat.h index b2a4e6bef..5ae55ba1b 100644 --- a/src/Magnum/Shaders/Flat.h +++ b/src/Magnum/Shaders/Flat.h @@ -96,10 +96,10 @@ struct FlatDrawUniform { * References a particular material from a @ref FlatMaterialUniform array. * Useful when an UBO with more than one material is supplied or in a * multi-draw scenario. Should be less than the material count passed to - * the @ref FlatGL::FlatGL(Flags, UnsignedInt, UnsignedInt) constructor, if - * material count is @cpp 1 @ce, this field is assumed to be @cpp 0 @ce and - * isn't even read by the shader. Default value is @cpp 0 @ce, meaning the - * first material gets used. + * @ref FlatGL::Configuration::setMaterialCount(), if material count is + * @cpp 1 @ce, this field is assumed to be @cpp 0 @ce and isn't even read + * by the shader. Default value is @cpp 0 @ce, meaning the first material + * gets used. */ /* This field is an UnsignedInt in the shader and materialId is extracted diff --git a/src/Magnum/Shaders/FlatGL.h b/src/Magnum/Shaders/FlatGL.h index 0ecb483de..d5a02b35b 100644 --- a/src/Magnum/Shaders/FlatGL.h +++ b/src/Magnum/Shaders/FlatGL.h @@ -180,10 +180,11 @@ can be supplied as well. A uniform buffer setup equivalent to the @snippet MagnumShaders-gl.cpp FlatGL-ubo For a multidraw workflow enable @ref Flag::MultiDraw (and possibly -@ref Flag::TextureArrays), supply desired material and draw count in the -@ref FlatGL(Flags, UnsignedInt, UnsignedInt) constructor and specify material -references and texture offsets/layers for every draw. The usage is similar for -all shaders, see @ref shaders-usage-multidraw for an example. +@ref Flag::TextureArrays), supply desired material and draw count via +@ref Configuration::setMaterialCount() and +@relativeref{Configuration,setDrawCount()} and specify material references and +texture offsets/layers for every draw. The usage is similar for all shaders, +see @ref shaders-usage-multidraw for an example. @requires_gl30 Extension @gl_extension{EXT,texture_array} for texture arrays. @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} for uniform @@ -341,7 +342,7 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: /** * @brief Flag * - * @see @ref Flags, @ref flags() + * @see @ref Flags, @ref flags(), @ref Configuration::setFlags() */ enum class Flag: UnsignedShort { /** @@ -652,7 +653,11 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: /** @brief Move assignment */ FlatGL& operator=(FlatGL&&) noexcept = default; - /** @brief Flags */ + /** + * @brief Flags + * + * @see @ref Configuration::setFlags() + */ Flags flags() const { return _flags; } #ifndef MAGNUM_TARGET_GLES2 @@ -661,8 +666,9 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * @m_since_latest * * Statically defined size of the @ref FlatMaterialUniform uniform - * buffer. Has use only if @ref Flag::UniformBuffers is set. - * @see @ref bindMaterialBuffer() + * buffer bound with @ref bindMaterialBuffer(). Has use only if + * @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setMaterialCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -675,8 +681,11 @@ template class MAGNUM_SHADERS_EXPORT FlatGL: public GL:: * Statically defined size of each of the * @ref TransformationProjectionUniform2D / * @ref TransformationProjectionUniform3D, @ref FlatDrawUniform and - * @ref TextureTransformationUniform uniform buffers. Has use only if + * @ref TextureTransformationUniform uniform buffers bound with + * @ref bindTransformationProjectionBuffer(), @ref bindDrawBuffer() and + * @ref bindTextureTransformationBuffer(). Has use only if * @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setDrawCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -1058,6 +1067,7 @@ template class FlatGL::Configuration { * @brief Set flags * * No flags are set by default. + * @see @ref FlatGL::flags() */ Configuration& setFlags(Flags flags) { _flags = flags; @@ -1078,7 +1088,8 @@ template class FlatGL::Configuration { * via @ref FlatDrawUniform::materialId. Default value is @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setDrawCount() + * @see @ref setFlags(), @ref setDrawCount(), + * @ref FlatGL::materialCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. @@ -1105,7 +1116,8 @@ template class FlatGL::Configuration { * @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setMaterialCount() + * @see @ref setFlags(), @ref setMaterialCount(), + * @ref FlatGL::drawCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. diff --git a/src/Magnum/Shaders/GenericGL.h b/src/Magnum/Shaders/GenericGL.h index e7f7195b2..e8b5644ba 100644 --- a/src/Magnum/Shaders/GenericGL.h +++ b/src/Magnum/Shaders/GenericGL.h @@ -226,7 +226,7 @@ recommended to so. If the custom shader diverges from predefined locations of common attributes, meshes configured for the builtin shaders (for example with @ref MeshTools::compile()) won't work with it and the mesh attribute configuration has to be done manually. It also becomes impossible to render a -mesh configured for a custom shader with for example @ref MeshVisualizer. +mesh configured for a custom shader with for example @ref MeshVisualizerGL3D. If you're using @ref GL::AbstractShaderProgram::bindAttributeLocation(), it's rather easy, as you can simply use the @ref GL::Attribute::Location of given diff --git a/src/Magnum/Shaders/MeshVisualizer.h b/src/Magnum/Shaders/MeshVisualizer.h index 3841717b0..0f5352b9a 100644 --- a/src/Magnum/Shaders/MeshVisualizer.h +++ b/src/Magnum/Shaders/MeshVisualizer.h @@ -96,11 +96,12 @@ struct MeshVisualizerDrawUniform2D { * References a particular material from a * @ref MeshVisualizerMaterialUniform array. Useful when an UBO with * more than one material is supplied or in a multi-draw scenario. Should - * be less than the material count passed to the @ref MeshVisualizerGL2D::MeshVisualizerGL2D(Flags, UnsignedInt, UnsignedInt) - * / @ref MeshVisualizerGL3D::MeshVisualizerGL3D(Flags, UnsignedInt, UnsignedInt) - * constructor, if material count is @cpp 1 @ce, this field is assumed to - * be @cpp 0 @ce and isn't even read by the shader. Default value is - * @cpp 0 @ce, meaning the first material gets used. + * be less than the material count passed to + * @ref MeshVisualizerGL2D::Configuration::setMaterialCount() / + * @ref MeshVisualizerGL3D::Configuration::setMaterialCount(), if material + * count is @cpp 1 @ce, this field is assumed to be @cpp 0 @ce and isn't + * even read by the shader. Default value is @cpp 0 @ce, meaning the first + * material gets used. */ /* This field is an UnsignedInt in the shader and materialId is extracted diff --git a/src/Magnum/Shaders/MeshVisualizerGL.h b/src/Magnum/Shaders/MeshVisualizerGL.h index d44faca1e..efae80101 100644 --- a/src/Magnum/Shaders/MeshVisualizerGL.h +++ b/src/Magnum/Shaders/MeshVisualizerGL.h @@ -254,7 +254,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua /** * @brief Flag * - * @see @ref Flags, @ref MeshVisualizerGL2D() + * @see @ref Flags, @ref flags(), @ref Configuration::setFlags() */ enum class Flag: UnsignedInt { /** @@ -537,7 +537,11 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua /** @brief Move assignment */ MeshVisualizerGL2D& operator=(MeshVisualizerGL2D&&) noexcept = default; - /** @brief Flags */ + /** + * @brief Flags + * + * @see @ref Configuration::setFlags() + */ Flags flags() const { return Flag(UnsignedInt(Implementation::MeshVisualizerGLBase::_flags)); } @@ -548,8 +552,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * @m_since_latest * * Statically defined size of the @ref MeshVisualizerMaterialUniform - * uniform buffer. Has use only if @ref Flag::UniformBuffers is set. - * @see @ref bindMaterialBuffer() + * uniform buffer bound with @ref bindMaterialBuffer(). Has use only if + * @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setMaterialCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -561,8 +566,10 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL2D: public Implementation::MeshVisua * * Statically defined size of each of the * @ref TransformationProjectionUniform2D and - * @ref MeshVisualizerDrawUniform2D uniform buffers. Has use only if - * @ref Flag::UniformBuffers is set. + * @ref MeshVisualizerDrawUniform2D uniform buffers bound with + * @ref bindTransformationProjectionBuffer() and @ref bindDrawBuffer(). + * Has use only if @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setDrawCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -879,6 +886,7 @@ class MeshVisualizerGL2D::Configuration { * @ref Flag::VertexId, @ref Flag::PrimitiveId or * @ref Flag::PrimitiveIdFromVertexId is expected to be enabled. No * flags are set by default. + * @see @ref MeshVisualizerGL2D::flags() */ Configuration& setFlags(Flags flags) { _flags = flags; @@ -900,7 +908,8 @@ class MeshVisualizerGL2D::Configuration { * @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setDrawCount() + * @see @ref setFlags(), @ref setDrawCount(), + * @ref MeshVisualizerGL2D::materialCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. @@ -926,7 +935,8 @@ class MeshVisualizerGL2D::Configuration { * @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setMaterialCount() + * @see @ref setFlags(), @ref setMaterialCount(), + * @ref MeshVisualizerGL2D::drawCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. @@ -971,8 +981,9 @@ class MeshVisualizerGL2D::CompileState: public MeshVisualizerGL2D { Visualizes wireframe, per-vertex/per-instance object ID, primitive ID or tangent space of 3D meshes. You need to provide the @ref Position attribute in -your triangle mesh at the very least. Use @ref setTransformationProjectionMatrix(), -@ref setColor() and others to configure the shader. +your triangle mesh at the very least. Use @ref setProjectionMatrix(), +@ref setTransformationMatrix(), @ref setColor() and others to configure the +shader. @m_class{m-row} @@ -1183,9 +1194,10 @@ here as well, as it's assumed to be set globally and rarely changed: @snippet MagnumShaders-gl.cpp MeshVisualizerGL3D-ubo For a multidraw workflow enable @ref Flag::MultiDraw, supply desired material -and draw count in the @ref MeshVisualizerGL3D(Flags, UnsignedInt, UnsignedInt) -constructor and specify material references for every draw. The usage is -similar for all shaders, see @ref shaders-usage-multidraw for an example. +and draw count via @ref Configuration::setMaterialCount() and +@relativeref{Configuration,setDrawCount()} and specify material references for +every draw. The usage is similar for all shaders, see +@ref shaders-usage-multidraw for an example. @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} for uniform buffers. @@ -1390,7 +1402,7 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua /** * @brief Flag * - * @see @ref Flags, @ref MeshVisualizer() + * @see @ref Flags, @ref flags(), @ref Configuration::setFlags() */ enum class Flag: UnsignedInt { /** @@ -1825,7 +1837,11 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua /** @brief Move assignment */ MeshVisualizerGL3D& operator=(MeshVisualizerGL3D&&) noexcept = default; - /** @brief Flags */ + /** + * @brief Flags + * + * @see @ref Configuration::setFlags() + */ Flags flags() const { return Flag(UnsignedInt(Implementation::MeshVisualizerGLBase::_flags)); } @@ -1836,8 +1852,9 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @m_since_latest * * Statically defined size of the @ref MeshVisualizerMaterialUniform - * uniform buffer. Has use only if @ref Flag::UniformBuffers is set. - * @see @ref bindMaterialBuffer() + * uniform buffer bound with @ref bindMaterialBuffer(). Has use only if + * @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setMaterialCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -1848,9 +1865,11 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizerGL3D: public Implementation::MeshVisua * @m_since_latest * * Statically defined size of each of the - * @ref TransformationProjectionUniform3D and - * @ref MeshVisualizerDrawUniform3D uniform buffers. Has use only if - * @ref Flag::UniformBuffers is set. + * @ref TransformationUniform3D and + * @ref MeshVisualizerDrawUniform3D uniform buffers, bound with + * @ref bindTransformationBuffer() and @ref bindDrawBuffer(). Has use + * only if @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setDrawCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -2446,6 +2465,7 @@ class MeshVisualizerGL3D::Configuration { * @ref Flag::ObjectId, @ref Flag::VertexId, @ref Flag::PrimitiveId or * @ref Flag::PrimitiveIdFromVertexId is expected to be enabled. No * flags are set by default. + * @see @ref MeshVisualizerGL3D::flags() */ Configuration& setFlags(Flags flags) { _flags = flags; @@ -2467,7 +2487,8 @@ class MeshVisualizerGL3D::Configuration { * @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setDrawCount() + * @see @ref setFlags(), @ref setDrawCount(), + * @ref MeshVisualizerGL3D::materialCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. @@ -2484,16 +2505,16 @@ class MeshVisualizerGL3D::Configuration { * @brief Set draw count * * If @ref Flag::UniformBuffers is set, describes size of a - * @ref ProjectionUniform3D / @ref TransformationUniform3D - * @ref MeshVisualizerDrawUniform3D / @ref TextureTransformationUniform - * buffer bound with @ref bindProjectionBuffer(), + * @ref TransformationUniform3D / @ref MeshVisualizerDrawUniform3D / + * @ref TextureTransformationUniform buffer bound with * @ref bindTransformationBuffer(), @ref bindDrawBuffer() and * @ref bindTextureTransformationBuffer(); as uniform buffers are * required to have a statically defined size. The draw offset is then * set via @ref setDrawOffset(). Default value is @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setMaterialCount() + * @see @ref setFlags(), @ref setMaterialCount(), + * @ref MeshVisualizerGL3D::drawCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. diff --git a/src/Magnum/Shaders/Phong.h b/src/Magnum/Shaders/Phong.h index 7f55eda3f..00f39decb 100644 --- a/src/Magnum/Shaders/Phong.h +++ b/src/Magnum/Shaders/Phong.h @@ -132,10 +132,10 @@ struct PhongDrawUniform { * References a particular material from a @ref PhongMaterialUniform array. * Useful when a UBO with more than one material is supplied or in a * multi-draw scenario. Should be less than the material count passed to - * the @ref PhongGL::PhongGL(Flags, UnsignedInt, UnsignedInt, UnsignedInt) - * constructor, if material count is @cpp 1 @ce, this field is assumed to - * be @cpp 0 @ce and isn't even read by the shader. Default value is - * @cpp 0 @ce, meaning the first material gets used. + * @ref PhongGL::Configuration::setMaterialCount(), if material count is + * @cpp 1 @ce, this field is assumed to be @cpp 0 @ce and isn't even read + * by the shader. Default value is @cpp 0 @ce, meaning the first material + * gets used. */ /* This field is an UnsignedInt in the shader and materialId is extracted diff --git a/src/Magnum/Shaders/PhongGL.h b/src/Magnum/Shaders/PhongGL.h index 015ec06d9..4724d3a6b 100644 --- a/src/Magnum/Shaders/PhongGL.h +++ b/src/Magnum/Shaders/PhongGL.h @@ -45,9 +45,9 @@ namespace Magnum { namespace Shaders { Uses ambient, diffuse and specular color or texture. For a colored mesh you need to provide the @ref Position and @ref Normal attributes in your triangle mesh. By default, the shader renders the mesh with a white color in an identity -transformation. Use @ref setTransformationMatrix(), @ref setNormalMatrix(), -@ref setProjectionMatrix(), @ref setLightPosition() and others to configure -the shader. +transformation. Use @ref setProjectionMatrix(). @ref setTransformationMatrix(), +@ref setNormalMatrix(), @ref setLightPosition() and others to configure the +shader. @image html shaders-phong.png width=256px @@ -271,14 +271,15 @@ with one default light, would look like this: @snippet MagnumShaders-gl.cpp PhongGL-ubo For a multidraw workflow enable @ref Flag::MultiDraw (and possibly -@ref Flag::TextureArrays) and supply desired light, material and draw count in -the @ref PhongGL(Flags, UnsignedInt, UnsignedInt, UnsignedInt) constructor. For -every draw then specify material references and texture offsets/layers. With -@ref Flag::LightCulling it's also possible to perform per-draw light culling by -supplying a subrange into the @ref PhongLightUniform array using -@ref PhongDrawUniform::lightOffset and @relativeref{PhongDrawUniform,lightCount}. -Besides that, the usage is similar for all shaders, see -@ref shaders-usage-multidraw for an example. +@ref Flag::TextureArrays) and supply desired light, material and draw count via +@ref Configuration::setLightCount(), +@relativeref{Configuration,setMaterialCount()} +and @relativeref{Configuration,setDrawCount()}. For every draw then specify +material references and texture offsets/layers. With @ref Flag::LightCulling +it's also possible to perform per-draw light culling by supplying a subrange +into the @ref PhongLightUniform array using @ref PhongDrawUniform::lightOffset +and @relativeref{PhongDrawUniform,lightCount}. Besides that, the usage is +similar for all shaders, see @ref shaders-usage-multidraw for an example. @requires_gl30 Extension @gl_extension{EXT,texture_array} for texture arrays. @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} for uniform @@ -313,7 +314,8 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief Normal direction * * @ref shaders-generic "Generic attribute", - * @ref Magnum::Vector3 "Vector3". + * @ref Magnum::Vector3 "Vector3". Used only if @ref lightCount() isn't + * @cpp 0 @ce. */ typedef GenericGL3D::Normal Normal; @@ -326,7 +328,8 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * 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 - * @cpp 1.0f @ce. Used only if @ref Flag::NormalTexture is set. + * @cpp 1.0f @ce. Used only if @ref Flag::NormalTexture is set and + * @ref lightCount() isn't @cpp 0 @ce. * @see @ref Shaders-PhongGL-normal-mapping */ typedef GenericGL3D::Tangent Tangent; @@ -339,7 +342,8 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @ref Magnum::Vector4 "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. + * instead. Used only if @ref Flag::NormalTexture is set and + * @ref lightCount() isn't @cpp 0 @ce. * @see @ref Shaders-PhongGL-normal-mapping */ typedef GenericGL3D::Tangent4 Tangent4; @@ -351,7 +355,7 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @ref shaders-generic "Generic attribute", * @ref Magnum::Vector3 "Vector3". Use either this or the @ref Tangent4 * attribute. Used only if both @ref Flag::NormalTexture and - * @ref Flag::Bitangent are set. + * @ref Flag::Bitangent are set and @ref lightCount() isn't @cpp 0 @ce. * @see @ref Shaders-PhongGL-normal-mapping */ typedef GenericGL3D::Bitangent Bitangent; @@ -496,7 +500,7 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { /** * @brief Flag * - * @see @ref Flags, @ref flags() + * @see @ref Flags, @ref flags(), @ref Configuration::setFlags() */ enum class Flag: UnsignedInt { /** @@ -865,15 +869,27 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { /** @brief Move assignment */ PhongGL& operator=(PhongGL&&) noexcept = default; - /** @brief Flags */ + /** + * @brief Flags + * + * @see @ref Configuration::setFlags() + */ Flags flags() const { return _flags; } /** * @brief Light count * + * If @ref Flag::UniformBuffers is not set, this is the number of + * light properties accepted by @ref setLightPositions() / + * @ref setLightPosition(), @ref setLightColors() / + * @ref setLightColor(), @ref setLightSpecularColors() / + * @ref setSpecularColor() and @ref setLightRanges() / + * @ref setLightRange(). + * * If @ref Flag::UniformBuffers is set, this is the statically defined - * size of the @ref PhongLightUniform uniform buffer. - * @see @ref bindLightBuffer() + * size of the @ref PhongLightUniform uniform buffer bound with + * @ref bindLightBuffer(). + * @see @ref Configuration::setLightCount() */ UnsignedInt lightCount() const { return _lightCount; } @@ -883,8 +899,9 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @m_since_latest * * Statically defined size of the @ref PhongMaterialUniform uniform - * buffer. Has use only if @ref Flag::UniformBuffers is set. - * @see @ref bindMaterialBuffer() + * buffer bound with @ref bindMaterialBuffer(). Has use only if + * @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setMaterialCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -894,10 +911,12 @@ class MAGNUM_SHADERS_EXPORT PhongGL: public GL::AbstractShaderProgram { * @brief Draw count * @m_since_latest * - * Statically defined size of each of the @ref ProjectionUniform3D, - * @ref TransformationUniform3D, @ref PhongDrawUniform and - * @ref TextureTransformationUniform uniform buffers. Has use only if - * @ref Flag::UniformBuffers is set. + * Statically defined size of each of the @ref TransformationUniform3D, + * @ref PhongDrawUniform and @ref TextureTransformationUniform uniform + * buffers bound with @ref bindTransformationBuffer(), + * @ref bindDrawBuffer() and @ref bindTextureTransformationBuffer(). + * Has use only if @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setDrawCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -1798,6 +1817,7 @@ class PhongGL::Configuration { * @brief Set flags * * No flags are set by default. + * @see @ref PhongGL::flags() */ Configuration& setFlags(Flags flags) { _flags = flags; @@ -1810,13 +1830,6 @@ class PhongGL::Configuration { /** * @brief Set light count * - * If @ref Flag::UniformBuffers is set, describes size of a - * @ref PhongLightUniform buffer bound with @ref bindLightBuffer(); as - * uniform buffers are required to have a statically defined size. The - * per-draw lights are then specified via - * @ref PhongDrawUniform::lightOffset and - * @ref PhongDrawUniform::lightCount. - * * If @ref Flag::UniformBuffers isn't set, describes how many lights * get applied to each draw, and corresponds to the range / array size * accepted by @ref setLightPosition() / @ref setLightPositions(), @@ -1824,9 +1837,17 @@ class PhongGL::Configuration { * @ref setLightSpecularColor() / @ref setLightSpecularColors() and * @ref setLightRange() / @ref setLightRanges(). * + * If @ref Flag::UniformBuffers is set, describes size of a + * @ref PhongLightUniform buffer bound with @ref bindLightBuffer(); as + * uniform buffers are required to have a statically defined size. The + * per-draw lights are then specified via + * @ref PhongDrawUniform::lightOffset and + * @ref PhongDrawUniform::lightCount. + * * Can be set to @cpp 0 @ce, in which case only the ambient * contribution to the color is used. Default value is @cpp 1 @ce. - * @see @ref setFlags(), @ref setMaterialCount(), @ref setDrawCount() + * @see @ref setFlags(), @ref setMaterialCount(), @ref setDrawCount(), + * @ref PhongGL::lightCount() */ Configuration& setLightCount(UnsignedInt count) { _lightCount = count; @@ -1847,7 +1868,8 @@ class PhongGL::Configuration { * via @ref PhongDrawUniform::materialId. Default value is @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setLightCount(), @ref setDrawCount() + * @see @ref setFlags(), @ref setLightCount(), @ref setDrawCount(), + * @ref PhongGL::materialCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. @@ -1864,16 +1886,16 @@ class PhongGL::Configuration { * @brief Set draw count * * If @ref Flag::UniformBuffers is set, describes size of a - * @ref ProjectionUniform3D / @ref TransformationUniform3D / - * @ref PhongDrawUniform / @ref TextureTransformationUniform buffer - * bound with @ref bindProjectionBuffer(), + * @ref TransformationUniform3D / @ref PhongDrawUniform / + * @ref TextureTransformationUniform buffer bound with * @ref bindTransformationBuffer(), @ref bindDrawBuffer() and * @ref bindTextureTransformationBuffer(); as uniform buffers are * required to have a statically defined size. The draw offset is then * set via @ref setDrawOffset(). Default value is @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setLightCount(), @ref setMaterialCount() + * @see @ref setFlags(), @ref setLightCount(), @ref setMaterialCount(), + * @ref PhongGL::drawCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. diff --git a/src/Magnum/Shaders/Vector.h b/src/Magnum/Shaders/Vector.h index 015a74a7f..53ffdb351 100644 --- a/src/Magnum/Shaders/Vector.h +++ b/src/Magnum/Shaders/Vector.h @@ -87,10 +87,10 @@ struct VectorDrawUniform { * References a particular material from a @ref VectorMaterialUniform * array. Useful when an UBO with more than one material is supplied or in * a multi-draw scenario. Should be less than the material count passed to - * the @ref VectorGL::VectorGL(Flags, UnsignedInt, UnsignedInt) - * constructor, if material count is @cpp 1 @ce, this field is assumed to - * be @cpp 0 @ce and isn't even read by the shader. Default value is - * @cpp 0 @ce, meaning the first material gets used. + * @ref VectorGL::Configuration::setMaterialCount(), if material count is + * @cpp 1 @ce, this field is assumed to be @cpp 0 @ce and isn't even read + * by the shader. Default value is @cpp 0 @ce, meaning the first material + * gets used. */ /* This field is an UnsignedInt in the shader and materialId is extracted diff --git a/src/Magnum/Shaders/VectorGL.h b/src/Magnum/Shaders/VectorGL.h index e8ffdef5e..f62fd4e89 100644 --- a/src/Magnum/Shaders/VectorGL.h +++ b/src/Magnum/Shaders/VectorGL.h @@ -96,11 +96,11 @@ setup equivalent to the above would look like this: @snippet MagnumShaders-gl.cpp VectorGL-ubo For a multidraw workflow enable @ref Flag::MultiDraw, supply desired material -and draw count in the @ref VectorGL(Flags, UnsignedInt, UnsignedInt) -constructor and specify material references and texture offsets for every draw. -Texture arrays aren't currently supported for this shader. Besides that, the -usage is similar for all shaders, see @ref shaders-usage-multidraw for an -example. +and draw count via @ref Configuration::setMaterialCount() and +@relativeref{Configuration,setDrawCount()} and specify material references and +texture offsets for every draw. Texture arrays aren't currently supported for +this shader. Besides that, the usage is similar for all shaders, see +@ref shaders-usage-multidraw for an example. @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} for uniform buffers. @@ -151,7 +151,7 @@ template class MAGNUM_SHADERS_EXPORT VectorGL: public GL * @brief Flag * @m_since{2020,06} * - * @see @ref Flags, @ref flags() + * @see @ref Flags, @ref flags(), @ref Configuration::setFlags() */ enum class Flag: UnsignedByte { /** @@ -327,6 +327,8 @@ template class MAGNUM_SHADERS_EXPORT VectorGL: public GL /** * @brief Flags * @m_since{2020,06} + * + * @see @ref Configuration::setFlags() */ Flags flags() const { return _flags; } @@ -336,8 +338,9 @@ template class MAGNUM_SHADERS_EXPORT VectorGL: public GL * @m_since_latest * * Statically defined size of the @ref VectorMaterialUniform uniform - * buffer. Has use only if @ref Flag::UniformBuffers is set. - * @see @ref bindMaterialBuffer() + * buffer bound with @ref bindMaterialBuffer(). Has use only if + * @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setMaterialCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -350,8 +353,11 @@ template class MAGNUM_SHADERS_EXPORT VectorGL: public GL * Statically defined size of each of the * @ref TransformationProjectionUniform2D / * @ref TransformationProjectionUniform3D, @ref VectorDrawUniform and - * @ref TextureTransformationUniform uniform buffers. Has use only if + * @ref TextureTransformationUniform uniform buffers bound with + * @ref bindTransformationProjectionBuffer(), @ref bindDrawBuffer() and + * @ref bindTextureTransformationBuffer(). Has use only if * @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setDrawCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -599,6 +605,7 @@ template class VectorGL::Configuration { * @brief Set flags * * No flags are set by default. + * @see @ref VectorGL::flags() */ Configuration& setFlags(Flags flags) { _flags = flags; @@ -619,7 +626,8 @@ template class VectorGL::Configuration { * via @ref VectorDrawUniform::materialId. Default value is @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setDrawCount() + * @see @ref setFlags(), @ref setDrawCount(), + * @ref VectorGL::materialCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. @@ -646,7 +654,8 @@ template class VectorGL::Configuration { * @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags(), @ref setMaterialCount() + * @see @ref setFlags(), @ref setMaterialCount(), + * @ref VectorGL::drawCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0. diff --git a/src/Magnum/Shaders/VertexColorGL.h b/src/Magnum/Shaders/VertexColorGL.h index 5dccbe45e..5049c7d81 100644 --- a/src/Magnum/Shaders/VertexColorGL.h +++ b/src/Magnum/Shaders/VertexColorGL.h @@ -94,8 +94,8 @@ this: @snippet MagnumShaders-gl.cpp VectorGL-ubo For a multidraw workflow enable @ref Flag::MultiDraw and supply desired draw -count in the @ref VertexColorGL(Flags, UnsignedInt) constructor. The usage is -similar for all shaders, see @ref shaders-usage-multidraw for an example. +count via @ref Configuration::setDrawCount(). The usage is similar for all +shaders, see @ref shaders-usage-multidraw for an example. @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} for uniform buffers. @@ -154,7 +154,7 @@ template class MAGNUM_SHADERS_EXPORT VertexColorGL: publ * @brief Flag * @m_since{2020,06} * - * @see @ref Flags, @ref flags() + * @see @ref Flags, @ref flags(), @ref Configuration::setFlags() */ enum class Flag: UnsignedByte { #ifndef MAGNUM_TARGET_GLES2 @@ -319,7 +319,11 @@ template class MAGNUM_SHADERS_EXPORT VertexColorGL: publ /** @brief Move assignment */ VertexColorGL& operator=(VertexColorGL&&) noexcept = default; - /** @brief Flags */ + /** + * @brief Flags + * + * @see @ref Configuration::setFlags() + */ Flags flags() const { return _flags; } #ifndef MAGNUM_TARGET_GLES2 @@ -329,8 +333,10 @@ template class MAGNUM_SHADERS_EXPORT VertexColorGL: publ * * Statically defined size of each of the * @ref TransformationProjectionUniform2D / - * @ref TransformationProjectionUniform3D uniform buffers. Has use only - * if @ref Flag::UniformBuffers is set. + * @ref TransformationProjectionUniform3D uniform buffers bound with + * @ref bindTransformationProjectionBuffer(). Has use only if + * @ref Flag::UniformBuffers is set. + * @see @ref Configuration::setDrawCount() * @requires_gles30 Not defined on OpenGL ES 2.0 builds. * @requires_webgl20 Not defined on WebGL 1.0 builds. */ @@ -452,6 +458,7 @@ template class VertexColorGL::Configuration * @brief Set flags * * No flags are set by default. + * @see @ref VertexColorGL::flags() */ Configuration& setFlags(Flags flags) { _flags = flags; @@ -473,7 +480,7 @@ template class VertexColorGL::Configuration * set via @ref setDrawOffset(). Default value is @cpp 1 @ce. * * If @ref Flag::UniformBuffers isn't set, this value is ignored. - * @see @ref setFlags() + * @see @ref setFlags(), @ref VertexColorGL::drawCount() * @requires_gl31 Extension @gl_extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. * @requires_webgl20 Uniform buffers are not available in WebGL 1.0.