The OpenGL context API interface that is used by the OpenGL backend to interact with the platform. More...

#include <kanzi/platform/platform/gl/common/gl_graphics_context.hpp>

Inheritance diagram for kanzi::platform::GlGraphicsContext:

Classes
struct	InitializationInfo
	The initialization parameters for the OpenGL context API. More...

struct	SurfaceContextHandle
	The SurfaceContext handle is used to identify an OpenGL context that is used by the rendering thread. More...

struct	SurfaceHandle
	The Surface handle is used to identify a platform surface that can be used as a target for OpenGL rendering. More...

struct	ThreadContextHandle
	The ThreadContext handle is used to identify an OpenGL context that is used by user threads to perform OpenGL operations on behalf of the rendering thread. More...

Public Member Functions
virtual SurfaceHandle	createSurface (NativeSurfaceHandle windowHandle, const SurfaceProperties &properties)=0
	Creates a new Surface, potentially a new GL Context for the surface.

virtual ThreadContextHandle	createThreadContext ()=0
	Creates a new headless OpenGL context that is shared with the default context.

virtual bool	destroySurface (SurfaceHandle surface)=0
	Destroy a created SurfaceHandle.

virtual void	destroyThreadContext (ThreadContextHandle context)=0
	Destroys the Thread context.

virtual SurfaceContextHandle	getCurrentSurfaceContext ()=0
	Gets the currently active SurfaceContextHandle.

virtual void *	getGLProcAddress (const char *name)=0
	Gets the address of an OpenGL entry point.

template<typename Return , typename... Args>
bool	getGLProcAddressInto (function_ptr< Return, Args... > &proc, const char *pName)
	Dynamically loads a GL function pointer into specified location.

virtual SurfaceContextHandle	getSurfaceGLContext (SurfaceHandle surface)=0
	Gets the SurfaceContextHandle associated with the given surface.

virtual SurfaceProperties	getSurfaceProperties (SurfaceHandle surface)=0
	Gets the SurfaceProperties for a given SurfaceHandle object.

virtual vector< SurfaceHandle >	getSurfaces (SurfaceContextHandle context)=0
	Gets the surfaces associated with a context.

virtual bool	initialize ()=0
	Initializes the OpenGL context API and creates a default headless SurfaceContext that can be used for off screen rendering.

virtual bool	isFeatureEnabled (PlatformFeatureId feature) const =0
	Tests if a platform FeatureId is enabled on the current platform.

virtual void	makeSurfaceCurrent (SurfaceHandle surface)=0
	Makes the requested SurfaceHandle current.

virtual void	makeThreadCurrent (ThreadContextHandle context)=0
	Makes the ThreadContextHandle active on the current thread.

virtual void	shutdown ()=0
	Shuts down the OpenGL context API.

virtual bool	swapBuffers (SurfaceHandle surface)=0
	Swaps the buffers associated with the SurfaceHandle.

virtual void	updateSurfaceDimensions (SurfaceHandle surface, uint32_t width, uint32_t height)
	Brings a surface in line with new dimensions of its native surface.

virtual	~GlGraphicsContext ()=default
	Destructor.

Detailed Description

The OpenGL context API interface that is used by the OpenGL backend to interact with the platform.

The threads that use thread contexts call makeThreadCurrent() and destroyThreadContext(), and the rendering thread calls the other functions. An implementation must keep its bookkeeping of contexts and surfaces consistent across those threads.

Since: Kanzi 4.0.0; Kanzi 4.1.0 renamed from GlContextApi.

Attention: This feature is experimental and is likely to change in future releases.

Constructor & Destructor Documentation

◆ ~GlGraphicsContext()

virtual kanzi::platform::GlGraphicsContext::~GlGraphicsContext ( )

virtualdefault

Destructor.

Member Function Documentation

◆ initialize()

virtual bool kanzi::platform::GlGraphicsContext::initialize ( )

pure virtual

Initializes the OpenGL context API and creates a default headless SurfaceContext that can be used for off screen rendering.

The newly created context is made current on the calling thread.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ shutdown()

virtual void kanzi::platform::GlGraphicsContext::shutdown ( )

pure virtual

Shuts down the OpenGL context API.

This will invalidate all SurfaceHandle, SurfaceContextHandle, and ThreadContextHandle instances. After this call, it is possible to call initialize() again.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ swapBuffers()

virtual bool kanzi::platform::GlGraphicsContext::swapBuffers ( SurfaceHandle surface )

pure virtual

Swaps the buffers associated with the SurfaceHandle.

Parameters

surface The surface will be swapped.

Returns: true if the operation was successful.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::EglOhosGraphicsContext, kanzi::platform::EglQnxStreamsGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ createThreadContext()

virtual ThreadContextHandle kanzi::platform::GlGraphicsContext::createThreadContext ( )

pure virtual

Creates a new headless OpenGL context that is shared with the default context.

Returns: The newly created ThreadContextHandle.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ destroyThreadContext()

virtual void kanzi::platform::GlGraphicsContext::destroyThreadContext ( ThreadContextHandle context )

pure virtual

Destroys the Thread context.

Called on the thread that owns the context, once that thread no longer uses it.

Parameters

context The thread context to be destroyed.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ createSurface()

virtual SurfaceHandle kanzi::platform::GlGraphicsContext::createSurface	(	NativeSurfaceHandle	windowHandle,
		const SurfaceProperties &	properties )

pure virtual

Creates a new Surface, potentially a new GL Context for the surface.

Also calls makeSurfaceCurrent on the new surface.

