Gtk.GLArea
Description: Reference for Gtk.GLArea

### Class

# GtkGLArea

#### Description [src]

    class Gtk.GLArea : Gtk.Widget {
      /* No available fields */
    }

`GtkGLArea` is a widget that allows drawing with OpenGL.

`GtkGLArea` sets up its own `GdkGLContext`, 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 `GtkGLArea::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 `GtkGLArea::render` signal:

The `render()` function will be called when the `GtkGLArea` 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;
    }

    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 `GtkWidget::realize` signal; you can use the `GtkWidget::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:

    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 `GtkGLArea::create-context` signal.

#### Hierarchy

#### Ancestors

- GtkWidget
- GInitiallyUnowned
- GObject

#### Implements

- GtkAccessible
- GtkBuildable
- GtkConstraintTarget

#### Constructors

###### gtk_gl_area_new

Creates a new `GtkGLArea` widget.

#### Instance methods

###### gtk_gl_area_attach_buffers

Binds buffers to the framebuffer.

###### gtk_gl_area_get_auto_render

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

###### gtk_gl_area_get_context

Retrieves the `GdkGLContext` used by `area`.

###### gtk_gl_area_get_error

Gets the current error set on the `area`.

###### gtk_gl_area_get_has_depth_buffer

Returns whether the area has a depth buffer.

###### gtk_gl_area_get_has_stencil_buffer

Returns whether the area has a stencil buffer.

###### gtk_gl_area_get_required_version

Retrieves the required version of OpenGL.

###### gtk_gl_area_get_use_es

Returns whether the `GtkGLArea` should use OpenGL ES.

###### gtk_gl_area_make_current

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

###### gtk_gl_area_queue_render

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

###### gtk_gl_area_set_auto_render

Sets whether the `GtkGLArea` is in auto render mode.

###### gtk_gl_area_set_error

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

###### gtk_gl_area_set_has_depth_buffer

Sets whether the `GtkGLArea` should use a depth buffer.

###### gtk_gl_area_set_has_stencil_buffer

Sets whether the `GtkGLArea` should use a stencil buffer.

###### gtk_gl_area_set_required_version

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

###### gtk_gl_area_set_use_es

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

##### Methods inherited from GtkWidget (161)

Please see GtkWidget for a full list of methods.

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

##### Methods inherited from GtkAccessible (10)

###### gtk_accessible_get_accessible_role

Retrieves the `GtkAccessibleRole` for the given `GtkAccessible`.

###### gtk_accessible_reset_property

Resets the accessible `property` to its default value.

###### gtk_accessible_reset_relation

Resets the accessible `relation` to its default value.

###### gtk_accessible_reset_state

Resets the accessible `state` to its default value.

###### gtk_accessible_update_property

Updates a list of accessible properties.

###### gtk_accessible_update_property_value

Updates an array of accessible properties.

###### gtk_accessible_update_relation

Updates a list of accessible relations.

###### gtk_accessible_update_relation_value

Updates an array of accessible relations.

###### gtk_accessible_update_state

Updates a list of accessible states. See the `GtkAccessibleState` documentation for the value types of accessible states.

###### gtk_accessible_update_state_value

Updates an array of accessible states.

##### Methods inherited from GtkBuildable (1)

###### gtk_buildable_get_buildable_id

Gets the ID of the `buildable` object.

#### Properties

###### Gtk.GLArea:auto-render

If set to `TRUE` the ::render signal will be emitted every time the widget draws.

###### Gtk.GLArea:context

The `GdkGLContext` used by the `GtkGLArea` widget.

###### Gtk.GLArea:has-depth-buffer

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

###### Gtk.GLArea:has-stencil-buffer

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

###### Gtk.GLArea:use-es

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

##### Properties inherited from GtkWidget (34)

###### Gtk.Widget:can-focus

Whether the widget or any of its descendents can accept the input focus.

###### Gtk.Widget:can-target

Whether the widget can receive pointer events.

###### Gtk.Widget:css-classes

A list of css classes applied to this widget.

###### Gtk.Widget:css-name

The name of this widget in the CSS tree.

###### Gtk.Widget:cursor

The cursor used by `widget`.

###### Gtk.Widget:focus-on-click

Whether the widget should grab focus when it is clicked with the mouse.

###### Gtk.Widget:focusable

