Magnum::GL::Shader class
#include <Magnum/GL/Shader.h>

Shader.

See AbstractShaderProgram for high-level usage information.

Driver workarounds

Some driver workarounds used by Magnum affect also shader code, and the class is implicitly defining the following macros depending on the Version passed to the constructor:

#define MAGNUM_DISABLE_GL_ARB_explicit_attrib_location if the ARB_explicit_attrib_location desktop extension is reported as supported by the shader compiler but isn't usable on given GLSL version. In this case GL::Context::isExtensionSupported(Version) const also returns false for this extension to be able to make appropriate adjustments during shader compilation.
#define MAGNUM_DISABLE_GL_ARB_shading_language_420pack if the ARB_shading_language_420pack desktop extension is reported as supported by the shader compiler but isn't usable on given GLSL version. In this case GL::Context::isExtensionSupported(Version) const also returns false for this extension to be able to make appropriate adjustments during shader compilation.
#define MAGNUM_DISABLE_GL_ARB_explicit_uniform_location if the ARB_explicit_attrib_location desktop extension is reported as supported by the shader compiler but isn't usable on given GLSL version. In this case GL::Context::isExtensionSupported(Version) const also returns false for this extension to be able to make appropriate adjustments during shader compilation.
#define MAGNUM_DISABLE_GL_MAGNUM_shader_vertex_id if the gl_VertexID builtin should be present on given GLSL version but isn't working correctly. You can use the artificial GL_MAGNUM_shader_vertex_id desktop, ES and WebGL extension to check for this case in GL::Context::isExtensionSupported(Version) const.
#define MAGNUM_GLSL_VERSION 310 or #define MAGNUM_GLSL_VERSION 320 if the builtin __VERSION__ macro doesn't have correct value for GLSL ES 3.10 or 3.20

See Driver workarounds for concrete information about driver workarounds used. If Version::None is passed to the constructor, none of the above defines are added.

To help localize shader compilation errors, each addSource() / addFile() call precedes the source with a #line n 1 directive, where n is the source number. Drivers then use the source number to print error location, usually in a form <file>(<line>): or <file>:<line>:.

Source number 0 is a #version directive added in the constructor together with potential workaround defines listed above, which means the first added source has a number 1. If Version::None is specified, the first added source has a number 0 instead.

Performance optimizations

Shader limits and implementation-defined values (such as maxUniformComponents()) are cached, so repeated queries don't result in repeated glGet() calls.

Base classes

class AbstractObject: Base for all OpenGL objects.

Public types

enum class Type: GLenum { Vertex = GL_VERTEX_SHADER, TessellationControl = GL_TESS_CONTROL_SHADER, TessellationEvaluation = GL_TESS_EVALUATION_SHADER, Geometry = GL_GEOMETRY_SHADER, Compute = GL_COMPUTE_SHADER, Fragment = GL_FRAGMENT_SHADER }: Shader type.

Public static functions

