Class GLArea

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.GLArea
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Proxy
@Generated("org.javagi.JavaGI") public class GLArea extends Widget implements Accessible, Buildable, ConstraintTarget

Allows drawing with OpenGL.

An example GtkGLArea

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

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

The initial contents of the framebuffer are transparent.

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

  // record the active framebuffer ID, so we can return to it
  // with `glBindFramebuffer (GL_FRAMEBUFFER, screen_fb)` should
  // we, for instance, intend on utilizing the results of an
  // intermediate render texture pass
  GLuint screen_fb = 0;
  glGetIntegerv (GL_FRAMEBUFFER_BINDING, &screen_fb);

  // 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 Gtk.Widget::realize signal; you can use the Gtk.Widget::unrealize signal to clean up. Since the GdkGLContext creation and initialization may fail, you will need to check for errors, using getError().

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 Gtk.GLArea::create-context signal.

  • Constructor Details

    • GLArea

      public GLArea(MemorySegment address)
      Create a GLArea instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • GLArea

      public GLArea()
      Create a new GLArea.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the GLArea class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected GLArea asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • attachBuffers

      public void attachBuffers()

      Binds buffers to the framebuffer.

      Ensures that the this GLArea framebuffer object is made the current draw and read target, and that all the required buffers for the this GLArea are created and bound to the framebuffer.

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

    • getAllowedApis

      public Set<GLAPI> getAllowedApis()

      Gets the allowed APIs.

      See setAllowedApis(Set).

      Returns:
      the allowed APIs
      Since:
      4.12

    • getApi

      public Set<GLAPI> getApi()

      Gets the API that is currently in use.

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

      Returns:
      the currently used API
      Since:
      4.12

    • getAutoRender

      public boolean getAutoRender()
      Returns whether the area is in auto render mode or not.
      Returns:
      true if the this GLArea is auto rendering, false otherwise

    • getContext

      public @Nullable GLContext getContext()
      Retrieves the GdkGLContext used by area.
      Returns:
      the GdkGLContext

    • getError

      public @Nullable GError getError()
      Gets the current error set on the area.
      Returns:
      the GError

    • getHasDepthBuffer

      public boolean getHasDepthBuffer()
      Returns whether the area has a depth buffer.
      Returns:
      true if the this GLArea has a depth buffer, false otherwise

    • getHasStencilBuffer

      public boolean getHasStencilBuffer()
      Returns whether the area has a stencil buffer.
      Returns:
      true if the this GLArea has a stencil buffer, false otherwise

    • getRequiredVersion

      public void getRequiredVersion(Out<Integer> major, Out<Integer> minor)

      Retrieves the required version of OpenGL.

      See setRequiredVersion(int, int).

      Parameters:
      major - return location for the required major version
      minor - return location for the required minor version

    • getUseEs

      @Deprecated public boolean getUseEs()
      Deprecated.
      Use getApi()

      Returns whether the GtkGLArea should use OpenGL ES.

      See setUseEs(boolean).

      Returns:
      true if the GtkGLArea should create an OpenGL ES context and false otherwise

    • makeCurrent

      public void makeCurrent()

      Ensures that the GdkGLContext used by this GLArea is associated with the GtkGLArea.

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

    • queueRender

      public void queueRender()

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

      This ensures that the Gtk.GLArea::render signal is emitted during the draw.

      This is only needed when setAutoRender(boolean) has been called with a false value. The default behaviour is to emit Gtk.GLArea::render on each draw.

    • setAllowedApis

      public void setAllowedApis(Set<GLAPI> apis)

      Sets the allowed APIs to create a context with.

      You should check Gtk.GLArea:api before drawing with either API.

      By default, all APIs are allowed.

      Parameters:
      apis - the allowed APIs
      Since:
      4.12

    • setAllowedApis

      public void setAllowedApis(GLAPI... apis)

      Sets the allowed APIs to create a context with.

      You should check Gtk.GLArea:api before drawing with either API.

      By default, all APIs are allowed.

      Parameters:
      apis - the allowed APIs
      Since:
      4.12

    • setAutoRender

      public void setAutoRender(boolean autoRender)

      Sets whether the GtkGLArea is in auto render mode.

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

      Parameters:
      autoRender - a boolean

    • setError

      public void setError(@Nullable GError error)

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

      This is useful in the Gtk.GLArea::create-context signal if GL context creation fails.

      Parameters:
      error - a new GError, or null to unset the error

    • setHasDepthBuffer

      public void setHasDepthBuffer(boolean hasDepthBuffer)

      Sets whether the GtkGLArea should use a depth buffer.

      If hasDepthBuffer is true the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none.

      Parameters:
      hasDepthBuffer - true to add a depth buffer

    • setHasStencilBuffer

      public void setHasStencilBuffer(boolean hasStencilBuffer)

      Sets whether the GtkGLArea should use a stencil buffer.

      If hasStencilBuffer is true the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise there will be none.

      Parameters:
      hasStencilBuffer - true to add a stencil buffer

    • setRequiredVersion

      public void setRequiredVersion(int major, int minor)

      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.

      Parameters:
      major - the major version
      minor - the minor version

    • setUseEs

      @Deprecated public void setUseEs(boolean useEs)
      Deprecated.
      Use setAllowedApis(Set)

      Sets whether the this GLArea should create an OpenGL or an OpenGL ES context.

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

      Parameters:
      useEs - whether to use OpenGL or OpenGL ES

    • createContext

      protected GLContext createContext()
      class closure for the GtkGLArea::create-context signal

    • render

      protected boolean render(GLContext context)
      class closure for the GtkGLArea::render signal

    • resize

      protected void resize(int width, int height)
      class closeure for the GtkGLArea::resize signal

    • onCreateContext

      public SignalConnection<GLArea.CreateContextCallback> onCreateContext(GLArea.CreateContextCallback handler)

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

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitCreateContext

      public GLContext emitCreateContext()
      Emits the "create-context" signal. See onCreateContext(GLArea.CreateContextCallback).

    • onRender

      public SignalConnection<GLArea.RenderCallback> onRender(GLArea.RenderCallback handler)

      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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitRender

      public boolean emitRender(@Nullable GLContext context)
      Emits the "render" signal. See onRender(GLArea.RenderCallback).

    • onResize

      public SignalConnection<GLArea.ResizeCallback> onResize(GLArea.ResizeCallback handler)

      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.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitResize

      public void emitResize(int width, int height)
      Emits the "resize" signal. See onResize(GLArea.ResizeCallback).

    • builder

      public static GLArea.Builder<? extends GLArea.Builder> builder()
      A GLArea.Builder object constructs a GLArea with the specified properties. Use the various set...() methods to set properties, and finish construction with GLArea.Builder.build().
      Returns:
      the builder object