Class: Gdk::GLContext

Inherits:

DrawContext

• Object
• DrawContext
• Gdk::GLContext

Defined in:

(unknown)

Overview

GdkGLContext is an object representing a platform-specific OpenGL draw context.

GdkGLContexts are created for a surface using [methodGdk.Surface.create_gl_context], and the context will match the characteristics of the surface.

A GdkGLContext is not tied to any particular normal framebuffer. For instance, it cannot draw to the surface back buffer. The GDK repaint system is in full control of the painting to that. Instead, you can create render buffers or textures and use [funccairo_draw_from_gl] in the draw function of your widget to draw them. Then GDK will handle the integration of your rendering with that of other widgets.

Support for GdkGLContext is platform-specific and context creation can fail, returning nil context.

A GdkGLContext has to be made "current" in order to start using it, otherwise any OpenGL call will be ignored.

Creating a new OpenGL context

In order to create a new GdkGLContext instance you need a GdkSurface, which you typically get during the realize call of a widget.

A GdkGLContext is not realized until either [methodGdk.GLContext.make_current] or [methodGdk.GLContext.realize] is called. It is possible to specify details of the GL context like the OpenGL version to be used, or whether the GL context should have extra state validation enabled after calling [methodGdk.Surface.create_gl_context] by calling [methodGdk.GLContext.realize]. If the realization fails you have the option to change the settings of the GdkGLContext and try again.

Using a GdkGLContext

You will need to make the GdkGLContext the current context before issuing OpenGL calls; the system sends OpenGL commands to whichever context is current. It is possible to have multiple contexts, so you always need to ensure that the one which you want to draw with is the current one before issuing commands:

gdk_gl_context_make_current (context);

You can now perform your drawing using OpenGL commands.

You can check which GdkGLContext is the current one by using [funcGdk.GLContext.get_current]; you can also unset any GdkGLContext that is currently set by calling [funcGdk.GLContext.clear_current].

Direct Known Subclasses

GdkX11::X11GLContext

Class Method Summary

• .clear_current ⇒ nil

  Clears the current GdkGLContext.

• .current ⇒ Gdk::GLContext

  Retrieves the current GdkGLContext.

Instance Method Summary

• #allowed_apis ⇒ Gdk::GLAPI

  The allowed APIs.

• #allowed_apis=(allowed_apis) ⇒ Gdk::GLAPI

  The allowed APIs.

• #api ⇒ Gdk::GLAPI

  The API currently in use.

• #api=(api) ⇒ Gdk::GLAPI

  The API currently in use.

• #debug_enabled ⇒ Boolean

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

• #debug_enabled=(enabled) ⇒ nil

  Sets whether the GdkGLContext should perform extra validations and runtime checking.

• #display ⇒ Gdk::Display

  Retrieves the display the context is created for.

• #forward_compatible ⇒ Boolean

  Retrieves whether the context is forward-compatible.

• #forward_compatible=(compatible) ⇒ nil

  Sets whether the GdkGLContext should be forward-compatible.

• #get_required_version(major, minor) ⇒ nil

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

• #get_version(major, minor) ⇒ nil

  Retrieves the OpenGL version of the context.

• #is_legacy ⇒ Boolean

  Whether the GdkGLContext is in legacy mode or not.

• #is_shared(other) ⇒ Boolean

  Checks if the two GL contexts can share resources.

• #make_current ⇒ nil

  Makes the context the current one.

• #realize ⇒ Boolean

  Realizes the given GdkGLContext.

• #set_required_version(major, minor) ⇒ nil

  Sets the major and minor version of OpenGL to request.

• #shared_context ⇒ Gdk::GLContext

  Always nil.

• #shared_context=(shared_context) ⇒ Gdk::GLContext

  Always nil.

• #surface ⇒ Gdk::Surface

  Retrieves the surface used by the context.

• #use_es ⇒ Boolean

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

• #use_es=(use_es) ⇒ nil

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

Methods inherited from DrawContext

#begin_frame, #display=, #end_frame, #frame_region, #is_in_frame, #surface=

Class Method Details

.clear_current ⇒ nil

Clears the current GdkGLContext.

Any OpenGL call after this function returns will be ignored until [methodGdk.GLContext.make_current] is called.

Returns:

• (nil)

.current ⇒ Gdk::GLContext

Retrieves the current GdkGLContext.

Returns:

• (Gdk::GLContext) —

  the current GdkGLContext

