GtkGLArea: GTK+ 3 Reference Manual

## GtkGLArea GtkGLArea — A widget for custom drawing with OpenGL |

## Functions

GtkWidget * | gtk_gl_area_new ()
GdkGLContext * | gtk_gl_area_get_context ()
void | gtk_gl_area_make_current ()
void | gtk_gl_area_queue_render ()
void | gtk_gl_area_attach_buffers ()
void | gtk_gl_area_set_error ()
GError * | gtk_gl_area_get_error ()
void | gtk_gl_area_set_has_alpha ()
gboolean | gtk_gl_area_get_has_alpha ()
void | gtk_gl_area_set_has_depth_buffer ()
gboolean | gtk_gl_area_get_has_depth_buffer ()
void | gtk_gl_area_set_has_stencil_buffer ()
gboolean | gtk_gl_area_get_has_stencil_buffer ()
void | gtk_gl_area_set_auto_render ()
gboolean | gtk_gl_area_get_auto_render ()
void | gtk_gl_area_get_required_version ()
void | gtk_gl_area_set_required_version ()
void | gtk_gl_area_set_use_es ()
gboolean | gtk_gl_area_get_use_es ()

## Properties

gboolean | auto-render | Read / Write
GdkGLContext * | context | Read
gboolean | has-alpha | Read / Write
gboolean | has-depth-buffer | Read / Write
gboolean | has-stencil-buffer | Read / Write
gboolean | use-es | Read / Write

## Signals

GdkGLContext* | create-context | Run Last
gboolean | render | Run Last
void | resize | Run Last

## Types and Values

struct | GtkGLArea
struct | GtkGLAreaClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkGLArea

## Implemented Interfaces

GtkGLArea implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <gtk/gtkunixprint.h>

## Description

GtkGLArea is a widget that allows drawing with OpenGL.

GtkGLArea sets up its own GdkGLContext 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 “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:

    1
    2
    3
    4
    5
    // 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 GtkGLArea is ready for you to draw its content:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    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 “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 `gtk_gl_area_get_error()`. An example of how to safely initialize the GL state is:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    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 GdkGLContext you should use the “create-context” signal.

## Functions

### gtk_gl_area_new ()

    GtkWidget *
    gtk_gl_area_new (void);

Creates a new GtkGLArea widget.

#### Returns

a new GtkGLArea

Since: 3.16

### gtk_gl_area_get_context ()

    GdkGLContext *
    gtk_gl_area_get_context (GtkGLArea *area);

Retrieves the GdkGLContext used by `area` .

#### Parameters

area | a GtkGLArea |

#### Returns

the GdkGLContext.

[transfer none]

Since: 3.16

### gtk_gl_area_make_current ()

    void
    gtk_gl_area_make_current (GtkGLArea *area);

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.

#### Parameters

area | a GtkGLArea |

Since: 3.16

### gtk_gl_area_queue_render ()

    void
    gtk_gl_area_queue_render (GtkGLArea *area);

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

This is only needed when the `gtk_gl_area_set_auto_render()` has been called with a `FALSE` value. The default behaviour is to emit “render” on each draw.

#### Parameters

area | a GtkGLArea |

Since: 3.16

### gtk_gl_area_attach_buffers ()

    void
    gtk_gl_area_attach_buffers (GtkGLArea *area);

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

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

#### Parameters

area | a GtkGLArea |

Since: 3.16

### gtk_gl_area_set_error ()

    void
    gtk_gl_area_set_error (GtkGLArea *area,
                           const GError *error);

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

area | a GtkGLArea |
error | a new GError, or `NULL` to unset the error. | [allow-none]

Since: 3.16

### gtk_gl_area_get_error ()

    GError *
    gtk_gl_area_get_error (GtkGLArea *area);

Gets the current error set on the `area` .

#### Parameters

area | a GtkGLArea |

#### Returns

the GError or `NULL`.

[nullable][transfer none]

Since: 3.16

### gtk_gl_area_set_has_alpha ()

    void
    gtk_gl_area_set_has_alpha (GtkGLArea *area,
                               gboolean has_alpha);

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.

#### Parameters

area | a GtkGLArea |
has_alpha | `TRUE` to add an alpha component |

Since: 3.16

### gtk_gl_area_get_has_alpha ()

    gboolean
    gtk_gl_area_get_has_alpha (GtkGLArea *area);

Returns whether the area has an alpha component.

#### Parameters

area | a GtkGLArea |

#### Returns

`TRUE` if the `area` has an alpha component, `FALSE` otherwise

Since: 3.16

