GstGLWindow: GStreamer Bad Plugins 1.0 Library Reference Manual

## GstGLWindow GstGLWindow — window/surface abstraction |

## Functions

GQuark | gst_gl_window_error_quark ()
void | (*GstGLWindowResizeCB) ()
#define | GST_GL_WINDOW_RESIZE_CB()
void | (*GstGLWindowCB) ()
#define | GST_GL_WINDOW_CB()
GstGLWindow * | gst_gl_window_new ()
void | gst_gl_window_draw ()
gboolean | gst_gl_window_is_running ()
void | gst_gl_window_quit ()
void | gst_gl_window_run ()
GstGLContext * | gst_gl_window_get_context ()
guintptr | gst_gl_window_get_display ()
void | gst_gl_window_send_message ()
void | gst_gl_window_send_message_async ()
void | gst_gl_window_set_close_callback ()
void | gst_gl_window_set_draw_callback ()
void | gst_gl_window_set_resize_callback ()
void | gst_gl_window_set_window_handle ()
guintptr | gst_gl_window_get_window_handle ()
void | gst_gl_window_set_preferred_size ()
void | gst_gl_window_show ()
void | gst_gl_window_get_surface_dimensions ()
void | gst_gl_window_handle_events ()
void | gst_gl_window_queue_resize ()
void | gst_gl_window_resize ()
gboolean | gst_gl_window_set_render_rectangle ()

## Signals

void | key-event | Run Last
void | mouse-event | Run Last

## Types and Values

enum | GstGLWindowError
#define | GST_GL_WINDOW_ERROR
| GstGLWindow
| GstGLWindowClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstGLWindow

## Description

GstGLWindow represents a window that elements can render into. A window can either be a user visible window (onscreen) or hidden (offscreen).

## Functions

### gst_gl_window_error_quark ()

    GQuark
    gst_gl_window_error_quark (void);

### GstGLWindowResizeCB ()

    void
    (*GstGLWindowResizeCB) (gpointer data,
                            guint width,
                            guint height);

### GST_GL_WINDOW_RESIZE_CB()

    #define GST_GL_WINDOW_RESIZE_CB(f)		 ((GstGLWindowResizeCB) (f))

### GstGLWindowCB ()

    void
    (*GstGLWindowCB) (gpointer data);

### GST_GL_WINDOW_CB()

    #define GST_GL_WINDOW_CB(f)			 ((GstGLWindowCB) (f))

### gst_gl_window_new ()

    GstGLWindow *
    gst_gl_window_new (GstGLDisplay *display);

#### Parameters

display | a GstGLDisplay |

#### Returns

a new GstGLWindow using `display` 's connection.

[transfer full]

Since: 1.4

### gst_gl_window_draw ()

    void
    gst_gl_window_draw (GstGLWindow *window);

Redraw the window contents. Implementations should invoke the draw callback.

#### Parameters

window | a GstGLWindow |

Since: 1.4

### gst_gl_window_is_running ()

    gboolean
    gst_gl_window_is_running (GstGLWindow *window);

Whether the runloop is running

#### Parameters

window | a GstGLWindow |

Since: 1.4

### gst_gl_window_quit ()

    void
    gst_gl_window_quit (GstGLWindow *window);

Quit the runloop's execution.

#### Parameters

window | a GstGLWindow |

Since: 1.4

### gst_gl_window_run ()

    void
    gst_gl_window_run (GstGLWindow *window);

Start the execution of the runloop.

#### Parameters

window | a GstGLWindow |

Since: 1.4

### gst_gl_window_get_context ()

    GstGLContext *
    gst_gl_window_get_context (GstGLWindow *window);

#### Parameters

window | a GstGLWindow |

#### Returns

the GstGLContext associated with this `window` .

[transfer full]

Since: 1.4

### gst_gl_window_get_display ()

    guintptr
    gst_gl_window_get_display (GstGLWindow *window);

#### Parameters

window | a GstGLWindow |

#### Returns

the windowing system display handle for this `window`

Since: 1.4

### gst_gl_window_send_message ()

    void
    gst_gl_window_send_message (GstGLWindow *window,
                                GstGLWindowCB callback,
                                gpointer data);

Invoke `callback` with data on the window thread. `callback` is guarenteed to have executed when this function returns.