static auto maxVertexOutputComponents() -> Int: Max supported component count on vertex shader output.
static auto maxTessellationControlInputComponents() -> Int: Max supported component count of tessellation control shader input vertex.
static auto maxTessellationControlOutputComponents() -> Int: Max supported component count of tessellation control shader output vertex.
static auto maxTessellationControlTotalOutputComponents() -> Int: Max supported component count of all tessellation control shader output vertices combined.
static auto maxTessellationEvaluationInputComponents() -> Int: Max supported component count of tessellation evaluation shader input vertex.
static auto maxTessellationEvaluationOutputComponents() -> Int: Max supported component count of tessellation evaluation shader output vertex.
static auto maxGeometryInputComponents() -> Int: Max supported component count of geometry shader input vertex.
static auto maxGeometryOutputComponents() -> Int: Max supported component count of geometry shader output vertex.
static auto maxGeometryTotalOutputComponents() -> Int: Max supported component count of all geometry shader output vertices combined.
static auto maxFragmentInputComponents() -> Int: Max supported component count on fragment shader input.
static auto maxUniformComponents(Type type) -> Int: Max supported uniform component count in default block.
static auto maxAtomicCounterBuffers(Type type) -> Int: Max supported atomic counter buffer count.
static auto maxCombinedAtomicCounterBuffers() -> Int: Max supported atomic counter buffer count for all stages combined.
static auto maxAtomicCounters(Type type) -> Int: Max supported atomic counter count.
static auto maxCombinedAtomicCounters() -> Int: Max supported atomic counter count for all stages combined.
static auto maxImageUniforms(Type type) -> Int: Max supported image uniform count.
static auto maxCombinedImageUniforms() -> Int: Max supported image uniform count for all stages combined.
static auto maxShaderStorageBlocks(Type type) -> Int: Max supported shader storage block count.
static auto maxCombinedShaderStorageBlocks() -> Int: Max supported shader storage block count for all stages combined.
static auto maxTextureImageUnits(Type type) -> Int: Max supported texture image unit count.
static auto maxCombinedTextureImageUnits() -> Int: Max supported texture image unit count for all stages combined.
static auto maxUniformBlocks(Type type) -> Int: Max supported uniform block count.
static auto maxCombinedUniformBlocks() -> Int: Max supported uniform block count for all stages combined.
static auto maxCombinedUniformComponents(Type type) -> Int: Max supported uniform component count in all blocks combined.
static auto compile(std::initializer_list<Containers::Reference<Shader>> shaders) -> bool deprecated in Git master: Compile multiple shaders simultaneously.
static auto wrap(Type type, GLuint id, ObjectFlags flags = {}) -> Shader new in Git master: Wrap existing OpenGL shader object.

Constructors, destructors, conversion operators

Shader(Version version, Type type) explicit: Constructor.
Shader(NoCreateT) explicit noexcept: Construct without creating the underlying OpenGL object.
Shader(const Shader&) deleted: Copying is not allowed.
Shader(Shader&& other) noexcept: Move constructor.
~Shader(): Destructor.

Public functions

auto operator=(const Shader&) -> Shader& deleted: Copying is not allowed.
auto operator=(Shader&& other) -> Shader& noexcept: Move assignment.
auto id() const -> GLuint: OpenGL shader ID.
auto release() -> GLuint new in Git master: Release the underlying OpenGL object.
auto label() const -> Containers::String: Shader label.
auto setLabel(Containers::StringView label) -> Shader&: Set shader label.
auto type() const -> Type: Shader type.
auto sources() const -> Containers::StringIterable: Shader sources.
auto addSource(Containers::StringView source) -> Shader&: Add shader source.
auto addSource(Containers::String&& source) -> Shader&
auto addFile(const Containers::StringView filename) -> Shader&: Add shader source file.
auto compile() -> bool: Compile the shader.
void submitCompile() new in Git master: Submit the shader for compilation.
auto checkCompile() -> bool new in Git master: Check shader compilation status and await completion.
auto isCompileFinished() -> bool new in Git master: Whether a submitCompile() operation has finished.

Enum documentation

enum class Magnum::GL::Shader::Type: GLenum

Shader type.

Enumerators
Vertex	Vertex shader
TessellationControl	Tessellation control shader Requires OpenGL 4.0 Extension ARB_tessellation_shader Requires OpenGL ES 3.0 Not defined in OpenGL ES 2.0. Requires OpenGL ES 3.2 Extension ANDROID_extension_pack_es31a / EXT_tessellation_shader Requires OpenGL ES or desktop OpenGL Tessellation shaders are not available in WebGL.
TessellationEvaluation	Tessellation evaluation shader Requires OpenGL 4.0 Extension ARB_tessellation_shader Requires OpenGL ES 3.0 Not defined in OpenGL ES 2.0. Requires OpenGL ES 3.2 Extension ANDROID_extension_pack_es31a / EXT_tessellation_shader Requires OpenGL ES or desktop OpenGL Tessellation shaders are not available in WebGL.
Geometry	Geometry shader Requires OpenGL 3.2 Extension ARB_geometry_shader4 Requires OpenGL ES 3.0 Not defined in OpenGL ES 2.0. Requires OpenGL ES 3.2 Extension ANDROID_extension_pack_es31a / EXT_geometry_shader Requires OpenGL ES or desktop OpenGL Geometry shaders are not available in WebGL.
Compute	Compute shader Requires OpenGL 4.3 Extension ARB_compute_shader Requires OpenGL ES 3.1 Compute shaders are not available in OpenGL ES 3.0 and older. Requires OpenGL ES or desktop OpenGL Compute shaders are not available in WebGL.
Fragment	Fragment shader

