Gtk.GLArea¶

Example¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (278), GObject.Object (37), Gtk.Buildable (10)
Structs:: Gtk.WidgetClass (12), GObject.ObjectClass (5)

class	`new` ()
	`attach_buffers` ()
	`get_auto_render` ()
	`get_context` ()
	`get_error` ()
	`get_has_alpha` ()
	`get_has_depth_buffer` ()
	`get_has_stencil_buffer` ()
	`get_required_version` ()
	`get_use_es` ()
	`make_current` ()
	`queue_render` ()
	`set_auto_render` (auto_render)
	`set_error` (error)
	`set_has_alpha` (has_alpha)
	`set_has_depth_buffer` (has_depth_buffer)
	`set_has_stencil_buffer` (has_stencil_buffer)
	`set_required_version` (major, minor)
	`set_use_es` (use_es)

Virtual Methods¶

Inherited:: Gtk.Widget (82), GObject.Object (7), Gtk.Buildable (10)

	`do_render` (context)
	`do_resize` (width, height)

Properties¶

Inherited:: Gtk.Widget (39)

Name	Type	Flags	Short Description
`auto-render`	`bool`	r/w/en	Whether the `Gtk.GLArea` renders on each redraw
`context`	`Gdk.GLContext`	r	The GL context
`has-alpha`	`bool`	r/w/en	Whether the color buffer has an alpha component
`has-depth-buffer`	`bool`	r/w/en	Whether a depth buffer is allocated
`has-stencil-buffer`	`bool`	r/w/en	Whether a stencil buffer is allocated
`use-es`	`bool`	r/w/en	Whether the context uses OpenGL or OpenGL ES

Style Properties¶

Inherited:: Gtk.Widget (17)

Signals¶

Inherited:: Gtk.Widget (69), GObject.Object (1)

Name	Short Description
`create-context`	The `::create-context` signal is emitted when the widget is being realized, and allows you to override how the GL context is created.
`render`	The `::render` signal is emitted every time the contents of the `Gtk.GLArea` should be redrawn.
`resize`	The `::resize` signal is emitted once when the widget is realized, and then each time the widget is changed while realized.

Fields¶

Inherited:: Gtk.Widget (69), GObject.Object (1)

Name	Type	Access	Description
parent_instance	`Gtk.Widget`	r

Class Details¶

class Gtk.GLArea(**kwargs)¶

Bases:: Gtk.Widget
Abstract:: No
Structure:: Gtk.GLAreaClass

Gtk.GLArea is a widget that allows drawing with OpenGL.

Gtk.GLArea sets up its own Gdk.GLContext for the window it creates, 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.

In order to draw, you have to connect to the Gtk.GLArea ::render signal, or subclass Gtk.GLArea and override the GtkGLAreaClass.render() virtual function.

The Gtk.GLArea widget ensures that the Gdk.GLContext 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 Gtk.GLArea

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

// 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);

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

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;
}

If you need to initialize OpenGL state, e.g. buffer objects or shaders, you should use the Gtk.Widget ::realize signal; you can use the Gtk.Widget ::unrealize signal to clean up. Since the Gdk.GLContext creation and initialization may fail, you will need to check for errors, using Gtk.GLArea.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 gtk_gl_area_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 Gdk.GLContext you should use the Gtk.GLArea ::create-context signal.

New in version 3.16.

classmethod new()[source]¶

Returns:: a new Gtk.GLArea
Return type:: Gtk.Widget

Creates a new Gtk.GLArea widget.

New in version 3.16.

attach_buffers()[source]¶

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

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

New in version 3.16.

get_auto_render()[source]¶

Returns:: True if the self is auto rendering, False otherwise
Return type:: bool

Returns whether the area is in auto render mode or not.

New in version 3.16.

get_context()[source]¶

Returns:: the Gdk.GLContext
Return type:: Gdk.GLContext

Retrieves the Gdk.GLContext used by self.

New in version 3.16.

get_error()[source]¶

Returns:: the GLib.Error or None
Return type:: GLib.Error or None

Gets the current error set on the self.

New in version 3.16.

get_has_alpha()[source]¶

Returns:: True if the self has an alpha component, False otherwise
Return type:: bool

Returns whether the area has an alpha component.

New in version 3.16.

get_has_depth_buffer()[source]¶

Returns:: True if the self has a depth buffer, False otherwise
Return type:: bool

Returns whether the area has a depth buffer.

New in version 3.16.

get_has_stencil_buffer()[source]¶

Returns:: True if the self has a stencil buffer, False otherwise
Return type:: bool

Returns whether the area has a stencil buffer.

New in version 3.16.

get_required_version()[source]¶

Returns:

major:: return location for the required major version
minor:: return location for the required minor version

Return type:

(major: int, minor: int)

Retrieves the required version of OpenGL set using Gtk.GLArea.set_required_version().

New in version 3.16.

get_use_es()[source]¶

Returns:: True if the Gtk.GLArea should create an OpenGL ES context and False otherwise
Return type:: bool

Retrieves the value set by Gtk.GLArea.set_use_es().

New in version 3.22.

make_current()[source]¶

Ensures that the Gdk.GLContext used by self is associated with the Gtk.GLArea.

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

New in version 3.16.

queue_render()[source]¶

Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget, ensuring that the Gtk.GLArea ::render signal is emitted during the draw.

