Magnum::Shaders::Phong class

Phong shader.

Uses ambient, diffuse and specular color or texture. For colored mesh you need to provide the Position and Normal attributes in your triangle mesh. By default, the shader renders the mesh with a white color in an identity transformation. Use setTransformationMatrix(), setNormalMatrix(), setProjectionMatrix(), setLightPosition() and others to configure the shader.

If you want to use textures, you need to provide also TextureCoordinates attribute. Pass appropriate Flags to constructor and then at render time don't forget to also call appropriate subset of bindAmbientTexture(), bindDiffuseTexture() and bindSpecularTexture() (or the combined bindTextures()). The texture is multipled by the color, which is by default set to fully opaque white for enabled textures.

Image

Example usage

Colored mesh

Common mesh setup:

struct Vertex {
    Vector3 position;
    Vector3 normal;
};
Vertex data[60]{
    // ...
};

GL::Buffer vertices;
vertices.setData(data, GL::BufferUsage::StaticDraw);

GL::Mesh mesh;
mesh.addVertexBuffer(vertices, 0,
    Shaders::Phong::Position{},
    Shaders::Phong::Normal{});

Common rendering setup:

Matrix4 transformationMatrix = Matrix4::translation(Vector3::zAxis(-5.0f));
Matrix4 projectionMatrix = Matrix4::perspectiveProjection(35.0_degf, 1.0f, 0.001f, 100.0f);

Shaders::Phong shader;
shader.setDiffuseColor(0x2f83cc_rgbf)
    .setShininess(200.0f)
    .setLightPosition({5.0f, 5.0f, 7.0f})
    .setTransformationMatrix(transformationMatrix)
    .setNormalMatrix(transformationMatrix.rotation())
    .setProjectionMatrix(projectionMatrix);

mesh.draw(shader);

Diffuse and specular texture

Common mesh setup:

struct Vertex {
    Vector3 position;
    Vector3 normal;
    Vector2 textureCoordinates;
};
Vertex data[60]{
    // ...
};

GL::Buffer vertices;
vertices.setData(data, GL::BufferUsage::StaticDraw);

GL::Mesh mesh;
mesh.addVertexBuffer(vertices, 0,
    Shaders::Phong::Position{},
    Shaders::Phong::Normal{},
    Shaders::Phong::TextureCoordinates{});

Common rendering setup:

Matrix4 transformationMatrix, projectionMatrix;
GL::Texture2D diffuseTexture, specularTexture;

Shaders::Phong shader{Shaders::Phong::Flag::DiffuseTexture|
                      Shaders::Phong::Flag::SpecularTexture};
shader.bindTextures(nullptr, &diffuseTexture, &specularTexture)
    .setLightPosition({5.0f, 5.0f, 7.0f})
    .setTransformationMatrix(transformationMatrix)
    .setNormalMatrix(transformationMatrix.rotation())
    .setProjectionMatrix(projectionMatrix);

mesh.draw(shader);

Alpha blending and masking

Enable Flag::AlphaMask and tune setAlphaMask() for simple binary alpha-masked drawing that doesn't require depth sorting or blending enabled. Note that this feature is implemented using the GLSL discard 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.

For general alpha-masked drawing you need to provide ambient texture with alpha channel and set alpha channel of diffuse/specular color to 0.0f so only ambient alpha will be taken into account. If you have diffuse texture combined with the alpha mask, you can use that texture for both ambient and diffuse part and then separate the alpha like this:

Shaders::Phong shader{Shaders::Phong::Flag::AmbientTexture|
                      Shaders::Phong::Flag::DiffuseTexture};
shader.bindTextures(&diffuseAlphaTexture, &diffuseAlphaTexture, nullptr)
    .setAmbientColor(0x000000ff_rgbaf)
    .setDiffuseColor(Color4{diffuseRgb, 0.0f})
    .setSpecularColor(Color4{specularRgb, 0.0f});

Base classes

class Magnum::GL::AbstractShaderProgram
Base for shader program implementations.

Public types

enum class Flag: UnsignedByte { AmbientTexture = 1 << 0, DiffuseTexture = 1 << 1, SpecularTexture = 1 << 2, AlphaMask = 1 << 3 }
Flag.
using Position = Generic3D::Position
Vertex position.
using Normal = Generic3D::Normal
Normal direction.
using TextureCoordinates = Generic3D::TextureCoordinates
2D texture coordinates
using Flags = Containers::EnumSet<Flag>
Flags.

Constructors, destructors, conversion operators

Phong(Flags flags = {}, UnsignedInt lightCount = 1) explicit
Constructor.
Phong(NoCreateT) explicit noexcept
Construct without creating the underlying OpenGL object.
Phong(const Phong&) deleted
Copying is not allowed.
Phong(Phong&&) noexcept defaulted
Move constructor.

Public functions

