diff --git a/doc/shaders.dox b/doc/shaders.dox index 48e5891a7..f2add45c4 100644 --- a/doc/shaders.dox +++ b/doc/shaders.dox @@ -99,8 +99,8 @@ Besides vertex attributes, the @ref Shaders::Generic contains generic definitions for framebuffer outputs as well --- in many cases a shader has just one (color) output, but some shaders such as @ref Shaders::Flat or @ref Shaders::Phong offer an object ID output as well. A setup equivalent to -what's done in Flat shader's @ref Shaders-Flat-usage-object-id but using the -generic definitions would look like this: +what's done in Flat shader's @ref Shaders-Flat-object-id but using the generic +definitions would look like this: @snippet MagnumShaders.cpp shaders-generic-object-id */ diff --git a/src/Magnum/Shaders/Flat.h b/src/Magnum/Shaders/Flat.h index ab4618bdc..e8a2158f2 100644 --- a/src/Magnum/Shaders/Flat.h +++ b/src/Magnum/Shaders/Flat.h @@ -59,24 +59,9 @@ shader renders the mesh with a white color in an identity transformation. Use @ref setTransformationProjectionMatrix(), @ref setColor() and others to configure the shader. -If you want to use a texture, you need to provide also the -@ref TextureCoordinates attribute. Pass @ref Flag::Textured to the constructor -and then at render time don't forget to bind also the texture via -@ref bindTexture(). The texture is multipled by the color, which is by default -set to @cpp 0xffffffff_rgbaf @ce. - @image html shaders-flat.png width=256px -For coloring the texture based on intensity you can use the @ref Vector shader. -The 3D version of this shader is equivalent to @ref Phong with zero lights, -however this implementation is much simpler and thus likely also faster. See -@ref Shaders-Phong-zero-lights "its documentation" for more information. -Conversely, enabling @ref Flag::VertexColor and using a default color with no -texturing makes this shader equivalent to @ref VertexColor. - -@section Shaders-Flat-usage Example usage - -@subsection Shaders-Flat-usage-colored Colored mesh +@section Shaders-Flat-colored Colored rendering Common mesh setup: @@ -86,9 +71,13 @@ Common rendering setup: @snippet MagnumShaders.cpp Flat-usage-colored2 -@subsection Shaders-Flat-usage-textured Textured mesh +@section Shaders-Flat-textured Textured rendering -Common mesh setup: +If you want to use a texture, you need to provide also the +@ref TextureCoordinates attribute. Pass @ref Flag::Textured to the constructor +and then at render time don't forget to bind also the texture via +@ref bindTexture(). The texture is multipled by the color, which is by default +set to @cpp 0xffffffff_rgbaf @ce. Common mesh setup: @snippet MagnumShaders.cpp Flat-usage-textured1 @@ -96,7 +85,14 @@ Common rendering setup: @snippet MagnumShaders.cpp Flat-usage-textured2 -@subsection Shaders-Flat-usage-alpha Alpha blending and masking +For coloring the texture based on intensity you can use the @ref Vector shader. +The 3D version of this shader is equivalent to @ref Phong with zero lights, +however this implementation is much simpler and thus likely also faster. See +@ref Shaders-Phong-zero-lights "its documentation" for more information. +Conversely, enabling @ref Flag::VertexColor and using a default color with no +texturing makes this shader equivalent to @ref VertexColor. + +@section Shaders-Flat-alpha Alpha blending and masking Enable @ref Flag::AlphaMask and tune @ref setAlphaMask() for simple binary alpha-masked drawing that doesn't require depth sorting or blending @@ -105,7 +101,7 @@ operation which is known to have considerable performance impact on some platforms. With proper depth sorting and blending you'll usually get much better performance and output quality. -@subsection Shaders-Flat-usage-object-id Object ID output +@section Shaders-Flat-object-id Object ID output The shader supports writing object ID to the framebuffer for object picking or other annotation purposes. Enable it using @ref Flag::ObjectId and set up an @@ -194,7 +190,7 @@ template class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab * present only if @ref Flag::ObjectId is set. Expects a * single-component unsigned integral attachment. Writes the value * set in @ref setObjectId() there, see - * @ref Shaders-Phong-usage-object-id for more information. + * @ref Shaders-Phong-object-id for more information. * @requires_gles30 Object ID output requires integer buffer * attachments, which are not available in OpenGL ES 2.0 or * WebGL 1.0. @@ -247,8 +243,8 @@ template class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab #ifndef MAGNUM_TARGET_GLES2 /** - * Enable object ID output. See @ref Shaders-Flat-usage-object-id - * for more information. + * Enable object ID output. See @ref Shaders-Flat-object-id for + * more information. * @requires_gles30 Object ID output requires integer buffer * attachments, which are not available in OpenGL ES 2.0 or * WebGL 1.0. @@ -261,7 +257,7 @@ template class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab * object ID from the @ref ObjectId attribute, outputting a sum of * the per-vertex ID and ID coming from @ref setObjectId(). * Implicitly enables @ref Flag::ObjectId. See - * @ref Shaders-Flat-usage-object-id for more information. + * @ref Shaders-Flat-object-id for more information. * @requires_gles30 Object ID output requires integer buffer * attachments, which are not available in OpenGL ES 2.0 or * WebGL 1.0. @@ -378,7 +374,7 @@ template class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab * * Expects that the shader was created with @ref Flag::ObjectId * enabled. Value set here is written to the @ref ObjectIdOutput, see - * @ref Shaders-Flat-usage-object-id for more information. Default is + * @ref Shaders-Flat-object-id for more information. Default is * @cpp 0 @ce. If @ref Flag::InstancedObjectId is enabled as well, this * value is combined with ID coming from the @ref ObjectId attribute. * @requires_gles30 Object ID output requires integer buffer diff --git a/src/Magnum/Shaders/Phong.h b/src/Magnum/Shaders/Phong.h index ff1537a77..33fc31df7 100644 --- a/src/Magnum/Shaders/Phong.h +++ b/src/Magnum/Shaders/Phong.h @@ -45,19 +45,9 @@ transformation. Use @ref setTransformationMatrix(), @ref setNormalMatrix(), @ref setProjectionMatrix(), @ref setLightPosition() and others to configure the shader. -If you want to use textures, you need to provide also the -@ref TextureCoordinates attribute. Pass appropriate @ref Flag combination to -the constructor and then at render time don't forget to also call appropriate -subset of @ref bindAmbientTexture(), @ref bindDiffuseTexture() and -@ref bindSpecularTexture() (or the combined @ref bindTextures()). The texture -is multipled by the color, which is by default set to fully opaque white for -enabled textures. - @image html shaders-phong.png width=256px -@section Shaders-Phong-usage Example usage - -@subsection Shaders-Phong-usage-colored Colored mesh +@section Shaders-Phong-colored Colored rendering Common mesh setup: @@ -67,9 +57,15 @@ Common rendering setup: @snippet MagnumShaders.cpp Phong-usage-colored2 -@subsection Shaders-Phong-usage-texture Diffuse and specular texture +@section Shaders-Phong-texture Textured rendering -Common mesh setup: +If you want to use textures, you need to provide also the +@ref TextureCoordinates attribute. Pass appropriate @ref Flag combination to +the constructor and then at render time don't forget to also call appropriate +subset of @ref bindAmbientTexture(), @ref bindDiffuseTexture() and +@ref bindSpecularTexture() (or the combined @ref bindTextures()). The texture +is multipled by the color, which is by default set to fully opaque white for +enabled textures. Mesh setup with a diffuse and a specular texture: @snippet MagnumShaders.cpp Phong-usage-texture1 @@ -77,7 +73,7 @@ Common rendering setup: @snippet MagnumShaders.cpp Phong-usage-texture2 -@subsection Shaders-Phong-usage-alpha Alpha blending and masking +@section Shaders-Phong-alpha Alpha blending and masking Enable @ref Flag::AlphaMask and tune @ref setAlphaMask() for simple binary alpha-masked drawing that doesn't require depth sorting or blending @@ -94,7 +90,7 @@ diffuse part and then separate the alpha like this: @snippet MagnumShaders.cpp Phong-usage-alpha -@subsection Shaders-Phong-usage-object-id Object ID output +@section Shaders-Phong-object-id Object ID output The shader supports writing object ID to the framebuffer for object picking or other annotation purposes. Enable it using @ref Flag::ObjectId and set up an @@ -104,8 +100,8 @@ and supply per-vertex IDs to the @ref ObjectId attribute. The output will contain a sum of the per-vertex ID and ID coming from @ref setObjectId(). The functionality is practically the same as in the @ref Flat shader, see -@ref Shaders-Flat-usage-object-id "its documentation" for more information and -usage example. +@ref Shaders-Flat-object-id "its documentation" for more information and usage +example. @requires_gles30 Object ID output requires integer buffer attachments, which are not available in OpenGL ES 2.0 or WebGL 1.0. @@ -208,7 +204,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram { * present only if @ref Flag::ObjectId is set. Expects a * single-component unsigned integral attachment. Writes the value * set in @ref setObjectId() there, see - * @ref Shaders-Phong-usage-object-id for more information. + * @ref Shaders-Phong-object-id for more information. * @requires_gles30 Object ID output requires integer buffer * attachments, which are not available in OpenGL ES 2.0 or * WebGL 1.0. @@ -282,7 +278,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram { #ifndef MAGNUM_TARGET_GLES2 /** - * Enable object ID output. See @ref Shaders-Phong-usage-object-id + * Enable object ID output. See @ref Shaders-Phong-object-id * for more information. * @requires_gles30 Object ID output requires integer buffer * attachments, which are not available in OpenGL ES 2.0 or @@ -296,7 +292,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram { * object ID from the @ref ObjectId attribute, outputting a sum of * the per-vertex ID and ID coming from @ref setObjectId(). * Implicitly enables @ref Flag::ObjectId. See - * @ref Shaders-Phong-usage-object-id for more information. + * @ref Shaders-Phong-object-id for more information. * @requires_gles30 Object ID output requires integer buffer * attachments, which are not available in OpenGL ES 2.0 or * WebGL 1.0. @@ -481,7 +477,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram { * * Expects that the shader was created with @ref Flag::ObjectId * enabled. Value set here is written to the @ref ObjectIdOutput, see - * @ref Shaders-Phong-usage-object-id for more information. Default is + * @ref Shaders-Phong-object-id for more information. Default is * @cpp 0 @ce. * @requires_gles30 Object ID output requires integer buffer * attachments, which are not available in OpenGL ES 2.0 or WebGL