Magnum::Shaders::PhongGL class new in Git master
#include <Magnum/Shaders/PhongGL.h>

Phong OpenGL shader.

Uses ambient, diffuse and specular color or texture. For a 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 setProjectionMatrix(). setTransformationMatrix(), setNormalMatrix(), setLightPosition() and others to configure the shader.

Image

Colored rendering

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::PhongGL::Position{},
    Shaders::PhongGL::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::PhongGL shader;
shader.setDiffuseColor(0x2f83cc_rgbf)
    .setShininess(200.0f)
    .setTransformationMatrix(transformationMatrix)
    .setNormalMatrix(transformationMatrix.normalMatrix())
    .setProjectionMatrix(projectionMatrix)
    .draw(mesh);

Textured rendering

If you want to use textures, you need to provide also the TextureCoordinates attribute. Pass appropriate Flag combination to Configuration::setFlags() 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 multiplied by the color, which is by default set to fully opaque white for enabled textures. Mesh setup with a diffuse and a specular texture:

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::PhongGL::Position{},
    Shaders::PhongGL::Normal{},
    Shaders::PhongGL::TextureCoordinates{});

Common rendering setup:

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

Shaders::PhongGL shader{Shaders::PhongGL::Configuration{}
    .setFlags(Shaders::PhongGL::Flag::DiffuseTexture|
              Shaders::PhongGL::Flag::SpecularTexture)};
shader.bindTextures(nullptr, &diffuseTexture, &specularTexture, nullptr)
    .setTransformationMatrix(transformationMatrix)
    .setNormalMatrix(transformationMatrix.normalMatrix())
    .setProjectionMatrix(projectionMatrix)
    .draw(mesh);

Light specification

By default, the shader provides a single directional "fill" light, coming from the center of the camera. With Configuration::setLightCount() you can specify how many lights you want, and then control light parameters using setLightPositions(), setLightColors(), setLightSpecularColors() and setLightRanges(). Light positions are specified as four-component vectors, the last component distinguishing between directional and point lights.

  • Point lights are specified with camera-relative position and the last component set to 1.0f together with setLightRanges() describing the attenuation. The range corresponds to the Trade::LightData::range() and the attenuation is calculated as the following — see Attenuation calculation for more information:

    \[ F_{att} = \frac{\operatorname{clamp}(1 - (\frac{d}{\color{m-info} R})^4, 0, 1)^2}{1 + d^2} \]

    If you use Constants::inf() as a range (which is also the default), the equation reduces down to a simple inverse square:

    \[ F_{att} = \lim_{{\color{m-info} R} \to \infty} \frac{{\color{m-dim} \operatorname{clamp}(} 1 \mathbin{\color{m-dim} -} {\color{m-dim} (\frac{d}{R})^4, 0, 1)^2}}{1 + d^2} = \frac{1}{1 + d^2} \]

  • Directional lights are specified with a camera-relative direction to the light with the last component set to 0.0f — which effectively makes $ d = 0 $ — and are not affected by values from setLightRanges() in any way:

    \[ F_{att} = \lim_{d \to 0} \frac{{\color{m-dim} \operatorname{clamp}(} 1 \mathbin{\color{m-dim} -} {\color{m-dim} (\frac{d}{R})^4, 0, 1)^2}}{1 \mathbin{\color{m-dim} +} {\color{m-dim} d^2}} = 1 \]

Light color and intensity, corresponding to Trade::LightData::color() and Trade::LightData::intensity(), is meant to be multiplied together and passed to setLightColors() and setLightSpecularColors().

The following example shows a three-light setup with one dim directional light shining from the top and two stronger but range-limited point lights:

Matrix4 directionalLight, pointLight1, pointLight2; // camera-relative

Shaders::PhongGL shader{Shaders::PhongGL::Configuration{}
    .setLightCount(3)};
shader
    .setLightPositions({Vector4{directionalLight.up(), 0.0f},
                        Vector4{pointLight1.translation(), 1.0f},
                        Vector4{pointLight2.translation(), 1.0f}})
    .setLightColors({0xf0f0ff_srgbf*0.1f,
                     0xff8080_srgbf*10.0f,
                     0x80ff80_srgbf*10.0f})
    .setLightColors(…)
    .setLightRanges({Constants::inf(),
                     2.0f,
                     2.0f});

Ambient lights

In order to avoid redundant uniform inputs, there's no dedicated way to specify ambient lights. Instead, they are handled by the ambient color input, as the math for ambient color and lights is equivalent. Add the ambient colors together and reuse the diffuse texture in the bindAmbientTexture() slot to have it affected by the ambient as well:

Trade::LightData ambientLight = …;

Shaders::PhongGL shader{Shaders::PhongGL::Configuration{}
    .setFlags(Shaders::PhongGL::Flag::AmbientTexture|…)};
shader
    .setAmbientColor(ambientColor + ambientLight.color()*ambientLight.intensity())
    .bindAmbientTexture(diffuseTexture)
    .bindDiffuseTexture(diffuseTexture);

Zero lights

As a special case, creating this shader with zero lights makes its output equivalent to the FlatGL3D shader — only setAmbientColor() and bindAmbientTexture() (if Flag::AmbientTexture is enabled) are taken into account, which corresponds to FlatGL::setColor() and FlatGL::bindTexture(). This is useful to reduce complexity in apps that render models with pre-baked lights. For instanced workflows using zero lights means the NormalMatrix instance attribute doesn't need to be supplied either. In addition, enabling Flag::VertexColor and using a default ambient color with no texturing makes this shader equivalent to VertexColorGL.

Alpha blending and masking

Alpha / transparency is supported by the shader implicitly, but to have it working on the framebuffer, you need to enable GL::Renderer::Feature::Blending and set up the blending function. See GL::Renderer::setBlendFunction() for details.

To avoid specular highlights on transparent areas, specular alpha should be always set to 0.0f. On the other hand, non-zero specular alpha can be for example used to render transparent materials which are still expected to have specular highlights such as glass or soap bubbles.

An alternative is to 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 an ambient texture with alpha channel and set alpha channel of the diffuse/specular color to 0.0f so only ambient alpha will be taken into account. If you have a 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::PhongGL shader{Shaders::PhongGL::Configuration{}
    .setFlags(Shaders::PhongGL::Flag::AmbientTexture|
              Shaders::PhongGL::Flag::DiffuseTexture)};
shader.bindTextures(&diffuseAlphaTexture, &diffuseAlphaTexture, nullptr, nullptr)
    .setAmbientColor(0x000000ff_rgbaf)
    .setDiffuseColor(Color4{diffuseRgb, 0.0f})
    .setSpecularColor(Color4{specularRgb, 0.0f});

Normal mapping

If you want to use normal textures, enable Flag::NormalTexture and call bindNormalTexture(). In addition you need to supply per-vertex tangent and bitangent direction:

If you supply just a three-component Tangent attribute and no bitangents, the shader will implicitly assume the fourth component to be 1.0f, forming a right-handed tangent space. This is a valid optimization when you have full control over the bitangent orientation, but won't work with general meshes.

The strength of the effect can be controlled by setNormalTextureScale(). See Trade::MaterialAttribute::NormalTextureScale for a description of the factor is used.

Object ID output