#### Parameters

window | a GstGLWindow |
callback | function to invoke. | [scope async]
data | data to invoke `callback` with. | [closure]

Since: 1.4

### gst_gl_window_send_message_async ()

    void
    gst_gl_window_send_message_async (GstGLWindow *window,
                                      GstGLWindowCB callback,
                                      gpointer data,
                                      GDestroyNotify destroy);

Invoke `callback` with `data` on the window thread. The callback may not have been executed when this function returns.

#### Parameters

window | a GstGLWindow |
callback | function to invoke. | [scope async]
data | data to invoke `callback` with. | [closure]
destroy | called when `data` is not needed anymore |

Since: 1.4

### gst_gl_window_set_close_callback ()

    void
    gst_gl_window_set_close_callback (GstGLWindow *window,
                                      GstGLWindowCB callback,
                                      gpointer data,
                                      GDestroyNotify destroy_notify);

Sets the callback called when the window is about to close.

#### Parameters

window | a GstGLWindow |
callback | function to invoke. | [scope notified]
data | data to invoke `callback` with. | [closure]
destroy_notify | called when `data` is not needed any more |

Since: 1.4

### gst_gl_window_set_draw_callback ()

    void
    gst_gl_window_set_draw_callback (GstGLWindow *window,
                                     GstGLWindowCB callback,
                                     gpointer data,
                                     GDestroyNotify destroy_notify);

Sets the draw callback called everytime `gst_gl_window_draw()` is called

#### Parameters

window | a GstGLWindow |
callback | function to invoke. | [scope notified]
data | data to invoke `callback` with. | [closure]
destroy_notify | called when `data` is not needed any more |

Since: 1.4

### gst_gl_window_set_resize_callback ()

    void
    gst_gl_window_set_resize_callback (GstGLWindow *window,
                                       GstGLWindowResizeCB callback,
                                       gpointer data,
                                       GDestroyNotify destroy_notify);

Sets the resize callback called everytime a resize of the window occurs.

#### Parameters

window | a GstGLWindow |
callback | function to invoke. | [scope notified]
data | data to invoke `callback` with. | [closure]
destroy_notify | called when `data` is not needed any more |

Since: 1.4

### gst_gl_window_set_window_handle ()

    void
    gst_gl_window_set_window_handle (GstGLWindow *window,
                                     guintptr handle);

Sets the window that this `window` should render into. Some implementations require this to be called with a valid handle before drawing can commence.

#### Parameters

window | a GstGLWindow |
handle | handle to the window |

Since: 1.4

### gst_gl_window_get_window_handle ()

    guintptr
    gst_gl_window_get_window_handle (GstGLWindow *window);

#### Parameters

window | a GstGLWindow |

#### Returns

the window handle we are currently rendering into

Since: 1.4

### gst_gl_window_set_preferred_size ()

    void
    gst_gl_window_set_preferred_size (GstGLWindow *window,
                                      gint width,
                                      gint height);

Set the preferred width and height of the window. Implementations are free to ignore this information.

#### Parameters

window | a GstGLWindow |
width | new preferred width |
height | new preferred height |

Since: 1.6

### gst_gl_window_show ()

    void
    gst_gl_window_show (GstGLWindow *window);

Present the window to the screen.

#### Parameters

window | a GstGLWindow |

Since: 1.6

### gst_gl_window_get_surface_dimensions ()

    void
    gst_gl_window_get_surface_dimensions (GstGLWindow *window,
                                          guint *width,
                                          guint *height);

#### Parameters

window | a GstGLWindow |
width | resulting surface width. | [out]
height | resulting surface height. | [out]

Since: 1.6

### gst_gl_window_handle_events ()

    void
    gst_gl_window_handle_events (GstGLWindow *window,
                                 gboolean handle_events);

Tell a `window` that it should handle events from the window system. These events are forwarded upstream as navigation events. In some window systems events are not propagated in the window hierarchy if a client is listening for them. This method allows you to disable events handling completely from the `window` .

#### Parameters

window | a GstGLWindow |
handle_events | a gboolean indicating if events should be handled or not. |

### gst_gl_window_queue_resize ()

    void
    gst_gl_window_queue_resize (GstGLWindow *window);

