This is a snapshot of a work-in-progress documentation theme. If you feel lost, miss something, or want to see the original Doxygen docs instead, head over to the archived version of this documentation page.

Magnum::Shader class

Shader.

See AbstractShaderProgram for usage information.

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 = 0x8B31, TessellationControl = 0x8E88, TessellationEvaluation = 0x8E87, Geometry = 0x8DD9, Compute = 0x91B9, Fragment = 0x8B30 }
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<std::reference_wrapper<Shader>> shaders) -> bool
Compile multiple shaders simultaneously.

Constructors, destructors, conversion operators

Shader(Version version, Type type) explicit
Constructor.
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 label() const -> std::string
Shader label.
auto setLabel(const std::string& label) -> Shader&
Set shader label.
template<std::size_t size>
auto setLabel(const char(&label)[size]) -> Shader&
auto type() const -> Type
Shader type.
auto sources() const -> std::vector<std::string>
Shader sources.
auto addSource(std::string source) -> Shader&
Add shader source.
auto addFile(const std::string& filename) -> Shader&
Add source file.
auto compile() -> bool
Compile shader.

Enum documentation

enum class Magnum::Shader::Type: GLenum

Shader type.

Enumerators
Vertex

Vertex shader

TessellationControl

Tessellation control shader

TessellationEvaluation

Tessellation evaluation shader

Geometry

Geometry shader

Compute

Compute shader

Fragment

Fragment shader

Function documentation

static Int Magnum::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::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::Shader::maxTessellationControlOutputComponents()

Max supported component count of tessellation control shader output 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::Shader::maxTessellationControlTotalOutputComponents()

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

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

Max supported component count of tessellation evaluation 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::Shader::maxTessellationEvaluationOutputComponents()

Max supported component count of tessellation evaluation shader output 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::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 ES extension is not available, returns 0.

static Int Magnum::Shader::maxGeometryOutputComponents()

Max supported component count of geometry shader output 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 ES extension is not available, returns 0.

static Int Magnum::Shader::maxGeometryTotalOutputComponents()

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

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 ES extension is not available, returns 0.

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

Max supported atomic counter 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::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::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::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::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::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::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::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::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::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::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::Shader::compile(std::initializer_list<std::reference_wrapper<Shader>> shaders)

Compile multiple shaders simultaneously.

Returns false if compilation of any shader failed, true if everything succeeded. Compiler messages (if any) are printed to error output. The operation is batched in a way that allows the driver to perform multiple compilations simultaneously (i.e. in multiple threads).

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

Destructor.

Deletes associated OpenGL shader.

std::string Magnum::Shader::label() const

Shader label.

The result is not cached, repeated queries will result in repeated OpenGL calls. If OpenGL 4.3 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::Shader::setLabel(const std::string& label)

Set shader label.

Returns Reference to self (for method chaining)

Default is empty string. If OpenGL 4.3 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.

template<std::size_t size>
Shader& Magnum::Shader::setLabel(const char(&label)[size])

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

Shader& Magnum::Shader::addSource(std::string source)

Add shader source.

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

Adds given source to source list, preceeded with #line directive marking first line of the source as n(1) where n is number of added source. The source number 0 is #version directive added in constructor, if any. If passed string is empty, the function does nothing.

Shader& Magnum::Shader::addFile(const std::string& filename)

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

Compile shader.

Compiles single shader. Prefer to compile multiple shaders at once using compile(std::initializer_list<std::reference_wrapper<Shader>>) for improved performance, see its documentation for more information.

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

Debug output operator.