The shader supports writing object ID to the framebuffer for object picking or other annotation purposes. Enable it using Flag::ObjectId and set up an integer buffer attached to the ObjectIdOutput attachment. If you have a batch of meshes with different object IDs, enable Flag::InstancedObjectId and supply per-vertex IDs to the ObjectId attribute. The object ID can be also supplied from an integer texture bound via bindObjectIdTexture() if Flag::ObjectIdTexture is enabled. The output will contain a sum of the per-vertex ID, texture ID and ID coming from setObjectId().

The functionality is practically the same as in the FlatGL shader, see its documentation for more information and usage example.

Skinning

To render skinned meshes, bind up to two sets of up to four-component joint ID and weight attributes to JointIds / SecondaryJointIds and Weights / SecondaryWeights, set an appropriate joint count and per-vertex primary and secondary joint count in Configuration::setJointCount() and upload appropriate joint matrices with setJointMatrices(). The usage is similar for all shaders, see Skinning for an example.

To avoid having to compile multiple shader variants for different joint matrix counts, set the maximum used joint count in Configuration::setJointCount() and then upload just a prefix via setJointMatrices(). Similarly, to avoid multiple variants for different per-vertex joint counts, enable Flag::DynamicPerVertexJointCount, set the maximum per-vertex joint count in Configuration::setJointCount() and then adjust the actual per-draw joint count with setPerVertexJointCount().

Instanced rendering

Enabling Flag::InstancedTransformation will turn the shader into an instanced one. It'll take per-instance transformation and normal matrix from the TransformationMatrix and NormalMatrix attributes, applying those before the matrix set by setTransformationMatrix() and setNormalMatrix(). Besides that, Flag::VertexColor (and the Color3 / Color4) attributes can work as both per-vertex and per-instance, and for texturing it's possible to have per-instance texture offset taken from TextureOffset when Flag::InstancedTextureOffset is enabled (similarly to transformation, applied before setTextureMatrix()). The snippet below shows adding a buffer with per-instance transformation to a mesh — note how a normal matrix attribute has to be populated and supplied as well to ensure lighting works:

struct {
    Matrix4 transformation;
    Matrix3x3 normal;
} instanceData[] {
    {Matrix4::translation({1.0f, 2.0f, 0.0f})*Matrix4::rotationX(90.0_degf), {}},
    {Matrix4::translation({2.0f, 1.0f, 0.0f})*Matrix4::rotationY(90.0_degf), {}},
    {Matrix4::translation({3.0f, 0.0f, 1.0f})*Matrix4::rotationZ(90.0_degf), {}},
    // ...
};
for(auto& instance: instanceData)
    instance.normal = instance.transformation.normalMatrix();

mesh.setInstanceCount(Containers::arraySize(instanceData))
    .addVertexBufferInstanced(GL::Buffer{instanceData}, 1, 0,
        Shaders::PhongGL::TransformationMatrix{},
        Shaders::PhongGL::NormalMatrix{});

For instanced skinning the joint buffer is assumed to contain joint transformations for all instances. By default all instances use the same joint transformations, seting setPerInstanceJointCount() will cause the shader to offset the per-vertex joint IDs with gl_InstanceID*perInstanceJointCount.

Uniform buffers

See Using uniform buffers for a high-level overview that applies to all shaders. In this particular case, the shader needs a separate ProjectionUniform3D and TransformationUniform3D buffer bound with bindProjectionBuffer() and bindTransformationBuffer(), respectively, lights are supplied via a PhongLightUniform buffer bound with bindLightBuffer(). To maximize use of the limited uniform buffer memory, materials are supplied separately in a PhongMaterialUniform buffer bound with bindMaterialBuffer() and then referenced via materialId from a PhongDrawUniform bound with bindDrawBuffer(); for optional texture transformation a per-draw TextureTransformationUniform buffer bound with bindTextureTransformationBuffer() can be supplied as well. A uniform buffer setup equivalent to the colored case at the top, with one default light, would look like this:

GL::Buffer projectionUniform, lightUniform, materialUniform,
    transformationUniform, drawUniform;
projectionUniform.setData({
    Shaders::ProjectionUniform3D{}
        .setProjectionMatrix(projectionMatrix)
});
lightUniform.setData({
    Shaders::PhongLightUniform{}
});
materialUniform.setData({
    Shaders::PhongMaterialUniform{}
        .setDiffuseColor(0x2f83cc_rgbf)
        .setShininess(200.0f)
});
transformationUniform.setData({
    Shaders::TransformationUniform3D{}
        .setTransformationMatrix(transformationMatrix)
});
drawUniform.setData({
    Shaders::PhongDrawUniform{}
        .setNormalMatrix(transformationMatrix.normalMatrix())
        .setMaterialId(0)
});

Shaders::PhongGL shader{Shaders::PhongGL::Configuration{}
    .setFlags(Shaders::PhongGL::Flag::UniformBuffers)};
shader
    .bindProjectionBuffer(projectionUniform)
    .bindLightBuffer(lightUniform)
    .bindMaterialBuffer(materialUniform)
    .bindTransformationBuffer(transformationUniform)
    .bindDrawBuffer(drawUniform)
    .draw(mesh);

For a multidraw workflow enable Flag::MultiDraw (and possibly Flag::TextureArrays) and supply desired light, material and draw count via Configuration::setLightCount(), setMaterialCount() and setDrawCount(). For every draw then specify material references and texture offsets/layers. With Flag::LightCulling it's also possible to perform per-draw light culling by supplying a subrange into the PhongLightUniform array using PhongDrawUniform::lightOffset and lightCount. Besides that, the usage is similar for all shaders, see Multidraw and reducing driver overhead for an example.

For skinning, joint matrices are supplied via a TransformationUniform3D buffer bound with bindJointBuffer(). In an instanced scenario the per-instance joint count is supplied via PhongDrawUniform::perInstanceJointCount, a per-draw joint offset for the multidraw scenario is supplied via PhongDrawUniform::jointOffset. Altogether for a particular draw, each per-vertex joint ID is offset with gl_InstanceID*perInstanceJointCount + jointOffset. The setPerVertexJointCount() stays as an immediate uniform in the UBO and multidraw scenario as well, as it is tied to a particular mesh layout and thus doesn't need to vary per draw.

Base classes

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

Derived classes

class Magnum::Shaders::PhongGL::CompileState new in Git master
Asynchronous compilation state.

Public types

