Gnome::Gtk4::GLArea

Table of Contents
Description

Drawing with GtkGLArea
Class initialization
new
:native-object
new-glarea
Methods
attach-buffers
get-allowed-apis This function is not yet available
get-api This function is not yet available
get-auto-render
get-context
get-error
get-has-depth-buffer
get-has-stencil-buffer
get-required-version
get-use-es
make-current
queue-render
set-allowed-apis This function is not yet available
set-auto-render
set-error
set-has-depth-buffer
set-has-stencil-buffer
set-required-version
set-use-es
Signals
create-context
render
resize

Description

Gnome::Gtk4::GLArea is a widget that allows drawing with OpenGL.

Gnome::Gtk4::GLArea sets up its own Gnome::Gdk4::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. The completed rendering is integrated into the larger GTK scene graph as a texture.

In order to draw, you have to connect to the render signal, or subclass Gnome::Gtk4::GLArea and override the GtkGLAreaClass.render virtual function.

The Gnome::Gtk4::GLArea widget ensures that the Gnome::Gdk4::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 GtkGLArea

The simplest way to draw using OpenGL commands in a Gnome::Gtk4::GLArea is to create a widget instance and connect to the render signal:

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

The initial contents of the framebuffer are transparent.

B<B><c> 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 Gnome::Gtk4::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 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 realize defined in Widget signal; you can use the unrealize defined in Widget signal to clean up. Since the Gnome::Gdk4::GLContext creation and initialization may fail, you will need to check for errors, using .get-error().

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

If you need to change the options for creating the Gnome::Gdk4::GLContext you should use the create-context signal.

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-glarea

Creates a new Gnome::Gtk4::GLArea widget.

method new-glarea ( --> Gnome::Gtk4::GLArea \)

Methods

attach-buffers

Binds buffers to the framebuffer.

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

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

method attach-buffers ( )

get-allowed-apis This function is not yet available

Gets the allowed APIs.

See .set-allowed-apis().

method get-allowed-apis (--> UInt )

Return value; the allowed APIs.

get-api This function is not yet available

Gets the API that is currently in use.

If the GL area has not been realized yet, 0 is returned.

method get-api (--> UInt )

Return value; the currently used API.

get-auto-render

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

method get-auto-render (--> Bool )

Return value; True if the $area is auto rendering, False otherwise.

get-context

Retrieves the Gnome::Gdk4::GLContext used by $area.

method get-context (--> N-Object )

Return value; the Gnome::Gdk4::GLContext.

get-error

Gets the current error set on the $area.

method get-error (--> N-Object )

Return value; the Gnome::Glib::N-Error.

get-has-depth-buffer

Returns whether the area has a depth buffer.

method get-has-depth-buffer (--> Bool )

Return value; True if the $area has a depth buffer, False otherwise.

get-has-stencil-buffer

Returns whether the area has a stencil buffer.

method get-has-stencil-buffer (--> Bool )

Return value; True if the $area has a stencil buffer, False otherwise.

get-required-version

Retrieves the required version of OpenGL.

See .set-required-version().

method get-required-version ( Array[Int] $major, Array[Int] $minor )

$major; (transfer ownership: full) return location for the required major version.
$minor; (transfer ownership: full) return location for the required minor version.

get-use-es

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.12

Returns whether the Gnome::Gtk4::GLArea should use OpenGL ES.

See .set-use-es().

method get-use-es (--> Bool )

Return value; True if the Gnome::Gtk4::GLArea should create an OpenGL ES context and False otherwise.

make-current

Ensures that the Gnome::Gdk4::GLContext used by $area is associated with the Gnome::Gtk4::GLArea.

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

method make-current ( )

queue-render

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

This ensures that the render signal is emitted during the draw.

This is only needed when .set-auto-render() has been called with a False value. The default behaviour is to emit render on each draw.

method queue-render ( )

set-allowed-apis This function is not yet available

Sets the allowed APIs to create a context with.

You should check api before drawing with either API.

By default, all APIs are allowed.

method set-allowed-apis ( UInt $apis )

$apis; the allowed APIs.

set-auto-render

Sets whether the Gnome::Gtk4::GLArea is in auto render mode.

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

method set-auto-render ( Bool() $auto-render )

$auto-render; a boolean.

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

method set-error ( N-Object $error )

$error; a new Gnome::Glib::N-Error, or undefined to unset the error

set-has-depth-buffer

Sets whether the Gnome::Gtk4::GLArea should use a 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.

method set-has-depth-buffer ( Bool() $has-depth-buffer )

$has-depth-buffer; True to add a depth buffer.

set-has-stencil-buffer

Sets whether the Gnome::Gtk4::GLArea should use a 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.

method set-has-stencil-buffer ( Bool() $has-stencil-buffer )

$has-stencil-buffer; True to add a stencil buffer.

set-required-version

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.

method set-required-version ( Int() $major, Int() $minor )

$major; the major version.
$minor; the minor version.

set-use-es

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.12

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

You should check the capabilities of the Gnome::Gdk4::GLContext before drawing with either API.

method set-use-es ( Bool() $use-es )

$use-es; whether to use OpenGL or OpenGL ES.

Signals

create-context

Emitted when the widget is being realized.

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

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::GLArea :$_widget,
  *C<user>-options
)

$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::GLArea object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

render

Emitted every time the contents of the Gnome::Gtk4::GLArea 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.

method handler (
   $context,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::GLArea :$_widget,
  *C<user>-options
  --> gboolean
)

$context; the Gnome::Gdk4::GLContext used by $area.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::GLArea object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value; True to stop other handlers from being invoked for the event. False to propagate the event further.

resize

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.

method handler (
  gint $width,
  gint $height,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::GLArea :$_widget,
  *C<user>-options
)

$width; the width of the viewport.
$height; the height of the viewport.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::GLArea object.
$_widget; The object which registered the signal. User code may have left the object going out of scope.
user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.