Magnum::GL::AbstractShaderProgram class

Base for shader program implementations.

Wraps an OpenGL shader program object. Meant to be only used through subclasses, either via builtin shaders in the Shaders namespace or by creating a custom shader implementation.

Subclassing workflow

This class is designed to be used via subclassing. Subclasses define these functions and properties:

  • Attribute definitions using Attribute typedefs with location and type for configuring meshes, for example:

    typedef GL::Attribute<0, Vector3> Position;
    typedef GL::Attribute<1, Vector3> Normal;
    typedef GL::Attribute<2, Vector2> TextureCoordinates;
  • Output attribute locations, if desired, for example:

    enum: UnsignedInt {
        ColorOutput = 0,
        NormalOutput = 1
    };
  • Constructor, which loads, compiles and attaches particular shaders and links the program together, for example:

    explicit MyShader() {
        /* Load shader sources */
        GL::Shader vert{GL::Version::GL430, GL::Shader::Type::Vertex};
        GL::Shader frag{GL::Version::GL430, GL::Shader::Type::Fragment};
        vert.addFile("MyShader.vert");
        frag.addFile("MyShader.frag");
    
        /* Compile them */
        CORRADE_INTERNAL_ASSERT_OUTPUT(vert.compile() && frag.compile());
    
        /* Attach the shaders */
        attachShaders({vert, frag});
    
        /* Link the program together */
        CORRADE_INTERNAL_ASSERT_OUTPUT(link());
    }
  • Uniform setting functions, which will provide public interface for protected setUniform() functions. For usability purposes you can implement also method chaining. Example:

    MyShader& setProjectionMatrix(const Matrix4& matrix) {
        setUniform(0, matrix);
        return *this;
    }
    MyShader& setTransformationMatrix(const Matrix4& matrix) {
        setUniform(1, matrix);
        return *this;
    }
    MyShader& setNormalMatrix(const Matrix3x3& matrix) {
        setUniform(2, matrix);
        return *this;
    }
  • Texture and texture image binding functions in which you bind the textures/images to particular texture/image units using *Texture::bind() / *Texture::bindImage() and similar, for example:

    MyShader& bindDiffuseTexture(GL::Texture2D& texture) {
        texture.bind(0);
        return *this;
    }
    MyShader& bindSpecularTexture(GL::Texture2D& texture) {
        texture.bind(1);
        return *this;
    }
  • Transform feedback setup function, if needed, in which you bind buffers to particular indices using TransformFeedback::attachBuffer() and similar, possibly with overloads based on desired use cases, e.g.:

    MyShader& setTransformFeedback(GL::TransformFeedback& feedback,
        GL::Buffer& positions, GL::Buffer& data)
    {
        feedback.attachBuffers(0, {&positions, &data});
        return *this;
    }
    MyShader& setTransformFeedback(GL::TransformFeedback& feedback, Int totalCount,
        GL::Buffer& positions, GLintptr positionsOffset, GL::Buffer& data,
        GLintptr dataOffset)
    {
        feedback.attachBuffers(0, {
            {&positions, positionsOffset, GLsizeiptr(totalCount*sizeof(Vector3))},
            {&data, dataOffset, GLsizeiptr(totalCount*sizeof(Vector2ui))}
        });
        return *this;
    }
  • And optionally, return derived type from relevant draw/dispatch functions to make it possible for users to easily chain draw calls; and on the other hand hide the irrelevant APIs to prevent users from accidentally calling draw() / drawTransformFeedback() on compute shaders, or dispatchCompute() on shaders that aren't compute. Because there's many overloads of those APIs and they differ based on target platform, it's recommended to be done via either MAGNUM_GL_ABSTRACTSHADERPROGRAM_SUBCLASS_DRAW_IMPLEMENTATION() or MAGNUM_GL_ABSTRACTSHADERPROGRAM_SUBCLASS_DISPATCH_IMPLEMENTATION():

    MAGNUM_GL_ABSTRACTSHADERPROGRAM_SUBCLASS_DRAW_IMPLEMENTATION(MyShader)

Binding attribute and fragment data location

The preferred workflow is to specify attribute location for vertex shader input attributes and fragment shader output attributes explicitly in the shader code, e.g.:

// GLSL 3.30, GLSL ES 3.00 or
#extension GL_ARB_explicit_attrib_location: require
layout(location = 0) in vec4 position;
layout(location = 1) in vec3 normal;
layout(location = 2) in vec2 textureCoordinates;

Similarly for output attributes, you can also specify blend equation color index for them (see Renderer::BlendFunction for more information about using color input index):

layout(location = 0, index = 0) out vec4 color;
layout(location = 1, index = 1) out vec3 normal;

If you don't have the required version/extension, declare the attributes without layout() qualifier and use functions bindAttributeLocation() and bindFragmentDataLocation() / bindFragmentDataLocationIndexed() between attaching the shaders and linking the program. Note that additional syntax changes may be needed for GLSL 1.20 and GLSL ES.

in vec4 position;
in vec3 normal;
in vec2 textureCoordinates;
out vec4 color;
out vec3 normal;
// Shaders attached...

bindAttributeLocation(Position::Location, "position");
bindAttributeLocation(Normal::Location, "normal");
bindAttributeLocation(TextureCoordinates::Location, "textureCoordinates");

bindFragmentDataLocation(ColorOutput, "color");
bindFragmentDataLocation(NormalOutput, "normal");

// Link...

Uniform locations

The preferred workflow is to specify uniform locations directly in the shader code, e.g.:

// GLSL 4.30, GLSL ES 3.10 or
#extension GL_ARB_explicit_uniform_location: require
layout(location = 0) uniform mat4 projectionMatrix;
layout(location = 1) uniform mat4 transformationMatrix;
layout(location = 2) uniform mat3 normalMatrix;

If you don't have the required version/extension, declare the uniforms without the layout() qualifier, get uniform location using uniformLocation() after linking stage and then use the queried location in uniform setting functions. Note that additional syntax changes may be needed for GLSL 1.20 and GLSL ES.