class CompileState new in Git master
Asynchronous compilation state.
class Configuration new in Git master
Configuration.
enum (anonymous): UnsignedInt { ColorOutput = GenericGL3D::ColorOutput new in 2019.10, ObjectIdOutput = GenericGL3D::ObjectIdOutput new in 2019.10 }
enum class Flag: UnsignedInt { AmbientTexture = 1 << 0, DiffuseTexture = 1 << 1, SpecularTexture = 1 << 2, NormalTexture = 1 << 4 new in 2019.10, AlphaMask = 1 << 3, VertexColor = 1 << 5 new in 2019.10, DoubleSided = 1 << 20 new in Git master, Bitangent = 1 << 11 new in Git master, TextureTransformation = 1 << 6 new in 2020.06, ObjectId = 1 << 7 new in 2019.10, InstancedObjectId = (1 << 8)|ObjectId new in 2020.06, ObjectIdTexture = (1 << 17)|ObjectId new in Git master, InstancedTransformation = 1 << 9 new in 2020.06, InstancedTextureOffset = (1 << 10)|TextureTransformation new in 2020.06, UniformBuffers = 1 << 12 new in Git master, ShaderStorageBuffers = UniformBuffers|(1 << 19) new in Git master, MultiDraw = UniformBuffers|(1 << 13) new in Git master, TextureArrays = 1 << 14 new in Git master, LightCulling = 1 << 15 new in Git master, NoSpecular = 1 << 16 new in Git master, DynamicPerVertexJointCount = 1 << 18 new in Git master }
Flag.
using Position = GenericGL3D::Position
Vertex position.
using Normal = GenericGL3D::Normal
Normal direction.
using Tangent = GenericGL3D::Tangent new in 2019.10
Tangent direction.
using Tangent4 = GenericGL3D::Tangent4 new in Git master
Tangent direction with a bitangent sign.
using Bitangent = GenericGL3D::Bitangent new in Git master
Bitangent direction.
using TextureCoordinates = GenericGL3D::TextureCoordinates
2D texture coordinates
using Color3 = GenericGL3D::Color3 new in 2019.10
Three-component vertex color.
using Color4 = GenericGL3D::Color4 new in 2019.10
Four-component vertex color.
using JointIds = GenericGL3D::JointIds new in Git master
Joint ids.
using Weights = GenericGL3D::Weights new in Git master
Weights.
using SecondaryJointIds = GenericGL3D::SecondaryJointIds new in Git master
Secondary joint ids.
using SecondaryWeights = GenericGL3D::SecondaryWeights new in Git master
Secondary weights.
using ObjectId = GenericGL3D::ObjectId new in 2020.06
(Instanced) object ID
using TransformationMatrix = GenericGL3D::TransformationMatrix new in 2020.06
(Instanced) transformation matrix
using NormalMatrix = GenericGL3D::NormalMatrix new in 2020.06
(Instanced) normal matrix
using TextureOffset = GenericGL3D::TextureOffset new in 2020.06
(Instanced) texture offset
using TextureOffsetLayer = GenericGL3D::TextureOffsetLayer new in Git master
(Instanced) texture offset and layer
using Flags = Containers::EnumSet<Flag>
Flags.

Public static functions

static auto compile(const Configuration& configuration = Configuration{}) -> CompileState new in Git master
Compile asynchronously.
static auto compile(Flags flags, UnsignedInt lightCount = 1) -> CompileState deprecated in Git master
Compile asynchronously.
static auto compile(Flags flags, UnsignedInt lightCount, UnsignedInt materialCount, UnsignedInt drawCount) -> CompileState deprecated in Git master
Compile for a multi-draw scenario asynchronously.

Constructors, destructors, conversion operators

PhongGL(const Configuration& configuration = Configuration{}) explicit new in Git master
Constructor.
PhongGL(Flags flags, UnsignedInt lightCount = 1) deprecated in Git master explicit
Constructor.
PhongGL(Flags flags, UnsignedInt lightCount, UnsignedInt materialCount, UnsignedInt drawCount) deprecated in Git master explicit
Construct for a multi-draw scenario.
PhongGL(CompileState&& state) explicit new in Git master
Finalize an asynchronous compilation.
PhongGL(NoCreateT) explicit noexcept
Construct without creating the underlying OpenGL object.
PhongGL(const PhongGL&) deleted
Copying is not allowed.
PhongGL(PhongGL&&) defaulted noexcept
Move constructor.

Public functions

auto operator=(const PhongGL&) -> PhongGL& deleted
Copying is not allowed.
auto operator=(PhongGL&&) -> PhongGL& defaulted noexcept
Move assignment.
auto flags() const -> Flags
Flags.
auto lightCount() const -> UnsignedInt
Light count.
auto perDrawLightCount() const -> UnsignedInt new in Git master
Per-draw light count.
auto jointCount() const -> UnsignedInt new in Git master
Joint count.
auto perVertexJointCount() const -> UnsignedInt new in Git master
Per-vertex joint count.
auto secondaryPerVertexJointCount() const -> UnsignedInt new in Git master
Secondary per-vertex joint count.
auto materialCount() const -> UnsignedInt new in Git master
Material count.
auto drawCount() const -> UnsignedInt new in Git master
Draw count.
auto setPerVertexJointCount(UnsignedInt count, UnsignedInt secondaryCount = 0) -> PhongGL& new in Git master
Set dynamic per-vertex skinning joint count.

Uniform setters

Used only if Flag::UniformBuffers is not set.

auto setAmbientColor(const Magnum::Color4& color) -> PhongGL&
Set ambient color.
auto setDiffuseColor(const Magnum::Color4& color) -> PhongGL&
Set diffuse color.
auto setNormalTextureScale(Float scale) -> PhongGL& new in Git master
Set normal texture scale.
auto setSpecularColor(const Magnum::Color4& color) -> PhongGL&
Set specular color.
auto setShininess(Float shininess) -> PhongGL&
Set shininess.
auto setAlphaMask(Float mask) -> PhongGL&
Set alpha mask value.
auto setObjectId(UnsignedInt id) -> PhongGL&
Set object ID.
auto setTransformationMatrix(const Matrix4& matrix) -> PhongGL&
Set transformation matrix.
auto setNormalMatrix(const Matrix3x3& matrix) -> PhongGL&
Set normal matrix.
auto setProjectionMatrix(const Matrix4& matrix) -> PhongGL&
Set projection matrix.
auto setTextureMatrix(const Matrix3& matrix) -> PhongGL& new in 2020.06
Set texture coordinate transformation matrix.
auto setTextureLayer(UnsignedInt layer) -> PhongGL& new in Git master
Set texture array layer.
auto setLightPositions(Containers::ArrayView<const Vector4> positions) -> PhongGL& new in Git master
Set light positions.
auto setLightPositions(std::initializer_list<Vector4> positions) -> PhongGL& new in Git master
auto setLightPositions(Containers::ArrayView<const Vector3> positions) -> PhongGL& deprecated in Git master
Set light positions.
auto setLightPositions(std::initializer_list<Vector3> positions) -> PhongGL& deprecated in Git master
auto setLightPosition(UnsignedInt id, const Vector4& position) -> PhongGL& new in Git master
Set position for given light.
auto setLightPosition(UnsignedInt id, const Vector3& position) -> PhongGL& deprecated in Git master
Set position for given light.
auto setLightPosition(const Vector3& position) -> PhongGL& deprecated in Git master
Set light position.
auto setLightColors(Containers::ArrayView<const Magnum::Color3> colors) -> PhongGL& new in Git master
Set light colors.
auto setLightColors(std::initializer_list<Magnum::Color3> colors) -> PhongGL& new in Git master
auto setLightColors(Containers::ArrayView<const Magnum::Color4> colors) -> PhongGL& deprecated in Git master
Set light colors.
auto setLightColors(std::initializer_list<Magnum::Color4> colors) -> PhongGL& deprecated in Git master
auto setLightColor(UnsignedInt id, const Magnum::Color3& color) -> PhongGL& new in Git master
Set color for given light.
auto setLightColor(UnsignedInt id, const Magnum::Color4& color) -> PhongGL& deprecated in Git master
Set color for given light.
auto setLightColor(const Magnum::Color4& color) -> PhongGL& deprecated in Git master
Set light color.
auto setLightSpecularColors(Containers::ArrayView<const Magnum::Color3> colors) -> PhongGL& new in Git master
Set light specular colors.
auto setLightSpecularColors(std::initializer_list<Magnum::Color3> colors) -> PhongGL& new in Git master
auto setLightSpecularColor(UnsignedInt id, const Magnum::Color3& color) -> PhongGL& new in Git master
Set specular color for given light.
auto setLightRanges(Containers::ArrayView<const Float> ranges) -> PhongGL& new in Git master
Set light attenuation ranges.
auto setLightRanges(std::initializer_list<Float> ranges) -> PhongGL& new in Git master
auto setLightRange(UnsignedInt id, Float range) -> PhongGL& new in Git master
Set attenuation range for given light.
auto setJointMatrices(const Containers::ArrayView<const Matrix4> matrices) -> PhongGL& new in Git master
Set joint matrices.
auto setJointMatrices(std::initializer_list<Matrix4> matrices) -> PhongGL& new in Git master
auto setJointMatrix(UnsignedInt id, const Matrix4& matrix) -> PhongGL& new in Git master
Set joint matrix for given joint.
auto setPerInstanceJointCount(UnsignedInt count) -> PhongGL& new in Git master
Set per-instance joint count.

