GtkGLArea

GtkGLArea — A widget for custom drawing with OpenGL

Functions

Properties

GdkGLContext * context Read
gboolean has-alpha Read / Write
gboolean has-depth-buffer Read / Write

Signals

gboolean render 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/gtk.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;
}

The draw_an_object() function draws a 2D, gold-colored triangle:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
static void
draw_an_object (void)
{
  // set the color
  glColor3f (1.0f, 0.85f, 0.35f);

  // draw our triangle
  glBegin (GL_TRIANGLES);
  {
    glVertex3f ( 0.0f,  0.6f,  0.0f);
    glVertex3f (-0.2f, -0.3f,  0.0f);
    glVertex3f ( 0.2f, -0.3f,  0.0f);
  }
  glEnd ();
}

This is an extremely simple example; in a real-world application you would probably replace the immediate mode drawing with persistent geometry primitives, like a Vertex Buffer Object, and only redraw what changed in your scene.

Functions

gtk_gl_area_new ()

GtkWidget *
gtk_gl_area_new (void);

Creates a new GtkGLArea widget.

Returns

the newly created GtkGLArea.

[transfer full]

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_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_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 should not be called by application code.

Parameters

area

a GtkGLArea

 

Since 3.16

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

The GtkGLAreaClass structure contains only private data.

Members

render ()

class closure for the “render” signal

 

Since 3.16

Property Details

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

Signal Details

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