gtkmm: Gdk::GLContext Class Reference

A Gdk::GLContext is an OpenGL context abstraction. More...

#include <gdkmm/glcontext.h>

Inheritance diagram for Gdk::GLContext:

[legend]

Public Member Functions
	GLContext (GLContext &&src) noexcept

GLContext &	operator= (GLContext &&src) noexcept

	~GLContext () noexcept override

GdkGLContext *	gobj ()
	Provides access to the underlying C GObject.

const GdkGLContext *	gobj () const
	Provides access to the underlying C GObject.

GdkGLContext *	gobj_copy ()
	Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Glib::RefPtr< Display >	get_display ()
	Retrieves the display the context is created for.

Glib::RefPtr< const Display >	get_display () const
	Retrieves the display the context is created for.

Glib::RefPtr< Surface >	get_surface ()
	Retrieves the surface used by the context.

Glib::RefPtr< const Surface >	get_surface () const
	Retrieves the surface used by the context.

Glib::RefPtr< GLContext >	get_shared_context ()
	Used to retrieves the `Gdk::GLContext` that this context share data with.

Glib::RefPtr< const GLContext >	get_shared_context () const
	Used to retrieves the `Gdk::GLContext` that this context share data with.

void	get_version (int &major, int &minor) const
	Retrieves the OpenGL version of the context.

bool	is_legacy () const
	Whether the `Gdk::GLContext` is in legacy mode or not.

bool	is_shared (const Glib::RefPtr< const GLContext > &other) const
	Checks if the two GL contexts can share resources.

void	get_required_version (int &major, int &minor) const
	Retrieves required OpenGL version set as a requirement for the context realization.

void	set_required_version (int major, int minor)
	Sets the major and minor version of OpenGL to request.

bool	get_debug_enabled () const
	Retrieves whether the context is doing extra validations and runtime checking.

void	set_debug_enabled (bool enabled=true)
	Sets whether the `Gdk::GLContext` should perform extra validations and runtime checking.

bool	get_forward_compatible () const
	Retrieves whether the context is forward-compatible.

void	set_forward_compatible (bool compatible=true)
	Sets whether the `Gdk::GLContext` should be forward-compatible.

void	set_allowed_apis (GLAPI apis)
	Sets the allowed APIs.

GLAPI	get_allowed_apis () const
	Gets the allowed APIs set via set_allowed_apis().

GLAPI	get_api () const
	Gets the API currently in use.

void	set_allowed_apis (GLApi apis)
	Sets the allowed APIs.

GLApi	get_allowed_apis2 () const
	Gets the allowed APIs set via set_allowed_apis().

GLApi	get_api2 () const
	Gets the API currently in use.

void	set_use_es (bool use_es=true)
	Requests that GDK create an OpenGL ES context instead of an OpenGL one.

void	unset_use_es ()
	Undo a previous call to set_use_es().

bool	get_use_es () const
	Checks whether the context is using an OpenGL or OpenGL ES profile.

bool	realize ()
	Realizes the given `Gdk::GLContext`.

void	make_current ()
	Makes the context the current one.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< GLContext > >	property_shared_context () const
	Always `nullptr`

Glib::PropertyProxy< GLAPI >	property_allowed_apis ()
	The allowed APIs.

Glib::PropertyProxy_ReadOnly< GLAPI >	property_allowed_apis () const
	The allowed APIs.

Glib::PropertyProxy_ReadOnly< GLAPI >	property_api () const
	The API currently in use.

Public Member Functions inherited from Gdk::DrawContext
	DrawContext (DrawContext &&src) noexcept

DrawContext &	operator= (DrawContext &&src) noexcept

	~DrawContext () noexcept override

GdkDrawContext *	gobj ()
	Provides access to the underlying C GObject.

const GdkDrawContext *	gobj () const
	Provides access to the underlying C GObject.

GdkDrawContext *	gobj_copy ()
	Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Glib::RefPtr< Display >	get_display ()
	Retrieves the `Gdk::Display` the context is created for.

Glib::RefPtr< const Display >	get_display () const
	Retrieves the `Gdk::Display` the context is created for.