Texture binding

auto bindAmbientTexture(GL::Texture2D& texture) -> PhongGL&
Bind an ambient texture.
auto bindAmbientTexture(GL::Texture2DArray& texture) -> PhongGL& new in Git master
Bind an ambient array texture.
auto bindDiffuseTexture(GL::Texture2D& texture) -> PhongGL&
Bind a diffuse texture.
auto bindDiffuseTexture(GL::Texture2DArray& texture) -> PhongGL& new in Git master
Bind a diffuse array texture.
auto bindSpecularTexture(GL::Texture2D& texture) -> PhongGL&
Bind a specular texture.
auto bindSpecularTexture(GL::Texture2DArray& texture) -> PhongGL& new in Git master
Bind a specular array texture.
auto bindNormalTexture(GL::Texture2D& texture) -> PhongGL& new in 2019.10
Bind a normal texture.
auto bindNormalTexture(GL::Texture2DArray& texture) -> PhongGL& new in Git master
Bind a normal array texture.
auto bindObjectIdTexture(GL::Texture2D& texture) -> PhongGL& new in Git master
Bind an object ID texture.
auto bindObjectIdTexture(GL::Texture2DArray& texture) -> PhongGL& new in Git master
Bind an object ID array texture.
auto bindTextures(GL::Texture2D* ambient, GL::Texture2D* diffuse, GL::Texture2D* specular, GL::Texture2D* normal = nullptr) -> PhongGL&
Bind textures.

Enum documentation

enum Magnum::Shaders::PhongGL::(anonymous): UnsignedInt

Enumerators
ColorOutput new in 2019.10

Color shader output. Generic output, present always. Expects three- or four-component floating-point or normalized buffer attachment.
ObjectIdOutput new in 2019.10

Object ID shader output. Generic output, present only if Flag::ObjectId is set. Expects a single-component unsigned integral attachment. Writes the value set in setObjectId() and possibly also a per-vertex ID and an ID fetched from a texture, see Object ID output for more information.

enum class Magnum::Shaders::PhongGL::Flag: UnsignedInt

Flag.

Enumerators
AmbientTexture

Multiply ambient color with a texture.
DiffuseTexture

Multiply diffuse color with a texture.
SpecularTexture

Multiply specular color with a texture.
NormalTexture new in 2019.10

Modify normals according to a texture. Requires the Tangent attribute to be present.
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.
VertexColor new in 2019.10

Multiply the diffuse and ambient color with a vertex color. Requires either the Color3 or Color4 attribute to be present.
DoubleSided new in Git master

Double-sided rendering. By default, lighting is applied only to front-facing triangles, with back-facing triangles receiving just the ambient color or being culled away. If enabled, the shader will evaluate the lighting also on back-facing triangles with the normal flipped. Has no effect if no lights are used.

Rendering back-facing triangles requires GL::Renderer::Feature::FaceCulling to be disabled.
Bitangent new in Git master

Use the separate Bitangent attribute for retrieving vertex bitangents. If this flag is not present, the last component of Tangent4 is used to calculate bitangent direction. See Normal mapping for more information.
TextureTransformation new in 2020.06

Enable texture coordinate transformation. If this flag is set, the shader expects that at least one of Flag::AmbientTexture, Flag::DiffuseTexture, Flag::SpecularTexture or Flag::NormalTexture is enabled as well.
ObjectId new in 2019.10

Enable object ID output. See Object ID output for more information.
InstancedObjectId new in 2020.06

Instanced object ID. Retrieves a per-instance / per-vertex object ID from the ObjectId attribute, outputting a sum of the per-vertex ID and ID coming from setObjectId() or PhongDrawUniform::objectId. Implicitly enables Flag::ObjectId. See Object ID output for more information.
ObjectIdTexture new in Git master

Object ID texture. Retrieves object IDs from a texture bound with bindObjectIdTexture(), outputting a sum of the object ID texture, the ID coming from setObjectId() or PhongDrawUniform::objectId and possibly also the per-vertex ID, if Flag::InstancedObjectId is enabled as well. Implicitly enables Flag::ObjectId. See Object ID output for more information.
InstancedTransformation new in 2020.06

Instanced transformation. Retrieves a per-instance transformation and normal matrix from the TransformationMatrix / NormalMatrix attributes and uses them together with matrices coming from setTransformationMatrix() and setNormalMatrix() or TransformationUniform3D::transformationMatrix and PhongDrawUniform::normalMatrix (first the per-instance, then the uniform matrix). See Instanced rendering for more information.
InstancedTextureOffset new in 2020.06

Instanced texture offset. Retrieves a per-instance offset vector from the TextureOffset attribute and uses it together with the matrix coming from setTextureMatrix() or TextureTransformationUniform::rotationScaling and TextureTransformationUniform::offset (first the per-instance vector, then the uniform matrix). Instanced texture scaling and rotation is not supported at the moment, you can specify that only via the uniform setTextureMatrix(). Implicitly enables Flag::TextureTransformation. See Instanced rendering for more information.

If Flag::TextureArrays is set as well, a three-component TextureOffsetLayer attribute can be used instead of TextureOffset to specify per-instance texture layer, which gets added to the uniform layer numbers set by setTextureLayer() or TextureTransformationUniform::layer.
UniformBuffers new in Git master

Use uniform buffers. Expects that uniform data are supplied via bindProjectionBuffer(), bindTransformationBuffer(), bindDrawBuffer(), bindTextureTransformationBuffer(), bindMaterialBuffer() and bindLightBuffer() instead of direct uniform setters.
ShaderStorageBuffers new in Git master

Use shader storage buffers. Superset of functionality provided by Flag::UniformBuffers, compared to it doesn't have any size limits on Configuration::setLightCount(), setJointCount(), setMaterialCount() and setDrawCount() in exchange for potentially more costly access and narrower platform support.
MultiDraw new in Git master

Enable multidraw functionality. Implies Flag::UniformBuffers and adds the value from setDrawOffset() with the gl_DrawID builtin, which makes draws submitted via GL::AbstractShaderProgram::draw(const Containers::Iterable<MeshView>&) and related APIs pick up per-draw parameters directly, without having to rebind the uniform buffers or specify setDrawOffset() before each draw. In a non-multidraw scenario, gl_DrawID is 0, which means a shader with this flag enabled can be used for regular draws as well.
TextureArrays new in Git master

