From dadce598ba1c06b6031a1ac842bbca9f9eae41e4 Mon Sep 17 00:00:00 2001 From: Matthew Waters Date: Sat, 23 Nov 2013 22:57:49 +1100 Subject: [PATCH] [859/906] window: provide some documetation --- gst-libs/gst/gl/gstglwindow.c | 127 +++++++++++++++++++++++++++++++++++++++++- gst-libs/gst/gl/gstglwindow.h | 27 ++++++++- 2 files changed, 149 insertions(+), 5 deletions(-) diff --git a/gst-libs/gst/gl/gstglwindow.c b/gst-libs/gst/gl/gstglwindow.c index 79bd4cd..903ee95 100644 --- a/gst-libs/gst/gl/gstglwindow.c +++ b/gst-libs/gst/gl/gstglwindow.c @@ -18,6 +18,16 @@ * Boston, MA 02110-1301, USA. */ +/** + * SECTION:gstglwindow + * @short_description: window/surface abstraction + * @title: GstGLWindow + * @see_also: #GstGLContext, #GstGLDisplay + * + * GstGLWindow represents a window that elements can render into. A window can + * either be a user visible window (onscreen) or hidden (offscreen). + */ + #if HAVE_CONFIG_H # include "config.h" #endif @@ -110,6 +120,12 @@ gst_gl_window_class_init (GstGLWindowClass * klass) G_OBJECT_CLASS (klass)->finalize = gst_gl_window_finalize; } +/** + * gst_gl_window_new: + * @display: a #GstGLDisplay + * + * Returns: (transfer full): a new #GstGLWindow using @display's connection + */ GstGLWindow * gst_gl_window_new (GstGLDisplay * display) { @@ -175,6 +191,14 @@ gst_gl_window_finalize (GObject * object) G_OBJECT_CLASS (gst_gl_window_parent_class)->finalize (object); } +/** + * gst_gl_window_set_window_handle: + * @window: a #GstGLWindow + * @handle: handle to the window + * + * Sets the window that this @window should render into. Some implementations + * require this to be called with a valid handle before drawing can commence. + */ void gst_gl_window_set_window_handle (GstGLWindow * window, guintptr handle) { @@ -190,6 +214,14 @@ gst_gl_window_set_window_handle (GstGLWindow * window, guintptr handle) GST_GL_WINDOW_UNLOCK (window); } +/** + * gst_gl_window_draw_unlocked: + * @window: a #GstGLWindow + * @width: requested width of the window + * @height: requested height of the window + * + * Redraw the window contents. Implementations should invoke the draw callback. + */ void gst_gl_window_draw_unlocked (GstGLWindow * window, guint width, guint height) { @@ -202,6 +234,14 @@ gst_gl_window_draw_unlocked (GstGLWindow * window, guint width, guint height) window_class->draw_unlocked (window, width, height); } +/** + * gst_gl_window_draw: + * @window: a #GstGLWindow + * @width: requested width of the window + * @height: requested height of the window + * + * Redraw the window contents. Implementations should invoke the draw callback. + */ void gst_gl_window_draw (GstGLWindow * window, guint width, guint height) { @@ -223,6 +263,12 @@ gst_gl_window_draw (GstGLWindow * window, guint width, guint height) GST_GL_WINDOW_UNLOCK (window); } +/** + * gst_gl_window_run: + * @window: a #GstGLWindow + * + * Start the execution of the runloop. + */ void gst_gl_window_run (GstGLWindow * window) { @@ -238,6 +284,12 @@ gst_gl_window_run (GstGLWindow * window) GST_GL_WINDOW_UNLOCK (window); } +/** + * gst_gl_window_quit: + * @window: a #GstGLWindow + * + * Quit the runloop's execution. + */ void gst_gl_window_quit (GstGLWindow * window) { @@ -309,6 +361,15 @@ gst_gl_window_default_send_message (GstGLWindow * window, g_cond_clear (&message.cond); } +/** + * gst_gl_window_send_message: + * @window: a #GstGLWindow + * @callback: (scope async): function to invoke + * @data: (closure): data to invoke @callback with + * + * Invoke @callback with data on the window thread. @callback is guarenteed to + * have executed when this function returns. + */ void gst_gl_window_send_message (GstGLWindow * window, GstGLWindowCB callback, gpointer data) @@ -325,6 +386,16 @@ gst_gl_window_send_message (GstGLWindow * window, GstGLWindowCB callback, GST_GL_WINDOW_UNLOCK (window); } +/** + * gst_gl_window_send_message_async: + * @window: a #GstGLWindow + * @callback: (scope async): function to invoke + * @data: (closure): data to invoke @callback with + * @destroy: (destroy): called when @data is not needed anymore + * + * Invoke @callback with @data on the window thread. The callback may not + * have been executed when this function returns. + */ void gst_gl_window_send_message_async (GstGLWindow * window, GstGLWindowCB callback, gpointer data, GDestroyNotify destroy) @@ -341,9 +412,8 @@ gst_gl_window_send_message_async (GstGLWindow * window, GstGLWindowCB callback, /** * gst_gl_window_set_need_lock: - * - * window: a #GstGLWindow - * need_lock: whether the @window needs to lock for concurrent access + * @window: a #GstGLWindow + * @need_lock: whether the @window needs to lock for concurrent access * * This API is intended only for subclasses of #GstGLWindow in order to ensure * correct interaction with the underlying window system. @@ -356,6 +426,15 @@ gst_gl_window_set_need_lock (GstGLWindow * window, gboolean need_lock) window->need_lock = need_lock; } +/** + * gst_gl_window_set_draw_callback: + * @window: a #GstGLWindow + * @callback: (scope notified): function to invoke + * @data: (closure): data to invoke @callback with + * @destroy_notify: (destroy): called when @data is not needed any more + * + * Sets the draw callback called everytime gst_gl_window_draw() is called + */ void gst_gl_window_set_draw_callback (GstGLWindow * window, GstGLWindowCB callback, gpointer data, GDestroyNotify destroy_notify) @@ -374,6 +453,15 @@ gst_gl_window_set_draw_callback (GstGLWindow * window, GstGLWindowCB callback, GST_GL_WINDOW_UNLOCK (window); } +/** + * gst_gl_window_set_resize_callback: + * @window: a #GstGLWindow + * @callback: (scope notified): function to invoke + * @data: (closure): data to invoke @callback with + * @destroy_notify: (destroy): called when @data is not needed any more + * + * Sets the resize callback called everytime a resize of the window occurs. + */ void gst_gl_window_set_resize_callback (GstGLWindow * window, GstGLWindowResizeCB callback, gpointer data, GDestroyNotify destroy_notify) @@ -392,6 +480,15 @@ gst_gl_window_set_resize_callback (GstGLWindow * window, GST_GL_WINDOW_UNLOCK (window); } +/** + * gst_gl_window_set_close_callback: + * @window: a #GstGLWindow + * @callback: (scope notified): function to invoke + * @data: (closure): data to invoke @callback with + * @destroy_notify: (destroy): called when @data is not needed any more + * + * Sets the callback called when the window is about to close. + */ void gst_gl_window_set_close_callback (GstGLWindow * window, GstGLWindowCB callback, gpointer data, GDestroyNotify destroy_notify) @@ -410,12 +507,24 @@ gst_gl_window_set_close_callback (GstGLWindow * window, GstGLWindowCB callback, GST_GL_WINDOW_UNLOCK (window); } +/** + * gst_gl_window_is_running: + * @window: a #GstGLWindow + * + * Whether the runloop is running + */ gboolean gst_gl_window_is_running (GstGLWindow * window) { return window->priv->alive; } +/** + * gst_gl_window_get_display: + * @window: a #GstGLWindow + * + * Returns: the windowing system display handle for this @window + */ guintptr gst_gl_window_get_display (GstGLWindow * window) { @@ -435,6 +544,12 @@ gst_gl_window_get_display (GstGLWindow * window) return ret; } +/** + * gst_gl_window_get_window_handle: + * @window: a #GstGLWindow + * + * Returns: the window handle we are currently rendering into + */ guintptr gst_gl_window_get_window_handle (GstGLWindow * window) { @@ -454,6 +569,12 @@ gst_gl_window_get_window_handle (GstGLWindow * window) return ret; } +/** + * gst_gl_window_get_context: + * @window: a #GstGLWindow + * + * Returns: (transfer full): the #GstGLContext associated with this @window + */ GstGLContext * gst_gl_window_get_context (GstGLWindow * window) { diff --git a/gst-libs/gst/gl/gstglwindow.h b/gst-libs/gst/gl/gstglwindow.h index 4a03fc8..fb8298b 100644 --- a/gst-libs/gst/gl/gstglwindow.h +++ b/gst-libs/gst/gl/gstglwindow.h @@ -25,6 +25,8 @@ #include #include +#include +#include G_BEGIN_DECLS @@ -64,11 +66,16 @@ typedef void (*GstGLWindowResizeCB) (gpointer data, guint width, guint height); #define GST_GL_WINDOW_CB(f) ((GstGLWindowCB) (f)) #define GST_GL_WINDOW_RESIZE_CB(f) ((GstGLWindowResizeCB) (f)) +/** + * GstGLWindow: + * + * #GstGLWindow is an opaque struct and should only be accessed through the + * provided api. + */ struct _GstGLWindow { /*< private >*/ GObject parent; - /*< public >*/ GMutex lock; gboolean need_lock; @@ -94,8 +101,24 @@ struct _GstGLWindow { GstGLWindowPrivate *priv; }; +/** + * GstGLWindowClass: + * @parent_class: Parent class + * @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_unlocked: redraw the window with the specified dimensions + * @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 + */ struct _GstGLWindowClass { - /*< private >*/ GObjectClass parent_class; guintptr (*get_display) (GstGLWindow *window); -- 2.7.4