GLAreaProtocol

public protocol GLAreaProtocol : WidgetProtocol

GtkGLArea is a widget that allows drawing with OpenGL.

An example GtkGLArea

GtkGLArea sets up its own [classGdk.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 [signalGtk.GLArea::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 [signalGtk.GLArea::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 [signalGtk.Widget::realize] signal; you can use the [signalGtk.Widget::unrealize] signal to clean up. Since the GdkGLContext creation and initialization may fail, you will need to check for errors, using [methodGtk.GLArea.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 [signalGtk.GLArea::create-context] signal.

The GLAreaProtocol protocol exposes the methods and properties of an underlying GtkGLArea instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GLArea. Alternatively, use GLAreaRef as a lighweight, unowned reference if you already have an instance you just want to use.

Show on GitHub

ptr
Untyped pointer to the underlying GtkGLArea instance.
Declaration
Swift

var ptr: UnsafeMutableRawPointer! { get }
Show on GitHub
gl_area_ptr Default implementation
Typed pointer to the underlying GtkGLArea instance.

Default Implementation

Return the stored, untyped pointer as a typed pointer to the GtkGLArea instance.
Declaration
Swift

var gl_area_ptr: UnsafeMutablePointer<GtkGLArea>! { get }
Show on GitHub
init(raw:)
Required Initialiser for types conforming to GLAreaProtocol
Declaration
Swift

init(raw: UnsafeMutableRawPointer)
Show on GitHub

GLArea Class


                    
                    
                    bind(property:to:_:flags:transformFrom:transformTo:)

Extension method

Bind a GLAreaPropertyName source property to a given target object.

Declaration

Swift

@discardableResult
@inlinable
func bind<Q, T>(property source_property: GLAreaPropertyName, to target: T, _ target_property: Q, flags f: BindingFlags = .default, transformFrom transform_from: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }, transformTo transform_to: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }) -> BindingRef! where Q : PropertyNameProtocol, T : ObjectProtocol

Parameters

`source_property`	the source property to bind
`target`	the target object to bind to
`target_property`	the target property to bind to
`flags`	the flags to pass to the `Binding`
`transform_from`	`ValueTransformer` to use for forward transformation
`transform_to`	`ValueTransformer` to use for backwards transformation

Return Value

binding reference or nil in case of an error

Show on GitHub


                    
                    
                    get(property:)

Extension method

Get the value of a GLArea property

Declaration

Swift

@inlinable
func get(property: GLAreaPropertyName) -> GLibObject.Value

Parameters


                                property

the property to get the value for

Return Value

the value of the named property

Show on GitHub


                    
                    
                    set(property:value:)

Extension method

Set the value of a GLArea property. Note that this will only have an effect on properties that are writable and not construct-only!

Declaration

Swift

@inlinable
func set(property: GLAreaPropertyName, value v: GLibObject.Value)

Parameters


                                property

the property to get the value for

Return Value

the value of the named property

Show on GitHub

GLArea signals


                    
                    
                    connect(signal:flags:handler:)

Extension method

Connect a Swift signal handler to the given, typed GLAreaSignalName signal

Declaration

Swift

@discardableResult
@inlinable
func connect(signal s: GLAreaSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> Int

Parameters

`signal`	The signal to connect
`flags`	The connection flags to use
`data`	A pointer to user data to provide to the callback
`destroyData`	A `GClosureNotify` C function to destroy the data pointed to by `userData`
`handler`	The Swift signal handler (function or callback) to invoke on the given signal

Return Value

The signal handler ID (always greater than 0 for successful connections)

Show on GitHub


                    
                    
                    connect(signal:flags:data:destroyData:signalHandler:)

Extension method

Connect a C signal handler to the given, typed GLAreaSignalName signal

Declaration

Swift

@discardableResult
@inlinable
func connect(signal s: GLAreaSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> Int

Parameters

`signal`	The signal to connect
`flags`	The connection flags to use
`data`	A pointer to user data to provide to the callback
`destroyData`	A `GClosureNotify` C function to destroy the data pointed to by `userData`
`signalHandler`	The C function to be called on the given signal

Return Value

The signal handler ID (always greater than 0 for successful connections)

Show on GitHub


                    
                    
                    createContextSignal

Extension method

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 [methodGtk.GLArea.set_error] to register a more detailed error of how the construction failed.

Note

This represents the underlying create-context signal

Warning

a onCreateContext wrapper for this signal could not be generated because it contains unimplemented features: { (9) Record return type is not yet supported }

Note

Instead, you can connect createContextSignal using the connect(signal:) methods

Declaration

Swift

static var createContextSignal: GLAreaSignalName { get }

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`handler`	a newly created `GdkGLContext`; the `GtkGLArea` widget will take ownership of the returned value.

Show on GitHub


                    
                    
                    onRender(flags:handler:)

Extension method

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.

Note

This represents the underlying render signal

Declaration

Swift

@discardableResult
@inlinable
func onRender(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GLAreaRef, _ context: Gdk.GLContextRef) -> Bool) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`context`	the `GdkGLContext` used by `area`
`handler`	`true` to stop other handlers from being invoked for the event. `false` to propagate the event further. Run the given callback whenever the `render` signal is emitted

Show on GitHub

renderSignal Extension method
Typed render signal for using the connect(signal:) methods
Declaration
Swift

static var renderSignal: GLAreaSignalName { get }
Show on GitHub


                    
                    
                    onResize(flags:handler:)

Extension method

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.

Note

This represents the underlying resize signal

Declaration

Swift

@discardableResult
@inlinable
func onResize(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GLAreaRef, _ width: Int, _ height: Int) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`width`	the width of the viewport
`height`	the height of the viewport
`handler`	The signal handler to call Run the given callback whenever the `resize` signal is emitted

Show on GitHub

resizeSignal Extension method
Typed resize signal for using the connect(signal:) methods
Declaration
Swift

static var resizeSignal: GLAreaSignalName { get }
Show on GitHub


                    
                    
                    onNotifyAutoRender(flags:handler:)

Extension method

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.

Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

(C Language Example):

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

Note

This represents the underlying notify::auto-render signal

Declaration

Swift

@discardableResult
@inlinable
func onNotifyAutoRender(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GLAreaRef, _ pspec: ParamSpecRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`pspec`	the `GParamSpec` of the property which changed.
`handler`	The signal handler to call Run the given callback whenever the `notifyAutoRender` signal is emitted

Show on GitHub

notifyAutoRenderSignal Extension method
Typed notify::auto-render signal for using the connect(signal:) methods
Declaration
Swift

static var notifyAutoRenderSignal: GLAreaSignalName { get }
Show on GitHub


                    
                    
                    onNotifyContext(flags:handler:)

Extension method

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.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

(C Language Example):

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

Note

This represents the underlying notify::context signal

Declaration

Swift

@discardableResult
@inlinable
func onNotifyContext(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GLAreaRef, _ pspec: ParamSpecRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`pspec`	the `GParamSpec` of the property which changed.
`handler`	The signal handler to call Run the given callback whenever the `notifyContext` signal is emitted

Show on GitHub

notifyContextSignal Extension method
Typed notify::context signal for using the connect(signal:) methods
Declaration
Swift

static var notifyContextSignal: GLAreaSignalName { get }
Show on GitHub


                    
                    
                    onNotifyHasDepthBuffer(flags:handler:)

Extension method

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.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

(C Language Example):

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

Note

This represents the underlying notify::has-depth-buffer signal

Declaration

Swift

@discardableResult
@inlinable
func onNotifyHasDepthBuffer(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GLAreaRef, _ pspec: ParamSpecRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`pspec`	the `GParamSpec` of the property which changed.
`handler`	The signal handler to call Run the given callback whenever the `notifyHasDepthBuffer` signal is emitted

Show on GitHub

notifyHasDepthBufferSignal Extension method
Typed notify::has-depth-buffer signal for using the connect(signal:) methods
Declaration
Swift

static var notifyHasDepthBufferSignal: GLAreaSignalName { get }
Show on GitHub


                    
                    
                    onNotifyHasStencilBuffer(flags:handler:)

Extension method

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.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

(C Language Example):

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

Note

This represents the underlying notify::has-stencil-buffer signal

Declaration

Swift

@discardableResult
@inlinable
func onNotifyHasStencilBuffer(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GLAreaRef, _ pspec: ParamSpecRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`pspec`	the `GParamSpec` of the property which changed.
`handler`	The signal handler to call Run the given callback whenever the `notifyHasStencilBuffer` signal is emitted

Show on GitHub

notifyHasStencilBufferSignal Extension method
Typed notify::has-stencil-buffer signal for using the connect(signal:) methods
Declaration
Swift

static var notifyHasStencilBufferSignal: GLAreaSignalName { get }
Show on GitHub


                    
                    
                    onNotifyUseEs(flags:handler:)

Extension method

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.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

(C Language Example):

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

Note

This represents the underlying notify::use-es signal

Declaration

Swift

@discardableResult
@inlinable
func onNotifyUseEs(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GLAreaRef, _ pspec: ParamSpecRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`pspec`	the `GParamSpec` of the property which changed.
`handler`	The signal handler to call Run the given callback whenever the `notifyUseEs` signal is emitted

Show on GitHub

notifyUseEsSignal Extension method
Typed notify::use-es signal for using the connect(signal:) methods
Declaration
Swift

static var notifyUseEsSignal: GLAreaSignalName { get }
Show on GitHub

GLArea Class: GLAreaProtocol extension (methods and fields)

attachBuffers() Extension method
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 [signalGtk.GLArea::render] signal, and doesn’t normally need to be called by application code.
Declaration
Swift

@inlinable func attachBuffers()
Show on GitHub
getAutoRender() Extension method
Returns whether the area is in auto render mode or not.
Declaration
Swift

@inlinable func getAutoRender() -> Bool
Show on GitHub
getContext() Extension method
Retrieves the GdkGLContext used by area.
Declaration
Swift

@inlinable func getContext() -> Gdk.GLContextRef!
Show on GitHub
getError() Extension method
Gets the current error set on the area.
Declaration
Swift

@inlinable func getError() -> GLib.ErrorRef!
Show on GitHub
getHasDepthBuffer() Extension method
Returns whether the area has a depth buffer.
Declaration
Swift

@inlinable func getHasDepthBuffer() -> Bool
Show on GitHub
getHasStencilBuffer() Extension method
Returns whether the area has a stencil buffer.
Declaration
Swift

@inlinable func getHasStencilBuffer() -> Bool
Show on GitHub
getRequiredVersion(major:minor:) Extension method
Retrieves the required version of OpenGL.

See [methodGtk.GLArea.set_required_version].
Declaration
Swift

@inlinable func getRequiredVersion(major: UnsafeMutablePointer<gint>!, minor: UnsafeMutablePointer<gint>!)
Show on GitHub
getUseEs() Extension method
Returns whether the GtkGLArea should use OpenGL ES.

See [methodGtk.GLArea.set_use_es].
Declaration
Swift

@inlinable func getUseEs() -> Bool
Show on GitHub
makeCurrent() Extension method
Ensures that the GdkGLContext used by area is associated with the GtkGLArea.

This function is automatically called before emitting the [signalGtk.GLArea::render] signal, and doesn’t normally need to be called by application code.
Declaration
Swift

@inlinable func makeCurrent()
Show on GitHub
queueRender() Extension method
Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget.

This ensures that the [signalGtk.GLArea::render] signal is emitted during the draw.

This is only needed when [methodGtk.GLArea.set_auto_render] has been called with a false value. The default behaviour is to emit [signalGtk.GLArea::render] on each draw.
Declaration
Swift

@inlinable func queueRender()
Show on GitHub
set(autoRender:) Extension method
Sets whether the GtkGLArea is in auto render mode.

If auto_render is true the [signalGtk.GLArea::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 [methodGtk.GLArea.queue_render] must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw.
Declaration
Swift

@inlinable func set(autoRender: Bool)
Show on GitHub
set(error:) Extension method
Sets an error on the area which will be shown instead of the GL rendering.

This is useful in the [signalGtk.GLArea::create-context] signal if GL context creation fails.
Declaration
Swift

@inlinable func set(error: ErrorRef? = nil)
Show on GitHub
set(error:) Extension method
Sets an error on the area which will be shown instead of the GL rendering.

This is useful in the [signalGtk.GLArea::create-context] signal if GL context creation fails.
Declaration
Swift

@inlinable func set<GLibErrorT>(error: GLibErrorT?) where GLibErrorT : ErrorProtocol
Show on GitHub
set(hasDepthBuffer:) Extension method
Sets whether the GtkGLArea 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.
Declaration
Swift

@inlinable func set(hasDepthBuffer: Bool)
Show on GitHub
set(hasStencilBuffer:) Extension method
Sets whether the GtkGLArea 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.
Declaration
Swift

@inlinable func set(hasStencilBuffer: Bool)
Show on GitHub
setRequiredVersion(major:minor:) Extension method
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.
Declaration
Swift

@inlinable func setRequiredVersion(major: Int, minor: Int)
Show on GitHub
set(useEs:) Extension method
Sets whether the area should create an OpenGL or an OpenGL ES context.

You should check the capabilities of the GdkGLContext before drawing with either API.
Declaration
Swift

@inlinable func set(useEs: Bool)
Show on GitHub
autoRender Extension method
Returns whether the area is in auto render mode or not.
Declaration
Swift

@inlinable var autoRender: Bool { get nonmutating set }
Show on GitHub
context Extension method
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.
Declaration
Swift

@inlinable var context: Gdk.GLContextRef! { get }
Show on GitHub
error Extension method
Gets the current error set on the area.
Declaration
Swift

@inlinable var error: GLib.ErrorRef! { get nonmutating set }
Show on GitHub
hasDepthBuffer Extension method
Returns whether the area has a depth buffer.
Declaration
Swift

@inlinable var hasDepthBuffer: Bool { get nonmutating set }
Show on GitHub
hasStencilBuffer Extension method
Returns whether the area has a stencil buffer.
Declaration
Swift

@inlinable var hasStencilBuffer: Bool { get nonmutating set }
Show on GitHub
useEs Extension method
Returns whether the GtkGLArea should use OpenGL ES.

See [methodGtk.GLArea.set_use_es].
Declaration
Swift

@inlinable var useEs: Bool { get nonmutating set }
Show on GitHub

GLAreaProtocol

Drawing with GtkGLArea

Declaration

Default Implementation

Declaration

Declaration

GLArea Class

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

GLArea signals

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

Declaration

Parameters

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

GLArea Class: GLAreaProtocol extension (methods and fields)

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration