Detailed Description

Singleton class to manage access to OpenGL contexts.

The ContextManager maintains two OpenGL contexts for the ImFusion SDK:

The main context, which will be associated with the application's main thread. It can be queried through ContextManager::mainContext() and used for all OpenGL processing happening in the main thread. Other parts of the SDK (e.g. DisplayWidget) will implicitly use this context for their needs.
The background context, which will be associated with the ContextManager's background processing thread. This will be used every time you use the runWithOpenGL() interface from any other thread than the main thread.

Note: Initialization and deinitialization is handled through GL::init() and GL::deinit(). Trying to access this class without the GL back end being initialized will yield undefined behavior.

Public Member Functions
std::unique_ptr< Context >	createContext ()
	Convenience method to create a OpenGL context for the calling thread.

void	ensureLocalContext ()
	Convenience method that creates a GL context for the local thread if necessary.

void	releaseLocalContext ()
	Delete a local context previously created by ensureLocalContext() and free its resources.

void	runWithOpenGL (const std::function< void()> &func, bool forceBackgroundThread=false)
	Ensures that the given function is run in a valid OpenGL context.

Context *	mainContext () const
	Access the main OpenGL context instance.

Static Public Member Functions
static ContextManager &	get ()
	Return the singleton instance of the manager.

static bool	hasCurrent ()
	Returns whether the calling thread has a current OpenGL context.

static bool	makeCurrent ()
	Convenience method to make the main context current.

static bool	doneCurrent ()
	Convenience method to release the currently active context of the calling thread. Can be called from any thread.

static void *	currentContextId ()
	Returns a platform-specific handle to the currently active OpenGL context.

static bool	useCoreContext ()

static bool	openGlDisabled ()

Member Function Documentation

◆ createContext()

std::unique_ptr< Context > createContext ( )

Convenience method to create a OpenGL context for the calling thread.

The context will be shared with the main and background context. This function returns nullptr if called from the main or background processing thread because creating another local context would violate the one-context-per-thread rule.

Note: The function returns a unique_ptr to the created context. The pointer must not go out of scope until it is no longer needed. When the pointer goes out of scope, the context will be destroyed and OpenGL will no longer be available for this thread.

Example:

std::thread newThread([]() {
    std::unique_ptr<Context> ctx = ContextManager::get().createContext();
    // OpenGL will be available in this thread as long as `ctx` remains alive
});

◆ ensureLocalContext()

void ensureLocalContext ( )

Convenience method that creates a GL context for the local thread if necessary.

If a GL context already exists for the calling thread (i.e. because it is the main or background thread, or because this function has already been called in the same thread), it will do nothing. It is safe to just call this function once before making use of OpenGL in code where the executing thread is undetermined (e.g. thread pool) to avoid problems related to the absence of a GL context.

Warning: A context created by this function will stay alive until the termination of the program or a call to releaseLocalContext() on the same thread. An OpenGL context is an expensive resource and you can easily swamp your system when using this function carelessly! Do not use this function out of laziness but only if manually managing a per-thread context (e.g. using createContext()) is not possible.

◆ releaseLocalContext()

void releaseLocalContext ( )

Delete a local context previously created by ensureLocalContext() and free its resources.

This function will do nothing if the current thread does not have a local context.

◆ runWithOpenGL()

void runWithOpenGL	(	const std::function< void()> &	func,
		bool	forceBackgroundThread = false )

Ensures that the given function is run in a valid OpenGL context.

If the calling thread has a current OpenGL context and forceBackgroundThread is false it will call func directly. Otherwise it will run func in a separate thread using the background OpenGL thread managed by ContextManager.

Warning: The blocking nature of this function makes it susceptible to deadlocks in certain call graphs. Prefer using createContext() in order to make OpenGL available in custom threads.

Parameters

func	Function object to call from a valid OpenGL context.
forceBackgroundThread	Set to true to force execution on background thread.

◆ makeCurrent()

static bool makeCurrent ( )

static

Convenience method to make the main context current.

Will only work if called from the main thread.

Warning: Calling this function from any other thread than the main thread is not allowed. In such case the function will not have any effect and return false.

◆ currentContextId()

static void * currentContextId ( )

static

Returns a platform-specific handle to the currently active OpenGL context.

Note: There is a 1-to-1 mapping of existing OpenGL contexts to the pointers returned. If there is no context current, this function will return 0. Apart from this you can not make any assumptions on the underlying type of the return value.

The documentation for this class was generated from the following file:

ImFusion/Core/GL/ContextManager.h