auto operator=(const Phong&) -> Phong& deleted
Copying is not allowed.
auto operator=(Phong&&) noexcept -> Phong& defaulted
Move assignment.
auto flags() const -> Flags
Flags.
auto lightCount() const -> UnsignedInt
Light count.
auto setAmbientColor(const Color4& color) -> Phong&
Set ambient color.
auto bindAmbientTexture(GL::Texture2D& texture) -> Phong&
Bind an ambient texture.
auto setAmbientTexture(GL::Texture2D& texture) -> Phong& deprecated
Bind an ambient texture.
auto setDiffuseColor(const Color4& color) -> Phong&
Set diffuse color.
auto bindDiffuseTexture(GL::Texture2D& texture) -> Phong&
Bind a diffuse texture.
auto setDiffuseTexture(GL::Texture2D& texture) -> Phong& deprecated
Bind a diffuse texture.
auto setSpecularColor(const Color4& color) -> Phong&
Set specular color.
auto bindSpecularTexture(GL::Texture2D& texture) -> Phong&
Bind a specular texture.
auto setSpecularTexture(GL::Texture2D& texture) -> Phong& deprecated
Bind a specular texture.
auto bindTextures(GL::Texture2D* ambient, GL::Texture2D* diffuse, GL::Texture2D* specular) -> Phong&
Bind textures.
auto setTextures(GL::Texture2D* ambient, GL::Texture2D* diffuse, GL::Texture2D* specular) -> Phong& deprecated
Bind textures.
auto setShininess(Float shininess) -> Phong&
Set shininess.
auto setAlphaMask(Float mask) -> Phong&
Set alpha mask value.
auto setTransformationMatrix(const Matrix4& matrix) -> Phong&
Set transformation matrix.
auto setNormalMatrix(const Matrix3x3& matrix) -> Phong&
Set normal matrix.
auto setProjectionMatrix(const Matrix4& matrix) -> Phong&
Set projection matrix.
auto setLightPositions(Containers::ArrayView<const Vector3> lights) -> Phong&
Set light positions.
auto setLightPositions(std::initializer_list<Vector3> lights) -> Phong&
auto setLightPosition(UnsignedInt id, const Vector3& position) -> Phong&
Set position for given light.
auto setLightPosition(const Vector3& position) -> Phong&
Set light position.
auto setLightColors(Containers::ArrayView<const Color4> colors) -> Phong&
Set light colors.
auto setLightColors(std::initializer_list<Color4> colors) -> Phong&
auto setLightColor(UnsignedInt id, const Color4& color) -> Phong&
Set position for given light.
auto setLightColor(const Color4& color) -> Phong&
Set light color.

Enum documentation

enum class Magnum::Shaders::Phong::Flag: UnsignedByte

Flag.

Enumerators
AmbientTexture

Multiply ambient color with a texture.

DiffuseTexture

Multiply diffuse color with a texture.

SpecularTexture

Multiply specular color with a texture.

AlphaMask

Enable alpha masking. If the combined fragment color has an alpha less than the value specified with setAlphaMask(), given fragment is discarded.

This uses the discard operation which is known to have considerable performance impact on some platforms. While useful for cheap alpha masking that doesn't require depth sorting, with proper depth sorting and blending you'll usually get much better performance and output quality.

Typedef documentation

typedef Generic3D::Position Magnum::Shaders::Phong::Position

Vertex position.

Generic attribute, Vector3.

typedef Generic3D::Normal Magnum::Shaders::Phong::Normal

Normal direction.

Generic attribute, Vector3.

typedef Generic3D::TextureCoordinates Magnum::Shaders::Phong::TextureCoordinates

2D texture coordinates

Generic attribute, Vector2, used only if at least one of Flag::AmbientTexture, Flag::DiffuseTexture and Flag::SpecularTexture is set.

typedef Containers::EnumSet<Flag> Magnum::Shaders::Phong::Flags

Flags.

Function documentation

Magnum::Shaders::Phong::Phong(Flags flags = {}, UnsignedInt lightCount = 1) explicit

Constructor.

Parameters
flags Flags
lightCount Count of light sources

Magnum::Shaders::Phong::Phong(NoCreateT) explicit noexcept

Construct without creating the underlying OpenGL object.

The constructed instance is equivalent to moved-from state. Useful in cases where you will overwrite the instance later anyway. Move another object over it to make it useful.

This function can be safely used for constructing (and later destructing) objects even without any OpenGL context being active.

Phong& Magnum::Shaders::Phong::setAmbientColor(const Color4& color)

Set ambient color.

Returns Reference to self (for method chaining)

If Flag::AmbientTexture is set, default value is 0xffffffff_rgbaf and the color will be multiplied with ambient texture, otherwise default value is 0x00000000_rgbaf.

Phong& Magnum::Shaders::Phong::bindAmbientTexture(GL::Texture2D& texture)

Bind an ambient texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::AmbientTexture enabled.

Phong& Magnum::Shaders::Phong::setAmbientTexture(GL::Texture2D& texture)

Bind an ambient texture.

Phong& Magnum::Shaders::Phong::setDiffuseColor(const Color4& color)