uniform mat4 projectionMatrix;
uniform mat4 transformationMatrix;
uniform mat3 normalMatrix;
Int projectionMatrixUniform = uniformLocation("projectionMatrix");
Int transformationMatrixUniform = uniformLocation("transformationMatrix");
Int normalMatrixUniform = uniformLocation("normalMatrix");

Uniform block bindings

The preferred workflow is to specify uniform block binding directly in the shader code, e.g.:

// GLSL 4.20, GLSL ES 3.10 or
#extension GL_ARB_shading_language_420pack: require
layout(std140, binding = 0) uniform matrices {
    mat4 projectionMatrix;
    mat4 transformationMatrix;
};
layout(std140, binding = 1) uniform material {
    vec4 diffuse;
    vec4 specular;
};

If you don't have the required version/extension, declare the uniform blocks without the layout() qualifier, get uniform block index using uniformBlockIndex() and then map it to the uniform buffer binding using setUniformBlockBinding(). Note that additional syntax changes may be needed for GLSL ES.

layout(std140) uniform matrices {
    mat4 projectionMatrix;
    mat4 transformationMatrix;
};
layout(std140) uniform material {
    vec4 diffuse;
    vec4 specular;
};
setUniformBlockBinding(uniformBlockIndex("matrices"), 0);
setUniformBlockBinding(uniformBlockIndex("material"), 1);

Shader storage block bindings

The workflow is to specify shader storage block binding directly in the shader code, e.g.:

// GLSL 4.30 or GLSL ES 3.10
layout(std430, binding = 0) buffer vertices {
    vec3 position;
    vec3 color;
};
layout(std430, binding = 1) buffer normals {
    vec3 normal;
};

Specifying texture and image binding units

The preferred workflow is to specify texture/image binding unit directly in the shader code, e.g.:

// GLSL 4.20, GLSL ES 3.10 or
#extension GL_ARB_shading_language_420pack: require
layout(binding = 0) uniform sampler2D diffuseTexture;
layout(binding = 1) uniform sampler2D specularTexture;

If you don't have the required version/extension, declare the uniforms without the binding qualifier and set the texture binding unit using setUniform(Int, Int). Note that additional syntax changes may be needed for GLSL ES.

uniform sampler2D diffuseTexture;
uniform sampler2D specularTexture;
setUniform(uniformLocation("diffuseTexture"), 0);
setUniform(uniformLocation("specularTexture"), 1);

Specifying transform feedback binding points

The preferred workflow is to specify output binding points directly in the shader code, e.g.:

// GLSL 4.40, or
#extension GL_ARB_enhanced_layouts: require
layout(xfb_buffer = 0, xfb_stride = 32) out block {
    layout(xfb_offset = 0) vec3 position;
    layout(xfb_offset = 16) vec3 normal;
};
layout(xfb_buffer = 1) out vec3 velocity;

If you don't have the required version/extension, declare the uniforms without the xfb_* qualifier and set the binding points using setTransformFeedbackOutputs(). Equivalent setup for the previous code would be the following:

out block {
    vec3 position;
    vec3 normal;
};
out vec3 velocity;
setTransformFeedbackOutputs({
        // Buffer 0
        "position", "gl_SkipComponents1", "normal", "gl_SkipComponents1",
        // Buffer 1
        "gl_NextBuffer", "velocity"
    }, TransformFeedbackBufferMode::InterleavedAttributes);

Rendering workflow

Basic workflow with AbstractShaderProgram subclasses is: instance shader class, configure attribute binding in meshes (see Mesh documentation for more information) and map shader outputs to framebuffer attachments if needed (see Framebuffer documentation for more information). In each draw event set all required shader parameters, bind specific framebuffer (if needed) and then call draw(). Example:

MyShader shader;
shader.setTransformationMatrix(transformation)
    .setProjectionMatrix(projection)
    .bindDiffuseTexture(diffuseTexture)
    .bindSpecularTexture(specularTexture)
    .draw(mesh);

Compute workflow

Add just the Shader::Type::Compute shader and implement uniform/texture setting functions as needed. After setting up required parameters call dispatchCompute().

Mapping between GLSL and Magnum types

See Math type system for more information, only types with GLSL equivalent can be used (and their super- or subclasses with the same size and underlying type). See also Attribute::DataType enum for additional type options.

Asynchronous shader compilation and linking

The workflow described at the very top compiles and links the shader directly in a constructor. While that's fine for many use cases, with heavier shaders, many shader combinations or on platforms that translate GLSL to other APIs such as HLSL or MSL, the compilation and linking can take a significant portion of application startup time.

To mitigate this problem, nowadays drivers implement asynchronous compilation — when shader compilation or linking is requested, the driver offloads the work to separate worker threads, and serializes it back to the application thread only once the application wants to retrieve the result of the operation. Which means, the ideal way to spread the operation over more CPU cores is to first submit compilation & linking of several shaders at once and only then ask for operation result. That allows the driver to perform compilation/linking of multiple shaders at once. Furthermore, the KHR_parallel_shader_compile extension adds a possibility to query whether the operation was finished for a particular shader. That allows the application to schedule other work in the meantime.

Async compilation and linking can be implemented by using Shader::submitCompile() and submitLink(), followed by checkLink() (which optionally delegates to Shader::checkCompile()), instead of Shader::compile() and link(). Calling the submit functions will trigger a (potentially async) compilation and linking, calling the check functions will check the operation result, potentially stalling if the async operation isn't finished yet.

The Shader::isCompileFinished() and isLinkFinished() APIs then provide a way to query if the submitted operation finished. If KHR_parallel_shader_compile is not available, those two implicitly return true, thus effectively causing a stall if the operation isn't yet done at the time you call Shader::checkCompile() / checkLink() — but compared to the linear workflow you still get the benefits from submitting multiple operations at once.

