class
#include <Magnum/GL/Shader.h>
Shader 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 thegl_VertexID
builtin should be present on given GLSL version but isn't working correctly. You can use the artificialGL_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::
Compilation error reporting
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::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
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 |
TessellationEvaluation |
Tessellation evaluation shader |
Geometry |
Geometry shader |
Compute |
Compute shader |
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_0
.
static Int Magnum:: GL:: 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_0
.
static Int Magnum:: GL:: 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_0
.
static Int Magnum:: GL:: 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_0
.
static Int Magnum:: GL:: 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_0
.
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_0
.
static Int Magnum:: GL:: 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_0
.
static Int Magnum:: GL:: 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_0
.
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_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_0
.
static Int Magnum:: GL:: 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_0
.
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_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_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_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_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_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_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_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_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::#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.
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_
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_
Containers:: StringIterable Magnum:: GL:: Shader:: sources() const
Shader sources.
The returned views are all Containers::#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::
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::
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::
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_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::
Debug& operator<<(Debug& debug,
Shader:: Type value)
Debug output operator.