From deeae48a0362068dce90909e9a2be1bfd505881e Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Mon, 23 May 2011 23:41:56 +0300 Subject: [PATCH] docs: update xoverlay docs for api addition and deprecation --- gst-libs/gst/interfaces/xoverlay.c | 70 +++++++++++++++--------------- gst-libs/gst/interfaces/xoverlay.h | 13 +++--- 2 files changed, 43 insertions(+), 40 deletions(-) diff --git a/gst-libs/gst/interfaces/xoverlay.c b/gst-libs/gst/interfaces/xoverlay.c index e7bd6558ff..6fcb5ccad0 100644 --- 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 055f510050..6ac355c25f 100644 --- 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 */