A common way to equip an AbstractShaderProgram subclass with async creation capability while keeping also the simple constructor is the following:

  1. An internal NoInit constructor for the subclass is added, which only creates the AbstractShaderProgram base but does nothing else.
  2. A CompileState inner class is defined as a subclass of MyShader. Besides that it holds all temporary state needed to finish the construction — in particular all Shader instances.
  3. A static CompileState compile() function does everything until and including linking as the original constructor did, except that it calls Shader::submitCompile() and submitLink() instead of Shader::compile() and link(), and returns a populated CompileState instance.
  4. A MyShader(CompileState&&) constructor then takes over the base of CompileState by delegating it into the move constructor. Then it calls checkLink(), passing all input shaders to it for a complete context in case of an error, and finally performs any remaining post-link steps such as uniform setup.
  5. The original MyShader() constructor now only passes the result of compile() to MyShader(CompileState&&).
class MyShader::CompileState: public MyShader {
    friend MyShader;

    explicit CompileState(MyShader&& shader, GL::Shader&& vert, GL::Shader&& frag):
        MyShader{std::move(shader)}, _vert{std::move(vert)}, _frag{std::move(frag)} {}

    GL::Shader _vert, _frag;
};

MyShader::CompileState MyShader::compile() {
    GL::Shader vert{GL::Version::GL430, GL::Shader::Type::Vertex};
    GL::Shader frag{GL::Version::GL430, GL::Shader::Type::Fragment};
    
    vert.submitCompile();
    frag.submitCompile();

    MyShader out{NoInit};
    
    out.attachShaders({vert, frag});
    out.submitLink();

    return CompileState{std::move(out), std::move(vert), std::move(frag)};
}

MyShader::MyShader(NoInitT) {}

MyShader::MyShader(CompileState&& state):
    MyShader{static_cast<MyShader&&>(std::move(state))}
{
    CORRADE_INTERNAL_ASSERT_OUTPUT(checkLink({state._vert, state._frag}));
    
}

MyShader::MyShader(): MyShader{compile()} {}

Usage-wise, it can look for example like below, with the last line waiting for linking to finish and making the shader ready to use. On drivers that don't perform any async compilation this will behave the same as if the construction was done the usual way.

MyShader::CompileState state = MyShader::compile();
// Other shaders to compile....

while(!state.isLinkFinished()) {
    // Do other work...
}

MyShader shader{std::move(state)};

Performance optimizations

The engine tracks currently used shader program to avoid unnecessary calls to glUseProgram(). Shader limits (such as maxVertexAttributes()) are cached, so repeated queries don't result in repeated glGet() calls. See also Context::resetState() and Context::State::Shaders.

If extension ARB_separate_shader_objects (part of OpenGL 4.1), EXT_separate_shader_objects OpenGL ES extension or OpenGL ES 3.1 is available, uniform setting functions use DSA functions to avoid unnecessary calls to glUseProgram(). See setUniform() documentation for more information.

To achieve least state changes, set all uniforms in one run — method chaining comes in handy.

Base classes

class AbstractObject
Base for all OpenGL objects.

Derived classes

template<UnsignedInt dimensions>
class Magnum::Shaders::DistanceFieldVectorGL new in Git master
Distance field vector OpenGL shader.
template<UnsignedInt dimensions>
class Magnum::Shaders::FlatGL new in Git master
Flat OpenGL shader.
class Magnum::Shaders::PhongGL new in Git master
Phong OpenGL shader.
template<UnsignedInt dimensions>
class Magnum::Shaders::VectorGL new in Git master
Vector OpenGL shader.
template<UnsignedInt dimensions>
class Magnum::Shaders::VertexColorGL new in Git master
Vertex color OpenGL shader.
class Magnum::Ui::AbstractUiShader
Base for UI shaders.

Public types

enum class TransformFeedbackBufferMode: GLenum { InterleavedAttributes = GL_INTERLEAVED_ATTRIBS, SeparateAttributes = GL_SEPARATE_ATTRIBS }
Buffer mode for transform feedback.

Public static functions

static auto maxVertexAttributes() -> Int
Max supported vertex attribute count.
static auto maxGeometryOutputVertices() -> Int new in 2020.06
Max supported count of vertices emitted by a geometry shader.
static auto maxAtomicCounterBufferSize() -> Int
Max supported atomic counter buffer size.
static auto maxComputeSharedMemorySize() -> Int
Max supported compute shared memory size.
static auto maxComputeWorkGroupInvocations() -> Int
Max supported compute work group invocation count.
static auto maxComputeWorkGroupCount() -> Vector3i
Max supported compute work group count.
static auto maxComputeWorkGroupSize() -> Vector3i
Max supported compute work group size.
static auto maxImageUnits() -> Int
Max supported image unit count.
static auto maxImageSamples() -> Int
Max supported image sample count.
static auto maxCombinedShaderOutputResources() -> Int
Max supported combined shader output resource count.
static auto maxShaderStorageBlockSize() -> Long
Max supported shader storage block size in bytes.
static auto maxUniformBlockSize() -> Int
Max supported uniform block size in bytes.
static auto maxUniformLocations() -> Int
Max supported explicit uniform location count.
static auto minTexelOffset() -> Int
Min supported program texel offset.
static auto maxTexelOffset() -> Int
Max supported program texel offset.

Constructors, destructors, conversion operators

AbstractShaderProgram() explicit
Constructor.
AbstractShaderProgram(NoCreateT) explicit noexcept
Construct without creating the underlying OpenGL object.
AbstractShaderProgram(const AbstractShaderProgram&) deleted
Copying is not allowed.
AbstractShaderProgram(AbstractShaderProgram&& other) noexcept
Move constructor.
~AbstractShaderProgram() pure virtual
Destructor.

Public functions

