[859/906] window: provide some documetation

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

gst-libs/gst/gl/gstglwindow.h

@@ -25,6 +25,8 @@
 #include <gst/gst.h>
 
 #include <gst/gl/gstgl_fwd.h>
+#include <gst/gl/gstglcontext.h>
+#include <gst/gl/gstgldisplay.h>
 
 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);