Glib::RefPtr< Surface >	get_surface ()
	Retrieves the surface that context is bound to.

Glib::RefPtr< const Surface >	get_surface () const
	Retrieves the surface that context is bound to.

void	begin_frame (const ::Cairo::RefPtr< const ::Cairo::Region > &region)
	Indicates that you are beginning the process of redrawing region on the context's surface.

void	end_frame ()
	Ends a drawing operation started with begin_frame().

bool	is_in_frame () const
	Returns `true` if context is in the process of drawing to its surface.

::Cairo::RefPtr< const ::Cairo::Region >	get_frame_region () const
	Retrieves the region that is currently being repainted.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Display > >	property_display () const
	The `Gdk::Display` used to create the `Gdk::DrawContext`.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Surface > >	property_surface () const
	The `Gdk::Surface` the context is bound to.

Static Public Member Functions
static GType	get_type ()
	Get the GType for this class, for use with the underlying GObject type system.

static Glib::RefPtr< GLContext >	get_current ()
	Retrieves the current `Gdk::GLContext`.

static void	clear_current ()
	Clears the current `Gdk::GLContext`.

Static Public Member Functions inherited from Gdk::DrawContext
static GType	get_type ()
	Get the GType for this class, for use with the underlying GObject type system.

Protected Member Functions
	GLContext ()

Protected Member Functions inherited from Gdk::DrawContext
	DrawContext ()
	This constructor is protected because only derived classes shall be instantiated.

Related Symbols
(Note that these are not member symbols.)
Glib::RefPtr< Gdk::GLContext >	wrap (GdkGLContext *object, bool take_copy=false)
	A Glib::wrap() method for this object.

Related Symbols inherited from Gdk::DrawContext
Glib::RefPtr< Gdk::DrawContext >	wrap (GdkDrawContext *object, bool take_copy=false)
	A Glib::wrap() method for this object.

Detailed Description

A Gdk::GLContext is an OpenGL context abstraction.

It's a low-level object, used to implement high-level objects such as Gtk::GLArea on the GTK level.

Note: Name clash! GLAPI is defined as a preprocessor macro in epoxy/gl.h. Use GLApi instead of GLAPI. If you include epoxy/gl.h and want to use API with Gdk::GLAPI, you must undef GLAPI.
#include <gdkmm/glcontext.h> // or <gtkmm.h>

#include <epoxy/gl.h>

#undef GLAPI

or
#include <epoxy/gl.h>

#undef GLAPI

#include <gdkmm/glcontext.h> // or <gtkmm.h>

Since gtkmm 3.18:

Constructor & Destructor Documentation

◆ GLContext() [1/2]

Gdk::GLContext::GLContext ( GLContext && src )

noexcept

◆ ~GLContext()

Gdk::GLContext::~GLContext ( )

overridenoexcept

◆ GLContext() [2/2]

Gdk::GLContext::GLContext ( )

protected

Member Function Documentation

◆ clear_current()

static void Gdk::GLContext::clear_current ( )

static

Clears the current Gdk::GLContext.

Any OpenGL call after this function returns will be ignored until make_current() is called.

Since gtkmm 3.18:

◆ get_allowed_apis()

GLAPI Gdk::GLContext::get_allowed_apis ( ) const

Gets the allowed APIs set via set_allowed_apis().

Since gtkmm 4.6:

Deprecated:: Use get_allowed_apis2() instead.

Returns: The allowed APIs.

◆ get_allowed_apis2()

GLApi Gdk::GLContext::get_allowed_apis2 ( ) const

Gets the allowed APIs set via set_allowed_apis().

Since gtkmm 4.8:

Returns: The allowed APIs.

◆ get_api()

GLAPI Gdk::GLContext::get_api ( ) const

Gets the API currently in use.

If the renderer has not been realized yet, 0 is returned.

Since gtkmm 4.6:

Deprecated:: Use get_api2() instead.

Returns: The currently used API.

◆ get_api2()

GLApi Gdk::GLContext::get_api2 ( ) const

Gets the API currently in use.

If the renderer has not been realized yet, 0 is returned.

Since gtkmm 4.8:

Returns: The currently used API.

◆ get_current()