auto operator=(const AbstractShaderProgram&) -> AbstractShaderProgram& deleted
Copying is not allowed.
auto operator=(AbstractShaderProgram&& other) -> AbstractShaderProgram& noexcept
Move assignment.
auto id() const -> GLuint
OpenGL program ID.
auto label() const -> Containers::String
Shader program label.
auto setLabel(Containers::StringView label) -> AbstractShaderProgram&
Set shader program label.
auto validate() -> std::pair<bool, std::string>
Validate program.
auto draw(Mesh& mesh) -> AbstractShaderProgram& new in 2020.06
Draw a mesh.
auto draw(Mesh&& mesh) -> AbstractShaderProgram& new in 2020.06
auto draw(MeshView& mesh) -> AbstractShaderProgram& new in 2020.06
Draw a mesh view.
auto draw(MeshView&& mesh) -> AbstractShaderProgram& new in 2020.06
auto draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& indexOffsets) -> AbstractShaderProgram& new in Git master
Draw multiple mesh views at once.
auto draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedLong>& indexOffsets) -> AbstractShaderProgram& new in Git master
Draw multiple mesh views at once.
auto draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, std::nullptr_t) -> AbstractShaderProgram& new in Git master
auto draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& indexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& instanceOffsets) -> AbstractShaderProgram& new in Git master
Draw multiple instanced mesh views with instance offsets at once.
auto draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedLong>& indexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& instanceOffsets) -> AbstractShaderProgram& new in Git master
Draw multiple instanced mesh views with instance offsets at once.
auto draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, std::nullptr_t, const Containers::StridedArrayView1D<const UnsignedInt>& instanceOffsets) -> AbstractShaderProgram& new in Git master
auto draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& indexOffsets) -> AbstractShaderProgram& new in Git master
Draw multiple instanced mesh views at once.
auto draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedLong>& indexOffsets) -> AbstractShaderProgram& new in Git master
Draw multiple instanced mesh views at once.
auto draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, std::nullptr_t) -> AbstractShaderProgram& new in Git master
auto draw(const Containers::Iterable<MeshView>& meshes) -> AbstractShaderProgram& new in 2020.06
Draw multiple mesh views at once.
auto drawTransformFeedback(Mesh& mesh, TransformFeedback& xfb, UnsignedInt stream = 0) -> AbstractShaderProgram& new in 2020.06
Draw a mesh with vertices coming out of transform feedback.
auto drawTransformFeedback(MeshView& mesh, TransformFeedback& xfb, UnsignedInt stream = 0) -> AbstractShaderProgram& new in 2020.06
Draw a mesh view with vertices coming out of transform feedback.
auto dispatchCompute(const Vector3ui& workgroupCount) -> AbstractShaderProgram&
Dispatch compute.
auto isLinkFinished() -> bool new in Git master
Whether a submitLink() operation has finished.

Protected static functions

static auto link(std::initializer_list<Containers::Reference<AbstractShaderProgram>> shaders) -> bool deprecated in Git master
Link multiple shaders simultaenously.

Protected functions

void setRetrievableBinary(bool enabled)
Allow retrieving program binary.
void setSeparable(bool enabled)
Allow the program to be bound to individual pipeline stages.
void attachShader(Shader& shader)
Attach a shader.
void attachShaders(const Containers::Iterable<Shader>& shaders)
Attach shaders.
void bindAttributeLocation(UnsignedInt location, const std::string& name)
Bind an attribute to given location.
template<std::size_t size>
void bindAttributeLocation(UnsignedInt location, const char(&name)[size])
void bindFragmentDataLocationIndexed(UnsignedInt location, UnsignedInt index, const std::string& name)
Bind fragment data to given location and color input index.
template<std::size_t size>
void bindFragmentDataLocationIndexed(UnsignedInt location, UnsignedInt index, const char(&name)[size])
void bindFragmentDataLocation(UnsignedInt location, const std::string& name)
Bind fragment data to given location and first color input index.
template<std::size_t size>
void bindFragmentDataLocation(UnsignedInt location, const char(&name)[size])
void setTransformFeedbackOutputs(Containers::ArrayView<const std::string> outputs, TransformFeedbackBufferMode bufferMode) new in Git master
Specify shader outputs to be recorded in transform feedback.
void setTransformFeedbackOutputs(std::initializer_list<std::string> outputs, TransformFeedbackBufferMode bufferMode)
auto link() -> bool
Link the shader.
void submitLink() new in Git master
Submit the shader for linking.
auto checkLink(const Containers::Iterable<Shader>& shaders) -> bool new in Git master
Check shader linking status and await completion.
auto uniformLocation(const std::string& name) -> Int
Get uniform location.
template<std::size_t size>
auto uniformLocation(const char(&name)[size]) -> Int
auto uniformBlockIndex(const std::string& name) -> UnsignedInt
Get uniform block index.
template<std::size_t size>
auto uniformBlockIndex(const char(&name)[size]) -> UnsignedInt
void setUniform(Int location, Float value)
Set a float uniform value.
void setUniform(Int location, const Math::Vector<2, Float>& value)
void setUniform(Int location, const Math::Vector<3, Float>& value)
void setUniform(Int location, const Math::Vector<4, Float>& value)
void setUniform(Int location, Int value)
Set an integer uniform value.
void setUniform(Int location, const Math::Vector<2, Int>& value)
void setUniform(Int location, const Math::Vector<3, Int>& value)
void setUniform(Int location, const Math::Vector<4, Int>& value)
void setUniform(Int location, UnsignedInt value)
Set an unsigned integer uniform value.
void setUniform(Int location, const Math::Vector<2, UnsignedInt>& value)
void setUniform(Int location, const Math::Vector<3, UnsignedInt>& value)
void setUniform(Int location, const Math::Vector<4, UnsignedInt>& value)
void setUniform(Int location, Double value)
Set a double uniform value.
void setUniform(Int location, const Math::Vector<2, Double>& value)
void setUniform(Int location, const Math::Vector<3, Double>& value)
void setUniform(Int location, const Math::Vector<4, Double>& value)
void setUniform(Int location, Containers::ArrayView<const Float> values)
Set float uniform values.
void setUniform(Int location, Containers::ArrayView<const Math::Vector<2, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Math::Vector<3, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Math::Vector<4, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Int> values)
Set integer uniform values.
void setUniform(Int location, Containers::ArrayView<const Math::Vector<2, Int>> values)
void setUniform(Int location, Containers::ArrayView<const Math::Vector<3, Int>> values)
void setUniform(Int location, Containers::ArrayView<const Math::Vector<4, Int>> values)
void setUniform(Int location, Containers::ArrayView<const UnsignedInt> values)
Set unsigned integer uniform values.
void setUniform(Int location, Containers::ArrayView<const Math::Vector<2, UnsignedInt>> values)
void setUniform(Int location, Containers::ArrayView<const Math::Vector<3, UnsignedInt>> values)
void setUniform(Int location, Containers::ArrayView<const Math::Vector<4, UnsignedInt>> values)
void setUniform(Int location, Containers::ArrayView<const Double> values)
Set double uniform values.
void setUniform(Int location, Containers::ArrayView<const Math::Vector<2, Double>> values)
void setUniform(Int location, Containers::ArrayView<const Math::Vector<3, Double>> values)
void setUniform(Int location, Containers::ArrayView<const Math::Vector<4, Double>> values)
template<std::size_t cols, std::size_t rows, class T>
void setUniform(Int location, const Math::RectangularMatrix<cols, rows, T>& value)
Set a float matrix uniform value.
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 2, Float>> values)
Set float matrix uniform values.
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 3, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 4, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 3, Float>> values)
Set rectangular float matrix uniform values.
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 2, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 4, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 2, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 4, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 3, Float>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 2, Double>> values)
Set double matrix uniform values.
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 3, Double>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 4, Double>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 3, Double>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 2, Double>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 4, Double>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 2, Double>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 4, Double>> values)
void setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 3, Double>> values)
void setUniformBlockBinding(UnsignedInt index, UnsignedInt binding)
Set uniform block binding.

