From c5a52004e0f9df21da4b04a9557c49a4c87411cd Mon Sep 17 00:00:00 2001 From: Julien Moutte Date: Sat, 26 Nov 2005 15:26:36 +0000 Subject: [PATCH] Added doc for xvimagesink. Original commit message from CVS: 2005-11-26 Julien MOUTTE * docs/plugins/Makefile.am: * docs/plugins/gst-plugins-base-plugins-docs.sgml: * docs/plugins/gst-plugins-base-plugins-sections.txt: * sys/xvimage/xvimagesink.c: Added doc for xvimagesink. --- ChangeLog | 7 ++ docs/plugins/Makefile.am | 3 +- docs/plugins/gst-plugins-base-plugins-docs.sgml | 1 + docs/plugins/gst-plugins-base-plugins-sections.txt | 8 ++ sys/xvimage/xvimagesink.c | 100 +++++++++++++++++++++ 5 files changed, 118 insertions(+), 1 deletion(-) diff --git a/ChangeLog b/ChangeLog index e5920b2..1b09b6b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -3,6 +3,13 @@ * docs/plugins/Makefile.am: * docs/plugins/gst-plugins-base-plugins-docs.sgml: * docs/plugins/gst-plugins-base-plugins-sections.txt: + * sys/xvimage/xvimagesink.c: Added doc for xvimagesink. + +2005-11-26 Julien MOUTTE + + * docs/plugins/Makefile.am: + * docs/plugins/gst-plugins-base-plugins-docs.sgml: + * docs/plugins/gst-plugins-base-plugins-sections.txt: * docs/plugins/inspect/plugin-adder.xml: * docs/plugins/inspect/plugin-alsa.xml: * docs/plugins/inspect/plugin-audioconvert.xml: diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am index 30cf675..d75d66a 100644 --- a/docs/plugins/Makefile.am +++ b/docs/plugins/Makefile.am @@ -85,7 +85,8 @@ EXTRA_HFILES = \ $(top_srcdir)/gst/tcp/gsttcpserversink.h \ $(top_srcdir)/gst/videotestsrc/gstvideotestsrc.h \ $(top_srcdir)/gst/volume/gstvolume.h \ - $(top_srcdir)/sys/ximage/ximagesink.h + $(top_srcdir)/sys/ximage/ximagesink.h \ + $(top_srcdir)/sys/xvimage/xvimagesink.h # Images to copy into HTML directory. HTML_IMAGES = diff --git a/docs/plugins/gst-plugins-base-plugins-docs.sgml b/docs/plugins/gst-plugins-base-plugins-docs.sgml index 402feee..f674716 100644 --- a/docs/plugins/gst-plugins-base-plugins-docs.sgml +++ b/docs/plugins/gst-plugins-base-plugins-docs.sgml @@ -25,6 +25,7 @@ + diff --git a/docs/plugins/gst-plugins-base-plugins-sections.txt b/docs/plugins/gst-plugins-base-plugins-sections.txt index 1e90049..9aad306 100644 --- a/docs/plugins/gst-plugins-base-plugins-sections.txt +++ b/docs/plugins/gst-plugins-base-plugins-sections.txt @@ -96,6 +96,14 @@ GstXImagesSinkClass
+element-xvimagesink +xvimagesink +GstXvImageSink + +GstXvImagesSinkClass +
+ +
private CLIENTS_UNLOCK diff --git a/sys/xvimage/xvimagesink.c b/sys/xvimage/xvimagesink.c index 102bd11..987ddb2 100644 --- a/sys/xvimage/xvimagesink.c +++ b/sys/xvimage/xvimagesink.c @@ -17,6 +17,106 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:element-xvimagesink + * + * + * + * XvImageSink renders video frames to a drawable (XWindow) on a local display + * using the XVideo extension. Rendering to a remote display is theorically + * possible but i doubt that the XVideo extension is actually available when + * connecting to a remote display. This element can receive a Window ID from the + * application through the XOverlay interface and will then render video frames + * in this drawable. If no Window ID was provided by the application, the + * element will create its own internal window and render into it. + * + * Scaling + * + * The XVideo extension, when it's available, handles hardware accelerated + * scaling of video frames. This means that the element will just accept + * incoming video frames no matter their geometry and will then put them to the + * drawable scaling them on the fly. Using the + * force-aspect-ratio + * property it is possible to enforce scaling with a constant aspect ratio, + * which means drawing black borders around the video frame. + * + * Events + * + * XvImageSink creates a thread to handle events coming from the drawable. There + * are several kind of events that can be grouped in 2 big categories: input + * events and window state related events. Input events will be translated to + * navigation events and pushed upstream for other elements to react on them. + * This includes events such as pointer moves, key press/release, clicks etc... + * Other events are used to handle the drawable appearance even when the data + * is not flowing (GST_STATE_PAUSED). That means that even when the element is + * paused, it will receive expose events from the drawable and draw the latest + * frame with correct borders/aspect-ratio. + * + * Pixel aspect ratio + * + * When changing state to GST_STATE_READY, XvImageSink will open a connection to + * the display specified in the + * display property or the + * default display if nothing specified. Once this connection is open it will + * inspect the display configuration including the physical display geometry and + * then calculate the pixel aspect ratio. When receiving video frames with a + * different pixel aspect ratio, XvImageSink will use hardware scaling to + * display the video frames correctly on display's pixel aspect ratio. + * Sometimes the calculated pixel aspect ratio can be wrong, it is + * then possible to enforce a specific pixel aspect ratio using the + * pixel-aspect-ratio + * property. + * + * Examples + * + * Here is a simple pipeline to test hardware scaling : + * + * gst-launch -v videotestsrc ! xvimagesink + * + * When the test video signal appears you can resize the window and see that + * video frames are scaled through hardware (no extra CPU cost). You can try + * again setting the force-aspect-ratio property to true and observe the borders + * drawn around the scaled image respecting aspect ratio. + * + * gst-launch -v videotestsrc ! xvimagesink force-aspect-ratio=true + * + * + * + * Here is a simple pipeline to test navigation events : + * + * gst-launch -v videotestsrc ! navigationtest ! xvimagesink + * + * While moving the mouse pointer over the test signal you will see a black box + * following the mouse pointer. If you press the mouse button somewhere on the + * video and release it somewhere else a green box will appear where you pressed + * the button and a red one where you released it. (The navigationtest element + * is part of gst-plugins-good.) You can observe here that even if the images + * are scaled through hardware the pointer coordinates are converted back to the + * original video frame geometry so that the box can be drawn to the correct + * position. This also handles borders correctly, limiting coordinates to the + * image area + * + * + * Here is a simple pipeline to test pixel aspect ratio : + * + * gst-launch -v videotestsrc ! video/x-raw-yuv, pixel-aspect-ratio=(fraction)4/3 ! xvimagesink + * + * This is faking a 4/3 pixel aspect ratio caps on video frames produced by + * videotestsrc, in most cases the pixel aspect ratio of the display will be + * 1/1. This means that XvImageSink will have to do the scaling to convert + * incoming frames to a size that will match the display pixel aspect ratio + * (from 320x240 to 320x180 in this case). Note that you might have to escape + * some characters for your shell like '\(fraction\)'. + * + * + * Here is a test pipeline to test the colorbalance interface : + * + * gst-launch -v videotestsrc ! xvimagesink hue=100 saturation=-100 brightness=100 + * + * + * + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif -- 2.7.4