Function documentation

static Int Magnum::GL::Shader::maxVertexOutputComponents()

Max supported component count on vertex shader output.

The result is cached, repeated queries don't result in repeated OpenGL calls. In OpenGL ES 2.0 the four-component vector count is queried and multiplied with 4.

static Int Magnum::GL::Shader::maxTessellationControlInputComponents()

Max supported component count of tessellation control shader input vertex.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither ARB_tessellation_shader (part of OpenGL 4.0) nor ANDROID_extension_pack_es31a / EXT_tessellation_shader ES extension is available, returns 0.

static Int Magnum::GL::Shader::maxTessellationControlOutputComponents()

Max supported component count of tessellation control shader output vertex.

static Int Magnum::GL::Shader::maxTessellationControlTotalOutputComponents()

Max supported component count of all tessellation control shader output vertices combined.

static Int Magnum::GL::Shader::maxTessellationEvaluationInputComponents()

Max supported component count of tessellation evaluation shader input vertex.

static Int Magnum::GL::Shader::maxTessellationEvaluationOutputComponents()

Max supported component count of tessellation evaluation shader output vertex.

static Int Magnum::GL::Shader::maxGeometryInputComponents()

Max supported component count of geometry shader input vertex.

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::Shader::maxGeometryOutputComponents()

Max supported component count of geometry shader output vertex.

static Int Magnum::GL::Shader::maxGeometryTotalOutputComponents()

Max supported component count of all geometry shader output vertices combined.

static Int Magnum::GL::Shader::maxFragmentInputComponents()

Max supported component count on fragment shader input.

The result is cached, repeated queries don't result in repeated OpenGL calls. In OpenGL ES 2.0 the four-component vector count is queried and multiplied with 4.

static Int Magnum::GL::Shader::maxUniformComponents(Type type)

Max supported uniform component count in default block.

The result is cached, repeated queries don't result in repeated OpenGL calls. If particular shader stage is not available, returns 0. In OpenGL ES 2.0 the four-component vector count is queried and multiplied with 4.

static Int Magnum::GL::Shader::maxAtomicCounterBuffers(Type type)

Max supported atomic counter buffer count.

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 or if particular shader stage is not available, returns 0.

static Int Magnum::GL::Shader::maxCombinedAtomicCounterBuffers()

Max supported atomic counter buffer count for all stages combined.

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::Shader::maxAtomicCounters(Type type)

Max supported atomic counter count.

static Int Magnum::GL::Shader::maxCombinedAtomicCounters()

Max supported atomic counter count for all stages combined.

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::Shader::maxImageUniforms(Type type)

Max supported image uniform 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 OpenGL ES 3.1 is available or if particular shader stage is not available, returns 0.

static Int Magnum::GL::Shader::maxCombinedImageUniforms()

Max supported image uniform count for all stages combined.

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 OpenGL ES 3.1 is available, returns 0.

static Int Magnum::GL::Shader::maxShaderStorageBlocks(Type type)

Max supported shader storage block count.

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 or if particular shader stage is not available, returns 0.

static Int Magnum::GL::Shader::maxCombinedShaderStorageBlocks()

Max supported shader storage block count for all stages combined.

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::Shader::maxTextureImageUnits(Type type)

Max supported texture image unit count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If particular shader stage is not available, returns 0.

static Int Magnum::GL::Shader::maxCombinedTextureImageUnits()

Max supported texture image unit count for all stages combined.

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

static Int Magnum::GL::Shader::maxUniformBlocks(Type type)

Max supported uniform block count.

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

static Int Magnum::GL::Shader::maxCombinedUniformBlocks()

Max supported uniform block count for all stages combined.

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

static Int Magnum::GL::Shader::maxCombinedUniformComponents(Type type)

Max supported uniform component count in all blocks combined.

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