### gtk_gl_area_set_has_depth_buffer ()

    void
    gtk_gl_area_set_has_depth_buffer (GtkGLArea *area,
                                      gboolean has_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

area | a GtkGLArea |
has_depth_buffer | `TRUE` to add a depth buffer |

Since: 3.16

### gtk_gl_area_get_has_depth_buffer ()

    gboolean
    gtk_gl_area_get_has_depth_buffer (GtkGLArea *area);

Returns whether the area has a depth buffer.

#### Parameters

area | a GtkGLArea |

#### Returns

`TRUE` if the `area` has a depth buffer, `FALSE` otherwise

Since: 3.16

### gtk_gl_area_set_has_stencil_buffer ()

    void
    gtk_gl_area_set_has_stencil_buffer (GtkGLArea *area,
                                        gboolean has_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

area | a GtkGLArea |
has_stencil_buffer | `TRUE` to add a stencil buffer |

Since: 3.16

### gtk_gl_area_get_has_stencil_buffer ()

    gboolean
    gtk_gl_area_get_has_stencil_buffer (GtkGLArea *area);

Returns whether the area has a stencil buffer.

#### Parameters

area | a GtkGLArea |

#### Returns

`TRUE` if the `area` has a stencil buffer, `FALSE` otherwise

Since: 3.16

### gtk_gl_area_set_auto_render ()

    void
    gtk_gl_area_set_auto_render (GtkGLArea *area,
                                 gboolean auto_render);

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

#### Parameters

area | a GtkGLArea |
auto_render | a boolean |

Since: 3.16

### gtk_gl_area_get_auto_render ()

    gboolean
    gtk_gl_area_get_auto_render (GtkGLArea *area);

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

#### Parameters

area | a GtkGLArea |

#### Returns

`TRUE` if the `area` is auto rendering, `FALSE` otherwise

Since: 3.16

### gtk_gl_area_get_required_version ()

    void
    gtk_gl_area_get_required_version (GtkGLArea *area,
                                      gint *major,
                                      gint *minor);

Retrieves the required version of OpenGL set using `gtk_gl_area_set_required_version()`.

#### Parameters

area | a GtkGLArea |
major | return location for the required major version. | [out]
minor | return location for the required minor version. | [out]

Since: 3.16

### gtk_gl_area_set_required_version ()

    void
    gtk_gl_area_set_required_version (GtkGLArea *area,
                                      gint major,
                                      gint minor);

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

area | a GtkGLArea |
major | the major version |
minor | the minor version |

Since: 3.16

### gtk_gl_area_set_use_es ()

    void
    gtk_gl_area_set_use_es (GtkGLArea *area,
                            gboolean use_es);

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.

#### Parameters

area | a GtkGLArea |
use_es | whether to use OpenGL or OpenGL ES |

Since: 3.22

### gtk_gl_area_get_use_es ()

    gboolean
    gtk_gl_area_get_use_es (GtkGLArea *area);

Retrieves the value set by `gtk_gl_area_set_use_es()`.

#### Parameters

area | a GtkGLArea |

#### Returns

`TRUE` if the GtkGLArea should create an OpenGL ES context and `FALSE` otherwise

Since: 3.22

## Types and Values

### struct GtkGLArea

    struct GtkGLArea;

A GtkWidget used for drawing with OpenGL.

Since: 3.16

### struct GtkGLAreaClass

    struct GtkGLAreaClass {
      gboolean       (* render)         (GtkGLArea        *area,
                                         GdkGLContext     *context);
      void           (* resize)         (GtkGLArea        *area,
                                         int               width,
                                         int               height);
      GdkGLContext * (* create_context) (GtkGLArea        *area);
    };

The `GtkGLAreaClass` structure contains only private data.

#### Members

`render` () | class closure for the “render” signal |
`resize` () | class closeure for the “resize” signal |
`create_context` () | class closure for the “create-context” signal |

Since: 3.16

## Property Details

### The `“auto-render”` property

      “auto-render”              gboolean

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

Flags: Read / Write

Default value: TRUE

Since: 3.16

### The `“context”` property

      “context”                  GdkGLContext *

The GdkGLContext used by the GtkGLArea widget.

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

Flags: Read

Since: 3.16

### The `“has-alpha”` property

      “has-alpha”                gboolean

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.

Flags: Read / Write

Default value: FALSE

Since: 3.16

### The `“has-depth-buffer”` property

      “has-depth-buffer”         gboolean

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

Flags: Read / Write

Default value: FALSE

Since: 3.16

### The `“has-stencil-buffer”` property

      “has-stencil-buffer”       gboolean

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

Flags: Read / Write

Default value: FALSE

Since: 3.16

### The `“use-es”` property

      “use-es”                   gboolean

If set to `TRUE` the widget will try to create a GdkGLContext using OpenGL ES instead of OpenGL.

See also: `gdk_gl_context_set_use_es()`

Flags: Read / Write

Default value: FALSE

Since: 3.22

## Signal Details

### The `“create-context”` signal

    GdkGLContext*
    user_function (GtkGLArea *area,
                   gpointer   user_data)

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_gl_area_set_error()` to register a more detailed error of how the construction failed.

#### Parameters

area | the GtkGLArea that emitted the signal |
error | location to store error information on failure. | [allow-none]
user_data | user data set when the signal handler was connected. |

#### Returns

a newly created GdkGLContext; the GtkGLArea widget will take ownership of the returned value.

[transfer full]

Flags: Run Last

Since: 3.16

### The `“render”` signal

    gboolean
    user_function (GtkGLArea    *area,
                   GdkGLContext *context,
                   gpointer      user_data)

The ::render signal is emitted every time the contents of the GtkGLArea 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.

#### Parameters

area | the GtkGLArea that emitted the signal |
context | the GdkGLContext used by `area` |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` to stop other handlers from being invoked for the event. `FALSE` to propagate the event further.

Flags: Run Last

Since: 3.16

### The `“resize”` signal

    void
    user_function (GtkGLArea *area,
                   gint       width,
                   gint       height,
                   gpointer   user_data)

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.

#### Parameters

area | the GtkGLArea that emitted the signal |
width | the width of the viewport |
height | the height of the viewport |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.16