docs: update xoverlay docs for api addition and deprecation

diff --git a/gst-libs/gst/interfaces/xoverlay.c b/gst-libs/gst/interfaces/xoverlay.c
index e7bd655..6fcb5cc 100644 (file)
--- a/gst-libs/gst/interfaces/xoverlay.c
+++ b/gst-libs/gst/interfaces/xoverlay.c
@@ -66,23 +66,23 @@
  *  // ignore anything but 'prepare-xwindow-id' element messages
  *  if (GST_MESSAGE_TYPE (message) != GST_MESSAGE_ELEMENT)
  *    return GST_BUS_PASS;
- *  
+ *
  *  if (!gst_structure_has_name (message->structure, "prepare-xwindow-id"))
  *    return GST_BUS_PASS;
- *  
+ *
  *  win = XCreateSimpleWindow (disp, root, 0, 0, 320, 240, 0, 0, 0);
- *  
+ *
  *  XSetWindowBackgroundPixmap (disp, win, None);
- *  
+ *
  *  XMapRaised (disp, win);
- *  
+ *
  *  XSync (disp, FALSE);
- *   
+ *
  *  gst_x_overlay_set_window_handle (GST_X_OVERLAY (GST_MESSAGE_SRC (message)),
  *      win);
- *   
+ *
  *  gst_message_unref (message);
- *   
+ *
  *  return GST_BUS_DROP;
  * }
  * ...
@@ -158,17 +158,17 @@
  *    return GST_BUS_PASS;
  *  if (!gst_structure_has_name (message->structure, "prepare-xwindow-id"))
  *    return GST_BUS_PASS;
- *  
+ *
  *  if (video_window_xid != 0) {
  *    GstXOverlay *xoverlay;
- *    
+ *
  *    // GST_MESSAGE_SRC (message) will be the video sink element
  *    xoverlay = GST_X_OVERLAY (GST_MESSAGE_SRC (message));
  *    gst_x_overlay_set_window_handle (xoverlay, video_window_xid);
  *  } else {
  *    g_warning ("Should have obtained video_window_xid by now!");
  *  }
- *  
+ *
  *  gst_message_unref (message);
  *  return GST_BUS_DROP;
  * }
@@ -182,7 +182,7 @@
  *   if (!gdk_window_ensure_native (widget->window))
  *     g_error ("Couldn't create native window needed for GstXOverlay!");
  * #endif
- * 
+ *
  * #ifdef GDK_WINDOWING_X11
  *   video_window_xid = GDK_WINDOW_XID (video_window->window);
  * #endif
@@ -208,12 +208,12 @@
  *   ...
  *   // show the GUI
  *   gtk_widget_show_all (app_window);
- * 
+ *
  *   // realize window now so that the video window gets created and we can
  *   // obtain its XID before the pipeline is started up and the videosink
  *   // asks for the XID of the window to render onto
  *   gtk_widget_realize (window);
- * 
+ *
  *   // we should have the XID now
  *   g_assert (video_window_xid != 0);
  *   ...
@@ -235,39 +235,39 @@
  * #include <glib.h>
  * #include <gst/gst.h>
  * #include <gst/interfaces/xoverlay.h>
- * 
+ *
  * #include <QApplication>
  * #include <QTimer>
  * #include <QWidget>
- * 
+ *
  * int main(int argc, char *argv[])
  * {
  *   if (!g_thread_supported ())
  *     g_thread_init (NULL);
- * 
+ *
  *   gst_init (&argc, &argv);
  *   QApplication app(argc, argv);
  *   app.connect(&app, SIGNAL(lastWindowClosed()), &app, SLOT(quit ()));
- * 
+ *
  *   // prepare the pipeline
- * 
+ *
  *   GstElement *pipeline = gst_pipeline_new ("xvoverlay");
  *   GstElement *src = gst_element_factory_make ("videotestsrc", NULL);
  *   GstElement *sink = gst_element_factory_make ("xvimagesink", NULL);
  *   gst_bin_add_many (GST_BIN (pipeline), src, sink, NULL);
  *   gst_element_link (src, sink);
- *   
+ *
  *   // prepare the ui
- * 
+ *
  *   QWidget window;
  *   window.resize(320, 240);
  *   window.show();
- *   
+ *
  *   WId xwinid = window.winId();
  *   gst_x_overlay_set_window_handle (GST_X_OVERLAY (sink), xwinid);
- * 
+ *
  *   // run the pipeline
- * 
+ *
  *   GstStateChangeReturn sret = gst_element_set_state (pipeline,
  *       GST_STATE_PLAYING);
  *   if (sret == GST_STATE_CHANGE_FAILURE) {
@@ -276,13 +276,13 @@
  *     // Exit application
  *     QTimer::singleShot(0, QApplication::activeWindow(), SLOT(quit()));
  *   }
- * 
+ *
  *   int ret = app.exec();
- *   
+ *
  *   window.hide();
  *   gst_element_set_state (pipeline, GST_STATE_NULL);
  *   gst_object_unref (pipeline);
- * 
+ *
  *   return ret;
  * }
  * ]|