Enum documentation

enum class Magnum::GL::AbstractShaderProgram::TransformFeedbackBufferMode: GLenum

Buffer mode for transform feedback.

Enumerators
InterleavedAttributes

Attributes will be interleaved at one buffer binding point

SeparateAttributes

Each attribute will be put into separate buffer binding point

Function documentation

static Int Magnum::GL::AbstractShaderProgram::maxVertexAttributes()

Max supported vertex attribute count.

The result is cached, repeated queries don't result in repeated OpenGL calls.

static Int Magnum::GL::AbstractShaderProgram::maxGeometryOutputVertices() new in 2020.06

Max supported count of vertices emitted by a geometry shader.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither ARB_geometry_shader4 (part of OpenGL 3.2) nor ANDROID_extension_pack_es31a / EXT_geometry_shader (part of OpenGL ES 3.2) is not available, returns 0.

static Int Magnum::GL::AbstractShaderProgram::maxAtomicCounterBufferSize()

Max supported atomic counter buffer size.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_shader_atomic_counters (part of OpenGL 4.2) nor OpenGL ES 3.1 is available, returns 0.

static Int Magnum::GL::AbstractShaderProgram::maxComputeSharedMemorySize()

Max supported compute shared memory size.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_compute_shader (part of OpenGL 4.3) nor OpenGL ES 3.1 is available, returns 0.

static Int Magnum::GL::AbstractShaderProgram::maxComputeWorkGroupInvocations()

Max supported compute work group invocation count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_compute_shader (part of OpenGL 4.3) nor OpenGL ES 3.1 is available, returns 0.

static Vector3i Magnum::GL::AbstractShaderProgram::maxComputeWorkGroupCount()

Max supported compute work group count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_compute_shader (part of OpenGL 4.3) nor OpenGL ES 3.1 is available, returns zero vector.

static Vector3i Magnum::GL::AbstractShaderProgram::maxComputeWorkGroupSize()

Max supported compute work group size.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_compute_shader (part of OpenGL 4.3) nor OpenGL ES 3.1 is available, returns zero vector.

static Int Magnum::GL::AbstractShaderProgram::maxImageUnits()

Max supported image unit count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If extension ARB_shader_image_load_store (part of OpenGL 4.2) or OpenGL ES 3.1 is not available, returns 0.

static Int Magnum::GL::AbstractShaderProgram::maxImageSamples()

Max supported image sample count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If extension ARB_shader_image_load_store (part of OpenGL 4.2) is not available, returns 0.

static Int Magnum::GL::AbstractShaderProgram::maxCombinedShaderOutputResources()

Max supported combined shader output resource count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_shader_image_load_store (part of OpenGL 4.2) nor extension ARB_shader_storage_buffer_object (part of OpenGL 4.3) nor OpenGL ES 3.1 is available, returns 0.

static Long Magnum::GL::AbstractShaderProgram::maxShaderStorageBlockSize()

Max supported shader storage block size in bytes.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_shader_storage_buffer_object (part of OpenGL 4.3) nor OpenGL ES 3.1 is available, returns 0.

static Int Magnum::GL::AbstractShaderProgram::maxUniformBlockSize()

Max supported uniform block size in bytes.

The result is cached, repeated queries don't result in repeated OpenGL calls. If extension ARB_uniform_buffer_object (part of OpenGL 3.1) is not available, returns 0.

static Int Magnum::GL::AbstractShaderProgram::maxUniformLocations()

Max supported explicit uniform location count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_explicit_uniform_location (part of OpenGL 4.3) nor OpenGL ES 3.1 is available, returns 0.

static Int Magnum::GL::AbstractShaderProgram::minTexelOffset()

Min supported program texel offset.

The result is cached, repeated queries don't result in repeated OpenGL calls. If extension EXT_gpu_shader4 (part of OpenGL 3.0) is not available, returns 0.

static Int Magnum::GL::AbstractShaderProgram::maxTexelOffset()