Use 2D texture arrays. Expects that the texture is supplied via bindAmbientTexture(GL::Texture2DArray&) / bindDiffuseTexture(GL::Texture2DArray&) / bindSpecularTexture(GL::Texture2DArray&) / bindNormalTexture(GL::Texture2DArray&) instead of bindAmbientTexture(GL::Texture2D&) / bindDiffuseTexture(GL::Texture2D&) / bindSpecularTexture(GL::Texture2D&) / bindNormalTexture(GL::Texture2D&) and the layer shared by all textures is set via setTextureLayer() or TextureTransformationUniform::layer. If Flag::InstancedTextureOffset is set as well and a three-component TextureOffsetLayer attribute is used instead of TextureOffset, the per-instance and uniform layer numbers are added together.
LightCulling new in Git master

Enable light culling in uniform buffer workflows using the PhongDrawUniform::lightOffset and PhongDrawUniform::lightCount fields. If not enabled, all perDrawLightCount() lights are used for every draw. Expects that Flag::UniformBuffers is enabled as well.
NoSpecular new in Git master

Disable specular contribution in light calculation. Can result in a significant performance improvement compared to calling setSpecularColor() with 0x00000000_rgbaf when specular highlights are not desired.
DynamicPerVertexJointCount new in Git master

Dynamic per-vertex joint count for skinning. Uses only the first M / N primary / secondary components defined by setPerVertexJointCount() instead of all primary / secondary components defined by Configuration::setJointCount() at shader compilation time. Useful in order to avoid having a shader permutation defined for every possible joint count. Unfortunately it's not possible to make use of default values for unspecified input components as the last component is always 1.0 instead of 0.0, on the other hand dynamically limiting the joint count can reduce the time spent executing the vertex shader compared to going through the full set of per-vertex joints always.

Typedef documentation

typedef GenericGL3D::Position Magnum::Shaders::PhongGL::Position

Vertex position.

Generic attribute, Vector3.

typedef GenericGL3D::Normal Magnum::Shaders::PhongGL::Normal

Normal direction.

Generic attribute, Vector3. Used only if perDrawLightCount() isn't 0.

typedef GenericGL3D::Tangent Magnum::Shaders::PhongGL::Tangent new in 2019.10

Tangent direction.

Generic attribute, Vector3. Use either this or the Tangent4 attribute. If only a three-component attribute is used and Flag::Bitangent is not enabled, it's the same as if Tangent4 was specified with the fourth component always being 1.0f. Used only if Flag::NormalTexture is set and perDrawLightCount() isn't 0.

typedef GenericGL3D::Tangent4 Magnum::Shaders::PhongGL::Tangent4 new in Git master

Tangent direction with a bitangent sign.

Generic attribute, Vector4. Use either this or the Tangent attribute. If Flag::Bitangent is set, the fourth component is ignored and bitangents are taken from the Bitangent attribute instead. Used only if Flag::NormalTexture is set and perDrawLightCount() isn't 0.

typedef GenericGL3D::Bitangent Magnum::Shaders::PhongGL::Bitangent new in Git master

Bitangent direction.

Generic attribute, Vector3. Use either this or the Tangent4 attribute. Used only if both Flag::NormalTexture and Flag::Bitangent are set and perDrawLightCount() isn't 0.

typedef GenericGL3D::TextureCoordinates Magnum::Shaders::PhongGL::TextureCoordinates

2D texture coordinates

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

typedef GenericGL3D::Color3 Magnum::Shaders::PhongGL::Color3 new in 2019.10

Three-component vertex color.

Generic attribute, Magnum::Color3. Use either this or the Color4 attribute. Used only if Flag::VertexColor is set.

typedef GenericGL3D::Color4 Magnum::Shaders::PhongGL::Color4 new in 2019.10

Four-component vertex color.

Generic attribute, Magnum::Color4. Use either this or the Color3 attribute. Used only if Flag::VertexColor is set.

typedef GenericGL3D::JointIds Magnum::Shaders::PhongGL::JointIds new in Git master

Joint ids.

Generic attribute, Vector4ui. Used only if perVertexJointCount() isn't 0.

typedef GenericGL3D::Weights Magnum::Shaders::PhongGL::Weights new in Git master

Weights.

Generic attribute, Vector4. Used only if perVertexJointCount() isn't 0.

typedef GenericGL3D::SecondaryJointIds Magnum::Shaders::PhongGL::SecondaryJointIds new in Git master

Secondary joint ids.

Generic attribute, Vector4ui. Used only if secondaryPerVertexJointCount() isn't 0.

typedef GenericGL3D::SecondaryWeights Magnum::Shaders::PhongGL::SecondaryWeights new in Git master

Secondary weights.

Generic attribute, Vector4. Used only if secondaryPerVertexJointCount() isn't 0.

typedef GenericGL3D::ObjectId Magnum::Shaders::PhongGL::ObjectId new in 2020.06

(Instanced) object ID

Generic attribute, UnsignedInt. Used only if Flag::InstancedObjectId is set.

typedef GenericGL3D::TextureOffsetLayer Magnum::Shaders::PhongGL::TextureOffsetLayer new in Git master

(Instanced) texture offset and layer

Generic attribute, Vector3, with the last component interpreted as an integer. Use either this or the TextureOffset attribute. First two components used only if Flag::InstancedTextureOffset is set, third component only if Flag::TextureArrays is set.

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

Flags.

Function documentation

static CompileState Magnum::Shaders::PhongGL::compile(const Configuration& configuration = Configuration{}) new in Git master

Compile asynchronously.

Compared to PhongGL(const Configuration&) can perform an asynchronous compilation and linking. See Async shader compilation and linking for more information.

static CompileState Magnum::Shaders::PhongGL::compile(Flags flags, UnsignedInt lightCount = 1)

Compile asynchronously.

static CompileState Magnum::Shaders::PhongGL::compile(Flags flags, UnsignedInt lightCount, UnsignedInt materialCount, UnsignedInt drawCount)

Compile for a multi-draw scenario asynchronously.

Magnum::Shaders::PhongGL::PhongGL(Flags flags, UnsignedInt lightCount = 1) explicit

Constructor.

Magnum::Shaders::PhongGL::PhongGL(Flags flags, UnsignedInt lightCount, UnsignedInt materialCount, UnsignedInt drawCount) explicit

Construct for a multi-draw scenario.

Magnum::Shaders::PhongGL::PhongGL(CompileState&& state) explicit new in Git master

Finalize an asynchronous compilation.

Takes an asynchronous compilation state returned by compile() and forms a ready-to-use shader object. See Async shader compilation and linking for more information.

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

Construct without creating the underlying OpenGL object.

The constructed instance is equivalent to a 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. However note that this is a low-level and a potentially dangerous API, see the documentation of NoCreate for alternatives.

Flags Magnum::Shaders::PhongGL::flags() const

Flags.

UnsignedInt Magnum::Shaders::PhongGL::lightCount() const

Light count.

If Flag::UniformBuffers is not set, this is the number of light properties accepted by setLightPositions() / setLightPosition(), setLightColors() / setLightColor(), setLightSpecularColors() / setSpecularColor() and setLightRanges() / setLightRange().