This is only needed when the Gtk.GLArea.set_auto_render() has been called with a False value. The default behaviour is to emit Gtk.GLArea ::render on each draw.

New in version 3.16.

set_auto_render(auto_render)[source]¶

Parameters:: auto_render (bool) – a boolean

If auto_render is True the Gtk.GLArea ::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 Gtk.GLArea.queue_render() must be called. This mode is useful when the scene changes seldomly, but takes a long time to redraw.

New in version 3.16.

set_error(error)[source]¶

Parameters:: error (GLib.Error or None) – a new GLib.Error, or None to unset the error

Sets an error on the area which will be shown instead of the GL rendering. This is useful in the Gtk.GLArea ::create-context signal if GL context creation fails.

New in version 3.16.

set_has_alpha(has_alpha)[source]¶

Parameters:: has_alpha (bool) – True to add an alpha component

If has_alpha is True the buffer allocated by the widget will have an alpha channel component, and when rendering to the window the result will be composited over whatever is below the widget.

If has_alpha is False there will be no alpha channel, and the buffer will fully replace anything below the widget.

New in version 3.16.

set_has_depth_buffer(has_depth_buffer)[source]¶

Parameters:: has_depth_buffer (bool) – True to add 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.

New in version 3.16.

set_has_stencil_buffer(has_stencil_buffer)[source]¶

Parameters:: has_stencil_buffer (bool) – True to add 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.

New in version 3.16.

set_required_version(major, minor)[source]¶

Parameters:

major (int) – the major version
minor (int) – the minor version

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.

New in version 3.16.

set_use_es(use_es)[source]¶

Parameters:: use_es (bool) – whether to use OpenGL or OpenGL ES

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

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

New in version 3.22.

do_render(context) virtual¶

Parameters:: context (Gdk.GLContext) –
Return type:: bool

do_resize(width, height) virtual¶

Parameters:

width (int) –
height (int) –

Signal Details¶

Gtk.GLArea.signals.create_context(g_l_area)¶

Signal Name:: create-context
Flags:: RUN_LAST
Parameters:: g_l_area (Gtk.GLArea) – The object which received the signal
Returns:: a newly created Gdk.GLContext; the Gtk.GLArea widget will take ownership of the returned value.
Return type:: Gdk.GLContext

The ::create-context signal is emitted when the widget is being realized, and allows you to override how the GL context is created. This is useful when you want to reuse an existing GL context, or if you want to try creating different kinds of GL options.

If context creation fails then the signal handler can use Gtk.GLArea.set_error() to register a more detailed error of how the construction failed.

New in version 3.16.

Gtk.GLArea.signals.render(g_l_area, context)¶

Signal Name:

render

Flags:

RUN_LAST

Parameters:

g_l_area (Gtk.GLArea) – The object which received the signal
context (Gdk.GLContext) – the Gdk.GLContext used by area

Returns:

True to stop other handlers from being invoked for the event. False to propagate the event further.

Return type:

bool

The ::render signal is emitted every time the contents of the Gtk.GLArea should be redrawn.

The context is bound to the area prior to emitting this function, and the buffers are painted to the window once the emission terminates.

New in version 3.16.

Gtk.GLArea.signals.resize(g_l_area, width, height)¶

Signal Name:

resize

Flags:

RUN_LAST

Parameters:

g_l_area (Gtk.GLArea) – The object which received the signal
width (int) – the width of the viewport
height (int) – the height of the viewport

The ::resize signal is emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep GL state up to date with the widget size, like for instance camera properties which may depend on the width/height ratio.

The GL context for the area is guaranteed to be current when this signal is emitted.

The default handler sets up the GL viewport.

New in version 3.16.

Property Details¶

Gtk.GLArea.props.auto_render¶

Name:: auto-render
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

If set to True the Gtk.GLArea ::render signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster.

If set to 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 Gtk.GLArea.queue_render() must be called. This mode is useful when the scene changes seldomly, but takes a long time to redraw.

New in version 3.16.

Gtk.GLArea.props.context¶

Name:: context
Type:: Gdk.GLContext
Default Value:: None
Flags:: READABLE

The Gdk.GLContext used by the Gtk.GLArea widget.

The Gtk.GLArea widget is responsible for creating the Gdk.GLContext instance. If you need to render with other kinds of buffers (stencil, depth, etc), use render buffers.

New in version 3.16.

Gtk.GLArea.props.has_alpha¶

Name:: has-alpha
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

If set to True the buffer allocated by the widget will have an alpha channel component, and when rendering to the window the result will be composited over whatever is below the widget.

If set to False there will be no alpha channel, and the buffer will fully replace anything below the widget.

New in version 3.16.

Gtk.GLArea.props.has_depth_buffer¶

Name:: has-depth-buffer
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

If set to True the widget will allocate and enable a depth buffer for the target framebuffer.

New in version 3.16.

Gtk.GLArea.props.has_stencil_buffer¶

Name:: has-stencil-buffer
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

If set to True the widget will allocate and enable a stencil buffer for the target framebuffer.

New in version 3.16.

Gtk.GLArea.props.use_es¶

Name:: use-es
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

If set to True the widget will try to create a Gdk.GLContext using OpenGL ES instead of OpenGL.