Magnum::GL::Context class

Magnum context.

Contents

Provides access to version and extension information. Instance available through Context::current() is automatically created during construction of *Application classes in Platform namespace. You can safely assume that the instance is available during whole lifetime of *Application object. It's also possible to create the context without using any *Application class using Platform::GLContext subclass, see Platform support documentation for more information.

Command-line options

The context is configurable through command-line options, that are passed either from the Platform::*Application classes or from the Platform::GLContext class. Usage:

<application> [--magnum-help] [--magnum-disable-workarounds LIST]
              [--magnum-disable-extensions LIST] ...

Arguments:

  • ... — main application arguments (see -h or --help for details)
  • --magnum-help — display this help message and exit
  • --magnum-disable-workarounds LIST — driver workarounds to disable (see Driver workarounds for detailed info) (environment: MAGNUM_DISABLE_WORKAROUNDS)
  • --magnum-disable-extensions LIST — OpenGL extensions to disable (environment: MAGNUM_DISABLE_EXTENSIONS)

Note that all options are prefixed with --magnum- to avoid conflicts with options passed to the application itself. Options that don't have this prefix are completely ignored, see documentation of the Utility::Arguments class for details.

Derived classes

class Magnum::Platform::GLContext
Platform-specific OpenGL context.

Public types

enum class Flag: GLint { Debug = GL_CONTEXT_FLAG_DEBUG_BIT, NoError = GL_CONTEXT_FLAG_NO_ERROR_BIT, RobustAccess = GL_CONTEXT_FLAG_ROBUST_ACCESS_BIT }
Context flag.
enum class State: UnsignedInt { Buffers = 1 << 0, Framebuffers = 1 << 1, Meshes = 1 << 2, MeshVao = 1 << 3, PixelStorage = 1 << 4, Renderer = 1 << 5, Shaders = 1 << 6, Textures = 1 << 7, TransformFeedback = 1 << 8, EnterExternal = MeshVao, ExitExternal = Buffers|Framebuffers|Meshes|MeshVao|PixelStorage|Renderer|Shaders|Textures |TransformFeedback }
State to reset.
enum class DetectedDriver: UnsignedShort { Amd = 1 << 0, AMD = UnsignedShort(DetectedDriver::Amd) deprecated, IntelWindows = 1 << 2, Mesa = 1 << 3, NVidia = 1 << 4, Svga3D = 1 << 5 }
Detected driver.
using Flags = Containers::EnumSet<Flag>
Context flags.
using States = Containers::EnumSet<State>
States to reset.
using DetectedDrivers = Containers::EnumSet<DetectedDriver>
Detected drivers.

Public static functions

static auto hasCurrent() -> bool
Whether there is any current context.
static auto current() -> Context&
Current context.

Constructors, destructors, conversion operators

Context(const Context&) deleted
Copying is not allowed.
Context(Context&& other)
Move constructor.

Public functions

auto operator=(const Context&) -> Context& deleted
Copying is not allowed.
auto operator=(Context&&) -> Context& deleted
Move assignment is not allowed.
auto version() const -> Version
OpenGL version.
auto vendorString() const -> std::string
Vendor string.
auto rendererString() const -> std::string
Renderer string.
auto versionString() const -> std::string
Version string.
auto shadingLanguageVersionString() const -> std::string
Shading language version string.
auto shadingLanguageVersionStrings() const -> std::vector<std::string>
Shading language version strings.
auto extensionStrings() const -> std::vector<std::string>
Extension strings.
auto flags() const -> Flags
Context flags.
auto supportedExtensions() const -> const std::vector<Extension>&
Supported extensions.
auto isCoreProfile() -> bool
Detect if current OpenGL context is a core profile.
auto isVersionSupported(Version version) const -> bool
Whether given OpenGL version is supported.
auto supportedVersion(std::initializer_list<Version> versions) const -> Version
Get supported OpenGL version.
template<class T>
auto isExtensionSupported() const -> bool
Whether given extension is supported.
template<class T>
auto isExtensionSupported(Version version) const -> bool
Whether given extension is supported in given version.
auto isExtensionSupported(const Extension& extension) const -> bool
Whether given extension is supported.
template<class T>
auto isExtensionDisabled() const -> bool
Whether given extension is disabled.
template<class T>
auto isExtensionDisabled(Version version) const -> bool
Whether given extension is disabled for given version.
auto isExtensionDisabled(const Extension& extension) const -> bool
Whether given extension is disabled.
void resetState(States states = ~States{})
Reset internal state tracker.
auto detectedDriver() -> DetectedDrivers
Detect driver.

