gi-gtk-3.0.11: Gtk bindings

CopyrightWill Thompson, Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.Gtk.Objects.GLArea

Contents

Description

GLArea is a widget that allows drawing with OpenGL.

GLArea sets up its own 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 gtkGLAreaClass.render() virtual function.

The GLArea widget ensures that the 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 GLArea is to create a widget instance and connect to the GLArea::render signal:

C code

 // 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:

C code

 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 GLContext creation and initialization may fail, you will need to check for errors, using gLAreaGetError. An example of how to safely initialize the GL state is:

C code

 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 GLContext you should use the GLArea::create-context signal.

Synopsis

Exported types

newtype GLArea Source #

Constructors

GLArea (ManagedPtr GLArea) 

Methods

attachBuffers

gLAreaAttachBuffers Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m () 

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

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

Since: 3.16

getAutoRender

gLAreaGetAutoRender Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m Bool

Returns: True if the area is auto rendering, False otherwise

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

Since: 3.16

getContext

gLAreaGetContext Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m GLContext

Returns: the GLContext

Retrieves the GLContext used by area.

Since: 3.16

getError

data GLAreaGetErrorMethodInfo Source #

Instances

((~) * signature (m (Maybe GError)), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetErrorMethodInfo a signature Source # 

gLAreaGetError Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m (Maybe GError)

Returns: the GError or Nothing

Gets the current error set on the area.

Since: 3.16

getHasAlpha

gLAreaGetHasAlpha Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m Bool

Returns: True if the area has an alpha component, False otherwise

Returns whether the area has an alpha component.

Since: 3.16

getHasDepthBuffer

gLAreaGetHasDepthBuffer Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m Bool

Returns: True if the area has a depth buffer, False otherwise

Returns whether the area has a depth buffer.

Since: 3.16

getHasStencilBuffer

gLAreaGetHasStencilBuffer Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m Bool

Returns: True if the area has a stencil buffer, False otherwise

Returns whether the area has a stencil buffer.

Since: 3.16

getRequiredVersion

gLAreaGetRequiredVersion Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m (Int32, Int32) 

Retrieves the required version of OpenGL set using gLAreaSetRequiredVersion.

Since: 3.16

getUseEs

data GLAreaGetUseEsMethodInfo Source #

Instances

((~) * signature (m Bool), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetUseEsMethodInfo a signature Source # 

gLAreaGetUseEs Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m Bool

Returns: True if the GLArea should create an OpenGL ES context and False otherwise

Retrieves the value set by gLAreaSetUseEs.

Since: 3.22

makeCurrent

data GLAreaMakeCurrentMethodInfo Source #

Instances

((~) * signature (m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaMakeCurrentMethodInfo a signature Source # 

gLAreaMakeCurrent Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m () 

Ensures that the GLContext used by area is associated with the GLArea.

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

Since: 3.16

new

gLAreaNew Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> m GLArea

Returns: the newly created GLArea

Creates a new GLArea widget.

Since: 3.16

queueRender

data GLAreaQueueRenderMethodInfo Source #

Instances

((~) * signature (m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaQueueRenderMethodInfo a signature Source # 

gLAreaQueueRender Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> m () 

Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget, ensuring that the GLArea::render signal is emitted during the draw.

This is only needed when the gLAreaSetAutoRender has been called with a False value. The default behaviour is to emit GLArea::render on each draw.

Since: 3.16

setAutoRender

data GLAreaSetAutoRenderMethodInfo Source #

Instances

((~) * signature (Bool -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetAutoRenderMethodInfo a signature Source # 

gLAreaSetAutoRender Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> Bool

autoRender: a boolean

-> m () 

If autoRender is True the 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 gLAreaQueueRender must be called. This mode is useful when the scene changes seldomly, but takes a long time to redraw.

Since: 3.16

setError

data GLAreaSetErrorMethodInfo Source #

Instances

((~) * signature (Maybe GError -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetErrorMethodInfo a signature Source # 

gLAreaSetError Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> Maybe GError

error: a new GError, or Nothing to unset the error

-> m () 

Sets an error on the area which will be shown instead of the GL rendering. This is useful in the GLArea::create-context signal if GL context creation fails.

Since: 3.16

setHasAlpha

data GLAreaSetHasAlphaMethodInfo Source #

Instances

((~) * signature (Bool -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetHasAlphaMethodInfo a signature Source # 

gLAreaSetHasAlpha Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> Bool

hasAlpha: True to add an alpha component

-> m () 

If hasAlpha 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 hasAlpha is False there will be no alpha channel, and the buffer will fully replace anything below the widget.

Since: 3.16

setHasDepthBuffer

gLAreaSetHasDepthBuffer Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> Bool

hasDepthBuffer: True to add a depth buffer

-> m () 

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

Since: 3.16

setHasStencilBuffer

gLAreaSetHasStencilBuffer Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> Bool

hasStencilBuffer: True to add a stencil buffer

-> m () 

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

Since: 3.16

setRequiredVersion

gLAreaSetRequiredVersion Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> Int32

major: the major version

-> Int32

minor: the minor version

-> m () 

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.

Since: 3.16

setUseEs

data GLAreaSetUseEsMethodInfo Source #

Instances

((~) * signature (Bool -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetUseEsMethodInfo a signature Source # 

gLAreaSetUseEs Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a) 
=> a

area: a GLArea

-> Bool

useEs: whether to use OpenGL or OpenGL ES

-> m () 

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

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

Since: 3.22

Properties

autoRender

data GLAreaAutoRenderPropertyInfo Source #

Instances

AttrInfo GLAreaAutoRenderPropertyInfo Source # 
type AttrOrigin GLAreaAutoRenderPropertyInfo Source # 
type AttrLabel GLAreaAutoRenderPropertyInfo Source # 
type AttrGetType GLAreaAutoRenderPropertyInfo Source # 
type AttrBaseTypeConstraint GLAreaAutoRenderPropertyInfo Source # 
type AttrSetTypeConstraint GLAreaAutoRenderPropertyInfo Source # 
type AttrAllowedOps GLAreaAutoRenderPropertyInfo Source # 

setGLAreaAutoRender :: (MonadIO m, IsGLArea o) => o -> Bool -> m () Source #

context

data GLAreaContextPropertyInfo Source #

Instances

AttrInfo GLAreaContextPropertyInfo Source # 
type AttrOrigin GLAreaContextPropertyInfo Source # 
type AttrLabel GLAreaContextPropertyInfo Source # 
type AttrGetType GLAreaContextPropertyInfo Source # 
type AttrBaseTypeConstraint GLAreaContextPropertyInfo Source # 
type AttrSetTypeConstraint GLAreaContextPropertyInfo Source # 
type AttrAllowedOps GLAreaContextPropertyInfo Source # 

hasAlpha

data GLAreaHasAlphaPropertyInfo Source #

Instances

AttrInfo GLAreaHasAlphaPropertyInfo Source # 
type AttrOrigin GLAreaHasAlphaPropertyInfo Source # 
type AttrLabel GLAreaHasAlphaPropertyInfo Source # 
type AttrGetType GLAreaHasAlphaPropertyInfo Source # 
type AttrBaseTypeConstraint GLAreaHasAlphaPropertyInfo Source # 
type AttrSetTypeConstraint GLAreaHasAlphaPropertyInfo Source # 
type AttrAllowedOps GLAreaHasAlphaPropertyInfo Source # 

setGLAreaHasAlpha :: (MonadIO m, IsGLArea o) => o -> Bool -> m () Source #

hasDepthBuffer

data GLAreaHasDepthBufferPropertyInfo Source #

Instances

AttrInfo GLAreaHasDepthBufferPropertyInfo Source # 
type AttrOrigin GLAreaHasDepthBufferPropertyInfo Source # 
type AttrLabel GLAreaHasDepthBufferPropertyInfo Source # 
type AttrGetType GLAreaHasDepthBufferPropertyInfo Source # 
type AttrBaseTypeConstraint GLAreaHasDepthBufferPropertyInfo Source # 
type AttrSetTypeConstraint GLAreaHasDepthBufferPropertyInfo Source # 
type AttrAllowedOps GLAreaHasDepthBufferPropertyInfo Source # 

hasStencilBuffer

data GLAreaHasStencilBufferPropertyInfo Source #

Instances

AttrInfo GLAreaHasStencilBufferPropertyInfo Source # 
type AttrOrigin GLAreaHasStencilBufferPropertyInfo Source # 
type AttrLabel GLAreaHasStencilBufferPropertyInfo Source # 
type AttrLabel GLAreaHasStencilBufferPropertyInfo = "has-stencil-buffer"
type AttrGetType GLAreaHasStencilBufferPropertyInfo Source # 
type AttrBaseTypeConstraint GLAreaHasStencilBufferPropertyInfo Source # 
type AttrSetTypeConstraint GLAreaHasStencilBufferPropertyInfo Source # 
type AttrAllowedOps GLAreaHasStencilBufferPropertyInfo Source # 

useEs

data GLAreaUseEsPropertyInfo Source #

Instances

AttrInfo GLAreaUseEsPropertyInfo Source # 
type AttrOrigin GLAreaUseEsPropertyInfo Source # 
type AttrLabel GLAreaUseEsPropertyInfo Source # 
type AttrGetType GLAreaUseEsPropertyInfo Source # 
type AttrBaseTypeConstraint GLAreaUseEsPropertyInfo Source # 
type AttrSetTypeConstraint GLAreaUseEsPropertyInfo Source # 
type AttrAllowedOps GLAreaUseEsPropertyInfo Source # 

setGLAreaUseEs :: (MonadIO m, IsGLArea o) => o -> Bool -> m () Source #

Signals

createContext

render

resize

type C_GLAreaResizeCallback = Ptr () -> Int32 -> Int32 -> Ptr () -> IO () Source #