If Flag::UniformBuffers is set, this is the statically defined size of the PhongLightUniform uniform buffer bound with bindLightBuffer(). Has no use if Flag::ShaderStorageBuffers is set.

UnsignedInt Magnum::Shaders::PhongGL::perDrawLightCount() const new in Git master

Per-draw light count.

Number of lights out of lightCount() applied per draw. If Flag::LightCulling is enabled, this is only an upper bound on the light count applied per draw, with the actual count supplied via PhongDrawUniform::lightCount. If 0, no lighting calculations are performed and only the ambient contribution to the color is used.

UnsignedInt Magnum::Shaders::PhongGL::jointCount() const new in Git master

Joint count.

If Flag::UniformBuffers is not set, this is the number of joint matrices accepted by setJointMatrices() / setJointMatrix(). If Flag::UniformBuffers is set, this is the statically defined size of the TransformationUniform3D uniform buffer bound with bindJointBuffer(). Has no use if Flag::ShaderStorageBuffers is set.

UnsignedInt Magnum::Shaders::PhongGL::perVertexJointCount() const new in Git master

Per-vertex joint count.

Returns the value set with Configuration::setJointCount(). If Flag::DynamicPerVertexJointCount is set, the count can be additionally modified per-draw using setPerVertexJointCount().

UnsignedInt Magnum::Shaders::PhongGL::secondaryPerVertexJointCount() const new in Git master

Secondary per-vertex joint count.

Returns the value set with Configuration::setJointCount(). If Flag::DynamicPerVertexJointCount is set, the count can be additionally modified per-draw using setPerVertexJointCount().

UnsignedInt Magnum::Shaders::PhongGL::materialCount() const new in Git master

Material count.

Statically defined size of the PhongMaterialUniform uniform buffer bound with bindMaterialBuffer(). Has use only if Flag::UniformBuffers is set and Flag::ShaderStorageBuffers is not set.

UnsignedInt Magnum::Shaders::PhongGL::drawCount() const new in Git master

Draw count.

Statically defined size of each of the TransformationUniform3D, PhongDrawUniform and TextureTransformationUniform uniform buffers bound with bindTransformationBuffer(), bindDrawBuffer() and bindTextureTransformationBuffer(). Has use only if Flag::UniformBuffers is set and Flag::ShaderStorageBuffers is not set.

PhongGL& Magnum::Shaders::PhongGL::setPerVertexJointCount(UnsignedInt count, UnsignedInt secondaryCount = 0) new in Git master

Set dynamic per-vertex skinning joint count.

Returns Reference to self (for method chaining)

Allows reducing the count of iterated joints for a particular draw call, making it possible to use a single shader with meshes that contain different count of per-vertex joints. See Flag::DynamicPerVertexJointCount for more information. As the joint count is tied to the mesh layout, this is a per-draw-call setting even in case of Flag::UniformBuffers instead of being a value in PhongDrawUniform. Initial value is the same as perVertexJointCount() and secondaryPerVertexJointCount().

Expects that Flag::DynamicPerVertexJointCount is set, count is not larger than perVertexJointCount() and secondaryCount not larger than secondaryPerVertexJointCount().

PhongGL& Magnum::Shaders::PhongGL::setAmbientColor(const Magnum::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. If Flag::VertexColor is set, the color is multiplied with a color coming from the Color3 / Color4 attribute.

Expects that Flag::UniformBuffers is not set, in that case fill PhongMaterialUniform::ambientColor and call bindMaterialBuffer() instead.

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

Set diffuse color.

Returns Reference to self (for method chaining)

Initial value is 0xffffffff_rgbaf. If Flag::DiffuseTexture is set, the color will be multiplied with the texture. If perDrawLightCount() is zero, this function is a no-op, as diffuse color doesn't contribute to the output in that case. If Flag::VertexColor is set, the color is multiplied with a color coming from the Color3 / Color4 attribute.

Expects that Flag::UniformBuffers is not set, in that case fill PhongMaterialUniform::diffuseColor and call bindMaterialBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setNormalTextureScale(Float scale) new in Git master

Set normal texture scale.

Returns Reference to self (for method chaining)

Affects strength of the normal mapping. Initial value is 1.0f, meaning the normal texture is not changed in any way; a value of 0.0f disables the normal texture effect altogether.

Expects that the shader was created with Flag::NormalTexture enabled. If perDrawLightCount() is zero, this function is a no-op, as normals don't contribute to the output in that case.

Expects that Flag::UniformBuffers is not set, in that case fill PhongMaterialUniform::normalTextureScale and call bindDrawBuffer() instead.

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

Set specular color.

Returns Reference to self (for method chaining)

Initial value is 0xffffff00_rgbaf. Expects that the shader was not created with Flag::NoSpecular. If Flag::SpecularTexture is set, the color will be multiplied with the texture. If you want to have a fully diffuse material, it's recommended to disable the specular contribution altogether with Flag::NoSpecular. If having a dedicated shader variant is not possible, set the specular color to 0x00000000_rgbaf. If perDrawLightCount() is zero, this function is a no-op, as specular color doesn't contribute to the output in that case.

Expects that Flag::UniformBuffers is not set, in that case fill PhongMaterialUniform::specularColor and call bindMaterialBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::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. If perDrawLightCount() is zero, this function is a no-op, as specular color doesn't contribute to the output in that case.

Expects that Flag::UniformBuffers is not set, in that case fill PhongMaterialUniform::shininess and call bindMaterialBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::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.

This corresponds to glAlphaFunc() in classic OpenGL.

Expects that Flag::UniformBuffers is not set, in that case fill PhongMaterialUniform::alphaMask and call bindMaterialBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setObjectId(UnsignedInt id)

Set object ID.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::ObjectId enabled. Value set here is written to the ObjectIdOutput, see Object ID output for more information. Initial value is 0. If Flag::InstancedObjectId and/or Flag::ObjectIdTexture is enabled as well, this value is added to the ID coming from the ObjectId attribute and/or the texture.

Expects that Flag::UniformBuffers is not set, in that case fill PhongDrawUniform::objectId and call bindDrawBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::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. If Flag::InstancedTransformation is set, the per-instance transformation coming from the TransformationMatrix attribute is applied first, before this one.

Expects that Flag::UniformBuffers is not set, in that case fill TransformationUniform3D::transformationMatrix and call bindTransformationBuffer() instead.

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

Set normal matrix.

Returns Reference to self (for method chaining)

The matrix doesn't need to be normalized, as renormalization is done per-fragment anyway. You need to set also setTransformationMatrix() with a corresponding value. Initial value is an identity matrix. If perDrawLightCount() is zero, this function is a no-op, as normals don't contribute to the output in that case. If Flag::InstancedTransformation is set, the per-instance normal matrix coming from the NormalMatrix attribute is applied first, before this one.

Expects that Flag::UniformBuffers is not set, in that case fill PhongDrawUniform::normalMatrix and call bindDrawBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::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).

Expects that Flag::UniformBuffers is not set, in that case fill ProjectionUniform3D::projectionMatrix and call bindProjectionBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setTextureMatrix(const Matrix3& matrix) new in 2020.06

Set texture coordinate transformation matrix.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::TextureTransformation enabled. Initial value is an identity matrix. If Flag::InstancedTextureOffset is set, the per-instance offset coming from the TextureOffset atttribute is applied first, before this matrix.

