class
#include <Magnum/GL/Context.h>
Context Magnum OpenGL context.
Provides access to OpenGL version and extension information and manages Magnum's internal OpenGL state tracker.
Creating a context
In order to use any Magnum OpenGL functionality, an instance of this class has to exist and be made current. If you use any Platform::*Application
classes, an instance available through Context::*Application
lifetime. It's also possible to create the context without using any *Application
class using the Platform::
Various options can be passed using the Configuration class, which is then extended by various Platform::
Command-line options
In addition to the Configuration, the context is configurable through command-line options, that are passed either from the Platform::*Application
classes or from the Platform::
<application> [--magnum-help] [--magnum-disable-workarounds LIST] [--magnum-disable-extensions LIST] [--magnum-gpu-validation off|on] [--magnum-log default|quiet|verbose] ...
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
). Corresponds to Configuration::addDisabledWorkarounds(). --magnum-disable-extensions LIST
— API extensions to disable (environment:MAGNUM_DISABLE_EXTENSIONS
). Corresponds to Configuration::addDisabledExtensions(). --magnum-gpu-validation off|on|no-error
— GPU validation using KHR_debug, if present (environment: MAGNUM_GPU_VALIDATION
) (default:off
). This sets up DebugOutput callbacks and also causes GLConfiguration::Flag:: Debug to be enabled for context creation for both windowed and windowless applications on supported platforms. Corresponds to Configuration:: Flag:: GpuValidation / Configuration:: Flag:: GpuValidationNoError. --magnum-log default|quiet|verbose
— console logging (environment:MAGNUM_LOG
) (default:default
). Corresponds to Configuration::Flag:: QuietLog and VerboseLog.
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::
Particular application implementations add more options for DPI scaling or GPU selection, see Platform::
Using multiple OpenGL contexts
By default, Magnum assumes you have one OpenGL context active at all times, and all state tracking is done by the Context instance that's associated with it. When you are using multiple OpenGL contexts, each of them needs to have a corresponding Context instance active at the same time, and you need to ensure you only access OpenGL objects that were created by the same context as is currently active.
To prevent accidents in common cases, the Context class expects that no other instance is active during its creation. In order to create additional instances for other OpenGL contexts, first you need to "unset" the current one with makeCurrent() and then create another instance, which will then become implicitly active:
Platform::GLContext context; SDL_GL_MakeCurrent(_window, _otherGLContext); // or other platform-specific API Platform::GLContext::makeCurrent(nullptr); Platform::GLContext other;
Once all needed instances are created, switch between them right after making the underlying GL context current:
Platform::GLContext::makeCurrent(&context); GL::Buffer a; // implicitly tied to `context` Platform::GLContext::makeCurrent(&other); GL::Buffer b; // implicitly tied to `other`
Thread safety
If Corrade is compiled with CORRADE_
Derived classes
- class Magnum::Platform::GLContext
- Platform-specific OpenGL context.
Public types
- class Configuration new in Git master
- Configuration.
- enum class Flag: GLint { Debug = GL_CONTEXT_FLAG_DEBUG_BIT, ForwardCompatible = GL_CONTEXT_FLAG_FORWARD_COMPATIBLE_BIT, NoError = GL_CONTEXT_FLAG_NO_ERROR_BIT, RobustAccess = GL_CONTEXT_FLAG_ROBUST_ACCESS_BIT }
- Context flag.
- enum class State: UnsignedInt { Buffers = 1 << 0, UnbindPixelBuffer = 1 << 1, Framebuffers = 1 << 2, Meshes = 1 << 3, MeshVao = 1 << 4, BindScratchVao = 1 << 5, PixelStorage = 1 << 6, Renderer = 1 << 7, Shaders = 1 << 8, Textures = 1 << 9, TransformFeedback = 1 << 10, EnterExternal = MeshVao |UnbindPixelBuffer, ExitExternal = Buffers|Framebuffers|Meshes|MeshVao|PixelStorage|Renderer|Shaders|Textures |TransformFeedback }
- State to reset.
- enum class DetectedDriver: UnsignedShort { Amd = 1 << 0, Angle = 1 << 1, IntelWindows = 1 << 2, Mesa = 1 << 3, NVidia = 1 << 4, Svga3D = 1 << 5, SwiftShader = 1 << 6 new in 2019.10, ArmMali = 1 << 7 new in 2019.10, QualcommAdreno = 1 << 8 new in Git master }
- 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.
- static void makeCurrent(Context* context) new in 2019.10
- Make a context current.
Constructors, destructors, conversion operators
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 -> Containers::
StringView - Vendor string.
-
auto vendorStringUnmasked() const -> Containers::
StringView new in Git master - Unmasked vendor string.
-
auto rendererString() const -> Containers::
StringView - Renderer string.
-
auto rendererStringUnmasked() const -> Containers::
StringView new in Git master - Unmasked renderer string.
-
auto versionString() const -> Containers::
StringView - Version string.
-
auto shadingLanguageVersionString() const -> Containers::
StringView - Shading language version string.
-
auto shadingLanguageVersionStrings() const -> Containers::
Array<Containers:: StringView> - Shading language version strings.
-
auto extensionStrings() const -> Containers::
Array<Containers:: StringView> - Extension strings.
- auto flags() const -> Flags
- Context flags.
-
auto supportedExtensions() const -> Containers::
ArrayView<const Extension> deprecated in Git master - 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 E>auto isExtensionSupported() const -> bool
- Whether given extension is supported.
-
template<class E>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 E>auto isExtensionDisabled() const -> bool
- Whether given extension is disabled.
-
template<class E>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. Enabled automatically by Platform windowed and windowless application implementations if the Configuration:: |
ForwardCompatible |
Forward compatible context |
NoError |
Context without error reporting. Enabled automatically by Platform windowed and windowless application implementations if the Configuration:: |
RobustAccess |
Context with robust access |
enum class Magnum:: GL:: Context:: State: UnsignedInt
State to reset.
Enumerators | |
---|---|
Buffers |
Reset tracked buffer-related bindings and state |
UnbindPixelBuffer |
Unbind currently bound PBO. Not all third-party code is aware of PBOs, and if a PBO is bound when Magnum transfers control to an unaware code, it can cause various issues with textures. This is a similar, but rarer, case to 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:: |
BindScratchVao |
Bind a "scratch" VAO on core profile. Use if external code is not VAO-aware and would otherwise try to enable vertex attributes on the default (zero) VAO, causing GL errors. Meant to be used together with State:: Does nothing on compatibility profile and ES / WebGL platforms, as using the default VAO is allowed there. |
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 State:: |
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, however State:: |
enum class Magnum:: GL:: Context:: DetectedDriver: UnsignedShort
Detected driver.
On WebGL, if WEBGL_
Enumerators | |
---|---|
Amd |
Proprietary AMD desktop drivers on Windows and Linux. In contrast, AMDGPU Mesa drivers report as DetectedDriver:: |
Angle |
OpenGL ES implementation by ANGLE (translated to D3D), used by browsers on Windows for WebGL. See also DetectedDriver:: |
IntelWindows |
Intel desktop drivers on Windows |
Mesa |
Mesa drivers on Windows and Linux. In particular, Intel, AMD and NVidia Mesa drivers match as this. See also DetectedDriver:: |
NVidia |
Proprietary NVidia drivers on Windows and Linux |
Svga3D |
VMware guest GL driver SVGA3D, implemented using Mesa, both Windows and Linux guests. See https:/ |
SwiftShader new in 2019.10 |
SwiftShader software renderer for OpenGL ES. Usually used by browsers in cases where a GPU isn't available. See also DetectedDriver:: |
ArmMali new in 2019.10 |
ARM Mali drivers on OpenGL ES. |
QualcommAdreno new in Git master |
Qualcomm Adreno drivers for OpenGL ES. |
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 Corrade is built with CORRADE_
static Context& Magnum:: GL:: Context:: current()
Current context.
Expect that there is current context. If Corrade is built with CORRADE_
static void Magnum:: GL:: Context:: makeCurrent(Context* context) new in 2019.10
Make a context current.
To be used when you need to manage multiple OpenGL contexts. See Using multiple OpenGL contexts for more information.
Containers:: StringView Magnum:: GL:: Context:: vendorString() const
Vendor string.
The result is not cached, repeated queries will result in repeated OpenGL calls. The returned view is always Containers::
Containers:: StringView Magnum:: GL:: Context:: vendorStringUnmasked() const new in Git master
Unmasked vendor string.
A WebGL counterpart to vendorString() that returns the real vendor string. If WEBGL_
The result is not cached, repeated queries will result in repeated OpenGL calls. The returned view is always Containers::
Containers:: StringView Magnum:: GL:: Context:: rendererString() const
Renderer string.
The result is not cached, repeated queries will result in repeated OpenGL calls. The returned view is always Containers::
Containers:: StringView Magnum:: GL:: Context:: rendererStringUnmasked() const new in Git master
Unmasked renderer string.
A WebGL counterpart to rendererString() that returns the real renderer string. If WEBGL_
The result is not cached, repeated queries will result in repeated OpenGL calls. The returned view is always Containers::
Containers:: StringView Magnum:: GL:: Context:: versionString() const
Version string.
The result is not cached, repeated queries will result in repeated OpenGL calls. The returned view is always Containers::
Containers:: StringView Magnum:: GL:: Context:: shadingLanguageVersionString() const
Shading language version string.
The result is not cached, repeated queries will result in repeated OpenGL calls. The returned view is always Containers::
Containers:: Array<Containers:: StringView> Magnum:: GL:: Context:: shadingLanguageVersionStrings() const
Shading language version strings.
The result is not cached, repeated queries will result in repeated OpenGL calls. The returned view is always Containers::
Containers:: Array<Containers:: StringView> 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 Extension::
Containers:: ArrayView<const 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::
template<class E>
bool Magnum:: GL:: Context:: isExtensionSupported() const
Whether given extension is supported.
Extensions usable with this function are listed in the Extensions namespace in the Magnum/
if(GL::Context::current().isExtensionSupported<GL::Extensions::ARB::tessellation_shader>()) { // draw fancy detailed model } else { // texture fallback }
template<class E>
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 E>
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 E>
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 at 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.