From 4f699b7f80bd3a963e10e23d7674f476c19c88fb Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Fri, 11 Jul 2008 06:10:24 +0000 Subject: [PATCH] Cleanup Plugin docs. Link to signals and properties. Fix sub-section titles. Drop mentining that all our example pipe... Original commit message from CVS: * docs/plugins/gst-plugins-base-plugins-docs.sgml: * docs/plugins/gst-plugins-base-plugins-overrides.txt: * docs/plugins/gst-plugins-base-plugins-sections.txt: * docs/plugins/gst-plugins-base-plugins.args: * docs/plugins/gst-plugins-base-plugins.hierarchy: * docs/plugins/gst-plugins-base-plugins.interfaces: * docs/plugins/gst-plugins-base-plugins.prerequisites: * docs/plugins/gst-plugins-base-plugins.signals: * docs/plugins/inspect/plugin-adder.xml: * docs/plugins/inspect/plugin-alsa.xml: * docs/plugins/inspect/plugin-audioconvert.xml: * docs/plugins/inspect/plugin-audiorate.xml: * docs/plugins/inspect/plugin-audioresample.xml: * docs/plugins/inspect/plugin-audiotestsrc.xml: * docs/plugins/inspect/plugin-cdparanoia.xml: * docs/plugins/inspect/plugin-decodebin.xml: * docs/plugins/inspect/plugin-ffmpegcolorspace.xml: * docs/plugins/inspect/plugin-gdp.xml: * docs/plugins/inspect/plugin-gnomevfs.xml: * docs/plugins/inspect/plugin-libvisual.xml: * docs/plugins/inspect/plugin-ogg.xml: * docs/plugins/inspect/plugin-pango.xml: * docs/plugins/inspect/plugin-playback.xml: * docs/plugins/inspect/plugin-queue2.xml: * docs/plugins/inspect/plugin-subparse.xml: * docs/plugins/inspect/plugin-tcp.xml: * docs/plugins/inspect/plugin-theora.xml: * docs/plugins/inspect/plugin-typefindfunctions.xml: * docs/plugins/inspect/plugin-uridecodebin.xml: * docs/plugins/inspect/plugin-video4linux.xml: * docs/plugins/inspect/plugin-videorate.xml: * docs/plugins/inspect/plugin-videoscale.xml: * docs/plugins/inspect/plugin-videotestsrc.xml: * docs/plugins/inspect/plugin-volume.xml: * docs/plugins/inspect/plugin-vorbis.xml: * docs/plugins/inspect/plugin-ximagesink.xml: * docs/plugins/inspect/plugin-xvimagesink.xml: * ext/alsa/gstalsamixer.c: * ext/alsa/gstalsasink.c: * ext/alsa/gstalsasrc.c: * ext/gio/gstgiosink.c: * ext/gio/gstgiosrc.c: * ext/gio/gstgiostreamsink.c: * ext/gio/gstgiostreamsrc.c: * ext/gnomevfs/gstgnomevfssink.c: * ext/gnomevfs/gstgnomevfssrc.c: * ext/ogg/gstoggdemux.c: * ext/ogg/gstoggmux.c: * ext/pango/gstclockoverlay.c: * ext/pango/gsttextoverlay.c: * ext/pango/gsttextrender.c: * ext/pango/gsttimeoverlay.c: * ext/theora/theoradec.c: * ext/theora/theoraenc.c: * ext/theora/theoraparse.c: * ext/vorbis/vorbisdec.c: * ext/vorbis/vorbisenc.c: * ext/vorbis/vorbisparse.c: * ext/vorbis/vorbistag.c: * gst/adder/gstadder.c: * gst/audioconvert/gstaudioconvert.c: * gst/audioresample/gstaudioresample.c: * gst/audiotestsrc/gstaudiotestsrc.c: * gst/ffmpegcolorspace/gstffmpegcolorspace.c: * gst/gdp/gstgdpdepay.c: * gst/gdp/gstgdppay.c: * gst/playback/gstdecodebin2.c: * gst/playback/gstplaybin.c: * gst/playback/gstplaybin2.c: * gst/playback/gstqueue2.c: * gst/playback/gsturidecodebin.c: * gst/tcp/gstmultifdsink.c: * gst/tcp/gsttcpserversink.c: * gst/videorate/gstvideorate.c: * gst/videoscale/gstvideoscale.c: * gst/videotestsrc/gstvideotestsrc.c: * gst/volume/gstvolume.c: * sys/ximage/ximagesink.c: * sys/xvimage/xvimagesink.c: Cleanup Plugin docs. Link to signals and properties. Fix sub-section titles. Drop mentining that all our example pipelines are "simple" pipelines. --- gst/videoscale/gstvideoscale.c | 24 ++++-------- gst/videotestsrc/gstvideotestsrc.c | 12 ++---- gst/volume/gstvolume.c | 12 ++---- sys/ximage/ximagesink.c | 56 ++++++++++++---------------- sys/xvimage/xvimagesink.c | 59 ++++++++++++------------------ 5 files changed, 64 insertions(+), 99 deletions(-) diff --git a/gst/videoscale/gstvideoscale.c b/gst/videoscale/gstvideoscale.c index be6cb4ce70..5813f70ae1 100644 --- a/gst/videoscale/gstvideoscale.c +++ b/gst/videoscale/gstvideoscale.c @@ -22,35 +22,27 @@ * SECTION:element-videoscale * @see_also: videorate, ffmpegcolorspace * - * - * * This element resizes video frames. By default the element will try to * negotiate to the same size on the source and sinkpad so that no scaling * is needed. It is therefore safe to insert this element in a pipeline to * get more robust behaviour without any cost if no scaling is needed. - * - * + * * This element supports a wide range of color spaces including various YUV and * RGB formats and is therefore generally able to operate anywhere in a * pipeline. - * + * + * * Example pipelines - * - * + * |[ * gst-launch -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! ffmpegcolorspace ! videoscale ! ximagesink - * - * Decode an Ogg/Theora and display the video using ximagesink. Since + * ]| Decode an Ogg/Theora and display the video using ximagesink. Since * ximagesink cannot perform scaling, the video scaling will be performed by * videoscale when you resize the video window. * To create the test Ogg/Theora file refer to the documentation of theoraenc. - * - * - * + * |[ * gst-launch -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoscale ! video/x-raw-yuv, width=50 ! xvimagesink - * - * Decode an Ogg/Theora and display the video using xvimagesink with a width of - * 50. - * + * ]| Decode an Ogg/Theora and display the video using xvimagesink with a width + * of 50. * * * Last reviewed on 2006-03-02 (0.10.4) diff --git a/gst/videotestsrc/gstvideotestsrc.c b/gst/videotestsrc/gstvideotestsrc.c index 678d0e23df..954c7c5650 100644 --- a/gst/videotestsrc/gstvideotestsrc.c +++ b/gst/videotestsrc/gstvideotestsrc.c @@ -21,19 +21,15 @@ /** * SECTION:element-videotestsrc * - * - * * The videotestsrc element is used to produce test video data in a wide variaty * of formats. The video test data produced can be controlled with the "pattern" * property. - * + * + * * Example launch line - * - * + * |[ * gst-launch -v videotestsrc pattern=snow ! ximagesink - * - * Shows random noise in an X window. - * + * ]| Shows random noise in an X window. * */ diff --git a/gst/volume/gstvolume.c b/gst/volume/gstvolume.c index c167f0fbdd..59e55f432b 100644 --- a/gst/volume/gstvolume.c +++ b/gst/volume/gstvolume.c @@ -24,19 +24,15 @@ /** * SECTION:element-volume * - * - * * The volume element changes the volume of the audio data. - * + * + * * Example launch line - * - * + * |[ * gst-launch -v -m audiotestsrc ! volume volume=0.5 ! level ! fakesink silent=TRUE - * - * This pipeline shows that the level of audiotestsrc has been halved + * ]| This pipeline shows that the level of audiotestsrc has been halved * (peak values are around -6 dB and RMS around -9 dB) compared to * the same pipeline without the volume element. - * * */ diff --git a/sys/ximage/ximagesink.c b/sys/ximage/ximagesink.c index 0b527028df..0f530af411 100644 --- a/sys/ximage/ximagesink.c +++ b/sys/ximage/ximagesink.c @@ -20,14 +20,13 @@ /** * SECTION:element-ximagesink * - * - * * XImageSink renders video frames to a drawable (XWindow) on a local or 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 * * As standard XImage rendering to a drawable is not scaled, XImageSink will use @@ -37,12 +36,13 @@ * or that an element generating the video frames can generate them with a * different geometry. This mechanism is handled during buffer allocations, for * each allocation request the video sink will check the drawable geometry, look - * at the - * force-aspect-ratio - * property, calculate the geometry of desired video frames and then check that - * the peer pad accept those new caps. If it does it will then allocate a buffer - * in video memory with this new geometry and return it with the new caps. + * at the #GstXImageSink:force-aspect-ratio property, calculate the geometry of + * desired video frames and then check that the peer pad accept those new caps. + * If it does it will then allocate a buffer in video memory with this new + * geometry and return it with the new caps. * + * + * * Events * * XImageSink creates a thread to handle events coming from the drawable. There @@ -55,11 +55,12 @@ * 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, XImageSink will open a connection to - * the display specified in the - * display property or the default + * the display specified in the #GstXImageSink: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 caps negotiation will occur, the @@ -67,43 +68,34 @@ * sure that incoming video frames will have the correct pixel aspect ratio for * this display. 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. + * #GstXImageSink:pixel-aspect-ratio property. * + * + * * Examples - * - * Here is a simple pipeline to test reverse negotiation : - * + * |[ * gst-launch -v videotestsrc ! queue ! ximagesink - * - * When the test video signal appears you can resize the window and see that - * scaled buffers of the desired size are going to arrive with a short delay. - * This illustrates how buffers of desired size are allocated along the way. - * If you take away the queue, scaling will happen almost immediately. - * - * - * Here is a simple pipeline to test navigation events : - * + * ]| A pipeline to test reverse negotiation. When the test video signal appears + * you can resize the window and see that scaled buffers of the desired size are + * going to arrive with a short delay. This illustrates how buffers of desired + * size are allocated along the way. If you take away the queue, scaling will + * happen almost immediately. + * |[ * gst-launch -v videotestsrc ! navigationtest ! ffmpegcolorspace ! ximagesink - * + * ]| A pipeline to test navigation events. * 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.) - * - * - * Here is a simple pipeline to test pixel aspect ratio : - * + * |[ * gst-launch -v videotestsrc ! video/x-raw-rgb, pixel-aspect-ratio=(fraction)4/3 ! videoscale ! ximagesink - * - * This is faking a 4/3 pixel aspect ratio caps on video frames produced by + * ]| 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 videoscale 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\)'. - * * */ diff --git a/sys/xvimage/xvimagesink.c b/sys/xvimage/xvimagesink.c index c9e7a3ce6c..966cb84796 100644 --- a/sys/xvimage/xvimagesink.c +++ b/sys/xvimage/xvimagesink.c @@ -20,8 +20,6 @@ /** * 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 @@ -29,17 +27,19 @@ * 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 + * drawable scaling them on the fly. Using the #GstXvImageSink: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 @@ -52,11 +52,12 @@ * 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 + * the display specified in the #GstXvImageSink: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 @@ -64,28 +65,24 @@ * 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. + * #GstXvImageSink:pixel-aspect-ratio property. * + * + * * Examples - * - * Here is a simple pipeline to test hardware scaling : - * + * |[ * gst-launch -v videotestsrc ! xvimagesink - * + * ]| A pipeline to test hardware scaling. * 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. - * + * video frames are scaled through hardware (no extra CPU cost). + * |[ * gst-launch -v videotestsrc ! xvimagesink force-aspect-ratio=true - * - * - * - * Here is a simple pipeline to test navigation events : - * + * ]| Same pipeline with #GstXvImageSink:force-aspect-ratio property set to true + * You can observe the borders drawn around the scaled image respecting aspect + * ratio. + * |[ * gst-launch -v videotestsrc ! navigationtest ! xvimagesink - * + * ]| A pipeline to test navigation events. * 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 @@ -95,25 +92,17 @@ * 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 + * ]| 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 - * - * + * ]| Demonstrates how to use the colorbalance interface. * */