ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Shaders: reorganize the Flat and Phong docs. 

Dry blabber followed by dry code is worse than those two interleaved.
pull/433/head
Vladimír Vondruš 6 years ago
parent
638f96f099
commit
e6010388c3
3 changed files with 40 additions and 48 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 4
      doc/shaders.dox
  2. 46
      src/Magnum/Shaders/Flat.h
  3. 38
      src/Magnum/Shaders/Phong.h

4
doc/shaders.dox
Unescape View File

@ -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 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 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 @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 what's done in Flat shader's @ref Shaders-Flat-object-id but using the generic
generic definitions would look like this: definitions would look like this:
@snippet MagnumShaders.cpp shaders-generic-object-id @snippet MagnumShaders.cpp shaders-generic-object-id
*/ */

46
src/Magnum/Shaders/Flat.h
Unescape View File

@ -59,24 +59,9 @@ shader renders the mesh with a white color in an identity transformation.
Use @ref setTransformationProjectionMatrix(), @ref setColor() and others to Use @ref setTransformationProjectionMatrix(), @ref setColor() and others to
configure the shader. 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 @image html shaders-flat.png width=256px
For coloring the texture based on intensity you can use the @ref Vector shader. @section Shaders-Flat-colored Colored rendering
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
Common mesh setup: Common mesh setup:
@ -86,9 +71,13 @@ Common rendering setup:
@snippet MagnumShaders.cpp Flat-usage-colored2 @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 @snippet MagnumShaders.cpp Flat-usage-textured1
@ -96,7 +85,14 @@ Common rendering setup:
@snippet MagnumShaders.cpp Flat-usage-textured2 @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 Enable @ref Flag::AlphaMask and tune @ref setAlphaMask() for simple
binary alpha-masked drawing that doesn't require depth sorting or blending 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 platforms. With proper depth sorting and blending you'll usually get much
better performance and output quality. 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 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 other annotation purposes. Enable it using @ref Flag::ObjectId and set up an
@ -194,7 +190,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab
* present only if @ref Flag::ObjectId is set. Expects a * present only if @ref Flag::ObjectId is set. Expects a
* single-component unsigned integral attachment. Writes the value * single-component unsigned integral attachment. Writes the value
* set in @ref setObjectId() there, see * 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 * @requires_gles30 Object ID output requires integer buffer
* attachments, which are not available in OpenGL ES 2.0 or * attachments, which are not available in OpenGL ES 2.0 or
* WebGL 1.0. * WebGL 1.0.
@ -247,8 +243,8 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab
#ifndef MAGNUM_TARGET_GLES2 #ifndef MAGNUM_TARGET_GLES2
/** /**
* Enable object ID output. See @ref Shaders-Flat-usage-object-id * Enable object ID output. See @ref Shaders-Flat-object-id for
* for more information. * more information.
* @requires_gles30 Object ID output requires integer buffer * @requires_gles30 Object ID output requires integer buffer
* attachments, which are not available in OpenGL ES 2.0 or * attachments, which are not available in OpenGL ES 2.0 or
* WebGL 1.0. * WebGL 1.0.
@ -261,7 +257,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab
* object ID from the @ref ObjectId attribute, outputting a sum of * object ID from the @ref ObjectId attribute, outputting a sum of
* the per-vertex ID and ID coming from @ref setObjectId(). * the per-vertex ID and ID coming from @ref setObjectId().
* Implicitly enables @ref Flag::ObjectId. See * 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 * @requires_gles30 Object ID output requires integer buffer
* attachments, which are not available in OpenGL ES 2.0 or * attachments, which are not available in OpenGL ES 2.0 or
* WebGL 1.0. * WebGL 1.0.
@ -378,7 +374,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab
* *
* Expects that the shader was created with @ref Flag::ObjectId * Expects that the shader was created with @ref Flag::ObjectId
* enabled. Value set here is written to the @ref ObjectIdOutput, see * 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 * @cpp 0 @ce. If @ref Flag::InstancedObjectId is enabled as well, this
* value is combined with ID coming from the @ref ObjectId attribute. * value is combined with ID coming from the @ref ObjectId attribute.
* @requires_gles30 Object ID output requires integer buffer * @requires_gles30 Object ID output requires integer buffer

38
src/Magnum/Shaders/Phong.h
Unescape View File

@ -45,19 +45,9 @@ transformation. Use @ref setTransformationMatrix(), @ref setNormalMatrix(),
@ref setProjectionMatrix(), @ref setLightPosition() and others to configure @ref setProjectionMatrix(), @ref setLightPosition() and others to configure
the shader. 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 @image html shaders-phong.png width=256px
@section Shaders-Phong-usage Example usage @section Shaders-Phong-colored Colored rendering
@subsection Shaders-Phong-usage-colored Colored mesh
Common mesh setup: Common mesh setup:
@ -67,9 +57,15 @@ Common rendering setup:
@snippet MagnumShaders.cpp Phong-usage-colored2 @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 @snippet MagnumShaders.cpp Phong-usage-texture1
@ -77,7 +73,7 @@ Common rendering setup:
@snippet MagnumShaders.cpp Phong-usage-texture2 @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 Enable @ref Flag::AlphaMask and tune @ref setAlphaMask() for simple
binary alpha-masked drawing that doesn't require depth sorting or blending 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 @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 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 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(). 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 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 @ref Shaders-Flat-object-id "its documentation" for more information and usage
usage example. example.
@requires_gles30 Object ID output requires integer buffer attachments, which @requires_gles30 Object ID output requires integer buffer attachments, which
are not available in OpenGL ES 2.0 or WebGL 1.0. 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 * present only if @ref Flag::ObjectId is set. Expects a
* single-component unsigned integral attachment. Writes the value * single-component unsigned integral attachment. Writes the value
* set in @ref setObjectId() there, see * 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 * @requires_gles30 Object ID output requires integer buffer
* attachments, which are not available in OpenGL ES 2.0 or * attachments, which are not available in OpenGL ES 2.0 or
* WebGL 1.0. * WebGL 1.0.
@ -282,7 +278,7 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram {
#ifndef MAGNUM_TARGET_GLES2 #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. * for more information.
* @requires_gles30 Object ID output requires integer buffer * @requires_gles30 Object ID output requires integer buffer
* attachments, which are not available in OpenGL ES 2.0 or * 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 * object ID from the @ref ObjectId attribute, outputting a sum of
* the per-vertex ID and ID coming from @ref setObjectId(). * the per-vertex ID and ID coming from @ref setObjectId().
* Implicitly enables @ref Flag::ObjectId. See * 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 * @requires_gles30 Object ID output requires integer buffer
* attachments, which are not available in OpenGL ES 2.0 or * attachments, which are not available in OpenGL ES 2.0 or
* WebGL 1.0. * 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 * Expects that the shader was created with @ref Flag::ObjectId
* enabled. Value set here is written to the @ref ObjectIdOutput, see * 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. * @cpp 0 @ce.
* @requires_gles30 Object ID output requires integer buffer * @requires_gles30 Object ID output requires integer buffer
* attachments, which are not available in OpenGL ES 2.0 or WebGL * attachments, which are not available in OpenGL ES 2.0 or WebGL

Write Preview
Loading…
Cancel
Save