static Glib::RefPtr< GLContext > Gdk::GLContext::get_current ( )

static

Retrieves the current Gdk::GLContext.

Since gtkmm 3.18:

Returns: The current Gdk::GLContext.

◆ get_debug_enabled()

bool Gdk::GLContext::get_debug_enabled ( ) const

Retrieves whether the context is doing extra validations and runtime checking.

See set_debug_enabled().

Since gtkmm 3.18:

Returns: true if debugging is enabled.

◆ get_display() [1/2]

Glib::RefPtr< Display > Gdk::GLContext::get_display ( )

Retrieves the display the context is created for.

Since gtkmm 3.18:

Returns: A Gdk::Display.

◆ get_display() [2/2]

Glib::RefPtr< const Display > Gdk::GLContext::get_display ( ) const

Retrieves the display the context is created for.

Since gtkmm 3.18:

Returns: A Gdk::Display.

◆ get_forward_compatible()

bool Gdk::GLContext::get_forward_compatible ( ) const

Retrieves whether the context is forward-compatible.

See set_forward_compatible().

Since gtkmm 3.18:

Returns: true if the context should be forward-compatible.

◆ get_required_version()

void Gdk::GLContext::get_required_version	(	int &	major,
		int &	minor
	)		const

Retrieves required OpenGL version set as a requirement for the context realization.

It will not change even if a greater OpenGL version is supported and used after the context is realized. See get_version() for the real version in use.

See set_required_version().

Since gtkmm 3.18:

Parameters

major	Return location for the major version to request.
minor	Return location for the minor version to request.

◆ get_shared_context() [1/2]

Glib::RefPtr< GLContext > Gdk::GLContext::get_shared_context ( )

Used to retrieves the Gdk::GLContext that this context share data with.

As many contexts can share data now and no single shared context exists anymore, this function has been deprecated and now always returns nullptr.

Deprecated: 4.4: Use is_shared() to check if contexts can be shared.

Since gtkmm 3.18:

Deprecated:: Always returns an empty RefPtr. Use is_shared() to check if contexts can be shared.

Returns: nullptr.

◆ get_shared_context() [2/2]

Glib::RefPtr< const GLContext > Gdk::GLContext::get_shared_context ( ) const

Used to retrieves the Gdk::GLContext that this context share data with.

As many contexts can share data now and no single shared context exists anymore, this function has been deprecated and now always returns nullptr.

Deprecated: 4.4: Use is_shared() to check if contexts can be shared.

Since gtkmm 3.18:

Deprecated:: Always returns an empty RefPtr. Use is_shared() to check if contexts can be shared.

Returns: nullptr.

◆ get_surface() [1/2]

Glib::RefPtr< Surface > Gdk::GLContext::get_surface ( )

Retrieves the surface used by the context.

Since gtkmm 3.18:

Returns: A Gdk::Surface.

◆ get_surface() [2/2]

Glib::RefPtr< const Surface > Gdk::GLContext::get_surface ( ) const

Retrieves the surface used by the context.

Since gtkmm 3.18:

Returns: A Gdk::Surface.

◆ get_type()

static GType Gdk::GLContext::get_type ( )

static

Get the GType for this class, for use with the underlying GObject type system.

◆ get_use_es()

bool Gdk::GLContext::get_use_es ( ) const

Checks whether the context is using an OpenGL or OpenGL ES profile.

Returns: true if the Gdk::GLContext is using an OpenGL ES profile; false if other profile is in use of if the context has not yet been realized.

◆ get_version()

void Gdk::GLContext::get_version	(	int &	major,
		int &	minor
	)		const

Retrieves the OpenGL version of the context.

The context must be realized prior to calling this function.

Since gtkmm 3.18:

Parameters

major	Return location for the major version.
minor	Return location for the minor version.

◆ gobj() [1/2]

GdkGLContext * Gdk::GLContext::gobj ( )

inline

Provides access to the underlying C GObject.

◆ gobj() [2/2]

const GdkGLContext * Gdk::GLContext::gobj ( ) const

inline

Provides access to the underlying C GObject.

◆ gobj_copy()

GdkGLContext * Gdk::GLContext::gobj_copy ( )

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

