GLArea#

class GLArea(**properties: Any)#

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget

GtkGLArea is a widget that allows drawing with OpenGL.

GtkGLArea sets up its own GLContext, and creates a custom GL framebuffer that the widget will do GL rendering onto. It also ensures that this framebuffer is the default GL rendering target when rendering. The completed rendering is integrated into the larger GTK scene graph as a texture.

In order to draw, you have to connect to the render signal, or subclass GtkGLArea and override the GtkGLAreaClass.render virtual function.

The GtkGLArea widget ensures that the GdkGLContext is associated with the widget’s drawing area, and it is kept updated when the size and position of the drawing area changes.

Drawing with GtkGLArea#

The simplest way to draw using OpenGL commands in a GtkGLArea is to create a widget instance and connect to the render signal:

The render() function will be called when the GtkGLArea is ready for you to draw its content:

The initial contents of the framebuffer are transparent.

static gboolean
render (GtkGLArea *area, GdkGLContext *context)
{
  // inside this function it's safe to use GL; the given
  // GdkGLContext has been made current to the drawable
  // surface used by the ``GtkGLArea`` and the viewport has
  // already been set to be the size of the allocation

  // we can start by clearing the buffer
  glClearColor (0, 0, 0, 0);
  glClear (GL_COLOR_BUFFER_BIT);

  // draw your object
  // draw_an_object ();

  // we completed our drawing; the draw commands will be
  // flushed at the end of the signal emission chain, and
  // the buffers will be drawn on the window
  return TRUE;
}

void setup_glarea (void)
{
  // create a GtkGLArea instance
  GtkWidget *gl_area = gtk_gl_area_new ();

  // connect to the "render" signal
  g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL);
}

If you need to initialize OpenGL state, e.g. buffer objects or shaders, you should use the realize signal; you can use the unrealize signal to clean up. Since the GdkGLContext creation and initialization may fail, you will need to check for errors, using get_error.

An example of how to safely initialize the GL state is:

static void
on_realize (GtkGLarea *area)
{
  // We need to make the context current if we want to
  // call GL API
  gtk_gl_area_make_current (area);

  // If there were errors during the initialization or
  // when trying to make the context current, this
  // function will return a GError for you to catch
  if (gtk_gl_area_get_error (area) != NULL)
    return;

  // You can also use :func:`~gi.repository.Gtk.GLArea.set_error` in order
  // to show eventual initialization errors on the
  // GtkGLArea widget itself
  GError *internal_error = NULL;
  init_buffer_objects (&error);
  if (error != NULL)
    {
      gtk_gl_area_set_error (area, error);
      g_error_free (error);
      return;
    }

  init_shaders (&error);
  if (error != NULL)
    {
      gtk_gl_area_set_error (area, error);
      g_error_free (error);
      return;
    }
}

If you need to change the options for creating the GdkGLContext you should use the create_context signal.

Constructors#

class GLArea

classmethod new() → Widget#: Creates a new GtkGLArea widget.

Methods#

class GLArea

attach_buffers() → None#

Binds buffers to the framebuffer.

Ensures that the area framebuffer object is made the current draw and read target, and that all the required buffers for the area are created and bound to the framebuffer.

This function is automatically called before emitting the render signal, and doesn’t normally need to be called by application code.

get_allowed_apis() → GLAPI#

Gets the allowed APIs.

See set_allowed_apis.

Added in version 4.12.

get_api() → GLAPI#

Gets the API that is currently in use.

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

Added in version 4.12.

get_auto_render() → bool#: Returns whether the area is in auto render mode or not.

get_context() → GLContext | None#: Retrieves the GdkGLContext used by area.

get_error() → GError | None#: Gets the current error set on the area.

get_has_depth_buffer() → bool#: Returns whether the area has a depth buffer.

get_has_stencil_buffer() → bool#: Returns whether the area has a stencil buffer.

get_required_version() → tuple[int, int]#

Retrieves the required version of OpenGL.

See set_required_version.

get_use_es() → bool#

Returns whether the GtkGLArea should use OpenGL ES.

See set_use_es.

Deprecated since version 4.12: Use get_api

make_current() → None#

Ensures that the GdkGLContext used by area is associated with the GtkGLArea.

This function is automatically called before emitting the render signal, and doesn’t normally need to be called by application code.

queue_render() → None#

Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget.

This ensures that the render signal is emitted during the draw.

This is only needed when set_auto_render has been called with a False value. The default behaviour is to emit render on each draw.

set_allowed_apis(apis: GLAPI) → None#

Sets the allowed APIs to create a context with.

You should check api before drawing with either API.

By default, all APIs are allowed.

Added in version 4.12.

Parameters:: apis – the allowed APIs

set_auto_render(auto_render: bool) → None#

Sets whether the GtkGLArea is in auto render mode.

If auto_render is True the render signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster.

If auto_render is False the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a rendering queue_render must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw.

Parameters:: auto_render – a boolean

set_error(error: GError | None = None) → None#

Sets an error on the area which will be shown instead of the GL rendering.

This is useful in the create_context signal if GL context creation fails.

Parameters:: error – a new GError, or None to unset the error

set_has_depth_buffer(has_depth_buffer: bool) → None#

Sets whether the GtkGLArea should use a depth buffer.

If has_depth_buffer is True the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none.

Parameters:: has_depth_buffer – True to add a depth buffer

set_has_stencil_buffer(has_stencil_buffer: bool) → None#

Sets whether the GtkGLArea should use a stencil buffer.

If has_stencil_buffer is True the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise there will be none.

Parameters:: has_stencil_buffer – True to add a stencil buffer

set_required_version(major: int, minor: int) → None#

Sets the required version of OpenGL to be used when creating the context for the widget.

This function must be called before the area has been realized.

Parameters:

major – the major version
minor – the minor version

set_use_es(use_es: bool) → None#

Sets whether the area should create an OpenGL or an OpenGL ES context.

You should check the capabilities of the GdkGLContext before drawing with either API.

Deprecated since version 4.12: Use set_allowed_apis

Parameters:: use_es – whether to use OpenGL or OpenGL ES

Properties#

class GLArea

props.allowed_apis: GLAPI#: The type of the None singleton.

Added in version 4.12.

props.api: GLAPI#: The type of the None singleton.

Added in version 4.12.

props.auto_render: bool#: The type of the None singleton.

props.context: GLContext#: The type of the None singleton.

props.has_depth_buffer: bool#: The type of the None singleton.

props.has_stencil_buffer: bool#: The type of the None singleton.

props.use_es: bool#: The type of the None singleton.

Deprecated since version 4.12: Use allowed_apis

Signals#

class GLArea.signals

create_context() → GLContext#: The type of the None singleton.

render(context: GLContext) → bool#

The type of the None singleton.

Parameters:: context – the GdkGLContext used by area

resize(width: int, height: int) → None#

The type of the None singleton.

Parameters:

width – the width of the viewport
height – the height of the viewport

Virtual Methods#

class GLArea

do_render(context: GLContext) → bool#

The type of the None singleton.

Parameters:: context

do_resize(width: int, height: int) → None#

The type of the None singleton.

Parameters:

width
height

Fields#

class GLArea

parent_instance#