Enum documentation

enum class Magnum::GL::Context::Flag: GLint

Context flag.

Enumerators
Debug

Debug context
NoError

Context without error reporting
RobustAccess

Context with robust access

enum class Magnum::GL::Context::State: UnsignedInt

State to reset.

Enumerators
Buffers

Reset tracked buffer-related bindings and state
Framebuffers

Reset tracked framebuffer-related bindings and state
Meshes

Reset tracked mesh-related bindings
MeshVao

Unbind currently bound VAO.

Magnum by default uses VAOs — each time a Mesh is drawn or configured, its VAO is bound, but it is not unbound afterwards to avoid needless state changes. This may introduce problems when using third-party OpenGL code — it may break internal state of a mesh that was used the most recently. Similar issue can happen the other way. Calling resetState() with State::MeshVao included unbounds any currently bound VAO to fix such case.
PixelStorage

Reset tracked pixel storage-related state
Renderer

Reset tracked renderer-related state
Shaders

Reset tracked shader-related bindings
Textures

Reset tracked texture-related bindings and state
TransformFeedback

Reset tracked transform feedback-related bindings
EnterExternal

Reset state on entering section with external OpenGL code.

Resets all state that could cause external code to accidentally modify Magnum objects. This includes only State::MeshVao.
ExitExternal

Reset state on exiting section with external OpenGL code.

Resets Magnum state tracker to avoid being confused by external state changes. This resets all states.

enum class Magnum::GL::Context::DetectedDriver: UnsignedShort

Detected driver.

Enumerators
Amd

Binary AMD desktop drivers on Windows and Linux
AMD

Binary AMD desktop drivers on Windows and Linux
IntelWindows

Intel desktop drivers on Windows
Mesa

Mesa drivers on Windows and Linux. See also DetectedDriver::Svga3D.
NVidia

Binary NVidia drivers on Windows and Linux
Svga3D

VMware guest GL driver SVGA3D, implemented using Mesa, both Windows and Linux guests. See https://www.mesa3d.org/vmware-guest.html for more information. Detected in combination with DetectedDriver::Mesa.

Typedef documentation

typedef Containers::EnumSet<Flag> Magnum::GL::Context::Flags

Context flags.

typedef Containers::EnumSet<State> Magnum::GL::Context::States

States to reset.

typedef Containers::EnumSet<DetectedDriver> Magnum::GL::Context::DetectedDrivers

Detected drivers.

Function documentation

static bool Magnum::GL::Context::hasCurrent()

Whether there is any current context.

If Magnum is built with MAGNUM_BUILD_MULTITHREADED, current context is thread-local instead of global (the default).

static Context& Magnum::GL::Context::current()

Current context.

Expect that there is current context. If Magnum is built with MAGNUM_BUILD_MULTITHREADED, current context is thread-local instead of global (the default).

Version Magnum::GL::Context::version() const

OpenGL version.

std::string Magnum::GL::Context::vendorString() const

Vendor string.

The result is not cached, repeated queries will result in repeated OpenGL calls.

std::string Magnum::GL::Context::rendererString() const

Renderer string.

The result is not cached, repeated queries will result in repeated OpenGL calls.

std::string Magnum::GL::Context::versionString() const

Version string.

The result is not cached, repeated queries will result in repeated OpenGL calls.

std::string Magnum::GL::Context::shadingLanguageVersionString() const

Shading language version string.

The result is not cached, repeated queries will result in repeated OpenGL calls.

std::vector<std::string> Magnum::GL::Context::shadingLanguageVersionStrings() const

Shading language version strings.

The result is not cached, repeated queries will result in repeated OpenGL calls.

std::vector<std::string> Magnum::GL::Context::extensionStrings() const

Extension strings.

The result is not cached, repeated queries will result in repeated OpenGL calls. Note that this function returns list of all extensions reported by the driver (even those not supported by Magnum), see supportedExtensions(), Extension::extensions() or isExtensionSupported() for alternatives.