### gst_gl_window_resize ()

    void
    gst_gl_window_resize (GstGLWindow *window,
                          guint width,
                          guint height);

### gst_gl_window_set_render_rectangle ()

    gboolean
    gst_gl_window_set_render_rectangle (GstGLWindow *window,
                                        gint x,
                                        gint y,
                                        gint width,
                                        gint height);

Tell a `window` that it should render into a specific region of the window according to the GstVideoOverlay interface.

#### Parameters

window | a GstGLWindow |
x | x position |
y | y position |
width | width |
height | height |

#### Returns

whether the specified region could be set

## Types and Values

### enum GstGLWindowError

#### Members

GST_GL_WINDOW_ERROR_FAILED | failed for a unspecified reason |
GST_GL_WINDOW_ERROR_OLD_LIBS | the implementation is too old |
GST_GL_WINDOW_ERROR_RESOURCE_UNAVAILABLE | no such resource was found |

### GST_GL_WINDOW_ERROR

    #define GST_GL_WINDOW_ERROR (gst_gl_window_error_quark ())

### GstGLWindow

    typedef struct _GstGLWindow GstGLWindow;

GstGLWindow is an opaque struct and should only be accessed through the provided api.

### GstGLWindowClass

    typedef struct {
      GstObjectClass parent_class;

      guintptr (*get_display)        (GstGLWindow *window);
      void     (*set_window_handle)  (GstGLWindow *window, guintptr id);
      guintptr (*get_window_handle)  (GstGLWindow *window);
      void     (*draw)               (GstGLWindow *window);
      void     (*run)                (GstGLWindow *window);
      void     (*quit)               (GstGLWindow *window);
      void     (*send_message)       (GstGLWindow *window, GstGLWindowCB callback, gpointer data);
      void     (*send_message_async) (GstGLWindow *window, GstGLWindowCB callback, gpointer data, GDestroyNotify destroy);

      gboolean (*open)               (GstGLWindow *window, GError **error);
      void     (*close)              (GstGLWindow *window);
      void     (*handle_events)      (GstGLWindow *window, gboolean handle_events);
      void     (*set_preferred_size) (GstGLWindow *window, gint width, gint height);
      void     (*show)               (GstGLWindow *window);
      gboolean (*set_render_rectangle)(GstGLWindow *window, gint x, gint y, gint width, gint height);
      void     (*queue_resize)       (GstGLWindow *window);
    } GstGLWindowClass;

#### Members

`get_display` () | Gets the current windowing system display connection |
`set_window_handle` () | Set a window to render into |
`get_window_handle` () | Gets the current window that this GstGLWindow is rendering into |
`draw` () | redraw the window with the specified dimensions |
`run` () | run the mainloop |
`quit` () | send a quit to the mainloop |
`send_message` () | invoke a function on the window thread. Required to be reentrant. |
`send_message_async` () | invoke a function on the window thread. `run` may or may not have been called. Required to be reentrant. |
`open` () | open the connection to the display |
`close` () | close the connection to the display |
`handle_events` () | whether to handle 'extra' events from the windowing system. Basic events like surface moves and resizes are still valid things to listen for. |
`set_preferred_size` () | request that the window change surface size. The implementation is free to ignore this information. |
`show` () | request that the window be shown to the user |
`set_render_rectangle` () | request a rectangle to render into. See GstVideoOverlay |
`queue_resize` () | request a resize to occur when possible |

## Signal Details

### The `“key-event”` signal

    void
    user_function (GstGLWindow *object,
                   gchar       *id,
                   gchar       *key,
                   gpointer     user_data)

Will be emitted when a key event is received by the GstGLwindow.

#### Parameters

object | the GstGLWindow |
id | the name of the event |
key | the id of the key pressed |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.6

### The `“mouse-event”` signal

    void
    user_function (GstGLWindow *object,
                   gchar       *id,
                   gint         button,
                   gdouble      x,
                   gdouble      y,
                   gpointer     user_data)

Will be emitted when a mouse event is received by the GstGLwindow.

#### Parameters

object | the GstGLWindow |
id | the name of the event |
button | the id of the button |
x | the x coordinate of the mouse event |
y | the y coordinate of the mouse event |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.6

## See Also

GstGLContext, GstGLDisplay