class Gtk::GLArea

• Gtk::GLArea
• Gtk::Widget
• GObject::InitiallyUnowned
• GObject::Object
• Reference
• Object

Overview

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

Gtk::GLArea sets up its own Gdk::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.

In order to draw, you have to connect to the Gtk::GLArea::#render signal, or subclass Gtk::GLArea and override the Gtk::GLAreaClass.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:

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

WARNING ⚠️ The following code is in c ⚠️

static gboolean
render (Gtk::GLArea *area, Gdk::GLContext *context)
{
  // inside this function it's safe to use GL; the given
  // Gdk::GLContext has been made current to the drawable
  // surface used by the `Gtk::GLArea` 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 Gtk::GLArea instance
  Gtk::Widget *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 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#error.

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

WARNING ⚠️ The following code is in c ⚠️

static void
on_realize (Gtk::GLarea *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
  // Gtk::GLArea 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 [signal@Gtk.GLArea::create-context] signal.

Included Modules

• Gtk::Accessible
• Gtk::Buildable
• Gtk::ConstraintTarget

Defined in:

Constructors

• .new : self

  Creates a new Gtk::GLArea widget.

• .new(*, accessible_role : Gtk::AccessibleRole? = nil, auto_render : Bool? = nil, can_focus : Bool? = nil, can_target : Bool? = nil, context : Gdk::GLContext? = nil, css_classes : Enumerable(String)? = nil, css_name : String? = nil, cursor : Gdk::Cursor? = nil, focus_on_click : Bool? = nil, focusable : Bool? = nil, halign : Gtk::Align? = nil, has_default : Bool? = nil, has_depth_buffer : Bool? = nil, has_focus : Bool? = nil, has_stencil_buffer : Bool? = nil, has_tooltip : Bool? = nil, height_request : Int32? = nil, hexpand : Bool? = nil, hexpand_set : Bool? = nil, layout_manager : Gtk::LayoutManager? = nil, margin_bottom : Int32? = nil, margin_end : Int32? = nil, margin_start : Int32? = nil, margin_top : Int32? = nil, name : String? = nil, opacity : Float64? = nil, overflow : Gtk::Overflow? = nil, parent : Gtk::Widget? = nil, receives_default : Bool? = nil, root : Gtk::Root? = nil, scale_factor : Int32? = nil, sensitive : Bool? = nil, tooltip_markup : String? = nil, tooltip_text : String? = nil, use_es : Bool? = nil, valign : Gtk::Align? = nil, vexpand : Bool? = nil, vexpand_set : Bool? = nil, visible : Bool? = nil, width_request : Int32? = nil)

Class Method Summary

• .g_type : UInt64

  Returns the type id (GType) registered in GLib type system.

Instance Method Summary

• #attach_buffers : Nil

  Binds buffers to the framebuffer.

• #auto_render : Bool

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

• #auto_render=(auto_render : Bool) : Nil

  Sets whether the Gtk::GLArea is in auto render mode.

• #auto_render? : Bool
• #context : Gdk::GLContext?

  Retrieves the Gdk::GLContext used by @area.

• #create_context_signal
• #error : GLib::Error?

  Gets the current error set on the @area.

• #error=(error : GLib::Error?) : Nil

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

• #has_depth_buffer : Bool

  Returns whether the area has a depth buffer.

• #has_depth_buffer=(has_depth_buffer : Bool) : Nil

  Sets whether the Gtk::GLArea should use a depth buffer.

• #has_depth_buffer? : Bool
• #has_stencil_buffer : Bool

  Returns whether the area has a stencil buffer.

• #has_stencil_buffer=(has_stencil_buffer : Bool) : Nil

  Sets whether the Gtk::GLArea should use a stencil buffer.

• #has_stencil_buffer? : Bool
• #make_current : Nil

  Ensures that the Gdk::GLContext used by @area is associated with the Gtk::GLArea.

• #queue_render : Nil

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

• #render_signal
• #required_version(major : Int32, minor : Int32) : Nil

  Retrieves the required version of OpenGL.

• #resize_signal
• #set_required_version(major : Int32, minor : Int32) : Nil

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

• #use_es : Bool

  Returns whether the Gtk::GLArea should use OpenGL ES.

• #use_es=(use_es : Bool) : Nil

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

• #use_es? : Bool

Constructor Detail

Class Method Detail

Instance Method Detail