Flags Magnum::GL::Context::flags() const

Context flags.

const std::vector<Extension>& Magnum::GL::Context::supportedExtensions() const

Supported extensions.

The list contains only extensions from OpenGL versions newer than the current.

bool Magnum::GL::Context::isCoreProfile()

Detect if current OpenGL context is a core profile.

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

bool Magnum::GL::Context::isVersionSupported(Version version) const

Whether given OpenGL version is supported.

Version Magnum::GL::Context::supportedVersion(std::initializer_list<Version> versions) const

Get supported OpenGL version.

Returns first supported OpenGL version from passed list. Convenient equivalent to subsequent isVersionSupported() calls — the two following examples produce the same result:

GL::Version v1 = GL::Context::current().isVersionSupported(GL::Version::GL330) ?
    GL::Version::GL330 : GL::Version::GL210;
GL::Version v2 = GL::Context::current().supportedVersion({
    GL::Version::GL330, GL::Version::GL210});

If no version from the list is supported, returns lowest available OpenGL version (Version::GL210 for desktop OpenGL, Version::GLES200 for OpenGL ES).

template<class T>
bool Magnum::GL::Context::isExtensionSupported() const

Whether given extension is supported.

Extensions usable with this function are listed in Extensions namespace in header Extensions.h. Example usage:

if(GL::Context::current().isExtensionSupported<GL::Extensions::ARB::tessellation_shader>()) {
    // draw fancy detailed model
} else {
    // texture fallback
}

template<class T>
bool Magnum::GL::Context::isExtensionSupported(Version version) const

Whether given extension is supported in given version.

Similar to isExtensionSupported(), but checks also that the minimal required version of the extension is larger or equal to version. Useful mainly in shader compilation when the decisions depend on selected GLSL version, for example:

const GL::Version version = GL::Context::current().supportedVersion({
    GL::Version::GL320, GL::Version::GL300, GL::Version::GL210});
if(GL::Context::current().isExtensionSupported<GL::Extensions::ARB::explicit_attrib_location>(version)) {
    // Called only if ARB_explicit_attrib_location is supported
    // *and* version is higher than GL 3.1
}

bool Magnum::GL::Context::isExtensionSupported(const Extension& extension) const

Whether given extension is supported.

Can be used e.g. for listing extensions available on current hardware, but for general usage prefer isExtensionSupported() const, as it does most operations in compile time.

template<class T>
bool Magnum::GL::Context::isExtensionDisabled() const

Whether given extension is disabled.

Can be used for detecting driver bug workarounds. Disabled extensions return false in isExtensionSupported() even if they are advertised as being supported by the driver.

template<class T>
bool Magnum::GL::Context::isExtensionDisabled(Version version) const

Whether given extension is disabled for given version.

Similar to above, but can also check for extensions which are disabled only for particular versions.

bool Magnum::GL::Context::isExtensionDisabled(const Extension& extension) const

Whether given extension is disabled.

Can be used e.g. for listing extensions available on current hardware, but for general usage prefer isExtensionDisabled() const, as it does most operations in compile time.

void Magnum::GL::Context::resetState(States states = ~States{})

Reset internal state tracker.

The engine internally tracks object bindings and other state to avoid redundant OpenGL calls. In some cases (e.g. when non-Magnum code makes GL calls) the internal tracker no longer reflects actual state. Equivalently the third party code can cause accidental modifications of Magnum objects. It's thus advised to call this function as a barrier between Magnum code and third-party GL code.

The default, when calling this function with no parameters, will reset all state. That's the safest option, but may have considerable performance impact when third-party and Magnum code is combined very often. For greater control it's possible to reset only particular states from the State enum.

See also State tracking and interaction with third-party code for more information.

DetectedDrivers Magnum::GL::Context::detectedDriver()

Detect driver.

Tries to detect driver using various OpenGL state queries. Once the detection is done, the result is cached, repeated queries don't result in repeated GL calls. Used primarily for enabling driver-specific workarounds.

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

Debug output operator.

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

Debug output operator.

Debug& operator<<(Debug& debug, Context::DetectedDriver value)

Debug output operator.

Debug& operator<<(Debug& debug, Context::DetectedDrivers value)

Debug output operator.