/* GStreamer Video Overlay interface * Copyright (C) 2003 Ronald Bultje * Copyright (C) 2011 Tim-Philipp Müller * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ /** * SECTION:gstvideooverlay * @title: GstVideoOverlay * @short_description: Interface for setting/getting a window system resource * on elements supporting it to configure a window into which to render a * video. * * The #GstVideoOverlay 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) * { * // ignore anything but 'prepare-window-handle' element messages * if (!gst_is_video_overlay_prepare_window_handle_message (message)) * 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_video_overlay_set_window_handle (GST_VIDEO_OVERLAY (GST_MESSAGE_SRC (message)), * win); * * gst_message_unref (message); * * 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, NULL); * ... * } * ]| * * ## Two basic usage scenarios * * There are two basic usage scenarios: in the simplest case, the application * uses #playbin or #plasink or knows exactly what particular element is used * for video output, which is usually the case when the application creates * the videosink to use (e.g. #xvimagesink, #ximagesink, etc.) itself; in this * case, the application can just create the videosink element, create and * realize the window to render the video on and then * call gst_video_overlay_set_window_handle() directly with the XID or native * window handle, before starting up the pipeline. * As #playbin and #playsink implement the video overlay interface and proxy * it transparently to the actual video sink even if it is created later, this * case also applies when using these elements. * * In the other and more common case, the application does not know in advance * what GStreamer video sink element will be used for video output. This is * usually the case when an element such as #autovideosink is used. * In this case, the video sink element itself is created * asynchronously from a GStreamer streaming thread some time after the * pipeline has been started up. When that happens, however, the video sink * will need to know right then whether to render onto an already existing * application window or whether to create its own window. This is when it * posts a prepare-window-handle message, and that is also why this message needs * to be handled in a sync bus handler which will be called from the streaming * thread directly (because the video sink will need an answer right then). * * As response to the prepare-window-handle element message in the bus sync * handler, the application may use gst_video_overlay_set_window_handle() to tell * the video sink to render onto an existing window surface. At this point the * application should already have obtained the window handle / XID, so it * just needs to set it. It is generally not advisable to call any GUI toolkit * functions or window system functions from the streaming thread in which the * prepare-window-handle message is handled, because most GUI toolkits and * windowing systems are not thread-safe at all and a lot of care would be * required to co-ordinate the toolkit and window system calls of the * different threads (Gtk+ users please note: prior to Gtk+ 2.18 * GDK_WINDOW_XID() was just a simple structure access, so generally fine to do * within the bus sync handler; this macro was changed to a function call in * Gtk+ 2.18 and later, which is likely to cause problems when called from a * sync handler; see below for a better approach without GDK_WINDOW_XID() * used in the callback). * * ## GstVideoOverlay and Gtk+ * * |[ * #include <gst/video/videooverlay.h> * #include <gtk/gtk.h> * #ifdef GDK_WINDOWING_X11 * #include <gdk/gdkx.h> // for GDK_WINDOW_XID * #endif * #ifdef GDK_WINDOWING_WIN32 * #include <gdk/gdkwin32.h> // for GDK_WINDOW_HWND * #endif * ... * static guintptr video_window_handle = 0; * ... * static GstBusSyncReply * bus_sync_handler (GstBus * bus, GstMessage * message, gpointer user_data) * { * // ignore anything but 'prepare-window-handle' element messages * if (!gst_is_video_overlay_prepare_window_handle_message (message)) * return GST_BUS_PASS; * * if (video_window_handle != 0) { * GstVideoOverlay *overlay; * * // GST_MESSAGE_SRC (message) will be the video sink element * overlay = GST_VIDEO_OVERLAY (GST_MESSAGE_SRC (message)); * gst_video_overlay_set_window_handle (overlay, video_window_handle); * } else { * g_warning ("Should have obtained video_window_handle by now!"); * } * * gst_message_unref (message); * return GST_BUS_DROP; * } * ... * static void * video_widget_realize_cb (GtkWidget * widget, gpointer data) * { * #if GTK_CHECK_VERSION(2,18,0) * // Tell Gtk+/Gdk to create a native window for this widget instead of * // drawing onto the parent widget. * // This is here just for pedagogical purposes, GDK_WINDOW_XID will call * // it as well in newer Gtk versions * if (!gdk_window_ensure_native (widget->window)) * g_error ("Couldn't create native window needed for GstVideoOverlay!"); * #endif * * #ifdef GDK_WINDOWING_X11 * { * gulong xid = GDK_WINDOW_XID (gtk_widget_get_window (video_window)); * video_window_handle = xid; * } * #endif * #ifdef GDK_WINDOWING_WIN32 * { * HWND wnd = GDK_WINDOW_HWND (gtk_widget_get_window (video_window)); * video_window_handle = (guintptr) wnd; * } * #endif * } * ... * int * main (int argc, char **argv) * { * GtkWidget *video_window; * GtkWidget *app_window; * ... * app_window = gtk_window_new (GTK_WINDOW_TOPLEVEL); * ... * video_window = gtk_drawing_area_new (); * g_signal_connect (video_window, "realize", * G_CALLBACK (video_widget_realize_cb), NULL); * gtk_widget_set_double_buffered (video_window, FALSE); * ... * // usually the video_window will not be directly embedded into the * // application window like this, but there will be many other widgets * // and the video window will be embedded in one of them instead * gtk_container_add (GTK_CONTAINER (ap_window), video_window); * ... * // 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/HWND before the pipeline is started up and the videosink * // asks for the XID/HWND of the window to render onto * gtk_widget_realize (video_window); * * // we should have the XID/HWND now * g_assert (video_window_handle != 0); * ... * // set up sync handler for setting the xid once the pipeline is started * bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); * gst_bus_set_sync_handler (bus, (GstBusSyncHandler) bus_sync_handler, NULL, * NULL); * gst_object_unref (bus); * ... * gst_element_set_state (pipeline, GST_STATE_PLAYING); * ... * } * ]| * * ## GstVideoOverlay and Qt * * |[ * #include <glib.h> * #include <gst/gst.h> * #include <gst/video/videooverlay.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_video_overlay_set_window_handle (GST_VIDEO_OVERLAY (sink), xwinid); * * // run the pipeline * * GstStateChangeReturn sret = gst_element_set_state (pipeline, * GST_STATE_PLAYING); * if (sret == GST_STATE_CHANGE_FAILURE) { * gst_element_set_state (pipeline, GST_STATE_NULL); * gst_object_unref (pipeline); * // 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; * } * ]| * */ #ifdef HAVE_CONFIG_H #include "config.h" #endif #include "videooverlay.h" enum { PROP_RENDER_RECTANGLE, }; GST_DEBUG_CATEGORY_STATIC (gst_video_overlay_debug); #define GST_CAT_DEFAULT gst_video_overlay_debug GType gst_video_overlay_get_type (void) { static GType gst_video_overlay_type = 0; if (!gst_video_overlay_type) { static const GTypeInfo gst_video_overlay_info = { sizeof (GstVideoOverlayInterface), NULL, NULL, NULL, NULL, NULL, 0, 0, NULL, }; gst_video_overlay_type = g_type_register_static (G_TYPE_INTERFACE, "GstVideoOverlay", &gst_video_overlay_info, 0); GST_DEBUG_CATEGORY_INIT (gst_video_overlay_debug, "videooverlay", 0, "videooverlay interface"); } return gst_video_overlay_type; } /** * gst_video_overlay_set_window_handle: * @overlay: a #GstVideoOverlay 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 an overlay to display video output to a * 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. */ void gst_video_overlay_set_window_handle (GstVideoOverlay * overlay, guintptr handle) { GstVideoOverlayInterface *iface; g_return_if_fail (overlay != NULL); g_return_if_fail (GST_IS_VIDEO_OVERLAY (overlay)); iface = GST_VIDEO_OVERLAY_GET_INTERFACE (overlay); if (iface->set_window_handle) { iface->set_window_handle (overlay, handle); } } /** * gst_video_overlay_got_window_handle: * @overlay: a #GstVideoOverlay which got a window * @handle: a platform-specific handle referencing the window * * This will post a "have-window-handle" element message on the bus. * * This function should only be used by video overlay plugin developers. */ void gst_video_overlay_got_window_handle (GstVideoOverlay * overlay, guintptr handle) { GstStructure *s; GstMessage *msg; g_return_if_fail (overlay != NULL); g_return_if_fail (GST_IS_VIDEO_OVERLAY (overlay)); GST_LOG_OBJECT (GST_OBJECT (overlay), "window_handle = %p", (gpointer) handle); s = gst_structure_new ("have-window-handle", "window-handle", G_TYPE_UINT64, (guint64) handle, NULL); msg = gst_message_new_element (GST_OBJECT (overlay), s); gst_element_post_message (GST_ELEMENT (overlay), msg); } /** * gst_video_overlay_prepare_window_handle: * @overlay: a #GstVideoOverlay which does not yet have an Window handle set * * This will post a "prepare-window-handle" element message on the bus * to give applications an opportunity to call * gst_video_overlay_set_window_handle() before a plugin creates its own * window. * * This function should only be used by video overlay plugin developers. */ void gst_video_overlay_prepare_window_handle (GstVideoOverlay * overlay) { GstStructure *s; GstMessage *msg; g_return_if_fail (overlay != NULL); g_return_if_fail (GST_IS_VIDEO_OVERLAY (overlay)); GST_LOG_OBJECT (GST_OBJECT (overlay), "prepare window handle"); s = gst_structure_new_empty ("prepare-window-handle"); msg = gst_message_new_element (GST_OBJECT (overlay), s); gst_element_post_message (GST_ELEMENT (overlay), msg); } /** * gst_video_overlay_expose: * @overlay: a #GstVideoOverlay to expose. * * Tell an overlay that it has been exposed. This will redraw the current frame * in the drawable even if the pipeline is PAUSED. */ void gst_video_overlay_expose (GstVideoOverlay * overlay) { GstVideoOverlayInterface *iface; g_return_if_fail (overlay != NULL); g_return_if_fail (GST_IS_VIDEO_OVERLAY (overlay)); iface = GST_VIDEO_OVERLAY_GET_INTERFACE (overlay); if (iface->expose) { iface->expose (overlay); } } /** * gst_video_overlay_handle_events: * @overlay: a #GstVideoOverlay to expose. * @handle_events: a #gboolean indicating if events should be handled or not. * * Tell an overlay that it should handle events from the window system. These * events are forwarded upstream as navigation events. In some window system, * events are not propagated in the window hierarchy if a client is listening * for them. This method allows you to disable events handling completely * from the #GstVideoOverlay. */ void gst_video_overlay_handle_events (GstVideoOverlay * overlay, gboolean handle_events) { GstVideoOverlayInterface *iface; g_return_if_fail (overlay != NULL); g_return_if_fail (GST_IS_VIDEO_OVERLAY (overlay)); iface = GST_VIDEO_OVERLAY_GET_INTERFACE (overlay); if (iface->handle_events) { iface->handle_events (overlay, handle_events); } } /** * gst_video_overlay_set_render_rectangle: * @overlay: a #GstVideoOverlay * @x: the horizontal offset of the render area inside the window * @y: the vertical offset of the render area inside the window * @width: the width of the render area inside the window * @height: the height of the render area inside the window * * Configure a subregion as a video target within the window set by * gst_video_overlay_set_window_handle(). If this is not used or not supported * the video will fill the area of the window set as the overlay to 100%. * By specifying the rectangle, the video can be overlayed to a specific region * of that window only. After setting the new rectangle one should call * gst_video_overlay_expose() to force a redraw. To unset the region pass -1 for * the @width and @height parameters. * * This method is needed for non fullscreen video overlay in UI toolkits that * do not support subwindows. * * Returns: %FALSE if not supported by the sink. */ gboolean gst_video_overlay_set_render_rectangle (GstVideoOverlay * overlay, gint x, gint y, gint width, gint height) { GstVideoOverlayInterface *iface; g_return_val_if_fail (overlay != NULL, FALSE); g_return_val_if_fail (GST_IS_VIDEO_OVERLAY (overlay), FALSE); g_return_val_if_fail ((width == -1 && height == -1) || (width > 0 && height > 0), FALSE); iface = GST_VIDEO_OVERLAY_GET_INTERFACE (overlay); if (iface->set_render_rectangle) { iface->set_render_rectangle (overlay, x, y, width, height); return TRUE; } return FALSE; } /** * gst_is_video_overlay_prepare_window_handle_message: * @msg: a #GstMessage * * Convenience function to check if the given message is a * "prepare-window-handle" message from a #GstVideoOverlay. * * Returns: whether @msg is a "prepare-window-handle" message */ gboolean gst_is_video_overlay_prepare_window_handle_message (GstMessage * msg) { g_return_val_if_fail (msg != NULL, FALSE); if (GST_MESSAGE_TYPE (msg) != GST_MESSAGE_ELEMENT) return FALSE; return gst_message_has_name (msg, "prepare-window-handle"); } /** * gst_video_overlay_install_properties: * @oclass: The class on which the properties will be installed * @last_prop_id: The first free property ID to use * * This helper shall be used by classes implementing the #GstVideoOverlay * interface that want the render rectangle to be controllable using * properties. This helper will install "render-rectangle" property into the * class. * * Since 1.14 */ void gst_video_overlay_install_properties (GObjectClass * oclass, gint last_prop_id) { g_object_class_install_property (oclass, last_prop_id + PROP_RENDER_RECTANGLE, gst_param_spec_array ("render-rectangle", "Render Rectangle", "The render rectangle ('')", g_param_spec_int ("rect-value", "Rectangle Value", "One of x, y, width or height value.", -1, G_MAXINT, -1, G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS), G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); } /** * gst_video_overlay_set_property: * @object: The instance on which the property is set * @last_prop_id: The highest property ID. * @property_id: The property ID * @value: The #GValue to be set * * This helper shall be used by classes implementing the #GstVideoOverlay * interface that want the render rectangle to be controllable using * properties. This helper will parse and set the render rectangle calling * gst_video_overlay_set_render_rectangle(). * * Returns: %TRUE if the @property_id matches the GstVideoOverlay property * * Since 1.14 */ gboolean gst_video_overlay_set_property (GObject * object, gint last_prop_id, guint property_id, const GValue * value) { gboolean ret = FALSE; if (property_id == last_prop_id) { const GValue *v; gint rect[4], i; ret = TRUE; if (gst_value_array_get_size (value) != 4) goto wrong_format; for (i = 0; i < 4; i++) { v = gst_value_array_get_value (value, i); if (!G_VALUE_HOLDS_INT (v)) goto wrong_format; rect[i] = g_value_get_int (v); } gst_video_overlay_set_render_rectangle (GST_VIDEO_OVERLAY (object), rect[0], rect[1], rect[2], rect[3]); } return ret; wrong_format: { GValue string = G_VALUE_INIT; g_value_init (&string, G_TYPE_STRING); g_value_transform (value, &string); g_critical ("Badly formated rectangle, must contains four gint (got '%s')", g_value_get_string (&string)); g_value_unset (&string); return TRUE; } }