Expects that Flag::UniformBuffers is not set, in that case fill TextureTransformationUniform::rotationScaling and TextureTransformationUniform::offset and call bindTextureTransformationBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setTextureLayer(UnsignedInt layer) new in Git master

Set texture array layer.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::TextureArrays enabled. Initial value is 0. If Flag::InstancedTextureOffset is set and a three-component TextureOffsetLayer attribute is used instead of TextureOffset, this value is added to the layer coming from the third component.

Expects that Flag::UniformBuffers is not set, in that case fill TextureTransformationUniform::layer and call bindTextureTransformationBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setLightPositions(Containers::ArrayView<const Vector4> positions) new in Git master

Set light positions.

Returns Reference to self (for method chaining)

Depending on the fourth component, the value is treated as either a camera-relative position of a point light, if the fourth component is 1.0f; or a direction to a directional light, if the fourth component is 0.0f. Expects that the size of the positions array is the same as lightCount(). Initial values are {0.0f, 0.0f, 1.0f, 0.0f} — a directional "fill" light coming from the camera.

Expects that Flag::UniformBuffers is not set, in that case fill PhongLightUniform::position and call bindLightBuffer() instead

PhongGL& Magnum::Shaders::PhongGL::setLightPositions(std::initializer_list<Vector4> positions) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::setLightPositions(Containers::ArrayView<const Vector3> positions)

Set light positions.

0.0f to preserve the original behavior as close as possible.

PhongGL& Magnum::Shaders::PhongGL::setLightPositions(std::initializer_list<Vector3> positions)

0.0f to preserve the original behavior as close as possible.

PhongGL& Magnum::Shaders::PhongGL::setLightPosition(UnsignedInt id, const Vector4& position) new in Git master

Set position for given light.

Returns Reference to self (for method chaining)

Unlike setLightPositions() updates just a single light position. If updating more than one light, prefer the batch function instead to reduce the count of GL API calls. Expects that id is less than lightCount().

Expects that Flag::UniformBuffers is not set, in that case fill PhongLightUniform::position and call bindLightBuffer() instead.

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

Set position for given light.

0.0f to preserve the original behavior as close as possible.

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

Set light position.

0.0f to preserve the original behavior as close as possible.

PhongGL& Magnum::Shaders::PhongGL::setLightColors(Containers::ArrayView<const Magnum::Color3> colors) new in Git master

Set light colors.

Returns Reference to self (for method chaining)

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

Expects that Flag::UniformBuffers is not set, in that case fill PhongLightUniform::color and call bindLightBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setLightColors(std::initializer_list<Magnum::Color3> colors) new in Git master

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

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

Set light colors.

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

PhongGL& Magnum::Shaders::PhongGL::setLightColor(UnsignedInt id, const Magnum::Color3& color) new in Git master

Set color for given light.

Returns Reference to self (for method chaining)

Unlike setLightColors() updates just a single light color. If updating more than one light, prefer the batch function instead to reduce the count of GL API calls. Expects that id is less than lightCount().

Expects that Flag::UniformBuffers is not set, in that case fill PhongLightUniform::color and call bindLightBuffer() instead.

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

Set color for given light.

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

Set light color.

PhongGL& Magnum::Shaders::PhongGL::setLightSpecularColors(Containers::ArrayView<const Magnum::Color3> colors) new in Git master

Set light specular colors.

Returns Reference to self (for method chaining)

Usually you'd set this value to the same as setLightColors(), but it allows for greater flexibility such as disabling specular highlights on certain lights. Initial values are 0xffffff_rgbf. Expects that the size of the colors array is the same as lightCount().

Expects that Flag::UniformBuffers is not set, in that case fill PhongLightUniform::specularColor and call bindLightBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setLightSpecularColors(std::initializer_list<Magnum::Color3> colors) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::setLightSpecularColor(UnsignedInt id, const Magnum::Color3& color) new in Git master

Set specular color for given light.

Returns Reference to self (for method chaining)

Unlike setLightSpecularColors() updates just a single light color. If updating more than one light, prefer the batch function instead to reduce the count of GL API calls. Expects that id is less than lightCount().

Expects that Flag::UniformBuffers is not set, in that case fill PhongLightUniform::specularColor and call bindLightBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setLightRanges(Containers::ArrayView<const Float> ranges) new in Git master

Set light attenuation ranges.

Returns Reference to self (for method chaining)

Initial values are Constants::inf(). Expects that the size of the ranges array is the same as lightCount().

Expects that Flag::UniformBuffers is not set, in that case fill PhongLightUniform::range and call bindLightBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setLightRanges(std::initializer_list<Float> ranges) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::setLightRange(UnsignedInt id, Float range) new in Git master

Set attenuation range for given light.

Returns Reference to self (for method chaining)

Unlike setLightRanges() updates just a single light range. If updating more than one light, prefer the batch function instead to reduce the count of GL API calls. Expects that id is less than lightCount().

Expects that Flag::UniformBuffers is not set, in that case fill PhongLightUniform::range and call bindLightBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setJointMatrices(const Containers::ArrayView<const Matrix4> matrices) new in Git master

Set joint matrices.

Returns Reference to self (for method chaining)

Initial values are identity transformations. Expects that the size of the matrices array is the same as jointCount().

Expects that Flag::UniformBuffers is not set, in that case fill TransformationUniform3D::transformationMatrix and call bindJointBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setJointMatrices(std::initializer_list<Matrix4> matrices) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::setJointMatrix(UnsignedInt id, const Matrix4& matrix) new in Git master

Set joint matrix for given joint.

Returns Reference to self (for method chaining)

Unlike setJointMatrices() updates just a single joint matrix. Expects that id is less than jointCount().

Expects that Flag::UniformBuffers is not set, in that case fill TransformationUniform3D::transformationMatrix and call bindJointBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setPerInstanceJointCount(UnsignedInt count) new in Git master

Set per-instance joint count.

Returns Reference to self (for method chaining)

Offset added to joint IDs in the JointIds and SecondaryJointIds in instanced draws. Should be less than jointCount(). Initial value is 0, meaning every instance will use the same joint matrices, setting it to a non-zero value causes the joint IDs to be interpreted as gl_InstanceID*count + jointId.

Expects that Flag::UniformBuffers is not set, in that case fill PhongDrawUniform::perInstanceJointCount and call bindDrawBuffer() instead.

PhongGL& Magnum::Shaders::PhongGL::setDrawOffset(UnsignedInt offset) new in Git master

Set a draw offset.

Returns Reference to self (for method chaining)

Specifies which item in the TransformationUniform3D, PhongDrawUniform and TextureTransformationUniform buffers bound with bindTransformationBuffer(), bindDrawBuffer() and bindTextureTransformationBuffer() should be used for current draw. Expects that Flag::UniformBuffers is set and offset is less than drawCount(). Initial value is 0, if drawCount() is 1, the function is a no-op as the shader assumes draw offset to be always zero.

If Flag::MultiDraw is set, gl_DrawID is added to this value, which makes each draw submitted via GL::AbstractShaderProgram::draw(const Containers::Iterable<MeshView>&) pick up its own per-draw parameters.

PhongGL& Magnum::Shaders::PhongGL::bindProjectionBuffer(GL::Buffer& buffer) new in Git master

Bind a projection uniform / shader storage buffer.

Returns Reference to self (for method chaining)

