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
Split 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
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
*/

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
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<UnsignedInt dimensions> 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<UnsignedInt dimensions> 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<UnsignedInt dimensions> 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<UnsignedInt dimensions> 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

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
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

Write Preview
Loading…
Cancel
Save