@@ -333,12 +333,12 @@ gst_x_overlay_base_init (gpointer g_class)
 
 /**
  * gst_x_overlay_set_xwindow_id:
- * @overlay: a #GstXOverlay to set the XWindow on.
- * @xwindow_id: a #XID referencing the XWindow.
+ * @overlay: a #GstXOverlay to set the window on.
+ * @xwindow_id: a XID referencing the XWindow.
  *
  * This will call the video overlay's set_xwindow_id method. You should
  * use this method to tell to a XOverlay to display video output to a
- * specific XWindow. Passing 0 as the xwindow_id will tell the overlay to
+ * specific XWindow. Passing 0 as the @xwindow_id will tell the overlay to
  * stop using that window and create an internal one.
  *
  * Deprecated: Use gst_x_overlay_set_window_handle() instead.
@@ -358,13 +358,13 @@ gst_x_overlay_set_xwindow_id (GstXOverlay * overlay, gulong xwindow_id)
 
 /**
  * gst_x_overlay_set_window_handle:
- * @overlay: a #GstXOverlay to set the XWindow on.
- * @xwindow_id: a #XID referencing the XWindow.
+ * @overlay: a #GstXOverlay to set the window on.
+ * @handle: a handle referencing the window.
  *
  * This will call the video overlay's set_window_handle method. You
  * should use this method to tell to a XOverlay to display video output to a
- * specific XWindow. Passing 0 as the xwindow_id will tell the overlay to
- * stop using that window and create an internal one.
+ * specific window (e.g. an XWindow on X11). Passing 0 as the  @handle will
+ * tell the overlay to stop using that window and create an internal one.
  *
  * Since: 0.10.31
  */
@@ -452,7 +452,7 @@ gst_x_overlay_got_window_handle (GstXOverlay * overlay, guintptr handle)
  * @overlay: a #GstXOverlay which does not yet have an XWindow.
  *
  * This will post a "prepare-xwindow-id" element message on the bus
- * to give applications an opportunity to call 
+ * to give applications an opportunity to call
  * gst_x_overlay_set_xwindow_id() before a plugin creates its own
  * window.
  *

diff --git a/gst-libs/gst/interfaces/xoverlay.h b/gst-libs/gst/interfaces/xoverlay.h
index 055f510..6ac355c 100644 (file)
--- a/gst-libs/gst/interfaces/xoverlay.h
+++ b/gst-libs/gst/interfaces/xoverlay.h
@@ -52,10 +52,11 @@ typedef struct _GstXOverlayClass GstXOverlayClass;
 /**
  * GstXOverlayClass:
  * @klass: parent interface type.
- * @set_xwindow_id: virtual method to configure the XWindow id
+ * @set_xwindow_id: (deprecated) virtual method to configure the XWindow handle
  * @expose: virtual method to handle expose events
  * @handle_events: virtual method to handle events
  * @set_render_rectangle: virtual method to set the render rectangle (since 0.10.29)
+ * @set_window_handle: virtual method to configure the window handle
  *
  * #GstXOverlay interface
  */
@@ -67,14 +68,16 @@ struct _GstXOverlayClass {
   void (* set_xwindow_id)      (GstXOverlay *overlay,
                                 gulong       xwindow_id);
 #else
+#ifndef __GTK_DOC_IGNORE__
   void (* set_xwindow_id_disabled) (GstXOverlay *overlay,
                                 gulong       xwindow_id);
+#endif
 #endif /* not GST_DISABLE_DEPRECATED */
 
   void (* expose)              (GstXOverlay *overlay);
-  
+
   void (* handle_events)       (GstXOverlay *overlay,
-                                gboolean     handle_events);  
+                                gboolean     handle_events);
 
   void (* set_render_rectangle) (GstXOverlay *overlay,
                                  gint x, gint y,
@@ -90,7 +93,7 @@ GType   gst_x_overlay_get_type          (void);
 
 /* virtual class function wrappers */
 #ifndef GST_DISABLE_DEPRECATED
-void gst_x_overlay_set_xwindow_id      (GstXOverlay *overlay, 
+void gst_x_overlay_set_xwindow_id      (GstXOverlay *overlay,
                                         gulong xwindow_id);
 #endif
 
@@ -103,7 +106,7 @@ void gst_x_overlay_expose              (GstXOverlay *overlay);
 void gst_x_overlay_handle_events       (GstXOverlay *overlay,
                                         gboolean     handle_events);
 
-void gst_x_overlay_set_window_handle   (GstXOverlay *overlay, 
+void gst_x_overlay_set_window_handle   (GstXOverlay *overlay,
                                         guintptr handle);
 
 /* public methods to dispatch bus messages */