Max supported program texel offset.

The result is cached, repeated queries don't result in repeated OpenGL calls. If extension EXT_gpu_shader4 (part of OpenGL 3.0) is not available, returns 0.

Magnum::GL::AbstractShaderProgram::AbstractShaderProgram() explicit

Constructor.

Creates one OpenGL shader program.

Magnum::GL::AbstractShaderProgram::AbstractShaderProgram(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. However note that this is a low-level and a potentially dangerous API, see the documentation of NoCreate for alternatives.

Magnum::GL::AbstractShaderProgram::~AbstractShaderProgram() pure virtual

Destructor.

Deletes associated OpenGL shader program.

Containers::String Magnum::GL::AbstractShaderProgram::label() const

Shader program label.

The result is not cached, repeated queries will result in repeated OpenGL calls. If OpenGL 4.3 / OpenGL ES 3.2 is not supported and neither KHR_debug (covered also by ANDROID_extension_pack_es31a) nor EXT_debug_label desktop or ES extension is available, this function returns empty string.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::setLabel(Containers::StringView label)

Set shader program label.

Returns Reference to self (for method chaining)

Default is empty string. If OpenGL 4.3 / OpenGL ES 3.2 is not supported and neither KHR_debug (covered also by ANDROID_extension_pack_es31a) nor EXT_debug_label desktop or ES extension is available, this function does nothing.

std::pair<bool, std::string> Magnum::GL::AbstractShaderProgram::validate()

Validate program.

Returns validation status and optional validation message.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh) new in 2020.06

Draw a mesh.

Returns Reference to self (for method chaining)

Expects that mesh is compatible with this shader and is fully set up. If its vertex/index count or instance count is 0, no draw commands are issued. See also class documentation for more information. If ARB_vertex_array_object (part of OpenGL 3.0), OpenGL ES 3.0, WebGL 2.0, OES_vertex_array_object in OpenGL ES 2.0 or OES_vertex_array_object in WebGL 1.0 is available, the associated vertex array object is bound instead of setting up the mesh from scratch.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh&& mesh) new in 2020.06

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

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(MeshView& mesh) new in 2020.06

Draw a mesh view.

Returns Reference to self (for method chaining)

See draw(Mesh&) for more information.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(MeshView&& mesh) new in 2020.06

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

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& indexOffsets) new in Git master

Draw multiple mesh views at once.

Parameters
mesh The mesh from which to draw
counts Vertex/index counts for each draw
vertexOffsets Offsets into the vertex array for non-indexed meshes, base vertex for indexed meshes. Expected to have the same size as counts, for indexed meshes it can be also empty in which case the base vertex is assumed to be 0 for all draws.
indexOffsets Offsets into the index buffer for indexed meshes, in bytes. Expected to have the same size as counts for indexed meshes, ignored for non-indexed.
Returns Reference to self (for method chaining)

Expects that mesh is compatible with this shader and is fully set up. If counts is empty, no draw commands are issued. If ARB_vertex_array_object (part of OpenGL 3.0), OpenGL ES 3.0, WebGL 2.0, OES_vertex_array_object in OpenGL ES 2.0 or OES_vertex_array_object in WebGL 1.0 is available, the associated vertex array object is bound instead of setting up the mesh from scratch.

If counts, vertexOffsets and indexOffsets are contiguous views, they get passed directly to the underlying GL functions, otherwise a temporary contiguous copy is allocated. There are the folllowing special cases, however:

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedLong>& indexOffsets) new in Git master

Draw multiple mesh views at once.

Returns Reference to self (for method chaining)

Defined only on 64-bit builds. Compared to draw(Mesh&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&) this overload can avoid allocating an array of 64-bit pointers for the glMultiDrawElements() / glMultiDrawElementsBaseVertex() function and can instead directly reuse the indexOffsets view if it's contiguous.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, std::nullptr_t) 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.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& indexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& instanceOffsets) new in Git master

Draw multiple instanced mesh views with instance offsets at once.

Parameters
mesh The mesh from which to draw
counts Vertex/index counts for each draw
instanceCounts Instance counts for each draw. Expected to have the same size as counts.
vertexOffsets Offsets into the vertex array for non-indexed meshes, base vertex for indexed meshes. Expected to have the same size as counts, for indexed meshes it can be also empty in which case the base vertex is assumed to be 0 for all draws.
indexOffsets Offsets into the index buffer for indexed meshes, in bytes. Expected to have the same size as counts for indexed meshes, ignored for non-indexed.
instanceOffsets Offsets to be added to the instance index for each draw. Expected to either be empty or have the same size as counts.
Returns Reference to self (for method chaining)

If counts, instanceCounts, vertexOffsets, indexOffsets and instanceOffsets are contiguous views, they get passed directly to the underlying GL functions, otherwise a temporary contiguous copy is allocated. There are the following special cases, however:

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedLong>& indexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& instanceOffsets) new in Git master

Draw multiple instanced mesh views with instance offsets at once.

Returns Reference to self (for method chaining)

Defined only on 64-bit builds. Compared to draw(Mesh&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&) this overload can avoid allocating an array of 64-bit pointers for the glMultiDrawElementsInstancedANGLE() / glMultiDrawElementsInstancedBaseVertexBaseInstanceANGLE() function and can instead directly reuse the indexOffsets view if it's contiguous. See the original overload for further information.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, std::nullptr_t, const Containers::StridedArrayView1D<const UnsignedInt>& instanceOffsets) 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.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedInt>& indexOffsets) new in Git master

Draw multiple instanced mesh views at once.

Returns Reference to self (for method chaining)

Compared to draw(Mesh&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&) lacks the last instanceOffsets parameter and as such is available also in OpenGL ES 2.0 and WebGL 1.0.

If OpenGL ES 3.0, WebGL 2.0, OES_vertex_array_object in OpenGL ES 2.0 or OES_vertex_array_object in WebGL 1.0 is available, the associated vertex array object is bound instead of setting up the mesh from scratch.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedLong>& indexOffsets) new in Git master

