Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
GI.Gtk.Objects.GLArea
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.
- newtype GLArea = GLArea (ManagedPtr GLArea)
- class GObject o => IsGLArea o
- toGLArea :: (MonadIO m, IsGLArea o) => o -> m GLArea
- noGLArea :: Maybe GLArea
- gLAreaAttachBuffers :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m ()
- gLAreaGetAutoRender :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- gLAreaGetContext :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m GLContext
- gLAreaGetError :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m (Maybe GError)
- gLAreaGetHasAlpha :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- gLAreaGetHasDepthBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- gLAreaGetHasStencilBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- gLAreaGetRequiredVersion :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m (Int32, Int32)
- gLAreaGetUseEs :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- gLAreaMakeCurrent :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m ()
- gLAreaNew :: (HasCallStack, MonadIO m) => m GLArea
- gLAreaQueueRender :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m ()
- gLAreaSetAutoRender :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- gLAreaSetError :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Maybe GError -> m ()
- gLAreaSetHasAlpha :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- gLAreaSetHasDepthBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- gLAreaSetHasStencilBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- gLAreaSetRequiredVersion :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Int32 -> Int32 -> m ()
- gLAreaSetUseEs :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- constructGLAreaAutoRender :: IsGLArea o => Bool -> IO (GValueConstruct o)
- getGLAreaAutoRender :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaAutoRender :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- getGLAreaContext :: (MonadIO m, IsGLArea o) => o -> m GLContext
- constructGLAreaHasAlpha :: IsGLArea o => Bool -> IO (GValueConstruct o)
- getGLAreaHasAlpha :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaHasAlpha :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- constructGLAreaHasDepthBuffer :: IsGLArea o => Bool -> IO (GValueConstruct o)
- getGLAreaHasDepthBuffer :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaHasDepthBuffer :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- constructGLAreaHasStencilBuffer :: IsGLArea o => Bool -> IO (GValueConstruct o)
- getGLAreaHasStencilBuffer :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaHasStencilBuffer :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- constructGLAreaUseEs :: IsGLArea o => Bool -> IO (GValueConstruct o)
- getGLAreaUseEs :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaUseEs :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- type C_GLAreaCreateContextCallback = Ptr () -> Ptr () -> IO (Ptr GLContext)
- type GLAreaCreateContextCallback = IO GLContext
- afterGLAreaCreateContext :: (IsGLArea a, MonadIO m) => a -> GLAreaCreateContextCallback -> m SignalHandlerId
- genClosure_GLAreaCreateContext :: GLAreaCreateContextCallback -> IO Closure
- mk_GLAreaCreateContextCallback :: C_GLAreaCreateContextCallback -> IO (FunPtr C_GLAreaCreateContextCallback)
- noGLAreaCreateContextCallback :: Maybe GLAreaCreateContextCallback
- onGLAreaCreateContext :: (IsGLArea a, MonadIO m) => a -> GLAreaCreateContextCallback -> m SignalHandlerId
- wrap_GLAreaCreateContextCallback :: GLAreaCreateContextCallback -> Ptr () -> Ptr () -> IO (Ptr GLContext)
- type C_GLAreaRenderCallback = Ptr () -> Ptr GLContext -> Ptr () -> IO CInt
- type GLAreaRenderCallback = GLContext -> IO Bool
- afterGLAreaRender :: (IsGLArea a, MonadIO m) => a -> GLAreaRenderCallback -> m SignalHandlerId
- genClosure_GLAreaRender :: GLAreaRenderCallback -> IO Closure
- mk_GLAreaRenderCallback :: C_GLAreaRenderCallback -> IO (FunPtr C_GLAreaRenderCallback)
- noGLAreaRenderCallback :: Maybe GLAreaRenderCallback
- onGLAreaRender :: (IsGLArea a, MonadIO m) => a -> GLAreaRenderCallback -> m SignalHandlerId
- wrap_GLAreaRenderCallback :: GLAreaRenderCallback -> Ptr () -> Ptr GLContext -> Ptr () -> IO CInt
- type C_GLAreaResizeCallback = Ptr () -> Int32 -> Int32 -> Ptr () -> IO ()
- type GLAreaResizeCallback = Int32 -> Int32 -> IO ()
- afterGLAreaResize :: (IsGLArea a, MonadIO m) => a -> GLAreaResizeCallback -> m SignalHandlerId
- genClosure_GLAreaResize :: GLAreaResizeCallback -> IO Closure
- mk_GLAreaResizeCallback :: C_GLAreaResizeCallback -> IO (FunPtr C_GLAreaResizeCallback)
- noGLAreaResizeCallback :: Maybe GLAreaResizeCallback
- onGLAreaResize :: (IsGLArea a, MonadIO m) => a -> GLAreaResizeCallback -> m SignalHandlerId
- wrap_GLAreaResizeCallback :: GLAreaResizeCallback -> Ptr () -> Int32 -> Int32 -> Ptr () -> IO ()
Exported types
Constructors
GLArea (ManagedPtr GLArea) |
Methods
attachBuffers
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area is in auto render mode or not.
Since: 3.16
getContext
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m GLContext | Returns: the |
Retrieves the GLContext
used by area
.
Since: 3.16
getError
Gets the current error set on the area
.
Since: 3.16
getHasAlpha
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area has an alpha component.
Since: 3.16
getHasDepthBuffer
gLAreaGetHasDepthBuffer Source #
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area has a depth buffer.
Since: 3.16
getHasStencilBuffer
gLAreaGetHasStencilBuffer Source #
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area has a stencil buffer.
Since: 3.16
getRequiredVersion
gLAreaGetRequiredVersion Source #
Retrieves the required version of OpenGL set
using gLAreaSetRequiredVersion
.
Since: 3.16
getUseEs
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Retrieves the value set by gLAreaSetUseEs
.
Since: 3.22
makeCurrent
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m () |
new
Arguments
:: (HasCallStack, MonadIO m) | |
=> m GLArea | Returns: the newly created |
Creates a new GLArea
widget.
Since: 3.16
queueRender
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> 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
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
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> 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 |
|
-> Bool |
|
-> 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 |
|
-> Bool |
|
-> 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 |
|
-> Int32 |
|
-> Int32 |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> 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
constructGLAreaAutoRender :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
context
hasAlpha
constructGLAreaHasAlpha :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
hasDepthBuffer
constructGLAreaHasDepthBuffer :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
hasStencilBuffer
constructGLAreaHasStencilBuffer :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
useEs
constructGLAreaUseEs :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
Signals
createContext
afterGLAreaCreateContext :: (IsGLArea a, MonadIO m) => a -> GLAreaCreateContextCallback -> m SignalHandlerId Source #
mk_GLAreaCreateContextCallback :: C_GLAreaCreateContextCallback -> IO (FunPtr C_GLAreaCreateContextCallback) Source #
onGLAreaCreateContext :: (IsGLArea a, MonadIO m) => a -> GLAreaCreateContextCallback -> m SignalHandlerId Source #
wrap_GLAreaCreateContextCallback :: GLAreaCreateContextCallback -> Ptr () -> Ptr () -> IO (Ptr GLContext) Source #
render
afterGLAreaRender :: (IsGLArea a, MonadIO m) => a -> GLAreaRenderCallback -> m SignalHandlerId Source #
onGLAreaRender :: (IsGLArea a, MonadIO m) => a -> GLAreaRenderCallback -> m SignalHandlerId Source #
wrap_GLAreaRenderCallback :: GLAreaRenderCallback -> Ptr () -> Ptr GLContext -> Ptr () -> IO CInt Source #
resize
afterGLAreaResize :: (IsGLArea a, MonadIO m) => a -> GLAreaResizeCallback -> m SignalHandlerId Source #
onGLAreaResize :: (IsGLArea a, MonadIO m) => a -> GLAreaResizeCallback -> m SignalHandlerId Source #
wrap_GLAreaResizeCallback :: GLAreaResizeCallback -> Ptr () -> Int32 -> Int32 -> Ptr () -> IO () Source #