From 6d509b7a1b3a4804baa644a0f3d7d7866efecc4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 21 Dec 2017 15:01:36 +0100 Subject: [PATCH] Random updates for the new documentation theme in the root namespace. --- src/Magnum/AbstractFramebuffer.h | 9 +- src/Magnum/AbstractResourceLoader.h | 8 +- src/Magnum/AbstractShaderProgram.h | 271 +++++++++++++++------------- src/Magnum/AbstractTexture.h | 5 +- src/Magnum/Context.h | 15 +- src/Magnum/Framebuffer.h | 12 +- src/Magnum/RectangleTexture.h | 2 +- src/Magnum/TransformFeedback.h | 2 +- src/Magnum/Version.h | 2 +- 9 files changed, 179 insertions(+), 147 deletions(-) diff --git a/src/Magnum/AbstractFramebuffer.h b/src/Magnum/AbstractFramebuffer.h index 9017417cf..7398e1639 100644 --- a/src/Magnum/AbstractFramebuffer.h +++ b/src/Magnum/AbstractFramebuffer.h @@ -155,8 +155,7 @@ namespace Implementation { struct FramebufferState; } See @ref DefaultFramebuffer and @ref Framebuffer for more information. -@anchor AbstractFramebuffer-performance-optimization -## Performance optimizations and security +@section AbstractFramebuffer-performance-optimization Performance optimizations and security The engine tracks currently bound framebuffer and current viewport to avoid unnecessary calls to @fn_gl{BindFramebuffer} and @fn_gl{Viewport} when @@ -376,7 +375,8 @@ class MAGNUM_EXPORT AbstractFramebuffer { /** @overload * * Convenience alternative to the above, example usage: - * @code + * + * @code{.cpp} * Image2D image = framebuffer.read(framebuffer.viewport(), {PixelFormat::RGBA, PixelType::UnsignedByte}); * @endcode */ @@ -414,7 +414,8 @@ class MAGNUM_EXPORT AbstractFramebuffer { /** @overload * * Convenience alternative to the above, example usage: - * @code + * + * @code{.cpp} * BufferImage2D image = framebuffer.read(framebuffer.viewport(), {PixelFormat::RGBA, PixelType::UnsignedByte}, BufferUsage::StaticRead); * @endcode */ diff --git a/src/Magnum/AbstractResourceLoader.h b/src/Magnum/AbstractResourceLoader.h index ec8da6336..f8f4a1600 100644 --- a/src/Magnum/AbstractResourceLoader.h +++ b/src/Magnum/AbstractResourceLoader.h @@ -40,7 +40,7 @@ namespace Magnum { Provides (a)synchronous resource loading for @ref ResourceManager. -## Usage and subclassing +@section AbstractResourceLoader-usage Usage and subclassing Usage is done by subclassing. Subclass instances can be added to @ref ResourceManager using @ref ResourceManager::setLoader(). After adding the @@ -64,7 +64,8 @@ You can also implement @ref doName() to provide meaningful names for resource keys. Example implementation for synchronous mesh loader: -@code + +@code{.cpp} class MeshResourceLoader: public AbstractResourceLoader { void doLoad(ResourceKey key) override { // Load the mesh... @@ -87,7 +88,8 @@ all resources. It allows you to use resources in the loader itself without having to delete the loader explicitly to ensure proper resource unloading. In the following code, however, the loader destroys itself (and removes itself from the manager) before the manager is destroyed. -@code + +@code{.cpp} MyResourceManager manager; MeshResourceLoader loader; diff --git a/src/Magnum/AbstractShaderProgram.h b/src/Magnum/AbstractShaderProgram.h index ad53249cb..9e1de2c25 100644 --- a/src/Magnum/AbstractShaderProgram.h +++ b/src/Magnum/AbstractShaderProgram.h @@ -48,100 +48,113 @@ namespace Implementation { struct ShaderProgramState; } /** @brief Base for shader program implementations -@anchor AbstractShaderProgram-subclassing -## Subclassing workflow +@section AbstractShaderProgram-subclassing Subclassing workflow This class is designed to be used via subclassing. Subclasses define these functions and properties: -- **Attribute definitions** with location and type for + + + +@subsection AbstractShaderProgram-attribute-location Binding attribute location The preferred workflow is to specify attribute location for vertex shader input attributes and fragment shader output attributes explicitly in the shader code, e.g.: -@code + +@code{.glsl} // GLSL 3.30, GLSL ES 3.00 or #extension GL_ARB_explicit_attrib_location: require layout(location = 0) in vec4 position; @@ -152,26 +165,30 @@ layout(location = 2) in vec2 textureCoordinates; Similarly for ouput attributes, you can also specify blend equation color index for them (see @ref Renderer::BlendFunction for more information about using color input index): -@code + +@code{.glsl} layout(location = 0, index = 0) out vec4 color; layout(location = 1, index = 1) out vec3 normal; @endcode If you don't have the required version/extension, declare the attributes -without `layout()` qualifier and use functions @ref bindAttributeLocation() and -@ref bindFragmentDataLocation() / @ref bindFragmentDataLocationIndexed() between -attaching the shaders and linking the program. Note that additional syntax -changes may be needed for GLSL 1.20 and GLSL ES. -@code +without @glsl layout() @ce qualifier and use functions @ref bindAttributeLocation() +and @ref bindFragmentDataLocation() / @ref bindFragmentDataLocationIndexed() +between attaching the shaders and linking the program. Note that additional +syntax changes may be needed for GLSL 1.20 and GLSL ES. + +@code{.glsl} in vec4 position; in vec3 normal; in vec2 textureCoordinates; @endcode -@code + +@code{.glsl} out vec4 color; out vec3 normal; @endcode -@code + +@code{.cpp} // Shaders attached... bindAttributeLocation(Position::Location, "position"); @@ -208,12 +225,12 @@ bindFragmentDataLocationIndexed(NormalOutput, 1, "normal"); @todo @extension2{EXT,separate_shader_objects,separate_shader_objects.gles} supports explicit attrib location -@anchor AbstractShaderProgram-uniform-location -### Uniform locations +@subsection AbstractShaderProgram-uniform-location Uniform locations The preferred workflow is to specify uniform locations directly in the shader code, e.g.: -@code + +@code{.glsl} // GLSL 4.30, GLSL ES 3.10 or #extension GL_ARB_explicit_uniform_location: require layout(location = 0) uniform mat4 projectionMatrix; @@ -222,15 +239,18 @@ layout(location = 2) uniform mat3 normalMatrix; @endcode If you don't have the required version/extension, declare the uniforms without -the `layout()` qualifier, get uniform location using @ref uniformLocation() *after* -linking stage and then use the queried location in uniform setting functions. -Note that additional syntax changes may be needed for GLSL 1.20 and GLSL ES. -@code +the @glsl layout() @ce qualifier, get uniform location using +@ref uniformLocation() *after* linking stage and then use the queried location +in uniform setting functions. Note that additional syntax changes may be needed +for GLSL 1.20 and GLSL ES. + +@code{.glsl} uniform mat4 projectionMatrix; uniform mat4 transformationMatrix; uniform mat3 normalMatrix; @endcode -@code + +@code{.cpp} Int projectionMatrixUniform = uniformLocation("projectionMatrix"); Int transformationMatrixUniform = uniformLocation("transformationMatrix"); Int normalMatrixUniform = uniformLocation("normalMatrix"); @@ -244,12 +264,12 @@ Int normalMatrixUniform = uniformLocation("normalMatrix"); @requires_gles Explicit uniform location is not supported in WebGL. Use @ref uniformLocation() instead. -@anchor AbstractShaderProgram-uniform-block-binding -### Uniform block bindings +@subsection AbstractShaderProgram-uniform-block-binding Uniform block bindings The preferred workflow is to specify uniform block binding directly in the shader code, e.g.: -@code + +@code{.glsl} // GLSL 4.20, GLSL ES 3.10 or #extension GL_ARB_shading_language_420pack: require layout(std140, binding = 0) uniform matrices { @@ -263,11 +283,12 @@ layout(std140, binding = 1) uniform material { @endcode If you don't have the required version/extension, declare the uniform blocks -without the `layout()` qualifier, get uniform block index using +without the @glsl layout() @ce qualifier, get uniform block index using @ref uniformBlockIndex() and then map it to the uniform buffer binding using @ref setUniformBlockBinding(). Note that additional syntax changes may be needed for GLSL ES. -@code + +@code{.glsl} layout(std140) uniform matrices { mat4 projectionMatrix; mat4 transformationMatrix; @@ -277,7 +298,8 @@ layout(std140) uniform material { vec4 specular; }; @endcode -@code + +@code{.cpp} setUniformBlockBinding(uniformBlockIndex("matrices"), 0); setUniformBlockBinding(uniformBlockIndex("material"), 1); @endcode @@ -295,12 +317,12 @@ setUniformBlockBinding(uniformBlockIndex("material"), 1); @requires_gles Explicit uniform block binding is not supported in WebGL. Use @ref uniformBlockIndex() and @ref setUniformBlockBinding() instead. -@anchor AbstractShaderProgram-shader-storage-block-binding -### Shader storage block bindings +@subsection AbstractShaderProgram-shader-storage-block-binding Shader storage block bindings The workflow is to specify shader storage block binding directly in the shader code, e.g.: -@code + +@code{.glsl} // GLSL 4.30 or GLSL ES 3.10 layout(std430, binding = 0) buffer vertices { vec3 position; @@ -316,12 +338,12 @@ layout(std430, binding = 1) buffer normals { @requires_gles31 Shader storage is not available in OpenGL ES 3.0 and older. @requires_gles Shader storage is not available in WebGL. -@anchor AbstractShaderProgram-texture-units -### Specifying texture and image binding units +@subsection AbstractShaderProgram-texture-units Specifying texture and image binding units The preferred workflow is to specify texture/image binding unit directly in the shader code, e.g.: -@code + +@code{.glsl} // GLSL 4.20, GLSL ES 3.10 or #extension GL_ARB_shading_language_420pack: require layout(binding = 0) uniform sampler2D diffuseTexture; @@ -332,11 +354,13 @@ If you don't have the required version/extension, declare the uniforms without the `binding` qualifier and set the texture binding unit using @ref setUniform(Int, const T&) "setUniform(Int, Int)". Note that additional syntax changes may be needed for GLSL ES. -@code + +@code{.glsl} uniform sampler2D diffuseTexture; uniform sampler2D specularTexture; @endcode -@code + +@code{.cpp} setUniform(uniformLocation("diffuseTexture"), 0); setUniform(uniformLocation("specularTexture"), 1); @endcode @@ -351,12 +375,12 @@ setUniform(uniformLocation("specularTexture"), 1); @requires_gles Explicit texture binding unit is not supported in WebGL. Use @ref setUniform(Int, const T&) "setUniform(Int, Int)" instead. -@anchor AbstractShaderProgram-transform-feedback -### Specifying transform feedback binding points +@subsection AbstractShaderProgram-transform-feedback Specifying transform feedback binding points The preferred workflow is to specify output binding points directly in the shader code, e.g.: -@code + +@code{.glsl} // GLSL 4.40, or #extension GL_ARB_enhanced_layouts: require layout(xfb_buffer = 0, xfb_stride = 32) out block { @@ -369,14 +393,16 @@ layout(xfb_buffer = 1) out vec3 velocity; If you don't have the required version/extension, declare the uniforms without the `xfb_*` qualifier and set the binding points using @ref setTransformFeedbackOutputs(). Equivalent setup for the previous code would be the following: -@code + +@code{.glsl} out block { vec3 position; vec3 normal; }; out vec3 velocity; @endcode -@code + +@code{.cpp} setTransformFeedbackOutputs({ // Buffer 0 "position", "gl_SkipComponents1", "normal", "gl_SkipComponents1", @@ -400,8 +426,7 @@ setTransformFeedbackOutputs({ in OpenGL ES or WebGL. @requires_webgl20 Transform feedback is not available in WebGL 1.0. -@anchor AbstractShaderProgram-rendering-workflow -## Rendering workflow +@section AbstractShaderProgram-rendering-workflow Rendering workflow Basic workflow with AbstractShaderProgram subclasses is: instance shader class, configure attribute binding in meshes (see @ref Mesh-configuration "Mesh documentation" @@ -409,7 +434,8 @@ for more information) and map shader outputs to framebuffer attachments if needed (see @ref Framebuffer-usage "Framebuffer documentation" for more information). In each draw event set all required shader parameters, bind specific framebuffer (if needed) and then call @ref Mesh::draw(). Example: -@code + +@code{.cpp} shader.setTransformation(transformation) .setProjection(projection) .setDiffuseTexture(diffuseTexture) @@ -418,15 +444,13 @@ shader.setTransformation(transformation) mesh.draw(shader); @endcode -@anchor AbstractShaderProgram-compute-workflow -## Compute workflow +@section AbstractShaderProgram-compute-workflow Compute workflow Add just the @ref Shader::Type::Compute shader and implement uniform/texture setting functions as needed. After setting up required parameters call @ref dispatchCompute(). -@anchor AbstractShaderProgram-types -## Mapping between GLSL and Magnum types +@section AbstractShaderProgram-types Mapping between GLSL and Magnum types See @ref types for more information, only types with GLSL equivalent can be used (and their super- or subclasses with the same size and underlying type). See @@ -458,8 +482,7 @@ also @ref Attribute::DataType enum for additional type options. @ref Matrix2x4, @ref Matrix4x2, @ref Matrix3x4 and @ref Matrix4x3) are not available in WebGL 1.0. -@anchor AbstractShaderProgram-performance-optimization -## Performance optimizations +@section AbstractShaderProgram-performance-optimization Performance optimizations The engine tracks currently used shader program to avoid unnecessary calls to @fn_gl{UseProgram}. Shader limits (such as @ref maxVertexAttributes()) are @@ -1024,7 +1047,7 @@ class MAGNUM_EXPORT AbstractShaderProgram: public AbstractObject { * @param name Uniform block name * * If given uniform block name is not found in the linked shader, a - * warning is printed and `0xffffffffu` is returned. + * warning is printed and @cpp 0xffffffffu @ce is returned. * @see @ref setUniformBlockBinding(), @fn_gl{GetUniformBlockIndex} * @requires_gl31 Extension @extension{ARB,uniform_buffer_object} * @requires_gles30 Uniform buffers are not available in OpenGL ES 2.0. diff --git a/src/Magnum/AbstractTexture.h b/src/Magnum/AbstractTexture.h index 2a0a9ba66..fc079600f 100644 --- a/src/Magnum/AbstractTexture.h +++ b/src/Magnum/AbstractTexture.h @@ -60,14 +60,13 @@ Encapsulates one OpenGL texture object. See @ref Texture, @ref TextureArray, @ref BufferTexture and @ref MultisampleTexture documentation for more information and usage examples. -## WebGL restrictions +@section AbstractTexture-webgl-restrictions WebGL restrictions @ref MAGNUM_TARGET_WEBGL "WebGL" puts some restrictions on type of data submitted to @ref Texture::setSubImage() "*Texture::setSubImage()", see its documentation for details. -@anchor AbstractTexture-performance-optimization -## Performance optimizations and security +@section AbstractTexture-performance-optimization Performance optimizations and security The engine tracks currently bound textures and images in all available texture units to avoid unnecessary calls to @fn_gl{ActiveTexture}, @fn_gl{BindTexture} diff --git a/src/Magnum/Context.h b/src/Magnum/Context.h index 8da8bee14..5fac9068f 100644 --- a/src/Magnum/Context.h +++ b/src/Magnum/Context.h @@ -448,7 +448,8 @@ class MAGNUM_EXPORT Context { * * Returns first supported OpenGL version from passed list. Convenient * equivalent to subsequent @ref isVersionSupported() calls, e.g.: - * @code + * + * @code{.cpp} * Version v = isVersionSupported(Version::GL330) ? Version::GL330 : Version::GL210; * Version v = supportedVersion({Version::GL330, Version::GL210}); * @endcode @@ -465,7 +466,8 @@ class MAGNUM_EXPORT Context { * * Extensions usable with this function are listed in @ref Extensions * namespace in header @ref Extensions.h. Example usage: - * @code + * + * @code{.cpp} * if(Context::current().isExtensionSupported()) { * // draw fancy detailed model * } else { @@ -488,7 +490,8 @@ class MAGNUM_EXPORT Context { * minimal required version of the extension is larger or equal to * @p version. Useful mainly in shader compilation when the decisions * depend on selected GLSL version, for example: - * @code + * + * @code{.cpp} * const Version version = Context::current()supportedVersion({Version::GL320, Version::GL300, Version::GL210}); * if(Context::current().isExtensionSupported(version)) { * // Called only if ARB_explicit_attrib_location is supported @@ -645,7 +648,8 @@ Useful for initial checks on availability of required features. By default, if assertion fails, an message is printed to error output and the application aborts. If `CORRADE_NO_ASSERT` is defined, this macro does nothing. Example usage: -@code + +@code{.cpp} MAGNUM_ASSERT_VERSION_SUPPORTED(Version::GL330); @endcode @@ -675,7 +679,8 @@ Useful for initial checks on availability of required features. By default, if assertion fails, an message is printed to error output and the application aborts. If `CORRADE_NO_ASSERT` is defined, this macro does nothing. Example usage: -@code + +@code{.cpp} MAGNUM_ASSERT_EXTENSION_SUPPORTED(Extensions::GL::ARB::geometry_shader4); @endcode diff --git a/src/Magnum/Framebuffer.h b/src/Magnum/Framebuffer.h index 28bca4b74..12415b680 100644 --- a/src/Magnum/Framebuffer.h +++ b/src/Magnum/Framebuffer.h @@ -47,8 +47,7 @@ Unlike @ref DefaultFramebuffer, which is used for on-screen rendering, this class is used for off-screen rendering, usable either in windowless applications, texture generation or for various post-processing effects. -@anchor Framebuffer-usage -## Example usage +@section Framebuffer-usage Example usage See @ref DefaultFramebuffer-usage "DefaultFramebuffer documentation" for introduction. Imagine you have shader with multiple outputs (e.g. for deferred @@ -56,7 +55,8 @@ rendering). You want to render them off-screen to textures and then use the textures for actual on-screen rendering. First you need to create the framebuffer with the same viewport as default framebuffer and attach textures and renderbuffers to desired outputs: -@code + +@code{.cpp} Framebuffer framebuffer({defaultFramebuffer.viewportPosition(), defaultFramebuffer.viewportSize()}); Texture2D color, normal; Renderbuffer depthStencil; @@ -70,7 +70,8 @@ framebuffer.attachRenderbuffer(Framebuffer::BufferAttachment::DepthStencil, dept Then you need to map outputs of your shader to color attachments in the framebuffer: -@code + +@code{.cpp} framebuffer.mapForDraw({{MyShader::ColorOutput, Framebuffer::ColorAttachment(0)}, {MyShader::NormalOutput, Framebuffer::ColorAttachment(1)}}); @endcode @@ -78,7 +79,8 @@ framebuffer.mapForDraw({{MyShader::ColorOutput, Framebuffer::ColorAttachment(0)} The actual @ref Platform::Sdl2Application::drawEvent() "drawEvent()" might look like this. First you clear all buffers you need, perform drawing to off-screen framebuffer, then bind the default and render the textures on screen: -@code + +@code{.cpp} void drawEvent() { defaultFramebuffer.clear(FramebufferClear::Color) framebuffer.clear(FramebufferClear::Color|FramebufferClear::Depth|FramebufferClear::Stencil); diff --git a/src/Magnum/RectangleTexture.h b/src/Magnum/RectangleTexture.h index 6641512be..c7defb549 100644 --- a/src/Magnum/RectangleTexture.h +++ b/src/Magnum/RectangleTexture.h @@ -59,7 +59,7 @@ texture.setMagnificationFilter(Sampler::Filter::Linear) .setSubImage({}, image); @endcode -In shader, the texture is used via sampler2DRect`, `sampler2DRectShadow`, +In shader, the texture is used via `sampler2DRect`, `sampler2DRectShadow`, `isampler2DRect` or `usampler2DRect`. See @ref AbstractShaderProgram documentation for more information about usage in shaders. diff --git a/src/Magnum/TransformFeedback.h b/src/Magnum/TransformFeedback.h index 9a6f6ea5d..e727052ea 100644 --- a/src/Magnum/TransformFeedback.h +++ b/src/Magnum/TransformFeedback.h @@ -400,7 +400,7 @@ class MAGNUM_EXPORT TransformFeedback: public AbstractObject { * * Ends transform feedback so the captured data can be used. * @see @ref begin(), @fn_gl{BindTransformFeedback} and - * @fn_gl{EndTransformFeedback} + * @fn_gl2{EndTransformFeedback,BeginTransformFeedback} */ void end(); diff --git a/src/Magnum/Version.h b/src/Magnum/Version.h index 25c8b1575..bb69ef48c 100644 --- a/src/Magnum/Version.h +++ b/src/Magnum/Version.h @@ -26,7 +26,7 @@ */ /** @file Version.h - * Enum @ref Magnum::Version, function @ref version() + * @brief Enum @ref Magnum::Version, function @ref version() */ #include