Struct gtk::GLArea

pub struct GLArea(_, _);

GLArea is a widget that allows drawing with OpenGL.

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 GLArea::render signal, or subclass GLArea and override the GLAreaClass.render() virtual function.

The 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 GLArea

The simplest way to draw using OpenGL commands in a GLArea is to create a widget instance and connect to the 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 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 Widget::realize signal; you can use the Widget::unrealize signal to clean up. Since the gdk::GLContext creation and initialization may fail, you will need to check for errors, using GLAreaExt::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 GLArea::create-context signal.

Feature: v3_16

Implements

GLAreaExt, WidgetExt, glib::object::ObjectExt, BuildableExt, WidgetExtManual, BuildableExtManual

Implementations

impl GLArea

pub fn new() -> GLArea

Creates a new GLArea widget.

Feature: v3_16

Returns

a new GLArea

Trait Implementations

impl Clone for GLArea

fn clone(&self) -> GLArea

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GLArea

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GLArea

fn default() -> Self

Returns the "default value" for a type.

impl Display for GLArea

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for GLArea

impl Hash for GLArea

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl IsA<Buildable> for GLArea

impl IsA<Widget> for GLArea

impl Ord for GLArea

fn cmp(&self, other: &GLArea) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T: ObjectType> PartialEq<T> for GLArea

fn eq(&self, other: &T) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: ObjectType> PartialOrd<T> for GLArea

fn partial_cmp(&self, other: &T) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for GLArea

fn static_type() -> Type

Returns the type identifier of Self.