Whether this widget itself will accept the input focus.

###### Gtk.Widget:halign

How to distribute horizontal space if widget gets extra space.

###### Gtk.Widget:has-default

Whether the widget is the default widget.

###### Gtk.Widget:has-focus

Whether the widget has the input focus.

###### Gtk.Widget:has-tooltip

Enables or disables the emission of the ::query-tooltip signal on `widget`.

###### Gtk.Widget:height-request

Override for height request of the widget.

###### Gtk.Widget:hexpand

Whether to expand horizontally.

###### Gtk.Widget:hexpand-set

Whether to use the `hexpand` property.

###### Gtk.Widget:layout-manager

The `GtkLayoutManager` instance to use to compute the preferred size of the widget, and allocate its children.

###### Gtk.Widget:margin-bottom

Margin on bottom side of widget.

###### Gtk.Widget:margin-end

Margin on end of widget, horizontally.

###### Gtk.Widget:margin-start

Margin on start of widget, horizontally.

###### Gtk.Widget:margin-top

Margin on top side of widget.

###### Gtk.Widget:name

The name of the widget.

###### Gtk.Widget:opacity

The requested opacity of the widget.

###### Gtk.Widget:overflow

How content outside the widget’s content area is treated.

###### Gtk.Widget:parent

The parent widget of this widget.

###### Gtk.Widget:receives-default

Whether the widget will receive the default action when it is focused.

###### Gtk.Widget:root

The `GtkRoot` widget of the widget tree containing this widget.

###### Gtk.Widget:scale-factor

The scale factor of the widget.

###### Gtk.Widget:sensitive

Whether the widget responds to input.

###### Gtk.Widget:tooltip-markup

Sets the text of tooltip to be the given string, which is marked up with Pango markup.

###### Gtk.Widget:tooltip-text

Sets the text of tooltip to be the given string.

###### Gtk.Widget:valign

How to distribute vertical space if widget gets extra space.

###### Gtk.Widget:vexpand

Whether to expand vertically.

###### Gtk.Widget:vexpand-set

Whether to use the `vexpand` property.

###### Gtk.Widget:visible

Whether the widget is visible.

###### Gtk.Widget:width-request

Override for width request of the widget.

##### Properties inherited from GtkAccessible (1)

###### GtkAccessible:accessible-role

The accessible role of the given `GtkAccessible` implementation.

#### Signals

###### Gtk.GLArea::create-context

Emitted when the widget is being realized.

###### Gtk.GLArea::render

Emitted every time the contents of the `GtkGLArea` should be redrawn.

###### Gtk.GLArea::resize

Emitted once when the widget is realized, and then each time the widget is changed while realized.

##### Signals inherited from GtkWidget (13)

###### GtkWidget::destroy

Signals that all holders of a reference to the widget should release the reference that they hold.

###### GtkWidget::direction-changed

Emitted when the text direction of a widget changes.

###### GtkWidget::hide

Emitted when `widget` is hidden.

###### GtkWidget::keynav-failed

Emitted if keyboard navigation fails.

###### GtkWidget::map

Emitted when `widget` is going to be mapped.

###### GtkWidget::mnemonic-activate

Emitted when a widget is activated via a mnemonic.

###### GtkWidget::move-focus

Emitted when the focus is moved.

###### GtkWidget::query-tooltip

Emitted when the widgets tooltip is about to be shown.

###### GtkWidget::realize

Emitted when `widget` is associated with a `GdkSurface`.

###### GtkWidget::show

Emitted when `widget` is shown.

###### GtkWidget::state-flags-changed

Emitted when the widget state changes.

###### GtkWidget::unmap

Emitted when `widget` is going to be unmapped.

###### GtkWidget::unrealize

Emitted when the `GdkSurface` associated with `widget` is destroyed.

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

#### Class structure

    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.

###### Class members

`render: gboolean (* render) ( GtkGLArea* area, GdkGLContext* context )`
  No description available.
`resize: void (* resize) ( GtkGLArea* area, int width, int height )`
  No description available.
`create_context: GdkGLContext* (* create_context) ( GtkGLArea* area )`
  No description available.

#### Virtual methods

###### Gtk.GLAreaClass.create_context

No description available.

###### Gtk.GLAreaClass.render

No description available.

###### Gtk.GLAreaClass.resize

No description available.