Draw multiple instanced mesh views at once.

Returns Reference to self (for method chaining)

Defined only on 64-bit builds. Compared to draw(Mesh&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&) this overload can avoid allocating an array of 64-bit pointers for the glMultiDrawElementsInstancedANGLE() / glMultiDrawElementsInstancedBaseVertexBaseInstanceANGLE() function and can instead directly reuse the indexOffsets view if it's contiguous. See the original overload for further information.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& instanceCounts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, std::nullptr_t) 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.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::draw(const Containers::Iterable<MeshView>& meshes) new in 2020.06

Draw multiple mesh views at once.

Returns Reference to self (for method chaining)

Extracts the vertex/index counts, vertex offsets and index offsets out of the mesh list and then calls draw(Mesh&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&, const Containers::StridedArrayView1D<const UnsignedInt>&) (or draw(Mesh& mesh, const Containers::StridedArrayView1D<const UnsignedInt>& counts, const Containers::StridedArrayView1D<const UnsignedInt>& vertexOffsets, const Containers::StridedArrayView1D<const UnsignedLong>& indexOffsets) on 64-bit builds).

On OpenGL ES, if neither EXT_multi_draw_arrays nor ANGLE_multi_draw is present, and on WebGL if WEBGL_multi_draw is not present, the functionality is instead emulated using a sequence of draw(MeshView&) calls. Note that WEBGL_multi_draw is only implemented since Emscripten 2.0.0, so it's not even advertised on older versions.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::drawTransformFeedback(Mesh& mesh, TransformFeedback& xfb, UnsignedInt stream = 0) new in 2020.06

Draw a mesh with vertices coming out of transform feedback.

Parameters
mesh Mesh to draw
xfb Transform feedback to use for vertex count
stream Transform feedback stream ID
Returns Reference to self (for method chaining)

Expects that mesh is compatible with this shader, is fully set up and that the output buffer(s) from xfb are used as vertex buffers in the mesh. If its instance count is 0, no draw commands are issued. Everything set by Mesh::setCount(), Mesh::setBaseInstance(), Mesh::setBaseVertex() and Mesh::setIndexBuffer() is ignored, the mesh is drawn as non-indexed and the vertex count is taken from the xfb object. If stream is 0, non-stream draw command is used. If ARB_vertex_array_object (part of OpenGL 3.0) is available, the associated vertex array object is bound instead of setting up the mesh from scratch.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::drawTransformFeedback(MeshView& mesh, TransformFeedback& xfb, UnsignedInt stream = 0) new in 2020.06

Draw a mesh view with vertices coming out of transform feedback.

Returns Reference to self (for method chaining)

Everything set by MeshView::setCount(), MeshView::setBaseInstance(), MeshView::setBaseVertex(), MeshView::setIndexRange() and Mesh::setIndexBuffer() is ignored, the mesh is drawn as non-indexed and the vertex count is taken from the xfb object. See drawTransformFeedback(Mesh&, TransformFeedback&, UnsignedInt) for more information.

AbstractShaderProgram& Magnum::GL::AbstractShaderProgram::dispatchCompute(const Vector3ui& workgroupCount)

Dispatch compute.

Parameters
workgroupCount Workgroup count in given dimension
Returns Reference to self (for method chaining)

Valid only on programs with compute shader attached. If workgroupCount is 0 in any dimension, no compute dispatch commands are issued.

bool Magnum::GL::AbstractShaderProgram::isLinkFinished() new in Git master

Whether a submitLink() operation has finished.

Has to be called only if submitLink() was called before, and before checkLink(). If returns false, a subsequent checkLink() call will block until the linking is finished. If KHR_parallel_shader_compile is not available, the function always returns true — i.e., as if the linking was done synchronously. See Asynchronous shader compilation and linking for more information.

static bool Magnum::GL::AbstractShaderProgram::link(std::initializer_list<Containers::Reference<AbstractShaderProgram>> shaders) protected

Link multiple shaders simultaenously.

Calls submitLink() on all shaders first, then checkLink(). Returns false if linking of any shader failed, true if everything succeeded.

void Magnum::GL::AbstractShaderProgram::setRetrievableBinary(bool enabled) protected

Allow retrieving program binary.

Initially disabled.

void Magnum::GL::AbstractShaderProgram::setSeparable(bool enabled) protected

Allow the program to be bound to individual pipeline stages.

Initially disabled.

void Magnum::GL::AbstractShaderProgram::attachShader(Shader& shader) protected

Attach a shader.

void Magnum::GL::AbstractShaderProgram::attachShaders(const Containers::Iterable<Shader>& shaders) protected

Attach shaders.

Convenience overload to the above, allowing the user to specify more than one shader at once. Other than that there is no other (performance) difference when using this function.

void Magnum::GL::AbstractShaderProgram::bindAttributeLocation(UnsignedInt location, const std::string& name) protected

Bind an attribute to given location.

Parameters
location Location
name Attribute name

Binds attribute to location which is used later for binding vertex buffers.

template<std::size_t size>
void Magnum::GL::AbstractShaderProgram::bindAttributeLocation(UnsignedInt location, const char(&name)[size]) protected

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

void Magnum::GL::AbstractShaderProgram::bindFragmentDataLocationIndexed(UnsignedInt location, UnsignedInt index, const std::string& name) protected

Bind fragment data to given location and color input index.

Parameters
location Location
index Blend equation color input index (0 or 1)
name Fragment output variable name

Binds fragment data to location which is used later for framebuffer operations. See also Renderer::BlendFunction for more information about using color input index.

template<std::size_t size>
void Magnum::GL::AbstractShaderProgram::bindFragmentDataLocationIndexed(UnsignedInt location, UnsignedInt index, const char(&name)[size]) protected

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

void Magnum::GL::AbstractShaderProgram::bindFragmentDataLocation(UnsignedInt location, const std::string& name) protected