Expects that Flag::UniformBuffers is set. The buffer is expected to contain at least one instance of ProjectionUniform3D. At the very least you need to call also bindTransformationBuffer(), bindDrawBuffer() and bindMaterialBuffer(), usually bindLightBuffer() as well.

PhongGL& Magnum::Shaders::PhongGL::bindProjectionBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::bindTransformationBuffer(GL::Buffer& buffer) new in Git master

Bind a transformation uniform / shader storage buffer.

Returns Reference to self (for method chaining)

Expects that Flag::UniformBuffers is set. The buffer is expected to contain drawCount() instances of TransformationUniform3D. At the very least you need to call also bindProjectionBuffer(), bindDrawBuffer() and bindMaterialBuffer(), usually bindLightBuffer() as well.

PhongGL& Magnum::Shaders::PhongGL::bindTransformationBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::bindDrawBuffer(GL::Buffer& buffer) new in Git master

Bind a draw uniform / shader storage buffer.

Returns Reference to self (for method chaining)

Expects that Flag::UniformBuffers is set. The buffer is expected to contain drawCount() instances of PhongDrawUniform. At the very least you need to call also bindProjectionBuffer(), bindTransformationBuffer() and bindMaterialBuffer(), usually bindLightBuffer() as well.

PhongGL& Magnum::Shaders::PhongGL::bindDrawBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::bindTextureTransformationBuffer(GL::Buffer& buffer) new in Git master

Bind a texture transformation uniform / shader storage buffer.

Returns Reference to self (for method chaining)

Expects that both Flag::UniformBuffers and Flag::TextureTransformation is set. The buffer is expected to contain drawCount() instances of TextureTransformationUniform.

PhongGL& Magnum::Shaders::PhongGL::bindTextureTransformationBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::bindMaterialBuffer(GL::Buffer& buffer) new in Git master

Bind a material uniform / shader storage buffer.

Returns Reference to self (for method chaining)

Expects that Flag::UniformBuffers is set. The buffer is expected to contain materialCount() instances of PhongMaterialUniform. At the very least you need to call also bindProjectionBuffer(), bindTransformationBuffer() and bindDrawBuffer(), usually bindLightBuffer() as well.

PhongGL& Magnum::Shaders::PhongGL::bindMaterialBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::bindLightBuffer(GL::Buffer& buffer) new in Git master

Bind a light uniform / shader storage buffer.

Returns Reference to self (for method chaining)

Expects that Flag::UniformBuffers is set. The buffer is expected to contain lightCount() instances of PhongLightUniform.

PhongGL& Magnum::Shaders::PhongGL::bindLightBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::bindJointBuffer(GL::Buffer& buffer) new in Git master

Bind a joint matrix uniform / shader storage buffer.

Returns Reference to self (for method chaining)

Expects that Flag::UniformBuffers is set. The buffer is expected to contain jointCount() instances of TransformationUniform3D.

PhongGL& Magnum::Shaders::PhongGL::bindJointBuffer(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) new in Git master

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

PhongGL& Magnum::Shaders::PhongGL::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. If Flag::TextureArrays is enabled as well, use bindAmbientTexture(GL::Texture2DArray&) instead.

PhongGL& Magnum::Shaders::PhongGL::bindAmbientTexture(GL::Texture2DArray& texture) new in Git master

Bind an ambient array texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with both Flag::AmbientTexture and Flag::TextureArrays enabled. If Flag::UniformBuffers is not enabled, the layer is set via setTextureLayer(); if Flag::UniformBuffers is enabled, Flag::TextureTransformation has to be enabled as well and the layer is set via TextureTransformationUniform::layer.

PhongGL& Magnum::Shaders::PhongGL::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. If Flag::TextureArrays is enabled as well, use bindDiffuseTexture(GL::Texture2DArray&) instead. If perDrawLightCount() is zero, this function is a no-op, as diffuse color doesn't contribute to the output in that case.

PhongGL& Magnum::Shaders::PhongGL::bindDiffuseTexture(GL::Texture2DArray& texture) new in Git master

Bind a diffuse array texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with both Flag::DiffuseTexture and Flag::TextureArrays enabled. If Flag::UniformBuffers is not enabled, the layer is set via setTextureLayer(); if Flag::UniformBuffers is enabled, Flag::TextureTransformation has to be enabled as well and the layer is set via TextureTransformationUniform::layer. If perDrawLightCount() is zero, this function is a no-op, as diffuse color doesn't contribute to the output in that case.

PhongGL& Magnum::Shaders::PhongGL::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 and that Flag::NoSpecular is not set. If Flag::TextureArrays is enabled as well, use bindSpecularTexture(GL::Texture2DArray&) instead. If perDrawLightCount() is zero, this function is a no-op, as specular color doesn't contribute to the output in that case.

PhongGL& Magnum::Shaders::PhongGL::bindSpecularTexture(GL::Texture2DArray& texture) new in Git master

Bind a specular array texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with both Flag::SpecularTexture and Flag::TextureArrays enabled and that Flag::NoSpecular is not set. If Flag::UniformBuffers is not enabled, the layer is set via setTextureLayer(); if Flag::UniformBuffers is enabled, Flag::TextureTransformation has to be enabled as well and the layer is set via TextureTransformationUniform::layer. If perDrawLightCount() is zero, this function is a no-op, as specular color doesn't contribute to the output in that case.

PhongGL& Magnum::Shaders::PhongGL::bindNormalTexture(GL::Texture2D& texture) new in 2019.10

Bind a normal texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::NormalTexture enabled and the Tangent attribute was supplied. If Flag::TextureArrays is enabled as well, use bindNormalTexture(GL::Texture2DArray&) instead. If perDrawLightCount() is zero, this function is a no-op, as normals don't contribute to the output in that case.

PhongGL& Magnum::Shaders::PhongGL::bindNormalTexture(GL::Texture2DArray& texture) new in Git master

Bind a normal array texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with both Flag::NormalTexture and Flag::TextureArrays enabled and the Tangent attribute was supplied. If perDrawLightCount() is zero, this function is a no-op, as normals don't contribute to the output in that case.

PhongGL& Magnum::Shaders::PhongGL::bindObjectIdTexture(GL::Texture2D& texture) new in Git master

Bind an object ID texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with Flag::ObjectIdTexture enabled. If Flag::TextureArrays is enabled as well, use bindObjectIdTexture(GL::Texture2DArray&) instead. The texture needs to have an unsigned integer format.

PhongGL& Magnum::Shaders::PhongGL::bindObjectIdTexture(GL::Texture2DArray& texture) new in Git master

Bind an object ID array texture.

Returns Reference to self (for method chaining)

Expects that the shader was created with both Flag::ObjectIdTexture and Flag::TextureArrays enabled. If Flag::UniformBuffers is not enabled, the layer is set via setTextureLayer(); if Flag::UniformBuffers is enabled, Flag::TextureTransformation has to be enabled as well and the layer is set via TextureTransformationUniform::layer.

PhongGL& Magnum::Shaders::PhongGL::bindTextures(GL::Texture2D* ambient, GL::Texture2D* diffuse, GL::Texture2D* specular, GL::Texture2D* normal = nullptr)

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, Flag::SpecularTexture or Flag::NormalTexture enabled and Flag::TextureArrays is not set. More efficient than setting each texture separately.

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

Debug output operator.

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

Debug output operator.