From 4a3356cd6f9c1b789bccc7ecee9171a92a60e090 Mon Sep 17 00:00:00 2001 From: Julien Moutte Date: Mon, 28 Nov 2005 13:06:05 +0000 Subject: [PATCH] Add docs for the Xoverlay interface. Original commit message from CVS: 2005-11-28 Julien MOUTTE * docs/libs/tmpl/gstcolorbalance.sgml: * docs/libs/tmpl/gstmixer.sgml: * docs/libs/tmpl/gstxoverlay.sgml: * gst-libs/gst/interfaces/xoverlay.c: Add docs for the Xoverlay interface. --- ChangeLog | 8 ++++ docs/libs/tmpl/gstcolorbalance.sgml | 2 +- docs/libs/tmpl/gstmixer.sgml | 2 +- docs/libs/tmpl/gstxoverlay.sgml | 2 +- gst-libs/gst/interfaces/xoverlay.c | 82 +++++++++++++++++++++++++++++++++++++ 5 files changed, 93 insertions(+), 3 deletions(-) diff --git a/ChangeLog b/ChangeLog index 3e1f62a..c5cfdc7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,13 @@ 2005-11-28 Julien MOUTTE + * docs/libs/tmpl/gstcolorbalance.sgml: + * docs/libs/tmpl/gstmixer.sgml: + * docs/libs/tmpl/gstxoverlay.sgml: + * gst-libs/gst/interfaces/xoverlay.c: Add docs for the Xoverlay + interface. + +2005-11-28 Julien MOUTTE + * sys/xvimage/xvimagesink.c: (gst_xvimagesink_xvimage_new): Refuse to create an XvImage if we can't find the format. diff --git a/docs/libs/tmpl/gstcolorbalance.sgml b/docs/libs/tmpl/gstcolorbalance.sgml index 500f485..ccb0ae2 100644 --- a/docs/libs/tmpl/gstcolorbalance.sgml +++ b/docs/libs/tmpl/gstcolorbalance.sgml @@ -2,7 +2,7 @@ gstcolorbalance - +interface for adjusting color balance settings diff --git a/docs/libs/tmpl/gstmixer.sgml b/docs/libs/tmpl/gstmixer.sgml index 6c1c9e3..20afe10 100644 --- a/docs/libs/tmpl/gstmixer.sgml +++ b/docs/libs/tmpl/gstmixer.sgml @@ -2,7 +2,7 @@ gstmixer - +interface for elements that provide mixer operations diff --git a/docs/libs/tmpl/gstxoverlay.sgml b/docs/libs/tmpl/gstxoverlay.sgml index 76779e0..af901f8 100644 --- a/docs/libs/tmpl/gstxoverlay.sgml +++ b/docs/libs/tmpl/gstxoverlay.sgml @@ -2,7 +2,7 @@ gstxoverlay - +interface for setting/getting a Window on elements supporting it. diff --git a/gst-libs/gst/interfaces/xoverlay.c b/gst-libs/gst/interfaces/xoverlay.c index ef919b3..4f4f17f 100644 --- a/gst-libs/gst/interfaces/xoverlay.c +++ b/gst-libs/gst/interfaces/xoverlay.c @@ -19,6 +19,88 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstxoverlay + * @short_description: Interface for setting/getting a Window on elements + * supporting it. + * + * + * + * The XOverlay interface is used for 2 main purposes : + * + * + * + * To get a grab on the Window where the video sink element is going to render. + * This is achieved by either being informed about the Window identifier that + * the video sink element generated, or by forcing the video sink element to use + * a specific Window identifier for rendering. + * + * + * + * + * To force a redrawing of the latest video frame the video sink element + * displayed on the Window. Indeed if the #GstPipeline is in #GST_STATE_PAUSED + * state, moving the Window around will damage its content. Application + * developers will want to handle the Expose events themselves and force the + * video sink element to refresh the Window's content. + * + * + * + * + * + * Using the Window created by the video sink is probably the simplest scenario, + * in some cases, though, it might not be flexible enough for application + * developers if they need to catch events such as mouse moves and button + * clicks. + * + * + * Setting a specific Window identifier on the video sink element is the most + * flexible solution but it has some issues. Indeed the application needs to set + * its Window identifier at the right time to avoid internal Window creation + * from the video sink element. To solve this issue a #GstMessage is posted on + * the bus to inform the application that it should set the Window identifier + * immediately. Here is an example on how to do that correctly: + * + * static GstBusSyncReply + * create_window (GstBus * bus, GstMessage * message, GstPipeline * pipeline) + * { + * XGCValues values; + * const GstStructure *s; + * + * s = gst_message_get_structure (message); + * if (!gst_structure_has_name (s, "prepare-xwindow-id")) { + * return GST_BUS_PASS; + * } + * + * win = XCreateSimpleWindow (disp, root, 0, 0, 320, 240, 0, 0, 0); + * + * XSetWindowBackgroundPixmap (disp, win, None); + * + * gc = XCreateGC (disp, win, 0, &values); + * + * XMapRaised (disp, win); + * + * XSync (disp, FALSE); + * + * gst_x_overlay_set_xwindow_id (GST_X_OVERLAY (GST_MESSAGE_SRC (message)), + * win); + * + * return GST_BUS_DROP; + * } + * ... + * int + * main (int argc, char **argv) + * { + * ... + * bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); + * gst_bus_set_sync_handler (bus, (GstBusSyncHandler) create_window, pipeline); + * ... + * } + * + * + * + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif -- 2.7.4