Bind fragment data to given location and first color input index.

Parameters
location Location
name Fragment output variable name

The same as bindFragmentDataLocationIndexed(), but with index set to 0.

template<std::size_t size>
void Magnum::GL::AbstractShaderProgram::bindFragmentDataLocation(UnsignedInt location, const char(&name)[size]) protected

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

void Magnum::GL::AbstractShaderProgram::setTransformFeedbackOutputs(Containers::ArrayView<const std::string> outputs, TransformFeedbackBufferMode bufferMode) protected new in Git master

Specify shader outputs to be recorded in transform feedback.

Parameters
outputs Names of output variables
bufferMode Buffer mode

Binds given output variables from vertex, geometry or tessellation shader to transform feedback buffer binding points. If TransformFeedbackBufferMode::SeparateAttributes is used, each output is bound to separate binding point. If TransformFeedbackBufferMode::InterleavedAttributes is used, the outputs are interleaved into single buffer binding point. In this case, special output name gl_NextBuffer causes the following output to be recorded into next buffer binding point and gl_SkipComponents# causes the transform feedback to offset the following output variable by # components.

void Magnum::GL::AbstractShaderProgram::setTransformFeedbackOutputs(std::initializer_list<std::string> outputs, TransformFeedbackBufferMode bufferMode) protected

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

bool Magnum::GL::AbstractShaderProgram::link() protected

Link the shader.

Calls submitLink(), immediately followed by checkLink(), passing back its return value. See documentation of those two functions for details.

void Magnum::GL::AbstractShaderProgram::submitLink() protected new in Git master

Submit the shader for linking.

The attached shaders must be at least submitted for compilation with Shader::submitCompile() or Shader::compile() before linking. Call isLinkFinished() or checkLink() after, see Asynchronous shader compilation and linking for more information.

bool Magnum::GL::AbstractShaderProgram::checkLink(const Containers::Iterable<Shader>& shaders) protected new in Git master

Check shader linking status and await completion.

Has to be called only if submitLink() was called before.

If shaders are not empty, first calls Shader::checkCompile() on each. If a compilation failure is reached, returns false without even checking link status. To have error messages with full context in case of a failed shader compilation or linking, an application is encouraged to pass all input Shader instances to this function or, if not possible, explicitly call Shader::checkCompile() on each.

Then, link status is checked and a message (if any) is printed Returns false if linking failed, true on success. If linking failed, it first goes through shaders and calls Shader::checkCompile() on each until a failure is reached. If no compilation failed, a linker message is printed to error output. The function will stall until a (potentially async) linking operation finishes, you can use isLinkFinished() to check the status instead. See Asynchronous shader compilation and linking for more information.

Int Magnum::GL::AbstractShaderProgram::uniformLocation(const std::string& name) protected

Get uniform location.

Parameters
name Uniform name

If given uniform is not found in the linked shader, a warning is printed and -1 is returned.

template<std::size_t size>
Int Magnum::GL::AbstractShaderProgram::uniformLocation(const char(&name)[size]) protected

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

UnsignedInt Magnum::GL::AbstractShaderProgram::uniformBlockIndex(const std::string& name) protected

Get uniform block index.

Parameters
name Uniform block name

If given uniform block name is not found in the linked shader, a warning is printed and 0xffffffffu is returned.

template<std::size_t size>
UnsignedInt Magnum::GL::AbstractShaderProgram::uniformBlockIndex(const char(&name)[size]) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Float value) protected

Set a float uniform value.

Parameters
location Uniform location
value Value

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<2, Float>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<3, Float>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<4, Float>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Int value) protected

Set an integer uniform value.

Parameters
location Uniform location
value Value

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<2, Int>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<3, Int>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<4, Int>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, UnsignedInt value) protected

Set an unsigned integer uniform value.

Parameters
location Uniform location
value Value

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<2, UnsignedInt>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<3, UnsignedInt>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<4, UnsignedInt>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Double value) protected

Set a double uniform value.

Parameters
location Uniform location
value Value

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<2, Double>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<3, Double>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::Vector<4, Double>& value) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Float> values) protected

Set float uniform values.

Parameters
location Uniform location
values Values

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<2, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<3, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<4, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Int> values) protected

Set integer uniform values.

Parameters
location Uniform location
values Values

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<2, Int>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<3, Int>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<4, Int>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const UnsignedInt> values) protected

Set unsigned integer uniform values.

Parameters
location Uniform location
values Values

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<2, UnsignedInt>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<3, UnsignedInt>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<4, UnsignedInt>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Double> values) protected

Set double uniform values.

Parameters
location Uniform location
values Values

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<2, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<3, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::Vector<4, Double>> values) protected

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

template<std::size_t cols, std::size_t rows, class T>
void Magnum::GL::AbstractShaderProgram::setUniform(Int location, const Math::RectangularMatrix<cols, rows, T>& value) protected

Set a float matrix uniform value.

Parameters
location Uniform location
value Value

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 2, Float>> values) protected

Set float matrix uniform values.

Parameters
location Uniform location
values Values

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 3, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 4, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 3, Float>> values) protected

Set rectangular float matrix uniform values.

Parameters
location Uniform location
values Values

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 2, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 4, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 2, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 4, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 3, Float>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 2, Double>> values) protected

Set double matrix uniform values.

Parameters
location Uniform location
values Values

If neither ARB_separate_shader_objects (part of OpenGL 4.1) nor EXT_separate_shader_objects OpenGL ES extension nor OpenGL ES 3.1 is available, the shader is marked for use before the operation.

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 3, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 4, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 3, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 2, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<2, 4, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 2, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<3, 4, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniform(Int location, Containers::ArrayView<const Math::RectangularMatrix<4, 3, Double>> values) protected

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

void Magnum::GL::AbstractShaderProgram::setUniformBlockBinding(UnsignedInt index, UnsignedInt binding) protected

Set uniform block binding.

Parameters
index Uniform block index
binding Uniform block binding