static bool Magnum::GL::Shader::compile(std::initializer_list<Containers::Reference<Shader>> shaders)

Compile multiple shaders simultaneously.

Calls submitCompile() on all shaders first, then checkCompile(). Returns false if compilation of any shader failed, true if everything succeeded.

static Shader Magnum::GL::Shader::wrap(Type type, GLuint id, ObjectFlags flags = {}) new in Git master

Wrap existing OpenGL shader object.

Parameters
type	Shader type
id	OpenGL shader ID
flags	Object creation flags

The id is expected to be of an existing OpenGL shader object. Unlike a shader created using a constructor, the OpenGL object is by default not deleted on destruction, use flags for different behavior.

Magnum::GL::Shader::Shader(Version version, Type type) explicit

Constructor.

Parameters
version	Target version
type	Shader type

Creates empty OpenGL shader and adds #version directive corresponding to version parameter at the beginning. If Version::None is specified, (not) adding the #version directive is left to the user.

Magnum::GL::Shader::Shader(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::Shader::~Shader()

Destructor.

Deletes associated OpenGL shader.

GLuint Magnum::GL::Shader::release() new in Git master

Release the underlying OpenGL object.

Releases ownership of the OpenGL shader object and returns its ID so it's not deleted on destruction. The internal state is then equivalent to a moved-from state.

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

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

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

Set shader 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.

Containers::StringIterable Magnum::GL::Shader::sources() const

Shader sources.

The returned views are all Containers::StringViewFlag::NullTerminated, Containers::StringViewFlag::Global is set for the initial #version directive and for global null-terminated views that were passed to addSource().

Shader& Magnum::GL::Shader::addSource(Containers::StringView source)

Add shader source.

Parameters
source	String with shader source
Returns	Reference to self (for method chaining)

If the string is not empty, adds it to the shader source list, preceded with a #line n 1 directive for improved compilation error reporting. If it's empty, the function is a no-op.

If the view is both Containers::StringViewFlag::NullTerminated and Containers::StringViewFlag::Global, it's directly referenced, otherwise a copy is made internally. For dynamic strings prefer to use the addSource(Containers::String&&) overload to avoid copies.

Shader& Magnum::GL::Shader::addSource(Containers::String&& source)

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

Shader& Magnum::GL::Shader::addFile(const Containers::StringView filename)

Add shader source file.

Parameters
filename	Name of source file to read from
Returns	Reference to self (for method chaining)

The file must exist and must be readable. Calls addSource() with the contents.

bool Magnum::GL::Shader::compile()

Compile the shader.

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

void Magnum::GL::Shader::submitCompile() new in Git master

Submit the shader for compilation.

You can call isCompileFinished() or checkCompile() after, but it's recommended to instead immediately call AbstractShaderProgram::attachShader() and submitLink(), then optionally continue with isLinkFinished() and pass all input shaders to checkLink() on the final program — if compilation would fail, subsequent linking will as well, and checkLink() will print the compilation error if linking failed due to that. See Asynchronous shader compilation and linking for more information.

bool Magnum::GL::Shader::checkCompile() new in Git master

Check shader compilation status and await completion.

Has to be called only if submitCompile() was called before. It's however recommended to instead immediately call AbstractShaderProgram::attachShader() and submitLink(), then optionally continue with isLinkFinished() and pass all input shaders to checkLink() on the final program — if compilation would fail, subsequent linking will as well, and checkLink() will print the compilation error if linking failed due to that. See Asynchronous shader compilation and linking for more information.

bool Magnum::GL::Shader::isCompileFinished() new in Git master

Whether a submitCompile() operation has finished.

Has to be called only if submitCompile() was called before, and before checkCompile(). If returns false, a subsequent checkCompile() call will block until the compilation is finished. If KHR_parallel_shader_compile is not available, the function always returns true — i.e., as if the compilation was done synchronously.

It's however recommended to wait only for the final link to finish, and not for particular compilations — i.e., right after submitCompile() continue with AbstractShaderProgram::attachShader() and submitLink(), and then check with isLinkFinished() on the final program. See Asynchronous shader compilation and linking for more information.

Debug& operator<<(Debug& debug, Shader::Type value)

Debug output operator.