Set diffuse color.

Returns Reference to self (for method chaining)

Initial value is 0xffffffff_rgbaf.

Phong& Magnum::Shaders::Phong::bindDiffuseTexture(GL::Texture2D& texture)

Bind a diffuse texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::DiffuseTexture enabled.

Phong& Magnum::Shaders::Phong::setDiffuseTexture(GL::Texture2D& texture)

Bind a diffuse texture.

Phong& Magnum::Shaders::Phong::setSpecularColor(const Color4& color)

Set specular color.

Returns Reference to self (for method chaining)

Initial value is 0xffffffff_rgbaf. Color will be multiplied with specular texture if Flag::SpecularTexture is set. If you want to have a fully diffuse material, set specular color to 0x000000ff_rgbaf.

Phong& Magnum::Shaders::Phong::bindSpecularTexture(GL::Texture2D& texture)

Bind a specular texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::SpecularTexture enabled.

Phong& Magnum::Shaders::Phong::setSpecularTexture(GL::Texture2D& texture)

Bind a specular texture.

Phong& Magnum::Shaders::Phong::bindTextures(GL::Texture2D* ambient, GL::Texture2D* diffuse, GL::Texture2D* specular)

Bind textures.

Returns Reference to self (for method chaining)

A particular texture has effect only if particular texture flag from Flag is set, you can use nullptr for the rest. Expects that the shader was created with at least one of Flag::AmbientTexture, Flag::DiffuseTexture or Flag::SpecularTexture enabled. More efficient than setting each texture separately.

Phong& Magnum::Shaders::Phong::setTextures(GL::Texture2D* ambient, GL::Texture2D* diffuse, GL::Texture2D* specular)

Bind textures.

Phong& Magnum::Shaders::Phong::setShininess(Float shininess)

Set shininess.

Returns Reference to self (for method chaining)

The larger value, the harder surface (smaller specular highlight). Initial value is 80.0f.

Phong& Magnum::Shaders::Phong::setAlphaMask(Float mask)

Set alpha mask value.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::AlphaMask enabled. Fragments with alpha values smaller than the mask value will be discarded. Initial value is 0.5f. See the flag documentation for further information.

Phong& Magnum::Shaders::Phong::setTransformationMatrix(const Matrix4& matrix)

Set transformation matrix.

Returns Reference to self (for method chaining)

You need to set also setNormalMatrix() with a corresponding value. Initial value is an identity matrix.

Phong& Magnum::Shaders::Phong::setNormalMatrix(const Matrix3x3& matrix)

Set normal matrix.

Returns Reference to self (for method chaining)

The matrix doesn't need to be normalized, as the renormalization must be done in the shader anyway. You need to set also setTransformationMatrix() with a corresponding value. Initial value is an identity matrix.

Phong& Magnum::Shaders::Phong::setProjectionMatrix(const Matrix4& matrix)

Set projection matrix.

Returns Reference to self (for method chaining)

Initial value is an identity matrix (i.e., an orthographic projection of the default $ [ -\boldsymbol{1} ; \boldsymbol{1} ] $ cube).

Phong& Magnum::Shaders::Phong::setLightPositions(Containers::ArrayView<const Vector3> lights)

Set light positions.

Returns Reference to self (for method chaining)

Initial values are zero vectors — that will in most cases cause the object to be rendered black (or in the ambient color), as the lights are is inside of it. Expects that the size of the lights array is the same as lightCount().

Phong& Magnum::Shaders::Phong::setLightPositions(std::initializer_list<Vector3> lights)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Phong& Magnum::Shaders::Phong::setLightPosition(UnsignedInt id, const Vector3& position)

Set position for given light.

Returns Reference to self (for method chaining)

Unlike setLightPosition() updates just a single light position. Expects that id is less than lightCount().

Phong& Magnum::Shaders::Phong::setLightPosition(const Vector3& position)

Set light position.

Returns Reference to self (for method chaining)

Convenience alternative to setLightPositions() when there is just one light.

Phong& Magnum::Shaders::Phong::setLightColors(Containers::ArrayView<const Color4> colors)

Set light colors.

Returns Reference to self (for method chaining)

Initial values are 0xffffffff_rgbaf. Expects that the size of the colors array is the same as lightCount().

Phong& Magnum::Shaders::Phong::setLightColors(std::initializer_list<Color4> colors)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Phong& Magnum::Shaders::Phong::setLightColor(UnsignedInt id, const Color4& color)

Set position for given light.

Returns Reference to self (for method chaining)

Unlike setLightColors() updates just a single light color. Expects that id is less than lightCount().

Phong& Magnum::Shaders::Phong::setLightColor(const Color4& color)

Set light color.

Returns Reference to self (for method chaining)

Convenience alternative to setLightColors() when there is just one light.

Debug& operator<<(Debug& debug, Phong::Flag value)

Debug output operator.

Debug& operator<<(Debug& debug, Phong::Flags value)

Debug output operator.