From 9a572279454e5debc0b9591dd3c873bb572276ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 23 Nov 2021 21:32:09 +0100 Subject: [PATCH] GL: refresh AbstractShaderProgram and Attribute docs slightly. With an emphasis on how these are only meant to be used by custom shader implementations and not end users. More needs to be done. --- src/Magnum/GL/AbstractShaderProgram.h | 10 ++++++++++ src/Magnum/GL/Attribute.h | 27 ++++++++++++++++----------- 2 files changed, 26 insertions(+), 11 deletions(-) diff --git a/src/Magnum/GL/AbstractShaderProgram.h b/src/Magnum/GL/AbstractShaderProgram.h index 2413ed922..33eea14ca 100644 --- a/src/Magnum/GL/AbstractShaderProgram.h +++ b/src/Magnum/GL/AbstractShaderProgram.h @@ -48,6 +48,16 @@ namespace Implementation { struct ShaderProgramState; } /** @brief Base for shader program implementations +Wraps an OpenGL shader program object. Meant to be only used through +subclasses, either via builtin shaders in the @ref Shaders namespace or by +creating a custom shader implementation. + +@m_class{m-note m-success} + +@par + A simple custom shader implementation is shown in the + @ref examples-texturedquad "Textured Quad example". + @section GL-AbstractShaderProgram-subclassing Subclassing workflow This class is designed to be used via subclassing. Subclasses define these diff --git a/src/Magnum/GL/Attribute.h b/src/Magnum/GL/Attribute.h index 1b27fc848..eb2b0b9b5 100644 --- a/src/Magnum/GL/Attribute.h +++ b/src/Magnum/GL/Attribute.h @@ -45,17 +45,22 @@ namespace Magnum { namespace GL { namespace Implementation { template struct Attribute; } /** -@brief Base class for vertex attribute location and type - -For use in @ref AbstractShaderProgram subclasses. The @p location template -parameter is vertex attribute location, a number between @cpp 0 @ce and -@ref AbstractShaderProgram::maxVertexAttributes(). To ensure compatibility, you -should always have a vertex attribute with location @cpp 0 @ce. - -The @p T template parameter is the type which is used for shader attribute, -e.g. @ref Magnum::Vector4i "Vector4i" for @glsl ivec4 @ce. @ref 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 +@brief Base class for specifying shader attributes + +Meant to be used mainly through a @cpp typedef @ce in +@ref AbstractShaderProgram subclasses. Shader consumers are then supposed to +use the @cpp typedef @ce, or in case of builtin attributes the definitions from +@ref Shaders::GenericGL and other classes from the @ref Shaders namespace. + +The @p location template parameter is a vertex attribute location, a number +between @cpp 0 @ce and @ref AbstractShaderProgram::maxVertexAttributes(). To +ensure compatibility, you should always have a vertex attribute with location +@cpp 0 @ce. + +The @p T template parameter is the type that matches the shader attribute +declaration, e.g. @ref Magnum::Vector4i "Vector4i" for @glsl ivec4 @ce. +@ref DataType is the 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 --