Instance Method Details

#allowed_apis ⇒ Gdk::GLAPI

The allowed APIs.

Returns:

• (Gdk::GLAPI) —

  allowed-apis

#allowed_apis=(allowed_apis) ⇒ Gdk::GLAPI

The allowed APIs.

Parameters:

• allowed_apis (Gdk::GLAPI)

Returns:

• (Gdk::GLAPI) —

  allowed-apis

• (Gdk::GLAPI) —

  allowed-apis

#api ⇒ Gdk::GLAPI

The API currently in use.

Returns:

• (Gdk::GLAPI) —

  api

#api=(api) ⇒ Gdk::GLAPI

The API currently in use.

Parameters:

• api (Gdk::GLAPI)

Returns:

• (Gdk::GLAPI) —

  api

• (Gdk::GLAPI) —

  api

#debug_enabled ⇒ Boolean

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

See [methodGdk.GLContext.set_debug_enabled].

Returns:

• (Boolean) —

  true if debugging is enabled

#debug_enabled=(enabled) ⇒ nil

Sets whether the GdkGLContext should perform extra validations and runtime checking.

This is useful during development, but has additional overhead.

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

Parameters:

• enabled (Boolean) —

  whether to enable debugging in the context

Returns:

• (nil)

#display ⇒ Gdk::Display

Retrieves the display the context is created for

Returns:

• (Gdk::Display) —

  a GdkDisplay

#forward_compatible ⇒ Boolean

Retrieves whether the context is forward-compatible.

See [methodGdk.GLContext.set_forward_compatible].

Returns:

• (Boolean) —

  true if the context should be forward-compatible

#forward_compatible=(compatible) ⇒ nil

Sets whether the GdkGLContext 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 GdkGLContext must not be realized or made current prior to calling this function.

Parameters:

• compatible (Boolean) —

  whether the context should be forward-compatible

Returns:

• (nil)

#get_required_version(major, minor) ⇒ nil

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 [methodGdk.GLContext.get_version] for the real version in use.

See [methodGdk.GLContext.set_required_version].

Parameters:

• major (Integer) —

  return location for the major version to request

• minor (Integer) —

  return location for the minor version to request

Returns:

• (nil)

#get_version(major, minor) ⇒ nil

Retrieves the OpenGL version of the context.

The context must be realized prior to calling this function.

Parameters:

• major (Integer) —

  return location for the major version

• minor (Integer) —

  return location for the minor version

Returns:

• (nil)

#is_legacy ⇒ Boolean

Whether the GdkGLContext is in legacy mode or not.

The GdkGLContext 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:

• (Boolean) —

  true if the GL context is in legacy mode

#is_shared(other) ⇒ Boolean

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 GdkGLTexture 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.

Parameters:

• other (Gdk::GLContext) —

  the GdkGLContext that should be compatible with self

Returns:

• (Boolean) —

  true if the two GL contexts are compatible.

#make_current ⇒ nil

Makes the context the current one.

Returns:

• (nil)

#realize ⇒ Boolean

Realizes the given GdkGLContext.

It is safe to call this function on a realized GdkGLContext.

Returns:

• (Boolean) —

  true if the context is realized

#set_required_version(major, minor) ⇒ nil

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.

Parameters:

• major (Integer) —

  the major version to request

• minor (Integer) —

  the minor version to request

Returns:

• (nil)

#shared_context ⇒ Gdk::GLContext

Always nil

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

Returns:

• (Gdk::GLContext) —

  shared-context

#shared_context=(shared_context) ⇒ Gdk::GLContext

Always nil

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

Parameters:

• shared_context (Gdk::GLContext)

Returns:

• (Gdk::GLContext) —

  shared-context

• (Gdk::GLContext) —

  shared-context

#surface ⇒ Gdk::Surface

Retrieves the surface used by the context.

Returns:

• (Gdk::Surface) —

  a GdkSurface

#use_es ⇒ Boolean

Checks whether the context is using an OpenGL or OpenGL ES profile. false if other profile is in use of if the context has not yet been realized.

Returns:

• (Boolean) —

  true if the GdkGLContext is using an OpenGL ES profile;

#use_es=(use_es) ⇒ nil

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 [methodGdk.GLContext.get_use_es] after calling [methodGdk.GLContext.realize] to decide whether to use the OpenGL or OpenGL ES API, extensions, or shaders.

Parameters:

• use_es (Integer) —

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

Returns:

• (nil)