◆ is_legacy()

bool Gdk::GLContext::is_legacy ( ) const

Whether the Gdk::GLContext is in legacy mode or not.

The Gdk::GLContext must be realized before calling this function.

When realizing a GL context, GDK will try to use the OpenGL 3.2 core profile; this profile removes all the OpenGL API that was deprecated prior to the 3.2 version of the specification. If the realization is successful, this function will return false.

If the underlying OpenGL implementation does not support core profiles, GDK will fall back to a pre-3.2 compatibility profile, and this function will return true.

You can use the value returned by this function to decide which kind of OpenGL API to use, or whether to do extension discovery, or what kind of shader programs to load.

Returns: true if the GL context is in legacy mode.

◆ is_shared()

bool Gdk::GLContext::is_shared ( const Glib::RefPtr< const GLContext > & other ) const

Checks if the two GL contexts can share resources.

When they can, the texture IDs from other can be used in self. This is particularly useful when passing Gdk::GLTexture objects between different contexts.

Contexts created for the same display with the same properties will always be compatible, even if they are created for different surfaces. For other contexts it depends on the GL backend.

Both contexts must be realized for this check to succeed. If either one is not, this function will return false.

Since gtkmm 4.4:

Parameters

other The Gdk::GLContext that should be compatible with self.

Returns: true if the two GL contexts are compatible.

◆ make_current()

void Gdk::GLContext::make_current ( )

Makes the context the current one.

Since gtkmm 3.18:

◆ operator=()

GLContext & Gdk::GLContext::operator= ( GLContext && src )

noexcept

◆ property_allowed_apis() [1/2]

Glib::PropertyProxy< GLAPI > Gdk::GLContext::property_allowed_apis ( )

The allowed APIs.

Since gtkmm 4.6:

Deprecated:: Use set/get-methods instead.

Default value: Gdk::GLApi::GL | Gdk::GLApi::GLES

Returns: A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

◆ property_allowed_apis() [2/2]

Glib::PropertyProxy_ReadOnly< GLAPI > Gdk::GLContext::property_allowed_apis ( ) const

The allowed APIs.

Since gtkmm 4.6:

Deprecated:: Use set/get-methods instead.

Default value: Gdk::GLApi::GL | Gdk::GLApi::GLES

Returns: A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ property_api()

Glib::PropertyProxy_ReadOnly< GLAPI > Gdk::GLContext::property_api ( ) const

The API currently in use.

Since gtkmm 4.6:

Deprecated:: Use get_api2() instead.

Default value: 0

Returns: A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ property_shared_context()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< GLContext > > Gdk::GLContext::property_shared_context ( ) const

Always nullptr

As many contexts can share data now and no single shared context exists anymore, this function has been deprecated and now always returns nullptr.

Deprecated: 4.4: Use Gdk::GLContext::is_shared() to check if contexts can be shared.

Since gtkmm 3.18:

Deprecated:: Always returns an empty RefPtr. Use is_shared() to check if contexts can be shared.

Returns: A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ realize()

bool Gdk::GLContext::realize ( )

Realizes the given Gdk::GLContext.

It is safe to call this function on a realized Gdk::GLContext.

Since gtkmm 3.18:

Returns: true if the context is realized.

Exceptions

Glib::Error

◆ set_allowed_apis() [1/2]

void Gdk::GLContext::set_allowed_apis ( GLAPI apis )

Sets the allowed APIs.

When realize() is called, only the allowed APIs will be tried. If you set this to 0, realizing will always fail.

If you set it on a realized context, the property will not have any effect. It is only relevant during realize().

By default, all APIs are allowed.

Since gtkmm 4.6:

Deprecated:: Use set_allowed_apis(GLApi apis) instead.

Parameters

apis	The allowed APIs.

◆ set_allowed_apis() [2/2]

void Gdk::GLContext::set_allowed_apis ( GLApi apis )

Sets the allowed APIs.

When realize() is called, only the allowed APIs will be tried. If you set this to 0, realizing will always fail.

If you set it on a realized context, the property will not have any effect. It is only relevant during realize().

By default, all APIs are allowed.

Since gtkmm 4.8:

Parameters

apis	The allowed APIs.

◆ set_debug_enabled()

void Gdk::GLContext::set_debug_enabled ( bool enabled = true )

Sets whether the Gdk::GLContext should perform extra validations and runtime checking.

This is useful during development, but has additional overhead.

The Gdk::GLContext must not be realized or made current prior to calling this function.

Since gtkmm 3.18:

Parameters

enabled Whether to enable debugging in the context.

◆ set_forward_compatible()

void Gdk::GLContext::set_forward_compatible ( bool compatible = true )

Sets whether the Gdk::GLContext should be forward-compatible.

Forward-compatible contexts must not support OpenGL functionality that has been marked as deprecated in the requested version; non-forward compatible contexts, on the other hand, must support both deprecated and non deprecated functionality.

The Gdk::GLContext must not be realized or made current prior to calling this function.

Since gtkmm 3.18:

Parameters

compatible Whether the context should be forward-compatible.

◆ set_required_version()

void Gdk::GLContext::set_required_version	(	int	major,
		int	minor
	)

Sets the major and minor version of OpenGL to request.

Setting major and minor to zero will use the default values.

Setting major and minor lower than the minimum versions required by GTK will result in the context choosing the minimum version.

The context must not be realized or made current prior to calling this function.

Since gtkmm 3.18:

Parameters

major	The major version to request.
minor	The minor version to request.

◆ set_use_es()

void Gdk::GLContext::set_use_es ( bool use_es = true )

Requests that GDK create an OpenGL ES context instead of an OpenGL one.

Not all platforms support OpenGL ES.

The context must not have been realized.

By default, GDK will attempt to automatically detect whether the underlying GL implementation is OpenGL or OpenGL ES once the context is realized.

You should check the return value of get_use_es() after calling realize() to decide whether to use the OpenGL or OpenGL ES API, extensions, or shaders.

Deprecated:: Use set_allowed_apis(GLApi apis) instead.

Parameters

use_es Whether the context should use OpenGL ES instead of OpenGL, or -1 to allow auto-detection.

◆ unset_use_es()

void Gdk::GLContext::unset_use_es ( )

Undo a previous call to set_use_es().

GDK will attempt to automatically detect whether the underlying GL implementation is OpenGL or OpenGL ES once the GLContext is realized.

Since gtkmm 3.24:

Deprecated:: Use set_allowed_apis(GLApi apis) instead.

Friends And Related Symbol Documentation

◆ wrap()

Glib::RefPtr< Gdk::GLContext > wrap	(	GdkGLContext *	object,
		bool	take_copy = `false`
	)

A Glib::wrap() method for this object.

Parameters

object	The C instance.
take_copy	False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns: A C++ instance that wraps this C instance.

Public Member Functions

Static Public Member Functions

Protected Member Functions

Related Symbols

Detailed Description

Constructor & Destructor Documentation

◆ GLContext() [1/2]

◆ ~GLContext()

◆ GLContext() [2/2]

Member Function Documentation

◆ clear_current()

◆ get_allowed_apis()

◆ get_allowed_apis2()

◆ get_api()

◆ get_api2()

◆ get_current()

◆ get_debug_enabled()

◆ get_display() [1/2]

◆ get_display() [2/2]

◆ get_forward_compatible()

◆ get_required_version()

◆ get_shared_context() [1/2]

◆ get_shared_context() [2/2]

◆ get_surface() [1/2]

◆ get_surface() [2/2]

◆ get_type()

◆ get_use_es()

◆ get_version()

◆ gobj() [1/2]

◆ gobj() [2/2]

◆ gobj_copy()

◆ is_legacy()

◆ is_shared()

◆ make_current()

◆ operator=()

◆ property_allowed_apis() [1/2]

◆ property_allowed_apis() [2/2]

◆ property_api()

◆ property_shared_context()

◆ realize()

◆ set_allowed_apis() [1/2]

◆ set_allowed_apis() [2/2]

◆ set_debug_enabled()

◆ set_forward_compatible()

◆ set_required_version()

◆ set_use_es()

◆ unset_use_es()

Friends And Related Symbol Documentation

◆ wrap()