If the default context can render this surface, the default context must be used. Otherwise, surfaces with a compatible format must share a context. The OpenGL backend makes its own copies of the OpenGL objects that cannot be shared in each context, so every additional context costs memory and context switches.

Parameters

windowHandle	Opaque platform specific window handle.
properties	The requested surface properties.

Returns: The newly created surface handle.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ destroySurface()

virtual bool kanzi::platform::GlGraphicsContext::destroySurface ( SurfaceHandle surface )

pure virtual

Destroy a created SurfaceHandle.

When the surface is the last surface of a context other than the default context, the context is destroyed too.

Parameters

surface The surface handle to destroy.

Returns: If the surface was found and destroyed, true, otherwise false.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ getSurfaceProperties()

virtual SurfaceProperties kanzi::platform::GlGraphicsContext::getSurfaceProperties ( SurfaceHandle surface )

pure virtual

Gets the SurfaceProperties for a given SurfaceHandle object.

Parameters

surface The surface handle to query.

Returns: The actual surface properties of the created surface.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ getSurfaceGLContext()

virtual SurfaceContextHandle kanzi::platform::GlGraphicsContext::getSurfaceGLContext ( SurfaceHandle surface )

pure virtual

Gets the SurfaceContextHandle associated with the given surface.

If the SurfaceHandle is the empty surface, the SurfaceContextHandle for the default context is returned.

Parameters

surface The surface handle.

Returns: The surface context handle.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ makeSurfaceCurrent()

virtual void kanzi::platform::GlGraphicsContext::makeSurfaceCurrent ( SurfaceHandle surface )

pure virtual

Makes the requested SurfaceHandle current.

If a compatible context is already active, no changes are made.

If the surface is the empty surface, the implementation must make the default context current on the calling thread, and can leave it bound to any surface that it renders. The OpenGL backend makes the empty surface current before work that does not render to a surface, such as creating resources or rendering to a framebuffer object, so it never uses the default framebuffer then. This lets an implementation skip the make-current call when the default context is already current with one of its surfaces.

Parameters

surface The surface handle to make current.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ getCurrentSurfaceContext()

virtual SurfaceContextHandle kanzi::platform::GlGraphicsContext::getCurrentSurfaceContext ( )

pure virtual

Gets the currently active SurfaceContextHandle.

Returns: The currently active surface context handle.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ getSurfaces()

virtual vector< SurfaceHandle > kanzi::platform::GlGraphicsContext::getSurfaces ( SurfaceContextHandle context )

pure virtual

Gets the surfaces associated with a context.

Parameters

context The context to query.

Returns: A list of surface handles associated with the context.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ getGLProcAddress()

virtual void * kanzi::platform::GlGraphicsContext::getGLProcAddress ( const char * name )

pure virtual

Gets the address of an OpenGL entry point.

Parameters

name	The name of the entry point.

Returns: The pointer to the OpenGL entry point.

Since: Kanzi 4.1.0 renamed from getOGLProcAddress.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ getGLProcAddressInto()

template<typename Return , typename... Args>

bool kanzi::platform::GlGraphicsContext::getGLProcAddressInto	(	function_ptr< Return, Args... > &	proc,
		const char *	pName )

inline

Dynamically loads a GL function pointer into specified location.

Template Parameters

Return	GL function return type.
Args	GL function argument types.

Parameters

proc	Out parameter for GL function pointer.
pName	GL function name.

Returns: On success, true, otherwise false.

Since: Kanzi 4.1.0

◆ makeThreadCurrent()

virtual void kanzi::platform::GlGraphicsContext::makeThreadCurrent ( ThreadContextHandle context )

pure virtual

Makes the ThreadContextHandle active on the current thread.

Must be on non-rendering threads.

Calling makeThreadCurrent with a default constructed ThreadContextHandle will release the context from the current thread and leave no context current.

Parameters

context The thread context to make current.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ isFeatureEnabled()

virtual bool kanzi::platform::GlGraphicsContext::isFeatureEnabled ( PlatformFeatureId feature ) const

pure virtual

Tests if a platform FeatureId is enabled on the current platform.

Parameters

feature The FeatureId to test.

Returns: True if the feature is supported, else false.

Implemented in kanzi::platform::EglGraphicsContext, kanzi::platform::GlxGraphicsContext, and kanzi::platform::WglGraphicsContext.

◆ updateSurfaceDimensions()

virtual void kanzi::platform::GlGraphicsContext::updateSurfaceDimensions	(	SurfaceHandle	surface,
		uint32_t	width,
		uint32_t	height )

inlinevirtual

Brings a surface in line with new dimensions of its native surface.

The OpenGL backend calls this on the rendering thread when the native surface is resized, before it renders the surface at the new dimensions. Implement this when a surface can keep a size that its native surface no longer has, for example because the next buffer is acquired when the previous one is presented. The default implementation does nothing.

Parameters

surface	The surface handle.
width	The new width of the native surface in pixels.
height	The new height of the native surface in pixels.

Since: Kanzi 4.1.2

Reimplemented in kanzi::platform::EglGraphicsContext.

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

kanzi/platform/platform/gl/common/gl_graphics_context.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~GlGraphicsContext()

Member Function Documentation

◆ initialize()

◆ shutdown()

◆ swapBuffers()

◆ createThreadContext()

◆ destroyThreadContext()

◆ createSurface()

◆ destroySurface()

◆ getSurfaceProperties()

◆ getSurfaceGLContext()

◆ makeSurfaceCurrent()

◆ getCurrentSurfaceContext()

◆ getSurfaces()

◆ getGLProcAddress()

◆ getGLProcAddressInto()

◆ makeThreadCurrent()

◆ isFeatureEnabled()

◆ updateSurfaceDimensions()