From 099ac9faf2c6e6fcf55fe4bee812c9f90aeb8602 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Mon, 23 Jan 2017 16:36:11 -0300 Subject: [PATCH] docs: Convert gtkdoc comments to markdown Modernizing the documentation, making it simpler to read an modify and allowing us to possibly switch to hotdoc in the future. --- ext/alsa/gstalsamidisrc.c | 9 +- ext/alsa/gstalsasink.c | 10 +- ext/alsa/gstalsasrc.c | 9 +- ext/ogg/gstoggdemux.c | 9 +- ext/ogg/gstoggmux.c | 19 +- ext/opus/gstopusdec.c | 9 +- ext/opus/gstopusenc.c | 9 +- ext/pango/gstclockoverlay.c | 12 +- ext/pango/gsttextoverlay.c | 15 +- ext/pango/gsttextrender.c | 8 +- ext/pango/gsttimeoverlay.c | 10 +- ext/theora/gsttheoradec.c | 9 +- ext/theora/gsttheoraenc.c | 9 +- ext/theora/gsttheoraparse.c | 12 +- ext/vorbis/gstvorbisdec.c | 10 +- ext/vorbis/gstvorbisenc.c | 12 +- ext/vorbis/gstvorbisparse.c | 12 +- ext/vorbis/gstvorbistag.c | 9 +- gst-libs/gst/allocators/gstdmabuf.c | 1 + gst-libs/gst/allocators/gstfdmemory.c | 1 + gst-libs/gst/app/gstappsink.c | 1 + gst-libs/gst/app/gstappsrc.c | 1 + gst-libs/gst/audio/audio-channels.c | 1 + gst-libs/gst/audio/audio-converter.c | 24 +- gst-libs/gst/audio/audio-resampler.c | 1 + gst-libs/gst/audio/audio-resampler.h | 8 +- gst-libs/gst/audio/audio.c | 3 +- gst-libs/gst/audio/gstaudiobasesink.c | 1 + gst-libs/gst/audio/gstaudiobasesrc.c | 1 + gst-libs/gst/audio/gstaudiocdsrc.c | 37 +- gst-libs/gst/audio/gstaudioclock.c | 1 + gst-libs/gst/audio/gstaudiodecoder.c | 80 +-- gst-libs/gst/audio/gstaudioencoder.c | 81 +-- gst-libs/gst/audio/gstaudiofilter.c | 1 + gst-libs/gst/audio/gstaudioiec61937.c | 1 + gst-libs/gst/audio/gstaudiometa.c | 1 + gst-libs/gst/audio/gstaudioringbuffer.c | 9 +- gst-libs/gst/audio/gstaudiosink.c | 46 +- gst-libs/gst/audio/gstaudiosrc.c | 39 +- gst-libs/gst/audio/streamvolume.c | 12 +- gst-libs/gst/fft/gstfft.c | 3 +- gst-libs/gst/fft/gstfftf32.c | 1 + gst-libs/gst/fft/gstfftf64.c | 1 + gst-libs/gst/fft/gstffts16.c | 1 + gst-libs/gst/fft/gstffts32.c | 1 + gst-libs/gst/pbutils/codec-utils.c | 72 +-- gst-libs/gst/pbutils/descriptions.c | 9 +- gst-libs/gst/pbutils/encoding-profile.c | 3 +- gst-libs/gst/pbutils/gstaudiovisualizer.c | 1 + gst-libs/gst/pbutils/gstdiscoverer.c | 1 + gst-libs/gst/pbutils/gstpluginsbaseversion.c | 1 + gst-libs/gst/pbutils/install-plugins.c | 518 +++++++----------- gst-libs/gst/pbutils/missing-plugins.c | 36 +- gst-libs/gst/pbutils/pbutils.c | 48 +- gst-libs/gst/riff/riff-read.c | 4 +- gst-libs/gst/riff/riff.c | 1 + gst-libs/gst/rtp/gstrtcpbuffer.c | 17 +- gst-libs/gst/rtp/gstrtpbaseaudiopayload.c | 9 +- gst-libs/gst/rtp/gstrtpbasedepayload.c | 57 +- gst-libs/gst/rtp/gstrtpbasepayload.c | 51 +- gst-libs/gst/rtp/gstrtpbuffer.c | 18 +- gst-libs/gst/rtp/gstrtphdrext.c | 5 +- gst-libs/gst/rtp/gstrtppayloads.c | 8 +- gst-libs/gst/rtp/gstrtppayloads.h | 1 - gst-libs/gst/rtsp/gstrtspconnection.c | 1 + gst-libs/gst/rtsp/gstrtspdefs.c | 5 +- gst-libs/gst/rtsp/gstrtspextension.c | 6 +- gst-libs/gst/rtsp/gstrtspmessage.c | 5 +- gst-libs/gst/rtsp/gstrtsprange.c | 3 +- gst-libs/gst/rtsp/gstrtsptransport.c | 9 +- gst-libs/gst/rtsp/gstrtspurl.c | 5 +- gst-libs/gst/sdp/gstmikey.c | 5 +- gst-libs/gst/sdp/gstsdpmessage.c | 6 +- gst-libs/gst/tag/gstexiftag.c | 1 + gst-libs/gst/tag/gstid3tag.c | 10 +- gst-libs/gst/tag/gsttagdemux.c | 52 +- gst-libs/gst/tag/gsttagmux.c | 33 +- gst-libs/gst/tag/gstvorbistag.c | 6 +- gst-libs/gst/tag/gstxmptag.c | 1 + gst-libs/gst/tag/lang.c | 6 +- gst-libs/gst/tag/licenses.c | 1 + gst-libs/gst/tag/tags.c | 8 +- gst-libs/gst/tag/xmpwriter.c | 9 +- gst-libs/gst/video/colorbalance.c | 13 +- gst-libs/gst/video/colorbalancechannel.c | 5 +- .../video/gstvideoaffinetransformationmeta.c | 2 +- gst-libs/gst/video/gstvideodecoder.c | 131 ++--- gst-libs/gst/video/gstvideoencoder.c | 79 +-- gst-libs/gst/video/gstvideofilter.c | 11 +- gst-libs/gst/video/gstvideometa.h | 2 +- gst-libs/gst/video/gstvideopool.c | 1 + gst-libs/gst/video/gstvideosink.c | 15 +- gst-libs/gst/video/gstvideosink.h | 2 +- gst-libs/gst/video/navigation.c | 40 +- gst-libs/gst/video/video-chroma.c | 1 + gst-libs/gst/video/video-converter.c | 24 +- gst-libs/gst/video/video-dither.c | 1 + gst-libs/gst/video/video-event.c | 2 +- .../gst/video/video-overlay-composition.c | 35 +- gst-libs/gst/video/video-resampler.c | 1 + gst-libs/gst/video/video-scaler.c | 1 + gst-libs/gst/video/video.c | 6 +- gst-libs/gst/video/videodirection.c | 1 + gst-libs/gst/video/videoorientation.c | 1 + gst-libs/gst/video/videooverlay.c | 71 +-- gst/adder/gstadder.c | 9 +- gst/app/gstapp.c | 2 + gst/audioconvert/gstaudioconvert.c | 12 +- gst/audiorate/gstaudiorate.c | 12 +- gst/audioresample/gstaudioresample.c | 9 +- gst/audiotestsrc/gstaudiotestsrc.c | 12 +- gst/encoding/gstencodebin.c | 58 +- gst/gio/gstgiosink.c | 17 +- gst/gio/gstgiosrc.c | 17 +- gst/gio/gstgiostreamsink.c | 9 +- gst/gio/gstgiostreamsrc.c | 9 +- gst/playback/gstdecodebin2.c | 41 +- gst/playback/gstdecodebin3.c | 25 +- gst/playback/gstparsebin.c | 41 +- gst/playback/gstplaybin2.c | 106 ++-- gst/playback/gstplaybin3.c | 107 ++-- gst/playback/gstsubtitleoverlay.c | 9 +- gst/playback/gsturidecodebin.c | 43 +- gst/playback/gsturisourcebin.c | 41 +- gst/rawparse/gstrawaudioparse.c | 12 +- gst/rawparse/gstrawvideoparse.c | 14 +- gst/tcp/gstmultifdsink.c | 33 +- gst/tcp/gstmultihandlesink.c | 33 +- gst/tcp/gstmultihandlesink.h | 2 +- gst/tcp/gstmultisocketsink.c | 33 +- gst/tcp/gstsocketsrc.c | 1 + gst/tcp/gsttcpclientsink.c | 9 +- gst/tcp/gsttcpclientsrc.c | 9 +- gst/tcp/gsttcpserversink.c | 8 +- gst/tcp/gsttcpserversrc.c | 8 +- gst/videoconvert/gstvideoconvert.c | 9 +- gst/videorate/gstvideorate.c | 15 +- gst/videoscale/gstvideoscale.c | 12 +- gst/videotestsrc/gstvideotestsrc.c | 9 +- gst/volume/gstvolume.c | 9 +- sys/ximage/ximagesink.c | 55 +- sys/ximage/ximagesink.h | 2 +- sys/xvimage/xvimagesink.c | 45 +- 143 files changed, 1216 insertions(+), 1708 deletions(-) diff --git a/ext/alsa/gstalsamidisrc.c b/ext/alsa/gstalsamidisrc.c index edf762494c..5e398b7e21 100644 --- a/ext/alsa/gstalsamidisrc.c +++ b/ext/alsa/gstalsamidisrc.c @@ -20,6 +20,7 @@ */ /** * SECTION:element-alsamidisrc + * @title: alsamidisrc * @see_also: #GstPushSrc * * The alsamidisrc element is an element that fetches ALSA MIDI sequencer @@ -28,13 +29,13 @@ * * It can be used to generate notes from a MIDI input device. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch -v alsamidisrc ports=129:0 ! fluiddec ! audioconvert ! autoaudiosink - * ]| This pipeline will listen for events from the sequencer device at port 129:0, + * ]| + * This pipeline will listen for events from the sequencer device at port 129:0, * and generate notes using the fluiddec element. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/alsa/gstalsasink.c b/ext/alsa/gstalsasink.c index 86606f7164..3cd5469620 100644 --- a/ext/alsa/gstalsasink.c +++ b/ext/alsa/gstalsasink.c @@ -22,16 +22,18 @@ /** * SECTION:element-alsasink + * @title: alsasink * @see_also: alsasrc * * This element renders audio samples using the ALSA audio API. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v uridecodebin uri=file:///path/to/audio.ogg ! audioconvert ! audioresample ! autoaudiosink - * ]| Play an Ogg/Vorbis file and output audio via ALSA. - * + * ]| + * + * Play an Ogg/Vorbis file and output audio via ALSA. + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/alsa/gstalsasrc.c b/ext/alsa/gstalsasrc.c index 74b8bf9483..4c4062b57b 100644 --- a/ext/alsa/gstalsasrc.c +++ b/ext/alsa/gstalsasrc.c @@ -21,16 +21,17 @@ /** * SECTION:element-alsasrc + * @title: alsasrc * @see_also: alsasink * * This element reads data from an audio card using the ALSA API. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v alsasrc ! queue ! audioconvert ! vorbisenc ! oggmux ! filesink location=alsasrc.ogg - * ]| Record from a sound card using ALSA and encode to Ogg/Vorbis. - * + * ]| + * Record from a sound card using ALSA and encode to Ogg/Vorbis. + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/ogg/gstoggdemux.c b/ext/ogg/gstoggdemux.c index 51c5509092..5307521fba 100644 --- a/ext/ogg/gstoggdemux.c +++ b/ext/ogg/gstoggdemux.c @@ -21,16 +21,17 @@ /** * SECTION:element-oggdemux + * @title: oggdemux * @see_also: oggmux * * This element demuxes ogg files into their encoded audio and video components. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v filesrc location=test.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! autoaudiosink - * ]| Decodes a vorbis audio stream stored inside an ogg container and plays it. - * + * ]| + * Decodes a vorbis audio stream stored inside an ogg container and plays it. + * */ diff --git a/ext/ogg/gstoggmux.c b/ext/ogg/gstoggmux.c index 9a8045447c..8925e8b53b 100644 --- a/ext/ogg/gstoggmux.c +++ b/ext/ogg/gstoggmux.c @@ -20,17 +20,18 @@ /** * SECTION:element-oggmux + * @title: oggmux * @see_also: oggdemux * * This element merges streams (audio and video) into ogg files. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 v4l2src num-buffers=500 ! video/x-raw,width=320,height=240 ! videoconvert ! videorate ! theoraenc ! oggmux ! filesink location=video.ogg - * ]| Encodes a video stream captured from a v4l2-compatible camera to Ogg/Theora + * ]| + * Encodes a video stream captured from a v4l2-compatible camera to Ogg/Theora * (the encoding will stop automatically after 500 frames) - * + * */ #ifdef HAVE_CONFIG_H @@ -968,14 +969,14 @@ no_granule: /* make sure at least one buffer is queued on all pads, two if possible - * + * * if pad->buffer == NULL, pad->next_buffer != NULL, then * we do not know if the buffer is the last or not * if pad->buffer != NULL, pad->next_buffer != NULL, then * pad->buffer is not the last buffer for the pad * if pad->buffer != NULL, pad->next_buffer == NULL, then * pad->buffer if the last buffer for the pad - * + * * returns a pointer to an oggpad that holds the best buffer, or * NULL when no pad was usable. "best" means the buffer marked * with the lowest timestamp. If best->buffer == NULL then either @@ -1409,7 +1410,7 @@ gst_ogg_mux_make_fistail (GstOggMux * mux, ogg_stream_state * os) * page that allows decoders to identify the type of the stream. * After that we need to write out all extra info for the decoders. * In the case of a codec that also needs data as configuration, we can - * find that info in the streamcaps. + * find that info in the streamcaps. * After writing the headers we must start a new page for the data. */ static GstFlowReturn @@ -2034,11 +2035,11 @@ gst_ogg_mux_send_start_events (GstOggMux * ogg_mux, GstCollectPads * pads) } /* This function is called when there is data on all pads. - * + * * It finds a pad to pull on, this is done by looking at the buffers * to decide which one to use, and using the 'oldest' one first. It then calls * gst_ogg_mux_process_best_pad() to process as much data as possible. - * + * * If all the pads have received EOS, it flushes out all data by continually * getting the best pad and calling gst_ogg_mux_process_best_pad() until they * are all empty, and then sends EOS. diff --git a/ext/opus/gstopusdec.c b/ext/opus/gstopusdec.c index 46d6663000..d8ca196b02 100644 --- a/ext/opus/gstopusdec.c +++ b/ext/opus/gstopusdec.c @@ -26,16 +26,17 @@ /** * SECTION:element-opusdec + * @title: opusdec * @see_also: opusenc, oggdemux * * This element decodes a OPUS stream to raw integer audio. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v filesrc location=opus.ogg ! oggdemux ! opusdec ! audioconvert ! audioresample ! alsasink - * ]| Decode an Ogg/Opus file. To create an Ogg/Opus file refer to the documentation of opusenc. - * + * ]| + * Decode an Ogg/Opus file. To create an Ogg/Opus file refer to the documentation of opusenc. + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/opus/gstopusenc.c b/ext/opus/gstopusenc.c index 2d653dd3a2..c8799aaa38 100644 --- a/ext/opus/gstopusenc.c +++ b/ext/opus/gstopusenc.c @@ -25,16 +25,17 @@ /** * SECTION:element-opusenc + * @title: opusenc * @see_also: opusdec, oggmux * * This element encodes raw audio to OPUS. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v audiotestsrc wave=sine num-buffers=100 ! audioconvert ! opusenc ! oggmux ! filesink location=sine.ogg - * ]| Encode a test sine signal to Ogg/OPUS. - * + * ]| + * Encode a test sine signal to Ogg/OPUS. + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/pango/gstclockoverlay.c b/ext/pango/gstclockoverlay.c index e5e177fc67..21cf1d26da 100644 --- a/ext/pango/gstclockoverlay.c +++ b/ext/pango/gstclockoverlay.c @@ -20,6 +20,7 @@ /** * SECTION:element-clockoverlay + * @title: clockoverlay * @see_also: #GstBaseTextOverlay, #GstTimeOverlay * * This element overlays the current clock time on top of a video @@ -28,18 +29,19 @@ * time is displayed in the top left corner of the picture, with some * padding to the left and to the top. * - * - * Example launch lines + * ## Example launch lines * |[ * gst-launch-1.0 -v videotestsrc ! clockoverlay ! autovideosink - * ]| Display the current wall clock time in the top left corner of the video picture + * ]| + * Display the current wall clock time in the top left corner of the video picture * |[ * gst-launch-1.0 -v videotestsrc ! clockoverlay halignment=right valignment=bottom text="Edge City" shaded-background=true font-desc="Sans, 36" ! videoconvert ! autovideosink - * ]| Another pipeline that displays the current time with some leading + * ]| + * Another pipeline that displays the current time with some leading * text in the bottom right corner of the video picture, with the background * of the text being shaded in order to make it more legible on top of a * bright video background. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/pango/gsttextoverlay.c b/ext/pango/gsttextoverlay.c index 453e51e791..49126f8008 100644 --- a/ext/pango/gsttextoverlay.c +++ b/ext/pango/gsttextoverlay.c @@ -25,6 +25,7 @@ /** * SECTION:element-textoverlay + * @title: textoverlay * @see_also: #GstTextRender, #GstTextOverlay, #GstTimeOverlay, #GstSubParse * * This plugin renders text on top of a video stream. This can be either @@ -37,18 +38,19 @@ * The text can contain newline characters and text wrapping is enabled by * default. * - * - * Example launch lines + * ## Example launch lines * |[ * gst-launch-1.0 -v gst-launch-1.0 videotestsrc ! textoverlay text="Room A" valignment=top halignment=left font-desc="Sans, 72" ! autovideosink - * ]| Here is a simple pipeline that displays a static text in the top left + * ]| + * Here is a simple pipeline that displays a static text in the top left * corner of the video picture * |[ * gst-launch-1.0 -v filesrc location=subtitles.srt ! subparse ! txt. videotestsrc ! timeoverlay ! textoverlay name=txt shaded-background=yes ! autovideosink - * ]| Here is another pipeline that displays subtitles from an .srt subtitle + * ]| + * Here is another pipeline that displays subtitles from an .srt subtitle * file, centered at the bottom of the picture and with a rectangular shading * around the text in the background: - * + * * If you do not have such a subtitle file, create one looking like this * in a text editor: * |[ @@ -66,8 +68,7 @@ * Uh? What are you talking about? * I don't understand (18-62s) * ]| - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/pango/gsttextrender.c b/ext/pango/gsttextrender.c index 8d59a1baf2..18b7337e47 100644 --- a/ext/pango/gsttextrender.c +++ b/ext/pango/gsttextrender.c @@ -22,21 +22,21 @@ /** * SECTION:element-textrender + * @title: textrender * @see_also: #GstTextOverlay * * This plugin renders text received on the text sink pad to a video * buffer (retaining the alpha channel), so it can later be overlayed * on top of video streams using other elements. * - * The text can contain newline characters. (FIXME: What about text + * The text can contain newline characters. (FIXME: What about text * wrapping? It does not make sense in this context) * - * - * Example launch lines + * ## Example launch lines * |[ * gst-launch-1.0 -v filesrc location=subtitles.srt ! subparse ! textrender ! videoconvert ! autovideosink * ]| - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/pango/gsttimeoverlay.c b/ext/pango/gsttimeoverlay.c index da943e7bfb..d9892f6ccf 100644 --- a/ext/pango/gsttimeoverlay.c +++ b/ext/pango/gsttimeoverlay.c @@ -20,6 +20,7 @@ /** * SECTION:element-timeoverlay + * @title: timeoverlay * @see_also: #GstBaseTextOverlay, #GstClockOverlay * * This element overlays the buffer time stamps of a video stream on @@ -28,17 +29,18 @@ * time stamp is displayed in the top left corner of the picture, with some * padding to the left and to the top. * - * * |[ * gst-launch-1.0 -v videotestsrc ! timeoverlay ! autovideosink - * ]| Display the time stamps in the top left corner of the video picture. + * ]| + * Display the time stamps in the top left corner of the video picture. * |[ * gst-launch-1.0 -v videotestsrc ! timeoverlay halignment=right valignment=bottom text="Stream time:" shaded-background=true font-desc="Sans, 24" ! autovideosink - * ]| Another pipeline that displays the time stamps with some leading + * ]| + * Another pipeline that displays the time stamps with some leading * text in the bottom right corner of the video picture, with the background * of the text being shaded in order to make it more legible on top of a * bright video background. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/theora/gsttheoradec.c b/ext/theora/gsttheoradec.c index 859b8677b8..14bd5b81d3 100644 --- a/ext/theora/gsttheoradec.c +++ b/ext/theora/gsttheoradec.c @@ -22,6 +22,7 @@ /** * SECTION:element-theoradec + * @title: theoradec * @see_also: theoraenc, oggdemux * * This element decodes theora streams into raw video @@ -29,13 +30,13 @@ * video codec maintained by the Xiph.org * Foundation, based on the VP3 codec. * - * - * Example pipeline + * ## Example pipeline * |[ * gst-launch-1.0 -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoconvert ! videoscale ! autovideosink - * ]| This example pipeline will decode an ogg stream and decodes the theora video in it. + * ]| + * This example pipeline will decode an ogg stream and decodes the theora video in it. * Refer to the theoraenc example to create the ogg file. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/theora/gsttheoraenc.c b/ext/theora/gsttheoraenc.c index d291221462..552068b2d1 100644 --- a/ext/theora/gsttheoraenc.c +++ b/ext/theora/gsttheoraenc.c @@ -22,6 +22,7 @@ /** * SECTION:element-theoraenc + * @title: theoraenc * @see_also: theoradec, oggmux * * This element encodes raw video into a Theora stream. @@ -45,14 +46,14 @@ * A videorate element is often required in front of theoraenc, especially * when transcoding and when putting Theora into the Ogg container. * - * - * Example pipeline + * ## Example pipeline * |[ * gst-launch-1.0 -v videotestsrc num-buffers=500 ! video/x-raw,width=1280,height=720 ! queue ! progressreport ! theoraenc ! oggmux ! filesink location=videotestsrc.ogg - * ]| This example pipeline will encode a test video source to theora muxed in an + * ]| + * This example pipeline will encode a test video source to theora muxed in an * ogg container. Refer to the theoradec documentation to decode the create * stream. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/theora/gsttheoraparse.c b/ext/theora/gsttheoraparse.c index 12a5fb1576..f55419b5b5 100644 --- a/ext/theora/gsttheoraparse.c +++ b/ext/theora/gsttheoraparse.c @@ -20,6 +20,7 @@ /** * SECTION:element-theoraparse + * @title: theoraparse * @see_also: theoradec, oggdemux, vorbisparse * * The theoraparse element will parse the header packets of the Theora @@ -40,18 +41,19 @@ * offsetting all buffers that it outputs by a specified amount, and updating * that offset from the value array whenever a keyframe is processed. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v filesrc location=video.ogg ! oggdemux ! theoraparse ! fakesink - * ]| This pipeline shows that the streamheader is set in the caps, and that each + * ]| + * This pipeline shows that the streamheader is set in the caps, and that each * buffer has the timestamp, duration, offset, and offset_end set. * |[ * gst-launch-1.0 filesrc location=video.ogg ! oggdemux ! theoraparse \ * ! oggmux ! filesink location=video-remuxed.ogg - * ]| This pipeline shows remuxing. video-remuxed.ogg might not be exactly the same + * ]| + * This pipeline shows remuxing. video-remuxed.ogg might not be exactly the same * as video.ogg, but they should produce exactly the same decoded data. - * + * */ /* FIXME 0.11: suppress warnings for deprecated API such as GValueArray diff --git a/ext/vorbis/gstvorbisdec.c b/ext/vorbis/gstvorbisdec.c index 467c636393..c4b92e35af 100644 --- a/ext/vorbis/gstvorbisdec.c +++ b/ext/vorbis/gstvorbisdec.c @@ -19,6 +19,7 @@ /** * SECTION:element-vorbisdec + * @title: vorbisdec * @see_also: vorbisenc, oggdemux * * This element decodes a Vorbis stream to raw float audio. @@ -27,13 +28,12 @@ * Foundation. As it outputs raw float audio you will often need to * put an audioconvert element after it. * - * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v filesrc location=sine.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! autoaudiosink - * ]| Decode an Ogg/Vorbis. To create an Ogg/Vorbis file refer to the documentation of vorbisenc. - * + * ]| + * Decode an Ogg/Vorbis. To create an Ogg/Vorbis file refer to the documentation of vorbisenc. + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/vorbis/gstvorbisenc.c b/ext/vorbis/gstvorbisenc.c index 5b90d8986a..cad6d9ae13 100644 --- a/ext/vorbis/gstvorbisenc.c +++ b/ext/vorbis/gstvorbisenc.c @@ -19,6 +19,7 @@ /** * SECTION:element-vorbisenc + * @title: vorbisenc * @see_also: vorbisdec, oggmux * * This element encodes raw float audio into a Vorbis stream. @@ -26,16 +27,17 @@ * audio codec maintained by the Xiph.org * Foundation. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v audiotestsrc wave=sine num-buffers=100 ! audioconvert ! vorbisenc ! oggmux ! filesink location=sine.ogg - * ]| Encode a test sine signal to Ogg/Vorbis. Note that the resulting file + * ]| + * Encode a test sine signal to Ogg/Vorbis. Note that the resulting file * will be really small because a sine signal compresses very well. * |[ * gst-launch-1.0 -v autoaudiosrc ! audioconvert ! vorbisenc ! oggmux ! filesink location=alsasrc.ogg - * ]| Record from a sound card and encode to Ogg/Vorbis. - * + * ]| + * Record from a sound card and encode to Ogg/Vorbis. + * */ #ifdef HAVE_CONFIG_H #include "config.h" diff --git a/ext/vorbis/gstvorbisparse.c b/ext/vorbis/gstvorbisparse.c index dd357a19f5..a91b0cb78f 100644 --- a/ext/vorbis/gstvorbisparse.c +++ b/ext/vorbis/gstvorbisparse.c @@ -20,6 +20,7 @@ /** * SECTION:element-vorbisparse + * @title: vorbisparse * @see_also: vorbisdec, oggdemux, theoraparse * * The vorbisparse element will parse the header packets of the Vorbis @@ -33,18 +34,19 @@ * vorbisparse outputs have all of the metadata that oggmux expects to receive, * which allows you to (for example) remux an ogg/vorbis file. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v filesrc location=sine.ogg ! oggdemux ! vorbisparse ! fakesink - * ]| This pipeline shows that the streamheader is set in the caps, and that each + * ]| + * This pipeline shows that the streamheader is set in the caps, and that each * buffer has the timestamp, duration, offset, and offset_end set. * |[ * gst-launch-1.0 filesrc location=sine.ogg ! oggdemux ! vorbisparse \ * ! oggmux ! filesink location=sine-remuxed.ogg - * ]| This pipeline shows remuxing. sine-remuxed.ogg might not be exactly the same + * ]| + * This pipeline shows remuxing. sine-remuxed.ogg might not be exactly the same * as sine.ogg, but they should produce exactly the same decoded data. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/ext/vorbis/gstvorbistag.c b/ext/vorbis/gstvorbistag.c index fded30cb62..4a8cdb2ca8 100644 --- a/ext/vorbis/gstvorbistag.c +++ b/ext/vorbis/gstvorbistag.c @@ -19,6 +19,7 @@ /** * SECTION:element-vorbistag + * @title: vorbistag * @see_also: #oggdemux, #oggmux, #vorbisparse, #GstTagSetter * * The vorbistags element can change the tag contained within a raw @@ -34,14 +35,14 @@ * automatically (and merged according to the merge mode set via the tag * setter interface). * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v filesrc location=foo.ogg ! oggdemux ! vorbistag ! oggmux ! filesink location=bar.ogg - * ]| This element is not useful with gst-launch-1.0, because it does not support + * ]| + * This element is not useful with gst-launch-1.0, because it does not support * setting the tags on a #GstTagSetter interface. Conceptually, the element * will usually be used in this order though. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/allocators/gstdmabuf.c b/gst-libs/gst/allocators/gstdmabuf.c index e4ee14ef2f..7d6bcab8fc 100644 --- a/gst-libs/gst/allocators/gstdmabuf.c +++ b/gst-libs/gst/allocators/gstdmabuf.c @@ -27,6 +27,7 @@ /** * SECTION:gstdmabuf + * @title: GstDmaBufAllocator * @short_description: Memory wrapper for Linux dmabuf memory * @see_also: #GstMemory * diff --git a/gst-libs/gst/allocators/gstfdmemory.c b/gst-libs/gst/allocators/gstfdmemory.c index f09da9e4e7..ad428a7478 100644 --- a/gst-libs/gst/allocators/gstfdmemory.c +++ b/gst-libs/gst/allocators/gstfdmemory.c @@ -20,6 +20,7 @@ /** * SECTION:gstfdmemory + * @title: GstFdAllocator * @short_description: Memory wrapper for fd backed memory * @see_also: #GstMemory * diff --git a/gst-libs/gst/app/gstappsink.c b/gst-libs/gst/app/gstappsink.c index 9ce4c29a64..adb26529f8 100644 --- a/gst-libs/gst/app/gstappsink.c +++ b/gst-libs/gst/app/gstappsink.c @@ -19,6 +19,7 @@ */ /** * SECTION:gstappsink + * @title: GstAppSink * @short_description: Easy way for applications to extract samples from a * pipeline * @see_also: #GstSample, #GstBaseSink, appsrc diff --git a/gst-libs/gst/app/gstappsrc.c b/gst-libs/gst/app/gstappsrc.c index c011334061..c4074d6a67 100644 --- a/gst-libs/gst/app/gstappsrc.c +++ b/gst-libs/gst/app/gstappsrc.c @@ -19,6 +19,7 @@ */ /** * SECTION:gstappsrc + * @title: GstAppSrc * @short_description: Easy way for applications to inject buffers into a * pipeline * @see_also: #GstBaseSrc, appsink diff --git a/gst-libs/gst/audio/audio-channels.c b/gst-libs/gst/audio/audio-channels.c index 8097a49599..d00f0b9723 100644 --- a/gst-libs/gst/audio/audio-channels.c +++ b/gst-libs/gst/audio/audio-channels.c @@ -18,6 +18,7 @@ */ /** * SECTION:gstaudiochannels + * @title: Audio-channels * @short_description: Support library for audio channel handling * * This library contains some helper functions for multichannel audio. diff --git a/gst-libs/gst/audio/audio-converter.c b/gst-libs/gst/audio/audio-converter.c index e4394c2df3..ef06b9b6b0 100644 --- a/gst-libs/gst/audio/audio-converter.c +++ b/gst-libs/gst/audio/audio-converter.c @@ -32,24 +32,18 @@ /** * SECTION:audioconverter + * @title: GstAudioConverter * @short_description: Generic audio conversion * - * - * * This object is used to convert audio samples from one format to another. * The object can perform conversion of: - * - * - * audio format with optional dithering and noise shaping - * - * - * audio samplerate - * - * - * audio channels and channel layout - * - * - * + * + * * audio format with optional dithering and noise shaping + * + * * audio samplerate + * + * * audio channels and channel layout + * */ #ifndef GST_DISABLE_GST_DEBUG @@ -1336,7 +1330,7 @@ gst_audio_converter_samples (GstAudioConverter * convert, } /** - * gst_audio_converter_supports_inplace + * gst_audio_converter_supports_inplace: * @convert: a #GstAudioConverter * * Returns whether the audio converter can perform the conversion in-place. diff --git a/gst-libs/gst/audio/audio-resampler.c b/gst-libs/gst/audio/audio-resampler.c index 8cb562ca8c..13c0b00ba4 100644 --- a/gst-libs/gst/audio/audio-resampler.c +++ b/gst-libs/gst/audio/audio-resampler.c @@ -42,6 +42,7 @@ GST_DEBUG_CATEGORY_STATIC (audio_resampler_debug); /** * SECTION:gstaudioresampler + * @title: GstAudioResampler * @short_description: Utility structure for resampler information * * #GstAudioResampler is a structure which holds the information diff --git a/gst-libs/gst/audio/audio-resampler.h b/gst-libs/gst/audio/audio-resampler.h index 1664e680d7..e4e73b1a55 100644 --- a/gst-libs/gst/audio/audio-resampler.h +++ b/gst-libs/gst/audio/audio-resampler.h @@ -28,20 +28,20 @@ G_BEGIN_DECLS typedef struct _GstAudioResampler GstAudioResampler; /** - * GST_AUDIO_RESAMPLER_OPT_CUTOFF + * GST_AUDIO_RESAMPLER_OPT_CUTOFF: * * G_TYPE_DOUBLE, Cutoff parameter for the filter. 0.940 is the default. */ #define GST_AUDIO_RESAMPLER_OPT_CUTOFF "GstAudioResampler.cutoff" /** - * GST_AUDIO_RESAMPLER_OPT_STOP_ATTENUTATION + * GST_AUDIO_RESAMPLER_OPT_STOP_ATTENUTATION: * * G_TYPE_DOUBLE, stopband attenuation in debibels. The attenutation * after the stopband for the kaiser window. 85 dB is the default. */ #define GST_AUDIO_RESAMPLER_OPT_STOP_ATTENUATION "GstAudioResampler.stop-attenutation" /** - * GST_AUDIO_RESAMPLER_OPT_TRANSITION_BANDWIDTH + * GST_AUDIO_RESAMPLER_OPT_TRANSITION_BANDWIDTH: * * G_TYPE_DOUBLE, transition bandwidth. The width of the * transition band for the kaiser window. 0.087 is the default. @@ -137,7 +137,7 @@ typedef enum { */ #define GST_AUDIO_RESAMPLER_OPT_FILTER_INTERPOLATION "GstAudioResampler.filter-interpolation" /** - * GST_AUDIO_RESAMPLER_OPT_FILTER_OVERSAMPLE + * GST_AUDIO_RESAMPLER_OPT_FILTER_OVERSAMPLE: * * G_TYPE_UINT, oversampling to use when interpolating filters * 8 is the default. diff --git a/gst-libs/gst/audio/audio.c b/gst-libs/gst/audio/audio.c index c723d20dda..af5da5d061 100644 --- a/gst-libs/gst/audio/audio.c +++ b/gst-libs/gst/audio/audio.c @@ -18,6 +18,7 @@ */ /** * SECTION:gstaudio + * @title: GstAudio * @short_description: Support library for audio elements * * This library contains some helper functions for audio elements. @@ -60,7 +61,7 @@ ensure_debug_category (void) * @segment: Segment in %GST_FORMAT_TIME or %GST_FORMAT_DEFAULT to which * the buffer should be clipped. * @rate: sample rate. - * @bpf: size of one audio frame in bytes. This is the size of one sample * + * @bpf: size of one audio frame in bytes. This is the size of one sample * * number of channels. * * Clip the buffer to the given %GstSegment. diff --git a/gst-libs/gst/audio/gstaudiobasesink.c b/gst-libs/gst/audio/gstaudiobasesink.c index d8eb9e0a02..79f650560b 100644 --- a/gst-libs/gst/audio/gstaudiobasesink.c +++ b/gst-libs/gst/audio/gstaudiobasesink.c @@ -22,6 +22,7 @@ /** * SECTION:gstaudiobasesink + * @title: GstAudioBaseSink * @short_description: Base class for audio sinks * @see_also: #GstAudioSink, #GstAudioRingBuffer. * diff --git a/gst-libs/gst/audio/gstaudiobasesrc.c b/gst-libs/gst/audio/gstaudiobasesrc.c index 601d95c06b..ffb725a6a4 100644 --- a/gst-libs/gst/audio/gstaudiobasesrc.c +++ b/gst-libs/gst/audio/gstaudiobasesrc.c @@ -22,6 +22,7 @@ /** * SECTION:gstaudiobasesrc + * @title: GstAudioBaseSrc * @short_description: Base class for audio sources * @see_also: #GstAudioSrc, #GstAudioRingBuffer. * diff --git a/gst-libs/gst/audio/gstaudiocdsrc.c b/gst-libs/gst/audio/gstaudiocdsrc.c index 79b7423d63..f2efeab3b7 100644 --- a/gst-libs/gst/audio/gstaudiocdsrc.c +++ b/gst-libs/gst/audio/gstaudiocdsrc.c @@ -36,62 +36,53 @@ /** * SECTION:gstaudiocdsrc + * @title: GstAudioCdSrc * @short_description: Base class for Audio CD sources * - * * Provides a base class for CD digital audio (CDDA) sources, which handles * things like seeking, querying, discid calculation, tags, and buffer * timestamping. - * - * - * Using GstAudioCdSrc-based elements in applications - * + * + * ## Using GstAudioCdSrc-based elements in applications + * * GstAudioCdSrc registers two #GstFormats of its own, namely * the "track" format and the "sector" format. Applications will usually * only find the "track" format interesting. You can retrieve that #GstFormat * for use in seek events or queries with gst_format_get_by_nick("track"). - * - * + * * In order to query the number of tracks, for example, an application would * set the CDDA source element to READY or PAUSED state and then query the * the number of tracks via gst_element_query_duration() using the track * format acquired above. Applications can query the currently playing track * in the same way. - * - * + * * Alternatively, applications may retrieve the currently playing track and * the total number of tracks from the taglist that will posted on the bus * whenever the CD is opened or the currently playing track changes. The * taglist will contain GST_TAG_TRACK_NUMBER and GST_TAG_TRACK_COUNT tags. - * - * + * * Applications playing back CD audio using playbin and cdda://n URIs should * issue a seek command in track format to change between tracks, rather than * setting a new cdda://n+1 URI on playbin (as setting a new URI on playbin * involves closing and re-opening the CD device, which is much much slower). - * - * - * - * Tags and meta-information - * + * + * ## Tags and meta-information + * * CDDA sources will automatically emit a number of tags, details about which * can be found in the libgsttag documentation. Those tags are: * #GST_TAG_CDDA_CDDB_DISCID, #GST_TAG_CDDA_CDDB_DISCID_FULL, * #GST_TAG_CDDA_MUSICBRAINZ_DISCID, #GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL, * among others. - * - * - * - * Tracks and Table of Contents (TOC) - * + * + * ## Tracks and Table of Contents (TOC) + * * Applications will be informed of the available tracks via a TOC message * on the pipeline's #GstBus. The #GstToc will contain a #GstTocEntry for * each track, with information about each track. The duration for each * track can be retrieved via the #GST_TAG_DURATION tag from each entry's * tag list, or calculated via gst_toc_entry_get_start_stop_times(). * The track entries in the TOC will be sorted by track number. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/audio/gstaudioclock.c b/gst-libs/gst/audio/gstaudioclock.c index 4a6fd4b1a2..a413611a6f 100644 --- a/gst-libs/gst/audio/gstaudioclock.c +++ b/gst-libs/gst/audio/gstaudioclock.c @@ -22,6 +22,7 @@ /** * SECTION:gstaudioclock + * @title: GstAudioClock * @short_description: Helper object for implementing audio clocks * @see_also: #GstAudioBaseSink, #GstSystemClock * diff --git a/gst-libs/gst/audio/gstaudiodecoder.c b/gst-libs/gst/audio/gstaudiodecoder.c index 198e0fcaa8..ffaf48f1a8 100644 --- a/gst-libs/gst/audio/gstaudiodecoder.c +++ b/gst-libs/gst/audio/gstaudiodecoder.c @@ -23,6 +23,7 @@ /** * SECTION:gstaudiodecoder + * @title: GstAudioDecoder * @short_description: Base class for audio decoders * @see_also: #GstBaseTransform * @@ -30,72 +31,48 @@ * raw audio samples. * * GstAudioDecoder and subclass should cooperate as follows. - * - * - * Configuration - * - * Initially, GstAudioDecoder calls @start when the decoder element + * + * ## Configuration + * + * * Initially, GstAudioDecoder calls @start when the decoder element * is activated, which allows subclass to perform any global setup. * Base class (context) parameters can already be set according to subclass * capabilities (or possibly upon receive more information in subsequent * @set_format). - * - * - * GstAudioDecoder calls @set_format to inform subclass of the format + * * GstAudioDecoder calls @set_format to inform subclass of the format * of input audio data that it is about to receive. * While unlikely, it might be called more than once, if changing input * parameters require reconfiguration. - * - * - * GstAudioDecoder calls @stop at end of all processing. - * - * - * + * * GstAudioDecoder calls @stop at end of all processing. + * * As of configuration stage, and throughout processing, GstAudioDecoder * provides various (context) parameters, e.g. describing the format of * output audio data (valid when output caps have been set) or current parsing state. * Conversely, subclass can and should configure context to inform * base class of its expectation w.r.t. buffer handling. - * - * - * Data processing - * - * Base class gathers input data, and optionally allows subclass + * + * ## Data processing + * * Base class gathers input data, and optionally allows subclass * to parse this into subsequently manageable (as defined by subclass) * chunks. Such chunks are subsequently referred to as 'frames', * though they may or may not correspond to 1 (or more) audio format frame. - * - * - * Input frame is provided to subclass' @handle_frame. - * - * - * If codec processing results in decoded data, subclass should call + * * Input frame is provided to subclass' @handle_frame. + * * If codec processing results in decoded data, subclass should call * @gst_audio_decoder_finish_frame to have decoded data pushed * downstream. - * - * - * Just prior to actually pushing a buffer downstream, + * * Just prior to actually pushing a buffer downstream, * it is passed to @pre_push. Subclass should either use this callback * to arrange for additional downstream pushing or otherwise ensure such * custom pushing occurs after at least a method call has finished since * setting src pad caps. - * - * - * During the parsing process GstAudioDecoderClass will handle both + * * During the parsing process GstAudioDecoderClass will handle both * srcpad and sinkpad events. Sink events will be passed to subclass * if @event callback has been provided. - * - * - * - * - * Shutdown phase - * - * GstAudioDecoder class calls @stop to inform the subclass that data + * + * ## Shutdown phase + * + * * GstAudioDecoder class calls @stop to inform the subclass that data * parsing will be stopped. - * - * - * - * * * Subclass is responsible for providing pad template caps for * source and sink pads. The pads need to be named "sink" and "src". It also @@ -125,23 +102,18 @@ * bitrates. * * Things that subclass need to take care of: - * - * Provide pad templates - * - * Set source pad caps when appropriate - * - * - * Set user-configurable properties to sane defaults for format and + * + * * Provide pad templates + * * Set source pad caps when appropriate + * * Set user-configurable properties to sane defaults for format and * implementing codec at hand, and convey some subclass capabilities and * expectations in context. - * - * - * Accept data in @handle_frame and provide encoded results to + * + * * Accept data in @handle_frame and provide encoded results to * @gst_audio_decoder_finish_frame. If it is prepared to perform * PLC, it should also accept NULL data in @handle_frame and provide for * data for indicated duration. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/audio/gstaudioencoder.c b/gst-libs/gst/audio/gstaudioencoder.c index b8715a8b5c..0b84f0bdea 100644 --- a/gst-libs/gst/audio/gstaudioencoder.c +++ b/gst-libs/gst/audio/gstaudioencoder.c @@ -21,6 +21,7 @@ /** * SECTION:gstaudioencoder + * @title: GstAudioEncoder * @short_description: Base class for audio encoders * @see_also: #GstBaseTransform * @@ -28,65 +29,46 @@ * encoded audio data. * * GstAudioEncoder and subclass should cooperate as follows. - * - * - * Configuration - * - * Initially, GstAudioEncoder calls @start when the encoder element + * + * ## Configuration + * + * * Initially, GstAudioEncoder calls @start when the encoder element * is activated, which allows subclass to perform any global setup. - * - * - * GstAudioEncoder calls @set_format to inform subclass of the format + * + * * GstAudioEncoder calls @set_format to inform subclass of the format * of input audio data that it is about to receive. Subclass should * setup for encoding and configure various base class parameters * appropriately, notably those directing desired input data handling. * While unlikely, it might be called more than once, if changing input * parameters require reconfiguration. - * - * - * GstAudioEncoder calls @stop at end of all processing. - * - * - * + * + * * GstAudioEncoder calls @stop at end of all processing. + * * As of configuration stage, and throughout processing, GstAudioEncoder * maintains various parameters that provide required context, * e.g. describing the format of input audio data. * Conversely, subclass can and should configure these context parameters * to inform base class of its expectation w.r.t. buffer handling. - * - * - * Data processing - * - * Base class gathers input sample data (as directed by the context's + * + * ## Data processing + * + * * Base class gathers input sample data (as directed by the context's * frame_samples and frame_max) and provides this to subclass' @handle_frame. - * - * - * If codec processing results in encoded data, subclass should call + * * If codec processing results in encoded data, subclass should call * gst_audio_encoder_finish_frame() to have encoded data pushed * downstream. Alternatively, it might also call * gst_audio_encoder_finish_frame() (with a NULL buffer and some number of * dropped samples) to indicate dropped (non-encoded) samples. - * - * - * Just prior to actually pushing a buffer downstream, + * * Just prior to actually pushing a buffer downstream, * it is passed to @pre_push. - * - * - * During the parsing process GstAudioEncoderClass will handle both + * * During the parsing process GstAudioEncoderClass will handle both * srcpad and sinkpad events. Sink events will be passed to subclass * if @event callback has been provided. - * - * - * - * - * Shutdown phase - * - * GstAudioEncoder class calls @stop to inform the subclass that data + * + * ## Shutdown phase + * + * * GstAudioEncoder class calls @stop to inform the subclass that data * parsing will be stopped. - * - * - * - * * * Subclass is responsible for providing pad template caps for * source and sink pads. The pads need to be named "sink" and "src". It also @@ -125,25 +107,16 @@ * by same sample count and sample rate). * * Things that subclass need to take care of: - * - * Provide pad templates - * - * Set source pad caps when appropriate - * - * - * Inform base class of buffer processing needs using context's + * + * * Provide pad templates + * * Set source pad caps when appropriate + * * Inform base class of buffer processing needs using context's * frame_samples and frame_bytes. - * - * - * Set user-configurable properties to sane defaults for format and + * * Set user-configurable properties to sane defaults for format and * implementing codec at hand, e.g. those controlling timestamp behaviour * and discontinuity processing. - * - * - * Accept data in @handle_frame and provide encoded results to + * * Accept data in @handle_frame and provide encoded results to * gst_audio_encoder_finish_frame(). - * - * * */ diff --git a/gst-libs/gst/audio/gstaudiofilter.c b/gst-libs/gst/audio/gstaudiofilter.c index 7abd011814..d13109af0f 100644 --- a/gst-libs/gst/audio/gstaudiofilter.c +++ b/gst-libs/gst/audio/gstaudiofilter.c @@ -21,6 +21,7 @@ /** * SECTION:gstaudiofilter + * @title: GstAudioFilter * @short_description: Base class for simple audio filters * * #GstAudioFilter is a #GstBaseTransform-derived base class for simple audio diff --git a/gst-libs/gst/audio/gstaudioiec61937.c b/gst-libs/gst/audio/gstaudioiec61937.c index 6ae854b926..948325e845 100644 --- a/gst-libs/gst/audio/gstaudioiec61937.c +++ b/gst-libs/gst/audio/gstaudioiec61937.c @@ -21,6 +21,7 @@ /** * SECTION:gstaudioiec61937 + * @title: GstAudio IEC61937 * @short_description: Utility functions for IEC 61937 payloading * * This module contains some helper functions for encapsulating various diff --git a/gst-libs/gst/audio/gstaudiometa.c b/gst-libs/gst/audio/gstaudiometa.c index 660cdb76cd..e7da037557 100644 --- a/gst-libs/gst/audio/gstaudiometa.c +++ b/gst-libs/gst/audio/gstaudiometa.c @@ -19,6 +19,7 @@ /** * SECTION:gstaudiometa + * @title: GstAudioDownmixMeta * @short_description: Buffer metadata for audio downmix matrix handling * * #GstAudioDownmixMeta defines an audio downmix matrix to be send along with diff --git a/gst-libs/gst/audio/gstaudioringbuffer.c b/gst-libs/gst/audio/gstaudioringbuffer.c index cd774bbc8f..2628697351 100644 --- a/gst-libs/gst/audio/gstaudioringbuffer.c +++ b/gst-libs/gst/audio/gstaudioringbuffer.c @@ -19,22 +19,19 @@ /** * SECTION:gstaudioringbuffer + * @title: GstAudioRingBuffer * @short_description: Base class for audio ringbuffer implementations * @see_also: #GstAudioBaseSink, #GstAudioSink * - * - * * This object is the base class for audio ringbuffers used by the base * audio source and sink classes. - * - * + * * The ringbuffer abstracts a circular buffer of data. One reader and * one writer can operate on the data from different threads in a lockfree * manner. The base class is sufficiently flexible to be used as an * abstraction for DMA based ringbuffers as well as a pure software * implementations. - * - * + * */ #include diff --git a/gst-libs/gst/audio/gstaudiosink.c b/gst-libs/gst/audio/gstaudiosink.c index a80462742e..cc48f7dbed 100644 --- a/gst-libs/gst/audio/gstaudiosink.c +++ b/gst-libs/gst/audio/gstaudiosink.c @@ -22,43 +22,27 @@ /** * SECTION:gstaudiosink + * @title: GstAudioSink * @short_description: Simple base class for audio sinks * @see_also: #GstAudioBaseSink, #GstAudioRingBuffer, #GstAudioSink. * * This is the most simple base class for audio sinks that only requires * subclasses to implement a set of simple functions: * - * - * - * open() - * Open the device. - * - * - * prepare() - * Configure the device with the specified format. - * - * - * write() - * Write samples to the device. - * - * - * reset() - * Unblock writes and flush the device. - * - * - * delay() - * Get the number of samples written but not yet played - * by the device. - * - * - * unprepare() - * Undo operations done by prepare. - * - * - * close() - * Close the device. - * - * + * * `open()` :Open the device. + * + * * `prepare()` :Configure the device with the specified format. + * + * * `write()` :Write samples to the device. + * + * * `reset()` :Unblock writes and flush the device. + * + * * `delay()` :Get the number of samples written but not yet played + * by the device. + * + * * `unprepare()` :Undo operations done by prepare. + * + * * `close()` :Close the device. * * All scheduling of samples and timestamps is done in this base class * together with #GstAudioBaseSink using a default implementation of a diff --git a/gst-libs/gst/audio/gstaudiosrc.c b/gst-libs/gst/audio/gstaudiosrc.c index 96871da4ad..c3faf8fff5 100644 --- a/gst-libs/gst/audio/gstaudiosrc.c +++ b/gst-libs/gst/audio/gstaudiosrc.c @@ -22,43 +22,20 @@ /** * SECTION:gstaudiosrc + * @title: GstAudioSrc * @short_description: Simple base class for audio sources * @see_also: #GstAudioBaseSrc, #GstAudioRingBuffer, #GstAudioSrc. * * This is the most simple base class for audio sources that only requires * subclasses to implement a set of simple functions: * - * - * - * open() - * Open the device. - * - * - * prepare() - * Configure the device with the specified format. - * - * - * read() - * Read samples from the device. - * - * - * reset() - * Unblock reads and flush the device. - * - * - * delay() - * Get the number of samples in the device but not yet read. - * - * - * - * unprepare() - * Undo operations done by prepare. - * - * - * close() - * Close the device. - * - * + * * `open()` :Open the device. + * * `prepare()` :Configure the device with the specified format. + * * `read()` :Read samples from the device. + * * `reset()` :Unblock reads and flush the device. + * * `delay()` :Get the number of samples in the device but not yet read. + * * `unprepare()` :Undo operations done by prepare. + * * `close()` :Close the device. * * All scheduling of samples and timestamps is done in this base class * together with #GstAudioBaseSrc using a default implementation of a diff --git a/gst-libs/gst/audio/streamvolume.c b/gst-libs/gst/audio/streamvolume.c index 9b7bf825db..cdcacc1b14 100644 --- a/gst-libs/gst/audio/streamvolume.c +++ b/gst-libs/gst/audio/streamvolume.c @@ -19,14 +19,12 @@ /** * SECTION:gststreamvolume + * @title: GstStreamVolume * @short_description: Interface for elements that provide a stream volume * - * - * * This interface is implemented by elements that provide a stream volume. Examples for * such elements are #volume and #playbin. - * - * + * * Applications can use this interface to get or set the current stream volume. For this * the "volume" #GObject property can be used or the helper functions gst_stream_volume_set_volume() * and gst_stream_volume_get_volume(). This volume is always a linear factor, i.e. 0.0 is muted @@ -36,13 +34,11 @@ * * Separate from the volume the stream can also be muted by the "mute" #GObject property or * gst_stream_volume_set_mute() and gst_stream_volume_get_mute(). - * - * + * * Elements that provide some kind of stream volume should implement the "volume" and * "mute" #GObject properties and handle setting and getting of them properly. * The volume property is defined to be a linear volume factor. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/fft/gstfft.c b/gst-libs/gst/fft/gstfft.c index 24b7e6ee22..86d921e244 100644 --- a/gst-libs/gst/fft/gstfft.c +++ b/gst-libs/gst/fft/gstfft.c @@ -19,8 +19,9 @@ /** * SECTION:gstfft + * @title: GstFFT * @short_description: General FFT functions and declarations - * + * * This library includes general definitions and functions, useful for * all typed FFT classes. */ diff --git a/gst-libs/gst/fft/gstfftf32.c b/gst-libs/gst/fft/gstfftf32.c index eff4413f58..943be5151a 100644 --- a/gst-libs/gst/fft/gstfftf32.c +++ b/gst-libs/gst/fft/gstfftf32.c @@ -31,6 +31,7 @@ /** * SECTION:gstfftf32 + * @title: GstFFTF32 * @short_description: FFT functions for 32 bit float samples * * #GstFFTF32 provides a FFT implementation and related functions for diff --git a/gst-libs/gst/fft/gstfftf64.c b/gst-libs/gst/fft/gstfftf64.c index 7ccbcb0f8b..9117dcd056 100644 --- a/gst-libs/gst/fft/gstfftf64.c +++ b/gst-libs/gst/fft/gstfftf64.c @@ -31,6 +31,7 @@ /** * SECTION:gstfftf64 + * @title: GstFFTF64 * @short_description: FFT functions for 64 bit float samples * * #GstFFTF64 provides a FFT implementation and related functions for diff --git a/gst-libs/gst/fft/gstffts16.c b/gst-libs/gst/fft/gstffts16.c index 01882433c2..7b0d2a5346 100644 --- a/gst-libs/gst/fft/gstffts16.c +++ b/gst-libs/gst/fft/gstffts16.c @@ -31,6 +31,7 @@ /** * SECTION:gstffts16 + * @title: GstFFTS16 * @short_description: FFT functions for signed 16 bit integer samples * * #GstFFTS16 provides a FFT implementation and related functions for diff --git a/gst-libs/gst/fft/gstffts32.c b/gst-libs/gst/fft/gstffts32.c index ae7d5e577b..4d81e7230b 100644 --- a/gst-libs/gst/fft/gstffts32.c +++ b/gst-libs/gst/fft/gstffts32.c @@ -31,6 +31,7 @@ /** * SECTION:gstffts32 + * @title: GstFFTS32 * @short_description: FFT functions for signed 32 bit integer samples * * #GstFFTS32 provides a FFT implementation and related functions for diff --git a/gst-libs/gst/pbutils/codec-utils.c b/gst-libs/gst/pbutils/codec-utils.c index 09162bd2ad..5397c6642a 100644 --- a/gst-libs/gst/pbutils/codec-utils.c +++ b/gst-libs/gst/pbutils/codec-utils.c @@ -24,14 +24,12 @@ /** * SECTION:gstpbutilscodecutils + * @title: Codec utilities * @short_description: Miscellaneous codec-specific utility functions * - * - * * Provides codec-specific ulility functions such as functions to provide the * codec profile and level in human-readable string form from header data. - * - * + * */ #ifdef HAVE_CONFIG_H @@ -173,9 +171,7 @@ gst_codec_utils_aac_get_channels (const guint8 * audio_config, guint len) * determined using the AudioObjectType field which is in the first 5 bits of * @audio_config. * - * - * HE-AAC support has not yet been implemented. - * + * > HE-AAC support has not yet been implemented. * * Returns: The profile as a const string and %NULL if the profile could not be * determined. @@ -221,23 +217,13 @@ gst_codec_utils_aac_get_profile (const guint8 * audio_config, guint len) * The @audio_config parameter follows the following format, starting from the * most significant bit of the first byte: * - * - * - * Bit 0:4 contains the AudioObjectType - * - * - * Bit 5:8 contains the sample frequency index (if this is 0xf, then the - * next 24 bits define the actual sample frequency, and subsequent - * fields are appropriately shifted). - * - * - * Bit 9:12 contains the channel configuration - * - * + * * Bit 0:4 contains the AudioObjectType + * * Bit 5:8 contains the sample frequency index (if this is 0xf, then the + * next 24 bits define the actual sample frequency, and subsequent + * fields are appropriately shifted). + * * Bit 9:12 contains the channel configuration * - * - * HE-AAC support has not yet been implemented. - * + * > HE-AAC support has not yet been implemented. * * Returns: The level as a const string and %NULL if the level could not be * determined. @@ -477,16 +463,14 @@ gst_codec_utils_aac_caps_set_level_and_profile (GstCaps * caps, * as a bitstream here, with bit 0 being the most significant bit of the first * byte. * - * - * Bit 0:7 - Profile indication - * Bit 8 - constraint_set0_flag - * Bit 9 - constraint_set1_flag - * Bit 10 - constraint_set2_flag - * Bit 11 - constraint_set3_flag - * Bit 12 - constraint_set3_flag - * Bit 13:15 - Reserved - * Bit 16:24 - Level indication - * + * * Bit 0:7 - Profile indication + * * Bit 8 - constraint_set0_flag + * * Bit 9 - constraint_set1_flag + * * Bit 10 - constraint_set2_flag + * * Bit 11 - constraint_set3_flag + * * Bit 12 - constraint_set3_flag + * * Bit 13:15 - Reserved + * * Bit 16:24 - Level indication * * Returns: The profile as a const string, or %NULL if there is an error. */ @@ -735,18 +719,16 @@ gst_codec_utils_h264_caps_set_level_and_profile (GstCaps * caps, * specification. The profile_tier_level is viewed as a bitstream here, * with bit 0 being the most significant bit of the first byte. * - * - * Bit 0:1 - general_profile_space - * Bit 2 - general_tier_flag - * Bit 3:7 - general_profile_idc - * Bit 8:39 - gernal_profile_compatibility_flags - * Bit 40 - general_progressive_source_flag - * Bit 41 - general_interlaced_source_flag - * Bit 42 - general_non_packed_constraint_flag - * Bit 43 - general_frame_only_constraint_flag - * Bit 44:87 - general_reserved_zero_44bits - * Bit 88:95 - general_level_idc - * + * * Bit 0:1 - general_profile_space + * * Bit 2 - general_tier_flag + * * Bit 3:7 - general_profile_idc + * * Bit 8:39 - gernal_profile_compatibility_flags + * * Bit 40 - general_progressive_source_flag + * * Bit 41 - general_interlaced_source_flag + * * Bit 42 - general_non_packed_constraint_flag + * * Bit 43 - general_frame_only_constraint_flag + * * Bit 44:87 - general_reserved_zero_44bits + * * Bit 88:95 - general_level_idc * * Returns: The profile as a const string, or %NULL if there is an error. * diff --git a/gst-libs/gst/pbutils/descriptions.c b/gst-libs/gst/pbutils/descriptions.c index cdea6b790c..66b8316ec3 100644 --- a/gst-libs/gst/pbutils/descriptions.c +++ b/gst-libs/gst/pbutils/descriptions.c @@ -19,21 +19,18 @@ /** * SECTION:gstpbutilsdescriptions + * @title: Descriptions * @short_description: Provides human-readable descriptions for caps/codecs * and encoder, decoder, URI source and URI sink elements * - * - * * The above functions provide human-readable strings for media formats * and decoder/demuxer/depayloader/encoder/muxer/payloader elements for use * in error dialogs or other messages shown to users. - * - * + * * gst_pb_utils_add_codec_description_to_tag_list() is a utility function * for demuxer and decoder elements to add audio/video codec tags from a * given (fixed) #GstCaps. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/pbutils/encoding-profile.c b/gst-libs/gst/pbutils/encoding-profile.c index 63d8c1a4f1..0946b8472b 100644 --- a/gst-libs/gst/pbutils/encoding-profile.c +++ b/gst-libs/gst/pbutils/encoding-profile.c @@ -20,6 +20,7 @@ /** * SECTION:encoding-profile + * @title: GstEncodingProfile * @short_description: Encoding profile library * * Functions to create and handle encoding profiles. @@ -189,7 +190,6 @@ * return (GstEncodingProfile*) prof; *} * - * * ]| * * # Example: Using an encoder preset with a profile @@ -232,7 +232,6 @@ * return (GstEncodingProfile*) prof; *} * - * * ]| * * # Example: Listing categories, targets and profiles diff --git a/gst-libs/gst/pbutils/gstaudiovisualizer.c b/gst-libs/gst/pbutils/gstaudiovisualizer.c index 717c2bef47..364c9b00e3 100644 --- a/gst-libs/gst/pbutils/gstaudiovisualizer.c +++ b/gst-libs/gst/pbutils/gstaudiovisualizer.c @@ -21,6 +21,7 @@ */ /** * SECTION:gstaudiovisualizer + * @title: GstAudioVisualizer * * A baseclass for scopes (visualizers). It takes care of re-fitting the * audio-rate to video-rate and handles renegotiation (downstream video size diff --git a/gst-libs/gst/pbutils/gstdiscoverer.c b/gst-libs/gst/pbutils/gstdiscoverer.c index 090e39a913..5d742a66c2 100644 --- a/gst-libs/gst/pbutils/gstdiscoverer.c +++ b/gst-libs/gst/pbutils/gstdiscoverer.c @@ -20,6 +20,7 @@ /** * SECTION:gstdiscoverer + * @title: GstDiscoverer * @short_description: Utility for discovering information on URIs. * * The #GstDiscoverer is a utility object which allows to get as much diff --git a/gst-libs/gst/pbutils/gstpluginsbaseversion.c b/gst-libs/gst/pbutils/gstpluginsbaseversion.c index 48555eb2e7..3b6f9ea749 100644 --- a/gst-libs/gst/pbutils/gstpluginsbaseversion.c +++ b/gst-libs/gst/pbutils/gstpluginsbaseversion.c @@ -19,6 +19,7 @@ /** * SECTION:gstpluginsbaseversion + * @title: Version * @short_description: GStreamer gst-plugins-base libraries version macros. * * Use the GST_PLUGINS_BASE_VERSION_* macros e.g. to check what version of diff --git a/gst-libs/gst/pbutils/install-plugins.c b/gst-libs/gst/pbutils/install-plugins.c index 7f33ab4591..d3eb3687f4 100644 --- a/gst-libs/gst/pbutils/install-plugins.c +++ b/gst-libs/gst/pbutils/install-plugins.c @@ -20,334 +20,239 @@ /** * SECTION:gstpbutilsinstallplugins + * @title: Install-plugins * @short_description: Missing plugin installation support for applications * - * - * Overview - * + * ## Overview + * * Using this API, applications can request the installation of missing - * GStreamer plugins. These may be missing decoders/demuxers or encoders/muxers - * for a certain format, sources or sinks for a certain URI protocol - * (e.g. 'http'), or certain elements known by their element factory name - * ('audioresample'). - * - * + * GStreamer plugins. These may be missing decoders/demuxers or + * encoders/muxers for a certain format, sources or sinks for a certain URI + * protocol (e.g. 'http'), or certain elements known by their element + * factory name ('audioresample'). + * * Whether plugin installation is supported or not depends on the operating - * system and/or distribution in question. The vendor of the operating system - * needs to make sure the necessary hooks and mechanisms are in place for - * plugin installation to work. See below for more detailed information. - * - * - * From the application perspective, plugin installation is usually triggered - * either - * - * - * when the application itself has found that it wants or needs to install a - * certain element - * - * - * when the application has been notified by an element (such as playbin or - * decodebin) that one or more plugins are missing and - * the application has decided that it wants to install one or more of those - * missing plugins - * - * - * - * Detail Strings - * - * The install functions in this section all take one or more 'detail strings'. - * These detail strings contain information about the type of plugin that - * needs to be installed (decoder, encoder, source, sink, or named element), - * and some additional information such GStreamer version used and a - * human-readable description of the component to install for user dialogs. - * - * + * system and/or distribution in question. The vendor of the operating + * system needs to make sure the necessary hooks and mechanisms are in + * place for plugin installation to work. See below for more detailed + * information. + * + * From the application perspective, plugin installation is usually + * triggered either + * + * - when the application itself has found that it wants or needs to + * install a certain element + * - when the application has been notified by an element (such as + * playbin or decodebin) that one or more plugins are missing *and* the + * application has decided that it wants to install one or more of + * those missing plugins + * + * The install functions in this section all take one or more 'detail + * strings'. These detail strings contain information about the type of + * plugin that needs to be installed (decoder, encoder, source, sink, or + * named element), and some additional information such GStreamer version + * used and a human-readable description of the component to install for + * user dialogs. + * * Applications should not concern themselves with the composition of the - * string itself. They should regard the string as if it was a shared secret - * between GStreamer and the plugin installer application. - * - * + * string itself. They should regard the string as if it was a shared + * secret between GStreamer and the plugin installer application. + * * Detail strings can be obtained using the function - * gst_missing_plugin_message_get_installer_detail() on a missing-plugin - * message. Such a message will either have been found by the application on - * a pipeline's #GstBus, or the application will have created it itself using - * gst_missing_element_message_new(), gst_missing_decoder_message_new(), - * gst_missing_encoder_message_new(), gst_missing_uri_sink_message_new(), or + * gst_missing_plugin_message_get_installer_detail() on a + * missing-plugin message. Such a message will either have been found by + * the application on a pipeline's #GstBus, or the application will have + * created it itself using gst_missing_element_message_new(), + * gst_missing_decoder_message_new(), + * gst_missing_encoder_message_new(), + * gst_missing_uri_sink_message_new(), or * gst_missing_uri_source_message_new(). - * - * Plugin Installation from the Application Perspective - * - * For each GStreamer element/plugin/component that should be installed, the - * application needs one of those 'installer detail' string mentioned in the - * previous section. This string can be obtained, as already mentioned above, - * from a missing-plugin message using the function - * gst_missing_plugin_message_get_installer_detail(). The missing-plugin - * message is either posted by another element and then found on the bus - * by the application, or the application has created it itself as described - * above. - * - * + * + * For each GStreamer element/plugin/component that should be installed, + * the application needs one of those 'installer detail' string mentioned + * in the previous section. This string can be obtained, as already + * mentioned above, from a missing-plugin message using the function + * gst_missing_plugin_message_get_installer_detail(). The + * missing-plugin message is either posted by another element and then + * found on the bus by the application, or the application has created it + * itself as described above. + * * The application will then call gst_install_plugins_async(), passing a * NULL-terminated array of installer detail strings, and a function that * should be called when the installation of the plugins has finished * (successfully or not). Optionally, a #GstInstallPluginsContext created - * with gst_install_plugins_context_new() may be passed as well. This way - * additional optional arguments like the application window's XID can be - * passed to the external installer application. - * - * + * with gst_install_plugins_context_new() may be passed as well. This + * way additional optional arguments like the application window's XID can + * be passed to the external installer application. + * * gst_install_plugins_async() will return almost immediately, with the * return code indicating whether plugin installation was started or not. * If the necessary hooks for plugin installation are in place and an * external installer application has in fact been called, the passed in - * function will be called with a result code as soon as the external installer - * has finished. If the result code indicates that new plugins have been - * installed, the application will want to call gst_update_registry() so the - * run-time plugin registry is updated and the new plugins are made available - * to the application. - * - * A Gtk/GLib main loop must be running in order for the result function to - * be called when the external installer has finished. If this is not the case, - * make sure to regularly call - * - * g_main_context_iteration (NULL,FALSE); - * - * from your code. - * - * - * Plugin Installation from the Vendor/Distribution Perspective - * - * 1. Installer hook - * - * + * function will be called with a result code as soon as the external + * installer has finished. If the result code indicates that new plugins + * have been installed, the application will want to call + * gst_update_registry() so the run-time plugin registry is updated and + * the new plugins are made available to the application. + * + * > A Gtk/GLib main loop must be running in order for the result function + * > to be called when the external installer has finished. If this is not + * > the case, make sure to regularly call in your code: + * > + * > g_main_context_iteration (NULL,FALSE); + * + * ## 1. Installer hook + * * When GStreamer applications initiate plugin installation via - * gst_install_plugins_async() or gst_install_plugins_sync(), a pre-defined - * helper application will be called. - * - * + * gst_install_plugins_async() or gst_install_plugins_sync(), a + * pre-defined helper application will be called. + * * The exact path of the helper application to be called is set at compile - * time, usually by the ./configure script based on the - * install prefix. For a normal package build into the /usr - * prefix, this will usually default to - * /usr/libexec/gst-install-plugins-helper or - * /usr/lib/gst-install-plugins-helper. - * - * + * time, usually by the `./configure` script based on the install prefix. + * For a normal package build into the `/usr` prefix, this will usually + * default to `/usr/libexec/gst-install-plugins-helper` or + * `/usr/lib/gst-install-plugins-helper`. + * * Vendors/distros who want to support GStreamer plugin installation should - * either provide such a helper script/application or use the - * ./configure option - * --with-install-plugins-helper=/path/to/installer to - * make GStreamer call an installer of their own directly. - * - * - * It is strongly recommended that vendors provide a small helper application - * as interlocutor to the real installer though, even more so if command line - * argument munging is required to transform the command line arguments - * passed by GStreamer to the helper application into arguments that are - * understood by the real installer. - * - * + * either provide such a helper script/application or use the `./configure` + * option `--with-install-plugins-helper=/path/to/installer` to make + * GStreamer call an installer of their own directly. + * + * It is strongly recommended that vendors provide a small helper + * application as interlocutor to the real installer though, even more so + * if command line argument munging is required to transform the command + * line arguments passed by GStreamer to the helper application into + * arguments that are understood by the real installer. + * * The helper application path defined at compile time can be overriden at - * runtime by setting the GST_INSTALL_PLUGINS_HELPER - * environment variable. This can be useful for testing/debugging purposes. - * - * - * 2. Arguments passed to the install helper - * - * - * GStreamer will pass the following arguments to the install helper (this is - * in addition to the path of the executable itself, which is by convention - * argv[0]): - * - * - * none to many optional arguments in the form of - * --foo-bar=val. Example: - * --transient-for=XID where XID is the X Window ID of - * the main window of the calling application (so the installer can make - * itself transient to that window). Unknown optional arguments should - * be ignored by the installer. - * - * - * one 'installer detail string' argument for each plugin to be installed; - * these strings will have a gstreamer prefix; the - * exact format of the detail string is explained below - * - * - * - * - * 3. Detail string describing the missing plugin - * - * - * The string is in UTF-8 encoding and is made up of several fields, separated - * by '|' characters (but neither the first nor the last character is a '|'). - * The fields are: - * - * - * plugin system identifier, ie. "gstreamer" - * - * This identifier determines the format of the rest of the detail string. - * Automatic plugin installers should not process detail strings with - * unknown identifiers. This allows other plugin-based libraries to use - * the same mechanism for their automatic plugin installation needs, or - * for the format to be changed should it turn out to be insufficient. - * - * - * plugin system version, e.g. "0.10" - * - * This is required so that when there is a GStreamer-0.12 or GStreamer-1.0 - * at some point in future, the different major versions can still co-exist - * and use the same plugin install mechanism in the same way. - * - * - * application identifier, e.g. "totem" - * - * This may also be in the form of "pid/12345" if the program name can't - * be obtained for some reason. - * - * - * human-readable localised description of the required component, - * e.g. "Vorbis audio decoder" - * - * - * identifier string for the required component (see below for details about - * how to map this to the package/plugin that needs installing), e.g. - * - * - * urisource-$(PROTOCOL_REQUIRED), e.g. urisource-http or urisource-mms - * - * - * element-$(ELEMENT_REQUIRED), e.g. element-videoconvert - * - * - * decoder-$(CAPS_REQUIRED), e.g. (do read below for more details!): - * - * decoder-audio/x-vorbis - * decoder-application/ogg - * decoder-audio/mpeg, mpegversion=(int)4 - * decoder-video/mpeg, systemstream=(boolean)true, mpegversion=(int)2 - - * - * - * encoder-$(CAPS_REQUIRED), e.g. encoder-audio/x-vorbis - * - * - * - * - * optional further fields not yet specified - * - * - * - * - * An entire ID string might then look like this, for example: - * - * gstreamer|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis - * - * - * - * Plugin installers parsing this ID string should expect further fields also - * separated by '|' symbols and either ignore them, warn the user, or error - * out when encountering them. - * - * - * Those unfamiliar with the GStreamer 'caps' system should note a few things - * about the caps string used in the above decoder/encoder case: - * - * - * the first part ("video/mpeg") of the caps string is a GStreamer media - * type and not a MIME type. Wherever possible, the - * GStreamer media type will be the same as the corresponding MIME type, - * but often it is not. - * - * - * a caps string may or may not have additional comma-separated fields - * of various types (as seen in the examples above) - * - * - * the caps string of a 'required' component (as above) will always have - * fields with fixed values, whereas an introspected string (see below) - * may have fields with non-fixed values. Compare for example: - * - * - * audio/mpeg, mpegversion=(int)4 vs. - * audio/mpeg, mpegversion=(int){2, 4} - * - * - * video/mpeg, mpegversion=(int)2 vs. - * video/mpeg, systemstream=(boolean){ true, false}, mpegversion=(int)[1, 2] - * - * - * - * - * - * - * 4. Exit codes the installer should return - * - * - * The installer should return one of the following exit codes when it exits: - * - * - * 0 if all of the requested plugins could be installed + * runtime by setting the GST_INSTALL_PLUGINS_HELPER environment + * variable. This can be useful for testing/debugging purposes. + * + * ## 2. Arguments passed to the install helper + * + * GStreamer will pass the following arguments to the install helper (this + * is in addition to the path of the executable itself, which is by + * convention argv[0]): + * + * - none to many optional arguments in the form of `--foo-bar=val`. + * Example: `--transient-for=XID` where XID is the X Window ID of the + * main window of the calling application (so the installer can make + * itself transient to that window). Unknown optional arguments should + * be ignored by the installer. + * + * - one 'installer detail string' argument for each plugin to be + * installed; these strings will have a `gstreamer` prefix; the exact + * format of the detail string is explained below + * + * ## 3. Detail string describing the missing plugin + * + * The string is in UTF-8 encoding and is made up of several fields, + * separated by '|' characters (but neither the first nor the last + * character is a '|'). The fields are: + * + * - plugin system identifier, ie. "gstreamer" + * This identifier determines the format of the rest of the detail + * string. Automatic plugin installers should not process detail + * strings with unknown identifiers. This allows other plugin-based + * libraries to use the same mechanism for their automatic plugin + * installation needs, or for the format to be changed should it turn + * out to be insufficient. + * - plugin system version, e.g. "0.10" + * This is required so that when there is a GStreamer-0.12 or + * GStreamer-1.0 at some point in future, the different major versions + * can still co-exist and use the same plugin install mechanism in the + * same way. + * - application identifier, e.g. "totem" + * This may also be in the form of "pid/12345" if the program name + * can't be obtained for some reason. + * - human-readable localised description of the required component, e.g. + * "Vorbis audio decoder" + * - identifier string for the required component (see below for details + * about how to map this to the package/plugin that needs installing), + * e.g. + * - urisource-$(PROTOCOL_REQUIRED), e.g. urisource-http or + * urisource-mms + * - element-$(ELEMENT_REQUIRED), e.g. element-videoconvert + * - decoder-$(CAPS_REQUIRED), e.g. (do read below for more + * details!): + * - decoder-audio/x-vorbis + * - decoder-application/ogg + * - decoder-audio/mpeg, mpegversion=(int)4 + * - decoder-video/mpeg, systemstream=(boolean)true, + * mpegversion=(int)2 + * - encoder-$(CAPS_REQUIRED), e.g. encoder-audio/x-vorbis + * - optional further fields not yet specified + * + * An entire ID string might then look like this, for example: ` + * gstreamer|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis` + * + * Plugin installers parsing this ID string should expect further fields + * also separated by '|' symbols and either ignore them, warn the user, or + * error out when encountering them. + * + * Those unfamiliar with the GStreamer 'caps' system should note a few + * things about the caps string used in the above decoder/encoder case: + * + * - the first part ("video/mpeg") of the caps string is a GStreamer + * media type and *not* a MIME type. Wherever possible, the GStreamer + * media type will be the same as the corresponding MIME type, but + * often it is not. + * - a caps string may or may not have additional comma-separated fields + * of various types (as seen in the examples above) + * - the caps string of a 'required' component (as above) will always + * have fields with fixed values, whereas an introspected string (see + * below) may have fields with non-fixed values. Compare for example: + * - `audio/mpeg, mpegversion=(int)4` vs. + * `audio/mpeg, mpegversion=(int){2, 4}` + * - `video/mpeg, mpegversion=(int)2` vs. + * `video/mpeg, systemstream=(boolean){ true, false}, mpegversion=(int)[1, 2]` + * + * ## 4. Exit codes the installer should return + * + * The installer should return one of the following exit codes when it + * exits: + * + * - 0 if all of the requested plugins could be installed * (#GST_INSTALL_PLUGINS_SUCCESS) - * - * - * 1 if no appropriate installation candidate for any of the requested - * plugins could be found. Only return this if nothing has been installed - * (#GST_INSTALL_PLUGINS_NOT_FOUND) - * - * - * 2 if an error occured during the installation. The application will + * - 1 if no appropriate installation candidate for any of the requested + * plugins could be found. Only return this if nothing has been + * installed (#GST_INSTALL_PLUGINS_NOT_FOUND) + * - 2 if an error occured during the installation. The application will * assume that the user will already have seen an error message by the * installer in this case and will usually not show another one * (#GST_INSTALL_PLUGINS_ERROR) - * - * - * 3 if some of the requested plugins could be installed, but not all + * - 3 if some of the requested plugins could be installed, but not all * (#GST_INSTALL_PLUGINS_PARTIAL_SUCCESS) - * - * - * 4 if the user aborted the installation (#GST_INSTALL_PLUGINS_USER_ABORT) - * - * - * - * - * 5. How to map the required detail string to packages - * - * + * - 4 if the user aborted the installation + * (#GST_INSTALL_PLUGINS_USER_ABORT) + * + * ## 5. How to map the required detail string to packages + * * It is up to the vendor to find mechanism to map required components from * the detail string to the actual packages/plugins to install. This could - * be a hardcoded list of mappings, for example, or be part of the packaging - * system metadata. - * - * + * be a hardcoded list of mappings, for example, or be part of the + * packaging system metadata. + * * GStreamer plugin files can be introspected for this information. The - * gst-inspect utility has a special command line option - * that will output information similar to what is required. For example - * + * `gst-inspect` utility has a special command line option that will output + * information similar to what is required. For example ` * $ gst-inspect-1.0 --print-plugin-auto-install-info /path/to/libgstvorbis.so - * * should output something along the lines of - * - * decoder-audio/x-vorbis - * element-vorbisdec - * element-vorbisenc - * element-vorbisparse - * element-vorbistag - * encoder-audio/x-vorbis - * - * Note that in the encoder and decoder case the introspected caps can be more - * complex with additional fields, e.g. - * audio/mpeg,mpegversion=(int){2,4}, so they will not - * always exactly match the caps wanted by the application. It is up to the - * installer to deal with this (either by doing proper caps intersection using - * the GStreamer #GstCaps API, or by only taking into account the media type). - * - * + * `decoder-audio/x-vorbis`, `element-vorbisdec` `element-vorbisenc` + * `element-vorbisparse`, `element-vorbistag`, `encoder-audio/x-vorbis` + * + * Note that in the encoder and decoder case the introspected caps can be + * more complex with additional fields, e.g. + * `audio/mpeg,mpegversion=(int){2,4}`, so they will not always exactly + * match the caps wanted by the application. It is up to the installer to + * deal with this (either by doing proper caps intersection using the + * GStreamer #GstCaps API, or by only taking into account the media type). + * * Another potential source of problems are plugins such as ladspa or * libvisual where the list of elements depends on the installed - * ladspa/libvisual plugins at the time. This is also up to the distribution - * to handle (but usually not relevant for playback applications). - * - * + * ladspa/libvisual plugins at the time. This is also up to the + * distribution to handle (but usually not relevant for playback + * applications). */ #ifdef HAVE_CONFIG_H @@ -455,11 +360,11 @@ gst_install_plugins_context_set_desktop_id (GstInstallPluginsContext * ctx, * * GTK+/GNOME applications should be able to create a startup notification ID * like this: - * + * |[ * timestamp = gtk_get_current_event_time (); * startup_id = g_strdup_printf ("_TIME%u", timestamp); * ... - * + * ]| * * Since: 1.6 */ @@ -487,7 +392,7 @@ void gst_install_plugins_context_set_startup_notification_id * * Gtk+/Gnome application should be able to obtain the XID of the top-level * window like this: - * + * |[ * ##include <gtk/gtk.h> * ##ifdef GDK_WINDOWING_X11 * ##include <gdk/gdkx.h> @@ -497,7 +402,8 @@ void gst_install_plugins_context_set_startup_notification_id * xid = GDK_WINDOW_XWINDOW (GTK_WIDGET (application_window)->window); * ##endif * ... - * + * ]| + * */ void gst_install_plugins_context_set_xid (GstInstallPluginsContext * ctx, guint xid) @@ -699,7 +605,7 @@ gst_install_plugins_installer_exited (GPid pid, gint status, gpointer data) * @ctx: (allow-none): a #GstInstallPluginsContext, or NULL * @func: (scope async): the function to call when the installer program returns * @user_data: (closure): the user data to pass to @func when called, or NULL - * + * * Requests plugin installation without blocking. Once the plugins have been * installed or installation has failed, @func will be called with the result * of the installation and your provided @user_data pointer. @@ -756,7 +662,7 @@ gst_install_plugins_async (const gchar * const *details, * @details: (array zero-terminated=1) (transfer none): NULL-terminated array * of installer string details * @ctx: (allow-none): a #GstInstallPluginsContext, or NULL - * + * * Requests plugin installation and block until the plugins have been * installed or installation has failed. * @@ -793,7 +699,7 @@ gst_install_plugins_sync (const gchar * const *details, /** * gst_install_plugins_return_get_name: * @ret: the return status code - * + * * Convenience function to return the descriptive string associated * with a status code. This function returns English strings and * should not be used for user messages. It is here only to assist @@ -835,7 +741,7 @@ gst_install_plugins_return_get_name (GstInstallPluginsReturn ret) /** * gst_install_plugins_installation_in_progress: - * + * * Checks whether plugin installation (initiated by this application only) * is currently in progress. * @@ -849,7 +755,7 @@ gst_install_plugins_installation_in_progress (void) /** * gst_install_plugins_supported: - * + * * Checks whether plugin installation is likely to be supported by the * current environment. This currently only checks whether the helper script * that is to be provided by the distribution or operating system vendor diff --git a/gst-libs/gst/pbutils/missing-plugins.c b/gst-libs/gst/pbutils/missing-plugins.c index 1228896b06..a08803b18e 100644 --- a/gst-libs/gst/pbutils/missing-plugins.c +++ b/gst-libs/gst/pbutils/missing-plugins.c @@ -19,35 +19,27 @@ /** * SECTION:gstpbutilsmissingplugins + * @title: Missing plugins * @short_description: Create, recognise and parse missing-plugins messages * - * - * * Functions to create, recognise and parse missing-plugins messages for * applications and elements. - * - * + * * Missing-plugin messages are posted on the bus by elements like decodebin * or playbin if they can't find an appropriate source element or decoder * element. The application can use these messages for two things: - * - * - * concise error/problem reporting to the user mentioning what exactly + * + * * concise error/problem reporting to the user mentioning what exactly * is missing, see gst_missing_plugin_message_get_description() - * - * - * initiate installation of missing plugins, see + * + * * initiate installation of missing plugins, see * gst_missing_plugin_message_get_installer_detail() and * gst_install_plugins_async() - * - * - * - * + * * Applications may also create missing-plugin messages themselves to install * required elements that are missing, using the install mechanism mentioned * above. - * - * + * */ #ifdef HAVE_CONFIG_H @@ -397,7 +389,7 @@ missing_structure_get_caps_detail (const GstStructure * s, GstCaps ** p_caps) * Returns an opaque string containing all the details about the missing * element to be passed to an external installer called via * gst_install_plugins_async() or gst_install_plugins_sync(). - * + * * This function is mainly for applications that call external plugin * installation mechanisms using one of the two above-mentioned functions. * @@ -653,7 +645,7 @@ gst_installer_detail_new (gchar * description, const gchar * type, * Returns an opaque string containing all the details about the missing * element to be passed to an external installer called via * gst_install_plugins_async() or gst_install_plugins_sync(). - * + * * This function is mainly for applications that call external plugin * installation mechanisms using one of the two above-mentioned functions in * the case where the application knows exactly what kind of plugin it is @@ -681,7 +673,7 @@ gst_missing_uri_source_installer_detail_new (const gchar * protocol) * Returns an opaque string containing all the details about the missing * element to be passed to an external installer called via * gst_install_plugins_async() or gst_install_plugins_sync(). - * + * * This function is mainly for applications that call external plugin * installation mechanisms using one of the two above-mentioned functions in * the case where the application knows exactly what kind of plugin it is @@ -709,7 +701,7 @@ gst_missing_uri_sink_installer_detail_new (const gchar * protocol) * Returns an opaque string containing all the details about the missing * element to be passed to an external installer called via * gst_install_plugins_async() or gst_install_plugins_sync(). - * + * * This function is mainly for applications that call external plugin * installation mechanisms using one of the two above-mentioned functions in * the case where the application knows exactly what kind of plugin it is @@ -736,7 +728,7 @@ gst_missing_element_installer_detail_new (const gchar * factory_name) * Returns an opaque string containing all the details about the missing * element to be passed to an external installer called via * gst_install_plugins_async() or gst_install_plugins_sync(). - * + * * This function is mainly for applications that call external plugin * installation mechanisms using one of the two above-mentioned functions in * the case where the application knows exactly what kind of plugin it is @@ -774,7 +766,7 @@ gst_missing_decoder_installer_detail_new (const GstCaps * decode_caps) * Returns an opaque string containing all the details about the missing * element to be passed to an external installer called via * gst_install_plugins_async() or gst_install_plugins_sync(). - * + * * This function is mainly for applications that call external plugin * installation mechanisms using one of the two above-mentioned functions in * the case where the application knows exactly what kind of plugin it is diff --git a/gst-libs/gst/pbutils/pbutils.c b/gst-libs/gst/pbutils/pbutils.c index 989dad62fd..e2271ec25c 100644 --- a/gst-libs/gst/pbutils/pbutils.c +++ b/gst-libs/gst/pbutils/pbutils.c @@ -19,53 +19,37 @@ /** * SECTION:gstpbutils + * @title: Pbutils * @short_description: General Application and Plugin Utility Library * - * - * * libgstpbutils is a general utility library for plugins and applications. * It currently provides the * following: - * - * - * - * - * human-readable description strings of codecs, elements, sources, decoders, + * + * * human-readable description strings of codecs, elements, sources, decoders, * encoders, or sinks from decoder/encoder caps, element names, or protocol * names. - * - * - * - * - * support for applications to initiate installation of missing plugins (if + * + * * support for applications to initiate installation of missing plugins (if * this is supported by the distribution or operating system used) - * - * - * - * - * API for GStreamer elements to create missing-plugin messages in order to + * + * * API for GStreamer elements to create missing-plugin messages in order to * communicate to the application that a certain type of plugin is missing * (decoder, encoder, URI protocol source, URI protocol sink, named element) - * - * - * - * - * API for applications to recognise and handle missing-plugin messages - * - * - * - * Linking to this library - * + * + * * API for applications to recognise and handle missing-plugin messages + * + * ## Linking to this library + * * You should obtain the required CFLAGS and LIBS using pkg-config on the * gstreamer-plugins-base-0.10 module. You will then also need to add * '-lgstpbutils-0.10' manually to your LIBS line. - * - * Library initialisation - * + * + * ## Library initialisation + * * Before using any of its functions, applications and plugins must call * gst_pb_utils_init() to initialise the library. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/riff/riff-read.c b/gst-libs/gst/riff/riff-read.c index 5a54029773..4972979fe0 100644 --- a/gst-libs/gst/riff/riff-read.c +++ b/gst-libs/gst/riff/riff-read.c @@ -362,7 +362,7 @@ too_small: * containing extradata for this particular stream (e.g. * palette, codec initialization data). * - * Parses a video stream´s strf structure plus optionally some + * Parses a video stream's strf structure plus optionally some * extradata from input data. This function takes ownership of @buf. * * Returns: TRUE if parsing succeeded, otherwise FALSE. The stream @@ -460,7 +460,7 @@ too_small: * containing extradata for this particular stream (e.g. * codec initialization data). * - * Parses an audio stream´s strf structure plus optionally some + * Parses an audio stream's strf structure plus optionally some * extradata from input data. This function takes ownership of @buf. * use. * diff --git a/gst-libs/gst/riff/riff.c b/gst-libs/gst/riff/riff.c index 70da254c89..af388d396d 100644 --- a/gst-libs/gst/riff/riff.c +++ b/gst-libs/gst/riff/riff.c @@ -20,6 +20,7 @@ */ /** * SECTION:gstriff + * @title: Riff utilities * @short_description: Riff fileformat utillity functions. * * A collection of functions to handle riff base files, such as avi, wav and diff --git a/gst-libs/gst/rtp/gstrtcpbuffer.c b/gst-libs/gst/rtp/gstrtcpbuffer.c index e540576c83..29057e3ff7 100644 --- a/gst-libs/gst/rtp/gstrtcpbuffer.c +++ b/gst-libs/gst/rtp/gstrtcpbuffer.c @@ -22,24 +22,21 @@ /** * SECTION:gstrtcpbuffer + * @title: GstRTCPBuffer * @short_description: Helper methods for dealing with RTCP buffers * @see_also: #GstRTPBasePayload, #GstRTPBaseDepayload, #gstrtpbuffer * * Note: The API in this module is not yet declared stable. * - * - * - * The GstRTPCBuffer helper functions makes it easy to parse and create regular + * The GstRTPCBuffer helper functions makes it easy to parse and create regular * #GstBuffer objects that contain compound RTCP packets. These buffers are typically * of 'application/x-rtcp' #GstCaps. - * - * + * * An RTCP buffer consists of 1 or more #GstRTCPPacket structures that you can * retrieve with gst_rtcp_buffer_get_first_packet(). #GstRTCPPacket acts as a pointer * into the RTCP buffer; you can move to the next packet with * gst_rtcp_packet_move_to_next(). - * - * + * */ #include @@ -497,7 +494,7 @@ end: * @type: the #GstRTCPType of the new packet * @packet: pointer to new packet * - * Add a new packet of @type to @rtcp. @packet will point to the newly created + * Add a new packet of @type to @rtcp. @packet will point to the newly created * packet. * * Returns: %TRUE if the packet could be created. This function returns %FALSE @@ -677,7 +674,7 @@ gst_rtcp_packet_get_count (GstRTCPPacket * packet) * gst_rtcp_packet_get_length: * @packet: a valid #GstRTCPPacket * - * Get the length field of @packet. This is the length of the packet in + * Get the length field of @packet. This is the length of the packet in * 32-bit words minus one. * * Returns: The length field of @packet. @@ -737,7 +734,7 @@ gst_rtcp_packet_sr_get_sender_info (GstRTCPPacket * packet, guint32 * ssrc, /** * gst_rtcp_packet_sr_set_sender_info: * @packet: a valid SR #GstRTCPPacket - * @ssrc: the SSRC + * @ssrc: the SSRC * @ntptime: the NTP time * @rtptime: the RTP time * @packet_count: the packet count diff --git a/gst-libs/gst/rtp/gstrtpbaseaudiopayload.c b/gst-libs/gst/rtp/gstrtpbaseaudiopayload.c index 917aeae6f3..e5b1d7edac 100644 --- a/gst-libs/gst/rtp/gstrtpbaseaudiopayload.c +++ b/gst-libs/gst/rtp/gstrtpbaseaudiopayload.c @@ -19,6 +19,7 @@ /** * SECTION:gstrtpbaseaudiopayload + * @title: GstRTPBaseAudioPayload * @short_description: Base class for audio RTP payloader * * Provides a base class for audio RTP payloaders for frame or sample based @@ -36,9 +37,8 @@ * sent in a last RTP packet. In the case of frame based codecs, the resulting * RTP packets always contain full frames. * - * - * Usage - * + * ## Usage + * * To use this base class, your child element needs to call either * gst_rtp_base_audio_payload_set_frame_based() or * gst_rtp_base_audio_payload_set_sample_based(). This is usually done in the @@ -50,8 +50,7 @@ * must set any variables or call/override any functions required by that base * class. The child element does not need to override any other functions * specific to GstRTPBaseAudioPayload. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/rtp/gstrtpbasedepayload.c b/gst-libs/gst/rtp/gstrtpbasedepayload.c index b95e8130ff..8773cee294 100644 --- a/gst-libs/gst/rtp/gstrtpbasedepayload.c +++ b/gst-libs/gst/rtp/gstrtpbasedepayload.c @@ -20,6 +20,7 @@ /** * SECTION:gstrtpbasedepayload + * @title: GstRTPBaseDepayload * @short_description: Base class for RTP depayloader * * Provides a base class for RTP depayloaders @@ -150,55 +151,17 @@ gst_rtp_base_depayload_class_init (GstRTPBaseDepayloadClass * klass) * application/x-rtp-depayload-stats containing the following fields relating to * the last processed buffer and current state of the stream being depayloaded: * - * - * - * clock-rate - * #G_TYPE_UINT, clock-rate of the - * stream - * - * - * npt-start - * #G_TYPE_UINT64, time of playback start - * - * - * - * npt-stop - * #G_TYPE_UINT64, time of playback stop - * - * - * - * play-speed - * #G_TYPE_DOUBLE, the playback speed - * - * - * - * play-scale - * #G_TYPE_DOUBLE, the playback scale - * - * - * - * running-time-dts - * #G_TYPE_UINT64, the last running-time of the + * * `clock-rate`: #G_TYPE_UINT, clock-rate of the stream + * * `npt-start`: #G_TYPE_UINT64, time of playback start + * * `npt-stop`: #G_TYPE_UINT64, time of playback stop + * * `play-speed`: #G_TYPE_DOUBLE, the playback speed + * * `play-scale`: #G_TYPE_DOUBLE, the playback scale + * * `running-time-dts`: #G_TYPE_UINT64, the last running-time of the * last DTS - * - * - * - * running-time-pts - * #G_TYPE_UINT64, the last running-time of the + * * `running-time-pts`: #G_TYPE_UINT64, the last running-time of the * last PTS - * - * - * - * seqnum - * #G_TYPE_UINT, the last seen seqnum - * - * - * - * timestamp - * #G_TYPE_UINT, the last seen RTP timestamp - * - * - * + * * `seqnum`: #G_TYPE_UINT, the last seen seqnum + * * `timestamp`: #G_TYPE_UINT, the last seen RTP timestamp **/ g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_STATS, g_param_spec_boxed ("stats", "Statistics", "Various statistics", diff --git a/gst-libs/gst/rtp/gstrtpbasepayload.c b/gst-libs/gst/rtp/gstrtpbasepayload.c index 39a44b46fc..b411af0b89 100644 --- a/gst-libs/gst/rtp/gstrtpbasepayload.c +++ b/gst-libs/gst/rtp/gstrtpbasepayload.c @@ -14,6 +14,7 @@ /** * SECTION:gstrtpbasepayload + * @title: GstRTPBasePayload * @short_description: Base class for RTP payloader * * Provides a base class for RTP payloaders @@ -275,48 +276,14 @@ gst_rtp_base_payload_class_init (GstRTPBasePayloadClass * klass) * application/x-rtp-payload-stats containing the following fields relating to * the last processed buffer and current state of the stream being payloaded: * - * - * - * clock-rate - * #G_TYPE_UINT, clock-rate of the - * stream - * - * - * running-time - * #G_TYPE_UINT64, running time - * - * - * - * seqnum - * #G_TYPE_UINT, sequence number, same as - * #GstRTPBasePayload:seqnum - * - * - * timestamp - * #G_TYPE_UINT, RTP timestamp, same as - * #GstRTPBasePayload:timestamp - * - * - * ssrc - * #G_TYPE_UINT, The SSRC in use - * - * - * - * pt - * #G_TYPE_UINT, The Payload type in use, same as - * #GstRTPBasePayload:pt - * - * - * seqnum-offset - * #G_TYPE_UINT, The current offset added to the - * seqnum - * - * - * timestamp-offset - * #G_TYPE_UINT, The current offset added to the - * timestamp - * - * + * * `clock-rate` :#G_TYPE_UINT, clock-rate of the stream + * * `running-time` :#G_TYPE_UINT64, running time + * * `seqnum` :#G_TYPE_UINT, sequence number, same as #GstRTPBasePayload:seqnum + * * `timestamp` :#G_TYPE_UINT, RTP timestamp, same as #GstRTPBasePayload:timestamp + * * `ssrc` :#G_TYPE_UINT, The SSRC in use + * * `pt` :#G_TYPE_UINT, The Payload type in use, same as #GstRTPBasePayload:pt + * * `seqnum-offset` :#G_TYPE_UINT, The current offset added to the seqnum + * * `timestamp-offset` :#G_TYPE_UINT, The current offset added to the timestamp **/ g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_STATS, g_param_spec_boxed ("stats", "Statistics", "Various statistics", diff --git a/gst-libs/gst/rtp/gstrtpbuffer.c b/gst-libs/gst/rtp/gstrtpbuffer.c index 9cb3e8ba78..d79403cb25 100644 --- a/gst-libs/gst/rtp/gstrtpbuffer.c +++ b/gst-libs/gst/rtp/gstrtpbuffer.c @@ -20,16 +20,14 @@ /** * SECTION:gstrtpbuffer + * @title: GstRTPBuffer * @short_description: Helper methods for dealing with RTP buffers * @see_also: #GstRTPBasePayload, #GstRTPBaseDepayload, gstrtcpbuffer * - * - * - * The GstRTPBuffer helper functions makes it easy to parse and create regular + * The GstRTPBuffer helper functions makes it easy to parse and create regular * #GstBuffer objects that contain RTP payloads. These buffers are typically of * 'application/x-rtp' #GstCaps. - * - * + * */ #include "gstrtpbuffer.h" @@ -658,7 +656,7 @@ gst_rtp_buffer_pad_to (GstRTPBuffer * rtp, guint len) * @rtp: the RTP packet * * Check if the extension bit is set on the RTP packet in @buffer. - * + * * Returns: TRUE if @buffer has the extension bit set. */ gboolean @@ -693,7 +691,7 @@ gst_rtp_buffer_set_extension (GstRTPBuffer * rtp, gboolean extension) * * If @buffer did not contain an extension, this function will return %FALSE * with @bits, @data and @wordlen unchanged. - * + * * Returns: TRUE if @buffer had the extension bit set. */ gboolean @@ -891,7 +889,7 @@ gst_rtp_buffer_set_extension_data (GstRTPBuffer * rtp, guint16 bits, * @rtp: the RTP packet * * Get the SSRC of the RTP packet in @buffer. - * + * * Returns: the SSRC of @buffer in host order. */ guint32 @@ -918,7 +916,7 @@ gst_rtp_buffer_set_ssrc (GstRTPBuffer * rtp, guint32 ssrc) * @rtp: the RTP packet * * Get the CSRC count of the RTP packet in @buffer. - * + * * Returns: the CSRC count of @buffer. */ guint8 @@ -933,7 +931,7 @@ gst_rtp_buffer_get_csrc_count (GstRTPBuffer * rtp) * @idx: the index of the CSRC to get * * Get the CSRC at index @idx in @buffer. - * + * * Returns: the CSRC at index @idx in host order. */ guint32 diff --git a/gst-libs/gst/rtp/gstrtphdrext.c b/gst-libs/gst/rtp/gstrtphdrext.c index 0b9174a76c..290805b63e 100644 --- a/gst-libs/gst/rtp/gstrtphdrext.c +++ b/gst-libs/gst/rtp/gstrtphdrext.c @@ -19,13 +19,10 @@ /** * SECTION:gstrtphdrext + * @title: GstRtphdrext * @short_description: Helper methods for dealing with RTP header extensions * @see_also: #GstRTPBasePayload, #GstRTPBaseDepayload, gstrtpbuffer * - * - * - * - * */ #include "gstrtphdrext.h" diff --git a/gst-libs/gst/rtp/gstrtppayloads.c b/gst-libs/gst/rtp/gstrtppayloads.c index 4a38f808c6..702cceb20f 100644 --- a/gst-libs/gst/rtp/gstrtppayloads.c +++ b/gst-libs/gst/rtp/gstrtppayloads.c @@ -22,16 +22,14 @@ /** * SECTION:gstrtppayloads + * @title: GstRTPPayloadInfo * @short_description: Helper methods for dealing with RTP payloads * @see_also: gstrtpbuffer * - * - * * The GstRTPPayloads helper functions makes it easy to deal with static and dynamic - * payloads. Its main purpose is to retrieve properties such as the default clock-rate + * payloads. Its main purpose is to retrieve properties such as the default clock-rate * and get session bandwidth information. - * - * + * */ #include diff --git a/gst-libs/gst/rtp/gstrtppayloads.h b/gst-libs/gst/rtp/gstrtppayloads.h index 11d7df763f..0ae5a83dd8 100644 --- a/gst-libs/gst/rtp/gstrtppayloads.h +++ b/gst-libs/gst/rtp/gstrtppayloads.h @@ -56,7 +56,6 @@ G_BEGIN_DECLS * @GST_RTP_PAYLOAD_MP2T: MPEG-2 transport stream (RFC 2250) * @GST_RTP_PAYLOAD_H263: Video H263 (RFC 2190) * - * * Standard predefined fixed payload types. * * The official list is at: diff --git a/gst-libs/gst/rtsp/gstrtspconnection.c b/gst-libs/gst/rtsp/gstrtspconnection.c index 5f3c8ba400..484f2c4101 100644 --- a/gst-libs/gst/rtsp/gstrtspconnection.c +++ b/gst-libs/gst/rtsp/gstrtspconnection.c @@ -42,6 +42,7 @@ /** * SECTION:gstrtspconnection + * @title: GstRTSPConnection * @short_description: manage RTSP connections * @see_also: gstrtspurl * diff --git a/gst-libs/gst/rtsp/gstrtspdefs.c b/gst-libs/gst/rtsp/gstrtspdefs.c index fa1fd05800..09d40d0cc0 100644 --- a/gst-libs/gst/rtsp/gstrtspdefs.c +++ b/gst-libs/gst/rtsp/gstrtspdefs.c @@ -42,10 +42,11 @@ /** * SECTION:gstrtspdefs + * @title: GstRtspdefs * @short_description: common RTSP defines * @see_also: gstrtspurl, gstrtspconnection - * - * Provides common defines for the RTSP library. + * + * Provides common defines for the RTSP library. */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/rtsp/gstrtspextension.c b/gst-libs/gst/rtsp/gstrtspextension.c index e178bc2085..86f7da5215 100644 --- a/gst-libs/gst/rtsp/gstrtspextension.c +++ b/gst-libs/gst/rtsp/gstrtspextension.c @@ -21,14 +21,12 @@ /** * SECTION:gstrtspextension + * @title: GstRTSPExtension * @short_description: Interface for extending RTSP protocols * - * - * * This interface is implemented e.g. by the Windows Media Streaming RTSP * exentension (rtspwms) and the RealMedia RTSP extension (rtspreal). - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/rtsp/gstrtspmessage.c b/gst-libs/gst/rtsp/gstrtspmessage.c index 06b6f2353b..1ff3b10297 100644 --- a/gst-libs/gst/rtsp/gstrtspmessage.c +++ b/gst-libs/gst/rtsp/gstrtspmessage.c @@ -44,9 +44,10 @@ /** * SECTION:gstrtspmessage + * @title: GstRTSPMessage * @short_description: RTSP messages * @see_also: gstrtspconnection - * + * * Provides methods for creating and parsing request, response and data messages. */ @@ -429,7 +430,7 @@ gst_rtsp_message_parse_data (GstRTSPMessage * msg, guint8 * channel) * @msg: a #GstRTSPMessage * * Unset the contents of @msg so that it becomes an uninitialized - * #GstRTSPMessage again. This function is mostly used in combination with + * #GstRTSPMessage again. This function is mostly used in combination with * gst_rtsp_message_init_request(), gst_rtsp_message_init_response() and * gst_rtsp_message_init_data() on stack allocated #GstRTSPMessage structures. * diff --git a/gst-libs/gst/rtsp/gstrtsprange.c b/gst-libs/gst/rtsp/gstrtsprange.c index 553f797653..33be288627 100644 --- a/gst-libs/gst/rtsp/gstrtsprange.c +++ b/gst-libs/gst/rtsp/gstrtsprange.c @@ -42,8 +42,9 @@ /** * SECTION:gstrtsprange + * @title: GstRTSPTimeRange * @short_description: dealing with time ranges - * + * * Provides helper functions to deal with time ranges. */ diff --git a/gst-libs/gst/rtsp/gstrtsptransport.c b/gst-libs/gst/rtsp/gstrtsptransport.c index 6d99f1c0f0..fa5393e7d6 100644 --- a/gst-libs/gst/rtsp/gstrtsptransport.c +++ b/gst-libs/gst/rtsp/gstrtsptransport.c @@ -43,8 +43,9 @@ /** * SECTION:gstrtsptransport + * @title: GstRTSPRange * @short_description: dealing with RTSP transports - * + * * Provides helper functions to deal with RTSP transport strings. */ @@ -146,7 +147,7 @@ G_STMT_START { \ * Allocate a new initialized #GstRTSPTransport. Use gst_rtsp_transport_free() * after usage. * - * Returns: a #GstRTSPResult. + * Returns: a #GstRTSPResult. */ GstRTSPResult gst_rtsp_transport_new (GstRTSPTransport ** transport) @@ -168,7 +169,7 @@ gst_rtsp_transport_new (GstRTSPTransport ** transport) * * Initialize @transport so that it can be used. * - * Returns: #GST_RTSP_OK. + * Returns: #GST_RTSP_OK. */ GstRTSPResult gst_rtsp_transport_init (GstRTSPTransport * transport) @@ -284,7 +285,7 @@ get_default_lower_trans (GstRTSPTransport * transport) * @manager will contain an element name or #NULL when no manager is * needed/available for @trans. * - * Returns: #GST_RTSP_OK. + * Returns: #GST_RTSP_OK. */ GstRTSPResult gst_rtsp_transport_get_manager (GstRTSPTransMode trans, const gchar ** manager, diff --git a/gst-libs/gst/rtsp/gstrtspurl.c b/gst-libs/gst/rtsp/gstrtspurl.c index 0acd3d79ab..12be279417 100644 --- a/gst-libs/gst/rtsp/gstrtspurl.c +++ b/gst-libs/gst/rtsp/gstrtspurl.c @@ -42,8 +42,9 @@ /** * SECTION:gstrtspurl + * @title: GstRTSPUrl * @short_description: handling RTSP urls - * + * * Provides helper functions to handle RTSP urls. */ @@ -308,7 +309,7 @@ gst_rtsp_url_get_port (const GstRTSPUrl * url, guint16 * port) * gst_rtsp_url_get_request_uri: * @url: a #GstRTSPUrl * - * Get a newly allocated string describing the request URI for @url. + * Get a newly allocated string describing the request URI for @url. * * Returns: a string with the request URI. g_free() after usage. */ diff --git a/gst-libs/gst/sdp/gstmikey.c b/gst-libs/gst/sdp/gstmikey.c index 95529d1b7a..3e999512d9 100644 --- a/gst-libs/gst/sdp/gstmikey.c +++ b/gst-libs/gst/sdp/gstmikey.c @@ -21,14 +21,11 @@ /** * SECTION:gstmikey + * @title: GstMIKEYMessage * @short_description: Helper methods for dealing with MIKEY messages * - * - * * The GstMIKEY helper functions makes it easy to parse and create MIKEY * messages. - * - * * * Since: 1.4 */ diff --git a/gst-libs/gst/sdp/gstsdpmessage.c b/gst-libs/gst/sdp/gstsdpmessage.c index 653d540a12..c3a11ad888 100644 --- a/gst-libs/gst/sdp/gstsdpmessage.c +++ b/gst-libs/gst/sdp/gstsdpmessage.c @@ -42,14 +42,12 @@ /** * SECTION:gstsdpmessage + * @title: GstSDPMessage * @short_description: Helper methods for dealing with SDP messages * - * - * * The GstSDPMessage helper functions makes it easy to parse and create SDP * messages. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/tag/gstexiftag.c b/gst-libs/gst/tag/gstexiftag.c index bcdcdde1ea..b615779be6 100644 --- a/gst-libs/gst/tag/gstexiftag.c +++ b/gst-libs/gst/tag/gstexiftag.c @@ -21,6 +21,7 @@ /** * SECTION:gsttagexif + * @title: GstExiftag * @short_description: tag mappings and support functions for plugins * dealing with exif tags * @see_also: #GstTagList diff --git a/gst-libs/gst/tag/gstid3tag.c b/gst-libs/gst/tag/gstid3tag.c index e2cec575dd..5718bae250 100644 --- a/gst-libs/gst/tag/gstid3tag.c +++ b/gst-libs/gst/tag/gstid3tag.c @@ -21,16 +21,14 @@ /** * SECTION:gsttagid3 + * @title: ID3 tag utils * @short_description: tag mappings and support functions for plugins * dealing with ID3v1 and ID3v2 tags * @see_also: #GstTagList - * - * - * + * * Contains various utility functions for plugins to parse or create * ID3 tags and map ID3v2 identifiers to and from GStreamer identifiers. - * - * + * */ #ifdef HAVE_CONFIG_H @@ -305,7 +303,7 @@ gst_tag_list_new_from_id3v1 (const guint8 * data) /** * gst_tag_id3_genre_count: * - * Gets the number of ID3v1 genres that can be identified. Winamp genres are + * Gets the number of ID3v1 genres that can be identified. Winamp genres are * included. * * Returns: the number of ID3v1 genres that can be identified diff --git a/gst-libs/gst/tag/gsttagdemux.c b/gst-libs/gst/tag/gsttagdemux.c index 124f7887f6..6cb91d8631 100644 --- a/gst-libs/gst/tag/gsttagdemux.c +++ b/gst-libs/gst/tag/gsttagdemux.c @@ -20,12 +20,11 @@ /** * SECTION:gsttagdemux + * @title: GstTagDemux * @see_also: GstApeDemux, GstID3Demux * @short_description: Base class for demuxing tags that are in chunks * directly at the beginning or at the end of a file - * - * - * + * * Provides a base class for demuxing tags at the beginning or end of a * stream and handles things like typefinding, querying, seeking, and * different modes of operation (chain-based, pull_range-based, and providing @@ -35,37 +34,26 @@ * there was no tag at all. Also, once the tag has been parsed, GstTagDemux * will try to determine the media type of the resulting stream and add a * source pad with the appropriate caps in order to facilitate auto-plugging. - * - * Deriving from GstTagDemux - * + * + * ## Deriving from GstTagDemux + * * Subclasses have to do four things: - * - * - * In their base init function, they must add a pad template for the sink - * pad to the element class, describing the media type they can parse in - * the caps of the pad template. - * - * - * In their class init function, they must override - * GST_TAG_DEMUX_CLASS(demux_klass)->identify_tag with their own identify - * function. - * - * - * In their class init function, they must override + * + * * In their base init function, they must add a pad template for the sink + * pad to the element class, describing the media type they can parse in + * the caps of the pad template. + * * In their class init function, they must override + * GST_TAG_DEMUX_CLASS(demux_klass)->identify_tag with their own identify + * function. + * * In their class init function, they must override * GST_TAG_DEMUX_CLASS(demux_klass)->parse_tag with their own parse * function. - * - * - * In their class init function, they must also set - * GST_TAG_DEMUX_CLASS(demux_klass)->min_start_size and/or + * * In their class init function, they must also set + * GST_TAG_DEMUX_CLASS(demux_klass)->min_start_size and/or * GST_TAG_DEMUX_CLASS(demux_klass)->min_end_size to the minimum size required * for the identify function to decide whether the stream has a supported tag * or not. A class parsing ID3v1 tags, for example, would set min_end_size to * 128 bytes. - * - * - * - * */ #ifdef HAVE_CONFIG_H @@ -120,9 +108,9 @@ struct _GstTagDemuxPrivate GList *pending_events; }; -/* Require at least 8kB of data before we attempt typefind. +/* Require at least 8kB of data before we attempt typefind. * Seems a decent value based on test files - * 40kB is massive overkill for the maximum, I think, but it + * 40kB is massive overkill for the maximum, I think, but it * doesn't do any harm (tpm: increased to 64kB after watching * typefinding fail on a wavpack file that needed 42kB to succeed) */ #define TYPE_FIND_MIN_SIZE 8192 @@ -552,7 +540,7 @@ gst_tag_demux_chain_parse_tag (GstTagDemux * demux) g_assert (gst_buffer_is_writable (collect)); - /* If we receive a buffer that's from the middle of the file, + /* If we receive a buffer that's from the middle of the file, * we can't read tags so move to typefinding */ if (GST_BUFFER_OFFSET_IS_VALID (collect) && GST_BUFFER_OFFSET (collect) != 0) { GST_DEBUG_OBJECT (demux, "Received buffer from non-zero offset %" @@ -1571,7 +1559,7 @@ gst_tag_demux_sink_activate (GstPad * sinkpad, GstObject * parent) /* 1: */ /* If we can activate pull_range upstream, then read any end and start - * tags, otherwise activate in push mode and the chain function will + * tags, otherwise activate in push mode and the chain function will * collect buffers, read the start tag and output a buffer to end * preroll. */ @@ -1656,7 +1644,7 @@ gst_tag_demux_read_range (GstTagDemux * demux, GstObject * parent, if (ret != GST_FLOW_OK) return ret; - /* Adjust offset and length of the request to trim off tag information. + /* Adjust offset and length of the request to trim off tag information. * For the returned buffer, adjust the output offset to match what downstream * should see */ in_offset = offset + demux->priv->strip_start; diff --git a/gst-libs/gst/tag/gsttagmux.c b/gst-libs/gst/tag/gsttagmux.c index 1d527904e8..df0ac8b4fb 100644 --- a/gst-libs/gst/tag/gsttagmux.c +++ b/gst-libs/gst/tag/gsttagmux.c @@ -22,33 +22,26 @@ /** * SECTION:gsttagmux + * @title: GstTagMux * @see_also: GstApeMux, GstId3Mux * @short_description: Base class for adding tags that are in one single chunk * directly at the beginning or at the end of a file * - * - * * Provides a base class for adding tags at the beginning or end of a * stream. - * - * Deriving from GstTagMux - * + * + * ## Deriving from GstTagMux + * * Subclasses have to do the following things: - * - * - * In their base init function, they must add pad templates for the sink - * pad and the source pad to the element class, describing the media type - * they accept and output in the caps of the pad template. - * - * - * In their class init function, they must override the - * GST_TAG_MUX_CLASS(mux_klass)->render_start_tag and/or - * GST_TAG_MUX_CLASS(mux_klass)->render_end_tag vfuncs and set up a render - * function. - * - * - * - * + * + * * In their base init function, they must add pad templates for the sink + * pad and the source pad to the element class, describing the media type + * they accept and output in the caps of the pad template. + * * In their class init function, they must override the + * GST_TAG_MUX_CLASS(mux_klass)->render_start_tag and/or + * GST_TAG_MUX_CLASS(mux_klass)->render_end_tag vfuncs and set up a render + * function. + * */ #ifdef HAVE_CONFIG_H #include diff --git a/gst-libs/gst/tag/gstvorbistag.c b/gst-libs/gst/tag/gstvorbistag.c index 130b5b22e0..e3c24529ce 100644 --- a/gst-libs/gst/tag/gstvorbistag.c +++ b/gst-libs/gst/tag/gstvorbistag.c @@ -21,16 +21,14 @@ /** * SECTION:gsttagvorbis + * @title: GstVorbisTag * @short_description: tag mappings and support functions for plugins * dealing with vorbiscomments * @see_also: #GstTagList * - * - * * Contains various utility functions for plugins to parse or create * vorbiscomments and map them to and from #GstTagLists. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/tag/gstxmptag.c b/gst-libs/gst/tag/gstxmptag.c index 656c10ea81..f131bd5b0d 100644 --- a/gst-libs/gst/tag/gstxmptag.c +++ b/gst-libs/gst/tag/gstxmptag.c @@ -22,6 +22,7 @@ /** * SECTION:gsttagxmp + * @title: GstXmptag * @short_description: tag mappings and support functions for plugins * dealing with xmp packets * @see_also: #GstTagList diff --git a/gst-libs/gst/tag/lang.c b/gst-libs/gst/tag/lang.c index b64cb9293e..2e9a4f306b 100644 --- a/gst-libs/gst/tag/lang.c +++ b/gst-libs/gst/tag/lang.c @@ -19,15 +19,13 @@ /** * SECTION:gsttaglanguagecodes + * @title: ISO-639 lang mappings * @short_description: mappings for ISO-639 language codes and names * @see_also: #GstTagList * - * - * * Provides helper functions to convert between the various ISO-639 language * codes, and to map language codes to language names. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/tag/licenses.c b/gst-libs/gst/tag/licenses.c index 6b748105dc..0f8bfe65fd 100644 --- a/gst-libs/gst/tag/licenses.c +++ b/gst-libs/gst/tag/licenses.c @@ -19,6 +19,7 @@ /** * SECTION:gsttaglicenses + * @title: Licenses * @short_description: utility functions for Creative Commons licenses * @see_also: #GstTagList * diff --git a/gst-libs/gst/tag/tags.c b/gst-libs/gst/tag/tags.c index 5a0214de84..3676c56cb1 100644 --- a/gst-libs/gst/tag/tags.c +++ b/gst-libs/gst/tag/tags.c @@ -32,16 +32,14 @@ /** * SECTION:gsttag + * @title: Tags * @short_description: additional tag definitions for plugins and applications * @see_also: #GstTagList - * - * - * + * * Contains additional standardized GStreamer tag definitions for plugins * and applications, and functions to register them with the GStreamer * tag system. - * - * + * */ #ifndef GST_DISABLE_GST_DEBUG diff --git a/gst-libs/gst/tag/xmpwriter.c b/gst-libs/gst/tag/xmpwriter.c index 69f090ce7a..d714e0a034 100644 --- a/gst-libs/gst/tag/xmpwriter.c +++ b/gst-libs/gst/tag/xmpwriter.c @@ -19,19 +19,16 @@ /** * SECTION:gsttagxmpwriter + * @title: GstTagXmpWriter * @short_description: Interface for elements that provide XMP serialization * - * - * * This interface is implemented by elements that are able to do XMP serialization. Examples for * such elements are #jifmux and #qtmux. - * - * + * * Applications can use this interface to configure which XMP schemas should be used when serializing * tags into XMP. Schemas are represented by their names, a full list of the supported schemas can be * obtained from gst_tag_xmp_list_schemas(). By default, all schemas are used. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/video/colorbalance.c b/gst-libs/gst/video/colorbalance.c index b149a7f18e..1673468747 100644 --- a/gst-libs/gst/video/colorbalance.c +++ b/gst-libs/gst/video/colorbalance.c @@ -28,16 +28,15 @@ /** * SECTION:gstcolorbalance + * @title: GstColorBalance * @short_description: Interface for adjusting color balance settings * - * * This interface is implemented by elements which can perform some color * balance operation on video frames they process. For example, modifying * the brightness, contrast, hue or saturation. - * + * * Example elements are 'xvimagesink' and 'colorbalance' - * - * + * */ /* FIXME 0.11: check if we need to add API for sometimes-supportedness @@ -146,7 +145,7 @@ gst_color_balance_list_channels (GstColorBalance * balance) * * Sets the current value of the channel to the passed value, which must * be between min_value and max_value. - * + * * See Also: The #GstColorBalanceChannel.min_value and * #GstColorBalanceChannel.max_value members of the * #GstColorBalanceChannel object. @@ -169,11 +168,11 @@ gst_color_balance_set_value (GstColorBalance * balance, * * Retrieve the current value of the indicated channel, between min_value * and max_value. - * + * * See Also: The #GstColorBalanceChannel.min_value and * #GstColorBalanceChannel.max_value members of the * #GstColorBalanceChannel object. - * + * * Returns: The current value of the channel. */ gint diff --git a/gst-libs/gst/video/colorbalancechannel.c b/gst-libs/gst/video/colorbalancechannel.c index 14c0f49ad4..83830a67d4 100644 --- a/gst-libs/gst/video/colorbalancechannel.c +++ b/gst-libs/gst/video/colorbalancechannel.c @@ -27,13 +27,14 @@ /** * SECTION:gstcolorbalancechannel + * @title: GstColorBalanceChannel * @short_description: Object representing a channel from the #GstColorBalance * interface. * - * The #GstColorBalanceChannel object represents a parameter + * The #GstColorBalanceChannel object represents a parameter * for modifying the color balance implemented by an element providing the * #GstColorBalance interface. For example, Hue or Saturation. - * + * */ enum diff --git a/gst-libs/gst/video/gstvideoaffinetransformationmeta.c b/gst-libs/gst/video/gstvideoaffinetransformationmeta.c index 3dd20b967c..5e3e4d818b 100644 --- a/gst-libs/gst/video/gstvideoaffinetransformationmeta.c +++ b/gst-libs/gst/video/gstvideoaffinetransformationmeta.c @@ -98,7 +98,7 @@ gst_video_affine_transformation_meta_get_info (void) } /** - * gst_buffer_add_video_affine_transformation_meta + * gst_buffer_add_video_affine_transformation_meta: * @buffer: a #GstBuffer * * Attaches GstVideoAffineTransformationMeta metadata to @buffer with diff --git a/gst-libs/gst/video/gstvideodecoder.c b/gst-libs/gst/video/gstvideodecoder.c index d4d0f55c01..3702243c70 100644 --- a/gst-libs/gst/video/gstvideodecoder.c +++ b/gst-libs/gst/video/gstvideodecoder.c @@ -24,6 +24,7 @@ /** * SECTION:gstvideodecoder + * @title: GstVideoDecoder * @short_description: Base class for video decoders * @see_also: * @@ -32,86 +33,61 @@ * * The GstVideoDecoder base class and derived subclasses should cooperate as * follows: - * - * - * Configuration - * - * Initially, GstVideoDecoder calls @start when the decoder element + * + * ## Configuration + * + * * Initially, GstVideoDecoder calls @start when the decoder element * is activated, which allows the subclass to perform any global setup. - * - * - * GstVideoDecoder calls @set_format to inform the subclass of caps + * + * * GstVideoDecoder calls @set_format to inform the subclass of caps * describing input video data that it is about to receive, including * possibly configuration data. * While unlikely, it might be called more than once, if changing input * parameters require reconfiguration. - * - * - * Incoming data buffers are processed as needed, described in Data + * + * * Incoming data buffers are processed as needed, described in Data * Processing below. - * - * - * GstVideoDecoder calls @stop at end of all processing. - * - * - * - * - * - * Data processing - * - * The base class gathers input data, and optionally allows subclass + * + * * GstVideoDecoder calls @stop at end of all processing. + * + * ## Data processing + * + * * The base class gathers input data, and optionally allows subclass * to parse this into subsequently manageable chunks, typically * corresponding to and referred to as 'frames'. - * - * - * Each input frame is provided in turn to the subclass' @handle_frame + * + * * Each input frame is provided in turn to the subclass' @handle_frame * callback. * The ownership of the frame is given to the @handle_frame callback. - * - * - * If codec processing results in decoded data, the subclass should call + * + * * If codec processing results in decoded data, the subclass should call * @gst_video_decoder_finish_frame to have decoded data pushed. * downstream. Otherwise, the subclass must call * @gst_video_decoder_drop_frame, to allow the base class to do timestamp * and offset tracking, and possibly to requeue the frame for a later * attempt in the case of reverse playback. - * - * - * - * - * Shutdown phase - * - * The GstVideoDecoder class calls @stop to inform the subclass that data + * + * ## Shutdown phase + * + * * The GstVideoDecoder class calls @stop to inform the subclass that data * parsing will be stopped. - * - * - * - * - * Additional Notes - * - * Seeking/Flushing - * - * When the pipeline is seeked or otherwise flushed, the subclass is - * informed via a call to its @reset callback, with the hard parameter - * set to true. This indicates the subclass should drop any internal data - * queues and timestamps and prepare for a fresh set of buffers to arrive - * for parsing and decoding. - * - * - * - * - * End Of Stream - * - * At end-of-stream, the subclass @parse function may be called some final - * times with the at_eos parameter set to true, indicating that the element - * should not expect any more data to be arriving, and it should parse and - * remaining frames and call gst_video_decoder_have_frame() if possible. - * - * - * - * - * - * + * + * ## Additional Notes + * + * * Seeking/Flushing + * + * * When the pipeline is seeked or otherwise flushed, the subclass is + * informed via a call to its @reset callback, with the hard parameter + * set to true. This indicates the subclass should drop any internal data + * queues and timestamps and prepare for a fresh set of buffers to arrive + * for parsing and decoding. + * + * * End Of Stream + * + * * At end-of-stream, the subclass @parse function may be called some final + * times with the at_eos parameter set to true, indicating that the element + * should not expect any more data to be arriving, and it should parse and + * remaining frames and call gst_video_decoder_have_frame() if possible. * * The subclass is responsible for providing pad template caps for * source and sink pads. The pads need to be named "sink" and "src". It also @@ -143,23 +119,18 @@ * incoming data. * * The bare minimum that a functional subclass needs to implement is: - * - * Provide pad templates - * - * Inform the base class of output caps via + * + * * Provide pad templates + * * Inform the base class of output caps via * @gst_video_decoder_set_output_state - * - * - * Parse input data, if it is not considered packetized from upstream + * + * * Parse input data, if it is not considered packetized from upstream * Data will be provided to @parse which should invoke * @gst_video_decoder_add_to_frame and @gst_video_decoder_have_frame to * separate the data belonging to each video frame. - * - * - * Accept data in @handle_frame and provide decoded results to + * + * * Accept data in @handle_frame and provide decoded results to * @gst_video_decoder_finish_frame, or call @gst_video_decoder_drop_frame. - * - * */ #ifdef HAVE_CONFIG_H @@ -3358,7 +3329,7 @@ gst_video_decoder_have_frame (GstVideoDecoder * decoder) } /* Pass the frame in priv->current_frame through the - * handle_frame() callback for decoding and passing to gvd_finish_frame(), + * handle_frame() callback for decoding and passing to gvd_finish_frame(), * or dropping by passing to gvd_drop_frame() */ static GstFlowReturn gst_video_decoder_decode_frame (GstVideoDecoder * decoder, @@ -3370,7 +3341,7 @@ gst_video_decoder_decode_frame (GstVideoDecoder * decoder, decoder_class = GST_VIDEO_DECODER_GET_CLASS (decoder); - /* FIXME : This should only have to be checked once (either the subclass has an + /* FIXME : This should only have to be checked once (either the subclass has an * implementation, or it doesn't) */ g_return_val_if_fail (decoder_class->handle_frame != NULL, GST_FLOW_ERROR); @@ -3538,7 +3509,7 @@ gst_video_decoder_get_oldest_frame (GstVideoDecoder * decoder) * @frame_number: system_frame_number of a frame * * Get a pending unfinished #GstVideoCodecFrame - * + * * Returns: (transfer full): pending unfinished #GstVideoCodecFrame identified by @frame_number. */ GstVideoCodecFrame * @@ -3568,7 +3539,7 @@ gst_video_decoder_get_frame (GstVideoDecoder * decoder, int frame_number) * @decoder: a #GstVideoDecoder * * Get all pending unfinished #GstVideoCodecFrame - * + * * Returns: (transfer full) (element-type GstVideoCodecFrame): pending unfinished #GstVideoCodecFrame. */ GList * diff --git a/gst-libs/gst/video/gstvideoencoder.c b/gst-libs/gst/video/gstvideoencoder.c index 6164a466d2..b4ae5982dc 100644 --- a/gst-libs/gst/video/gstvideoencoder.c +++ b/gst-libs/gst/video/gstvideoencoder.c @@ -24,6 +24,7 @@ /** * SECTION:gstvideoencoder + * @title: GstVideoEncoder * @short_description: Base class for video encoders * @see_also: * @@ -31,59 +32,40 @@ * encoded video data. * * GstVideoEncoder and subclass should cooperate as follows. - * - * - * Configuration - * - * Initially, GstVideoEncoder calls @start when the encoder element + * + * ## Configuration + * + * * Initially, GstVideoEncoder calls @start when the encoder element * is activated, which allows subclass to perform any global setup. - * - * - * GstVideoEncoder calls @set_format to inform subclass of the format + * * GstVideoEncoder calls @set_format to inform subclass of the format * of input video data that it is about to receive. Subclass should * setup for encoding and configure base class as appropriate * (e.g. latency). While unlikely, it might be called more than once, * if changing input parameters require reconfiguration. Baseclass * will ensure that processing of current configuration is finished. - * - * - * GstVideoEncoder calls @stop at end of all processing. - * - * - * - * - * - * Data processing - * - * Base class collects input data and metadata into a frame and hands + * * GstVideoEncoder calls @stop at end of all processing. + * + * ## Data processing + * + * * Base class collects input data and metadata into a frame and hands * this to subclass' @handle_frame. - * - * - * If codec processing results in encoded data, subclass should call + * + * * If codec processing results in encoded data, subclass should call * @gst_video_encoder_finish_frame to have encoded data pushed * downstream. - * - * - * If implemented, baseclass calls subclass @pre_push just prior to + * + * * If implemented, baseclass calls subclass @pre_push just prior to * pushing to allow subclasses to modify some metadata on the buffer. * If it returns GST_FLOW_OK, the buffer is pushed downstream. - * - * - * GstVideoEncoderClass will handle both srcpad and sinkpad events. + * + * * GstVideoEncoderClass will handle both srcpad and sinkpad events. * Sink events will be passed to subclass if @event callback has been * provided. - * - * - * - * - * Shutdown phase - * - * GstVideoEncoder class calls @stop to inform the subclass that data + * + * ## Shutdown phase + * + * * GstVideoEncoder class calls @stop to inform the subclass that data * parsing will be stopped. - * - * - * - * * * Subclass is responsible for providing pad template caps for * source and sink pads. The pads need to be named "sink" and "src". It should @@ -91,16 +73,11 @@ * @gst_video_encoder_finish_frame. * * Things that subclass need to take care of: - * - * Provide pad templates - * - * Provide source pad caps before pushing the first buffer - * - * - * Accept data in @handle_frame and provide encoded results to + * + * * Provide pad templates + * * Provide source pad caps before pushing the first buffer + * * Accept data in @handle_frame and provide encoded results to * @gst_video_encoder_finish_frame. - * - * * */ @@ -1928,7 +1905,7 @@ foreach_metadata (GstBuffer * inbuf, GstMeta ** meta, gpointer user_data) /** * gst_video_encoder_finish_frame: * @encoder: a #GstVideoEncoder - * @frame: (transfer full): an encoded #GstVideoCodecFrame + * @frame: (transfer full): an encoded #GstVideoCodecFrame * * @frame must have a valid encoded data buffer, whose metadata fields * are then appropriately set according to frame data or no buffer at @@ -2367,7 +2344,7 @@ gst_video_encoder_get_oldest_frame (GstVideoEncoder * encoder) * @frame_number: system_frame_number of a frame * * Get a pending unfinished #GstVideoCodecFrame - * + * * Returns: (transfer full): pending unfinished #GstVideoCodecFrame identified by @frame_number. */ GstVideoCodecFrame * @@ -2397,7 +2374,7 @@ gst_video_encoder_get_frame (GstVideoEncoder * encoder, int frame_number) * @encoder: a #GstVideoEncoder * * Get all pending unfinished #GstVideoCodecFrame - * + * * Returns: (transfer full) (element-type GstVideoCodecFrame): pending unfinished #GstVideoCodecFrame. */ GList * diff --git a/gst-libs/gst/video/gstvideofilter.c b/gst-libs/gst/video/gstvideofilter.c index a91053eb97..9fd217530f 100644 --- a/gst-libs/gst/video/gstvideofilter.c +++ b/gst-libs/gst/video/gstvideofilter.c @@ -20,17 +20,14 @@ /** * SECTION:gstvideofilter + * @title: GstVideoFilter * @short_description: Base class for video filters - * - * - * + * * Provides useful functions and a base class for video filters. - * - * + * * The videofilter will by default enable QoS on the parent GstBaseTransform * to implement frame dropping. - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst-libs/gst/video/gstvideometa.h b/gst-libs/gst/video/gstvideometa.h index d5e1562a6e..55da189dee 100644 --- a/gst-libs/gst/video/gstvideometa.h +++ b/gst-libs/gst/video/gstvideometa.h @@ -170,7 +170,7 @@ typedef enum * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_NORMAL_Y_FLIP: Bottom line first in memory, left row first * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_NORMAL: Top line first in memory, right row first * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_FLIP: Bottom line first in memory, right row first - * + * * The orientation of the GL texture. */ typedef enum diff --git a/gst-libs/gst/video/gstvideopool.c b/gst-libs/gst/video/gstvideopool.c index 99d122a729..2ada77afc2 100644 --- a/gst-libs/gst/video/gstvideopool.c +++ b/gst-libs/gst/video/gstvideopool.c @@ -26,6 +26,7 @@ GST_DEBUG_CATEGORY_STATIC (gst_video_pool_debug); /** * SECTION:gstvideopool + * @title: GstVideoBufferPool * @short_description: GstBufferPool for raw video buffers * @see_also: #GstBufferPool * diff --git a/gst-libs/gst/video/gstvideosink.c b/gst-libs/gst/video/gstvideosink.c index 1b22cb2d73..3d74dbf0dc 100644 --- a/gst-libs/gst/video/gstvideosink.c +++ b/gst-libs/gst/video/gstvideosink.c @@ -20,18 +20,15 @@ /** * SECTION:gstvideosink + * @title: GstVideoSink * @short_description: Base class for video sinks - * - * - * - * Provides useful functions and a base class for video sinks. - * - * + * + * Provides useful functions and a base class for video sinks. + * * GstVideoSink will configure the default base sink to drop frames that * arrive later than 20ms as this is considered the default threshold for * observing out-of-sync frames. - * - * + * */ #ifdef HAVE_CONFIG_H @@ -92,7 +89,7 @@ static GstFlowReturn gst_video_sink_show_frame (GstBaseSink * bsink, * @dst: the #GstVideoRectangle describing the destination area * @result: a pointer to a #GstVideoRectangle which will receive the result area * @scaling: a #gboolean indicating if scaling should be applied or not - * + * * Takes @src rectangle and position it at the center of @dst rectangle with or * without @scaling. It handles clipping if the @src rectangle is bigger than * the @dst one and @scaling is set to FALSE. diff --git a/gst-libs/gst/video/gstvideosink.h b/gst-libs/gst/video/gstvideosink.h index cc57be923c..d645058164 100644 --- a/gst-libs/gst/video/gstvideosink.h +++ b/gst-libs/gst/video/gstvideosink.h @@ -105,7 +105,7 @@ struct _GstVideoSink { * @parent_class: the parent class structure * @show_frame: render a video frame. Maps to #GstBaseSinkClass.render() and * #GstBaseSinkClass.preroll() vfuncs. Rendering during preroll will be - * suppressed if the #GstVideoSink:show-preroll-frame property is set to + * suppressed if the #GstVideoSink:show-preroll-frame property is set to * %FALSE. * * The video sink class structure. Derived classes should override the diff --git a/gst-libs/gst/video/navigation.c b/gst-libs/gst/video/navigation.c index 54bac853ed..800117bcae 100644 --- a/gst-libs/gst/video/navigation.c +++ b/gst-libs/gst/video/navigation.c @@ -22,6 +22,7 @@ /** * SECTION:gstnavigation + * @title: GstNavigation * @short_description: Interface for creating, sending and parsing navigation * events. * @@ -31,32 +32,21 @@ * receiving navigation related bus events. One main usecase is DVD menu navigation. * * The main parts of the API are: - * - * - * - * The GstNavigation interface, implemented by elements which provide an application - * with the ability to create and inject navigation events into the pipeline. - * - * - * - * - * GstNavigation event handling API. GstNavigation events are created in response to - * calls on a GstNavigation interface implementation, and sent in the pipeline. Upstream - * elements can use the navigation event API functions to parse the contents of received - * messages. - * - * - * - * - * GstNavigation message handling API. GstNavigation messages may be sent on the message - * bus to inform applications of navigation related changes in the pipeline, such as the - * mouse moving over a clickable region, or the set of available angles changing. - * + * + * * The GstNavigation interface, implemented by elements which provide an application + * with the ability to create and inject navigation events into the pipeline. + * * GstNavigation event handling API. GstNavigation events are created in response to + * calls on a GstNavigation interface implementation, and sent in the pipeline. Upstream + * elements can use the navigation event API functions to parse the contents of received + * messages. + * + * * GstNavigation message handling API. GstNavigation messages may be sent on the message + * bus to inform applications of navigation related changes in the pipeline, such as the + * mouse moving over a clickable region, or the set of available angles changing. + * * The GstNavigation message functions provide functions for creating and parsing * custom bus messages for signaling GstNavigation changes. - * - * - * + * */ #ifdef HAVE_CONFIG_H @@ -777,7 +767,7 @@ gst_navigation_event_parse_key_event (GstEvent * event, const gchar ** key) * event. * @y: Pointer to a gdouble to receive the y coordinate of the mouse button * event. - * + * * Retrieve the details of either a #GstNavigation mouse button press event or * a mouse button release event. Determine which type the event is using * gst_navigation_event_get_type() to retrieve the #GstNavigationEventType. diff --git a/gst-libs/gst/video/video-chroma.c b/gst-libs/gst/video/video-chroma.c index 0996f7a5df..b994658a95 100644 --- a/gst-libs/gst/video/video-chroma.c +++ b/gst-libs/gst/video/video-chroma.c @@ -30,6 +30,7 @@ /** * SECTION:gstvideochroma + * @title: GstVideoChromaResample * @short_description: Functions and utility object for operating on chroma video planes * * The functions gst_video_chroma_from_string() and gst_video_chroma_to_string() convert diff --git a/gst-libs/gst/video/video-converter.c b/gst-libs/gst/video/video-converter.c index 85f4267dc4..3f34739253 100644 --- a/gst-libs/gst/video/video-converter.c +++ b/gst-libs/gst/video/video-converter.c @@ -39,27 +39,17 @@ /** * SECTION:videoconverter + * @title: GstVideoConverter * @short_description: Generic video conversion * - * - * * This object is used to convert video frames from one format to another. * The object can perform conversion of: - * - * - * video format - * - * - * video colorspace - * - * - * chroma-siting - * - * - * video size - * - * - * + * + * * video format + * * video colorspace + * * chroma-siting + * * video size + * */ /* diff --git a/gst-libs/gst/video/video-dither.c b/gst-libs/gst/video/video-dither.c index ea5ab999bd..3f5e6bd723 100644 --- a/gst-libs/gst/video/video-dither.c +++ b/gst-libs/gst/video/video-dither.c @@ -24,6 +24,7 @@ /** * SECTION:gstvideodither + * @title: GstVideoDither * @short_description: Utility object for dithering and quantizing lines of video * * GstVideoDither provides implementations of several dithering algorithms diff --git a/gst-libs/gst/video/video-event.c b/gst-libs/gst/video/video-event.c index 2776365ab3..faf7adb2f6 100644 --- a/gst-libs/gst/video/video-event.c +++ b/gst-libs/gst/video/video-event.c @@ -134,7 +134,7 @@ gst_video_event_new_downstream_force_key_unit (GstClockTime timestamp, * @count: integer that can be used to number key units * * Creates a new upstream force key unit event. An upstream force key unit event - * can be sent to request upstream elements to produce a key unit. + * can be sent to request upstream elements to produce a key unit. * * @running_time can be set to request a new key unit at a specific * running_time. If set to GST_CLOCK_TIME_NONE, upstream elements will produce a diff --git a/gst-libs/gst/video/video-overlay-composition.c b/gst-libs/gst/video/video-overlay-composition.c index 7ed9ce6fe7..97538ce577 100644 --- a/gst-libs/gst/video/video-overlay-composition.c +++ b/gst-libs/gst/video/video-overlay-composition.c @@ -21,39 +21,32 @@ /** * SECTION:gstvideooverlaycomposition + * @title: GstVideoOverlayRectangle * @short_description: Video Buffer Overlay Compositions (Subtitles, Logos) * - * - * * Functions to create and handle overlay compositions on video buffers. - * - * + * * An overlay composition describes one or more overlay rectangles to be * blended on top of a video buffer. - * - * + * * This API serves two main purposes: - * - * - * it can be used to attach overlay information (subtitles or logos) - * to non-raw video buffers such as GL/VAAPI/VDPAU surfaces. The actual - * blending of the overlay can then be done by e.g. the video sink that - * processes these non-raw buffers. - * - * - * it can also be used to blend overlay rectangles on top of raw video - * buffers, thus consolidating blending functionality for raw video in - * one place. - * + * + * * it can be used to attach overlay information (subtitles or logos) + * to non-raw video buffers such as GL/VAAPI/VDPAU surfaces. The actual + * blending of the overlay can then be done by e.g. the video sink that + * processes these non-raw buffers. + * + * * it can also be used to blend overlay rectangles on top of raw video + * buffers, thus consolidating blending functionality for raw video in + * one place. + * * Together, this allows existing overlay elements to easily handle raw * and non-raw video as input in without major changes (once the overlays * have been put into a #GstOverlayComposition object anyway) - for raw * video the overlay can just use the blending function to blend the data * on top of the video, and for surface buffers it can just attach them to * the buffer and let the sink render the overlays. - * - * - * + * */ /* TODO: diff --git a/gst-libs/gst/video/video-resampler.c b/gst-libs/gst/video/video-resampler.c index 0848961d13..119343f99d 100644 --- a/gst-libs/gst/video/video-resampler.c +++ b/gst-libs/gst/video/video-resampler.c @@ -51,6 +51,7 @@ ensure_debug_category (void) /** * SECTION:gstvideoresampler + * @title: GstVideoResampler * @short_description: Utility structure for resampler information * * #GstVideoResampler is a structure which holds the information diff --git a/gst-libs/gst/video/video-scaler.c b/gst-libs/gst/video/video-scaler.c index cd100c8f4f..f2057da672 100644 --- a/gst-libs/gst/video/video-scaler.c +++ b/gst-libs/gst/video/video-scaler.c @@ -27,6 +27,7 @@ /** * SECTION:gstvideoscaler + * @title: GstVideoScaler * @short_description: Utility object for rescaling video frames * * #GstVideoScaler is a utility object for rescaling and resampling diff --git a/gst-libs/gst/video/video.c b/gst-libs/gst/video/video.c index 230ebae455..79187d1098 100644 --- a/gst-libs/gst/video/video.c +++ b/gst-libs/gst/video/video.c @@ -31,14 +31,12 @@ /** * SECTION:gstvideo + * @title: GstVideoAlignment * @short_description: Support library for video operations * - * - * * This library contains some helper functions and includes the * videosink and videofilter base classes. - * - * + * */ /** diff --git a/gst-libs/gst/video/videodirection.c b/gst-libs/gst/video/videodirection.c index da908a9c28..a7e87d6753 100644 --- a/gst-libs/gst/video/videodirection.c +++ b/gst-libs/gst/video/videodirection.c @@ -29,6 +29,7 @@ /** * SECTION:gstvideodirection + * @title: GstVideoDirection * @short_description: Interface for elements providing video * rotation and flipping controls * diff --git a/gst-libs/gst/video/videoorientation.c b/gst-libs/gst/video/videoorientation.c index 0f714fe028..6ef407e58b 100644 --- a/gst-libs/gst/video/videoorientation.c +++ b/gst-libs/gst/video/videoorientation.c @@ -29,6 +29,7 @@ /** * SECTION:gstvideoorientation + * @title: GstVideoOrientation * @short_description: Interface for elements providing video orientation * controls * diff --git a/gst-libs/gst/video/videooverlay.c b/gst-libs/gst/video/videooverlay.c index cd232bacb1..bcea1df7a0 100644 --- a/gst-libs/gst/video/videooverlay.c +++ b/gst-libs/gst/video/videooverlay.c @@ -19,40 +19,28 @@ */ /** * 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. - * - * - * - * - * + * + * * 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 @@ -93,11 +81,9 @@ * ... * } * ]| - * - * - * - * Two basic usage scenarios - * + * + * ## 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 @@ -109,8 +95,7 @@ * 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. @@ -122,8 +107,7 @@ * 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 @@ -139,11 +123,9 @@ * 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+ - * + * + * ## GstVideoOverlay and Gtk+ + * * |[ * #include <gst/video/videooverlay.h> * #include <gtk/gtk.h> @@ -242,11 +224,9 @@ * ... * } * ]| - * - * - * - * GstVideoOverlay and Qt - * + * + * ## GstVideoOverlay and Qt + * * |[ * #include <glib.h> * #include <gst/gst.h> @@ -302,8 +282,7 @@ * return ret; * } * ]| - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/adder/gstadder.c b/gst/adder/gstadder.c index 6d45980957..aa8848c505 100644 --- a/gst/adder/gstadder.c +++ b/gst/adder/gstadder.c @@ -22,6 +22,7 @@ */ /** * SECTION:element-adder + * @title: adder * * The adder allows to mix several streams into one by adding the data. * Mixed data is clamped to the min/max values of the data format. @@ -33,12 +34,12 @@ * audio mixing element: It will sync input streams correctly and also handle * live inputs properly. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 audiotestsrc freq=100 ! adder name=mix ! audioconvert ! autoaudiosink audiotestsrc freq=500 ! mix. - * ]| This pipeline produces two sine waves mixed together. - * + * ]| + * This pipeline produces two sine waves mixed together. + * */ /* Element-Checklist-Version: 5 */ diff --git a/gst/app/gstapp.c b/gst/app/gstapp.c index 0fb9e785ac..9732fc8c20 100644 --- a/gst/app/gstapp.c +++ b/gst/app/gstapp.c @@ -18,6 +18,7 @@ */ /** * SECTION:element-appsrc + * @title: appsrc * * The appsrc element can be used by applications to insert data into a * GStreamer pipeline. Unlike most GStreamer elements, Appsrc provides @@ -29,6 +30,7 @@ */ /** * SECTION:element-appsink + * @title: appsink * * Appsink is a sink plugin that supports many different methods for making * the application get a handle on the GStreamer data in a pipeline. Unlike diff --git a/gst/audioconvert/gstaudioconvert.c b/gst/audioconvert/gstaudioconvert.c index 6cd770945e..1bd05431c2 100644 --- a/gst/audioconvert/gstaudioconvert.c +++ b/gst/audioconvert/gstaudioconvert.c @@ -23,25 +23,27 @@ /** * SECTION:element-audioconvert + * @title: audioconvert * * Audioconvert converts raw audio buffers between various possible formats. * It supports integer to float conversion, width/depth conversion, * signedness and endianness conversion and channel transformations * (ie. upmixing and downmixing), as well as dithering and noise-shaping. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 -v -m audiotestsrc ! audioconvert ! audio/x-raw,format=S8,channels=2 ! level ! fakesink silent=TRUE - * ]| This pipeline converts audio to 8-bit. The level element shows that + * ]| + * This pipeline converts audio to 8-bit. The level element shows that * the output levels still match the one for a sine wave. * |[ * gst-launch-1.0 -v -m uridecodebin uri=file:///path/to/audio.flac ! audioconvert ! vorbisenc ! oggmux ! filesink location=audio.ogg - * ]| The vorbis encoder takes float audio data instead of the integer data + * ]| + * The vorbis encoder takes float audio data instead of the integer data * output by most other audio elements. This pipeline decodes a FLAC audio file * (or any other audio file for which decoders are installed) and re-encodes * it into an Ogg/Vorbis audio file. - * + * */ /* diff --git a/gst/audiorate/gstaudiorate.c b/gst/audiorate/gstaudiorate.c index ad8720c567..a61d88bc58 100644 --- a/gst/audiorate/gstaudiorate.c +++ b/gst/audiorate/gstaudiorate.c @@ -19,6 +19,7 @@ /** * SECTION:element-audiorate + * @title: audiorate * @see_also: #GstVideoRate * * This element takes an incoming stream of timestamped raw audio frames and @@ -48,19 +49,20 @@ * that the incoming data is then simply shifted (by less than the indicated * tolerance) to a perfect time. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v autoaudiosrc ! audiorate ! audioconvert ! wavenc ! filesink location=alsa.wav - * ]| Capture audio from the sound card and turn it into a perfect stream + * ]| + * Capture audio from the sound card and turn it into a perfect stream * for saving in a raw audio file. * |[ * gst-launch-1.0 -v uridecodebin uri=file:///path/to/audio.file ! audiorate ! audioconvert ! wavenc ! filesink location=alsa.wav - * ]| Decodes an audio file and transforms it into a perfect stream for saving + * ]| + * Decodes an audio file and transforms it into a perfect stream for saving * in a raw audio WAV file. Without the audio rate, the timing might not be * preserved correctly in the WAV file in case the decoded stream is jittery * or there are samples missing. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/audioresample/gstaudioresample.c b/gst/audioresample/gstaudioresample.c index df6782b6cc..8a48c30b4f 100644 --- a/gst/audioresample/gstaudioresample.c +++ b/gst/audioresample/gstaudioresample.c @@ -21,6 +21,7 @@ /** * SECTION:element-audioresample + * @title: audioresample * * audioresample resamples raw audio buffers to different sample rates using * a configurable windowing function to enhance quality. @@ -33,14 +34,14 @@ * to initialize when the element is created. A third mode exists, which uses the full table * unless said table would become too large, in which case the interpolated one is used instead. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 -v uridecodebin uri=file:///path/to/audio.ogg ! audioconvert ! audioresample ! audio/x-raw, rate=8000 ! autoaudiosink - * ]| Decode an audio file and downsample it to 8Khz and play sound. + * ]| + * Decode an audio file and downsample it to 8Khz and play sound. * To create the Ogg/Vorbis file refer to the documentation of vorbisenc. * This assumes there is an audio sink that will accept/handle 8kHz audio. - * + * */ /* TODO: diff --git a/gst/audiotestsrc/gstaudiotestsrc.c b/gst/audiotestsrc/gstaudiotestsrc.c index 51b25907dc..bd1f88c5e5 100644 --- a/gst/audiotestsrc/gstaudiotestsrc.c +++ b/gst/audiotestsrc/gstaudiotestsrc.c @@ -18,22 +18,24 @@ */ /** * SECTION:element-audiotestsrc + * @title: audiotestsrc * * AudioTestSrc can be used to generate basic audio signals. It support several * different waveforms and allows to set the base frequency and volume. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 audiotestsrc ! audioconvert ! autoaudiosink - * ]| This pipeline produces a sine with default frequency, 440 Hz, and the + * ]| + * This pipeline produces a sine with default frequency, 440 Hz, and the * default volume, 0.8 (relative to a maximum 1.0). * |[ * gst-launch-1.0 audiotestsrc wave=2 freq=200 ! tee name=t ! queue ! audioconvert ! autoaudiosink t. ! queue ! audioconvert ! libvisual_lv_scope ! videoconvert ! autovideosink - * ]| In this example a saw wave is generated. The wave is shown using a + * ]| + * In this example a saw wave is generated. The wave is shown using a * scope visualizer from libvisual, allowing you to visually verify that * the saw wave is correct. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/encoding/gstencodebin.c b/gst/encoding/gstencodebin.c index e8319948e7..5e757f9153 100644 --- a/gst/encoding/gstencodebin.c +++ b/gst/encoding/gstencodebin.c @@ -31,6 +31,7 @@ /** * SECTION:element-encodebin + * @title: encodebin * * EncodeBin provides a bin for encoding/muxing various streams according to * a specified #GstEncodingProfile. @@ -41,67 +42,54 @@ * provide it raw or pre-encoded streams of data in input and have your * encoded/muxed/converted stream in output. * - * - * Features - * - * - * Automatic encoder and muxer selection based on elements available on the + * ## Features + * + * * Automatic encoder and muxer selection based on elements available on the * system. - * - * - * Conversion of raw audio/video streams (scaling, framerate conversion, + * + * * Conversion of raw audio/video streams (scaling, framerate conversion, * colorspace conversion, samplerate conversion) to conform to the profile * output format. - * - * - * Variable number of streams. If the presence property for a stream encoding + * + * * Variable number of streams. If the presence property for a stream encoding * profile is 0, you can request any number of sink pads for it via the * standard request pad gstreamer API or the #GstEncodeBin::request-pad action * signal. - * - * - * Avoid reencoding (passthrough). If the input stream is already encoded and is + * + * * Avoid reencoding (passthrough). If the input stream is already encoded and is * compatible with what the #GstEncodingProfile expects, then the stream won't * be re-encoded but just passed through downstream to the muxer or the output. - * - * - * Mix pre-encoded and raw streams as input. In addition to the passthrough + * + * * Mix pre-encoded and raw streams as input. In addition to the passthrough * feature above, you can feed both raw audio/video *AND* already-encoded data * to a pad. #GstEncodeBin will take care of passing through the compatible * segments and re-encoding the segments of media that need encoding. - * - * - * Standard behaviour is to use a #GstEncodingContainerProfile to have both + * + * * Standard behaviour is to use a #GstEncodingContainerProfile to have both * encoding and muxing performed. But you can also provide a single stream * profile (like #GstEncodingAudioProfile) to only have the encoding done and * handle the encoded output yourself. - * - * - * Audio imperfection corrections. Incoming audio streams can have non perfect + * + * * Audio imperfection corrections. Incoming audio streams can have non perfect * timestamps (jitter), like the streams coming from ASF files. #GstEncodeBin * will automatically fix those imperfections for you. See * #GstEncodeBin:audio-jitter-tolerance for more details. - * - * - * Variable or Constant video framerate. If your #GstEncodingVideoProfile has + * + * * Variable or Constant video framerate. If your #GstEncodingVideoProfile has * the variableframerate property deactivated (default), then the incoming * raw video stream will be retimestampped in order to produce a constant * framerate. - * - * - * Cross-boundary re-encoding. When feeding compatible pre-encoded streams that + * + * * Cross-boundary re-encoding. When feeding compatible pre-encoded streams that * fall on segment boundaries, and for supported formats (right now only H263), * the GOP will be decoded/reencoded when needed to produce an encoded output * that fits exactly within the request GstSegment. - * - * - * Missing plugin support. If a #GstElement is missing to encode/mux to the + * + * * Missing plugin support. If a #GstElement is missing to encode/mux to the * request profile formats, a missing-plugin #GstMessage will be posted on the * #GstBus, allowing systems that support the missing-plugin system to offer the * user a way to install the missing element. - * - * - * + * */ diff --git a/gst/gio/gstgiosink.c b/gst/gio/gstgiosink.c index cf02090d2c..e94aeb49df 100644 --- a/gst/gio/gstgiosink.c +++ b/gst/gio/gstgiosink.c @@ -21,6 +21,7 @@ /** * SECTION:element-giosink + * @title: giosink * @see_also: #GstFileSink, #GstGnomeVFSSink, #GstGioSrc * * This plugin writes incoming data to a local or remote location specified @@ -44,22 +45,24 @@ * on the bus if the target location is not mounted yet and needs to be * mounted. This message can be used by application to mount the location * and retry after the location was mounted successfully. - * - * - * Example pipelines + * + * ## Example pipelines * |[ * gst-launch-1.0 -v filesrc location=input.xyz ! giosink location=file:///home/joe/out.xyz - * ]| The above pipeline will simply copy a local file. Instead of giosink, + * ]| + * The above pipeline will simply copy a local file. Instead of giosink, * we could just as well have used the filesink element here. * |[ * gst-launch-1.0 -v uridecodebin uri=file:///path/to/audio.file ! audioconvert ! flacenc ! giosink location=smb://othercomputer/foo.flac - * ]| The above pipeline will re-encode an audio file into FLAC format and store + * ]| + * The above pipeline will re-encode an audio file into FLAC format and store * it on a remote host using the Samba protocol. * |[ * gst-launch-1.0 -v audiotestsrc num-buffers=100 ! vorbisenc ! oggmux ! giosink location=file:///home/foo/bar.ogg - * ]| The above pipeline will encode a 440Hz sine wave to Ogg Vorbis and stores + * ]| + * The above pipeline will encode a 440Hz sine wave to Ogg Vorbis and stores * it in the home directory of user foo. - * + * */ /* FIXME: We would like to mount the enclosing volume of an URL diff --git a/gst/gio/gstgiosrc.c b/gst/gio/gstgiosrc.c index 9f9bae58c3..167f941d93 100644 --- a/gst/gio/gstgiosrc.c +++ b/gst/gio/gstgiosrc.c @@ -21,6 +21,7 @@ /** * SECTION:element-giosrc + * @title: giosrc * @see_also: #GstFileSrc, #GstGnomeVFSSrc, #GstGioSink * * This plugin reads data from a local or remote location specified @@ -40,22 +41,24 @@ * message was received and gst_bus_set_flushing(bus, FALSE) after the * mounting was successful. * - * - * Example launch lines + * ## Example launch lines * |[ * gst-launch-1.0 -v giosrc location=file:///home/joe/foo.xyz ! fakesink - * ]| The above pipeline will simply read a local file and do nothing with the + * ]| + * The above pipeline will simply read a local file and do nothing with the * data read. Instead of giosrc, we could just as well have used the * filesrc element here. * |[ * gst-launch-1.0 -v giosrc location=smb://othercomputer/foo.xyz ! filesink location=/home/joe/foo.xyz - * ]| The above pipeline will copy a file from a remote host to the local file + * ]| + * The above pipeline will copy a file from a remote host to the local file * system using the Samba protocol. * |[ * gst-launch-1.0 -v giosrc location=smb://othercomputer/demo.mp3 ! decodebin ! audioconvert ! audioresample ! autoaudiosink - * ]| The above pipeline will read and decode and play an mp3 file from a + * ]| + * The above pipeline will read and decode and play an mp3 file from a * SAMBA server. - * + * */ /* FIXME: We would like to mount the enclosing volume of an URL @@ -118,7 +121,7 @@ gst_gio_src_class_init (GstGioSrcClass * klass) /** * GstGioSrc:file: - * + * * %GFile to read from. */ g_object_class_install_property (gobject_class, PROP_FILE, diff --git a/gst/gio/gstgiostreamsink.c b/gst/gio/gstgiostreamsink.c index 96ff9fcee0..2c5357bc54 100644 --- a/gst/gio/gstgiostreamsink.c +++ b/gst/gio/gstgiostreamsink.c @@ -21,15 +21,15 @@ /** * SECTION:element-giostreamsink + * @title: giostreamsink * * This plugin writes incoming data to a custom GIO #GOutputStream. * * It can, for example, be used to write a stream to memory with a * #GMemoryOuputStream or to write to a file with a #GFileOuputStream. * - * - * Example code - * + * ## Example code + * * The following example writes the received data to a #GMemoryOutputStream. * |[ @@ -58,8 +58,7 @@ out_data = g_memory_ouput_stream_get_data (G_MEMORY_OUTPUT_STREAM (stream)); ... * ]| - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/gio/gstgiostreamsrc.c b/gst/gio/gstgiostreamsrc.c index 0d91e0ab52..57fb9037a4 100644 --- a/gst/gio/gstgiostreamsrc.c +++ b/gst/gio/gstgiostreamsrc.c @@ -21,6 +21,7 @@ /** * SECTION:element-giostreamsrc + * @title: giostreamsrc * * This plugin reads data from a custom GIO #GInputStream. * @@ -28,9 +29,8 @@ * #GMemoryInputStream or to read from a file with a * #GFileInputStream. * - * - * Example code - * + * ## Example code + * * The following example reads data from a #GMemoryInputStream. * |[ @@ -58,8 +58,7 @@ g_object_set (G_OBJECT (src), "stream", stream, NULL); ... * ]| - * - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/playback/gstdecodebin2.c b/gst/playback/gstdecodebin2.c index 7e577bf5dd..439c3dc504 100644 --- a/gst/playback/gstdecodebin2.c +++ b/gst/playback/gstdecodebin2.c @@ -24,6 +24,7 @@ /** * SECTION:element-decodebin + * @title: decodebin * * #GstBin that auto-magically constructs a decoding pipeline using available * decoders and demuxers via auto-plugging. @@ -717,11 +718,9 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) * This signal is emitted whenever decodebin finds a new stream. It is * emitted before looking for any elements that can handle that stream. * - * - * Invocation of signal handlers stops after the first signal handler - * returns #FALSE. Signal handlers are invoked in the order they were - * connected in. - * + * > Invocation of signal handlers stops after the first signal handler + * > returns #FALSE. Signal handlers are invoked in the order they were + * > connected in. * * Returns: #TRUE if you wish decodebin to look for elements that can * handle the given @caps. If #FALSE, those caps will be considered as @@ -749,11 +748,9 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) * If this function returns an empty array, the pad will be considered as * having an unhandled type media type. * - * - * Only the signal handler that is connected first will ever by invoked. - * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this - * signal, they will never be invoked! - * + * > Only the signal handler that is connected first will ever by invoked. + * > Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * > signal, they will never be invoked! * * Returns: a #GValueArray* with a list of factories to try. The factories are * by default tried in the returned order or based on the index returned by @@ -781,13 +778,11 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) * The callee should copy and modify @factories or return #NULL if the * order should not change. * - * - * Invocation of signal handlers stops after one signal handler has - * returned something else than #NULL. Signal handlers are invoked in - * the order they were connected in. - * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this - * signal, they will never be invoked! - * + * > Invocation of signal handlers stops after one signal handler has + * > returned something else than #NULL. Signal handlers are invoked in + * > the order they were connected in. + * > Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * > signal, they will never be invoked! * * Returns: A new sorted array of #GstElementFactory objects. */ @@ -821,13 +816,11 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) * A value of #GST_AUTOPLUG_SELECT_SKIP will skip @factory and move to the * next factory. * - * - * The signal handler will not be invoked if any of the previously - * registered signal handlers (if any) return a value other than - * GST_AUTOPLUG_SELECT_TRY. Which also means that if you return - * GST_AUTOPLUG_SELECT_TRY from one signal handler, handlers that get - * registered next (again, if any) can override that decision. - * + * > The signal handler will not be invoked if any of the previously + * > registered signal handlers (if any) return a value other than + * > GST_AUTOPLUG_SELECT_TRY. Which also means that if you return + * > GST_AUTOPLUG_SELECT_TRY from one signal handler, handlers that get + * > registered next (again, if any) can override that decision. * * Returns: a #GST_TYPE_AUTOPLUG_SELECT_RESULT that indicates the required * operation. the default handler will always return diff --git a/gst/playback/gstdecodebin3.c b/gst/playback/gstdecodebin3.c index 0489781b4c..773f6246ae 100644 --- a/gst/playback/gstdecodebin3.c +++ b/gst/playback/gstdecodebin3.c @@ -36,6 +36,7 @@ /** * SECTION:element-decodebin3 + * @title: decodebin3 * * #GstBin that auto-magically constructs a decoding pipeline using available * decoders and demuxers via auto-plugging. The output is raw audio, video @@ -43,27 +44,20 @@ * * decodebin3 differs from the previous decodebin (decodebin2) in important ways: * - * - * - * supports publication and selection of stream information via + * * supports publication and selection of stream information via * GstStreamCollection messages and #GST_EVENT_SELECT_STREAM events. - * - * - * dynamically switches stream connections internally, and + * + * * dynamically switches stream connections internally, and * reuses decoder elements when stream selections change, so that in * the normal case it maintains 1 decoder of each type (video/audio/subtitle) * and only creates new elements when streams change and an existing decoder * is not capable of handling the new format. - * - * - * supports multiple input pads for the parallel decoding of auxilliary streams + * + * * supports multiple input pads for the parallel decoding of auxilliary streams * not muxed with the primary stream. - * - * - * does not handle network stream buffering. decodebin3 expects that network stream + * + * * does not handle network stream buffering. decodebin3 expects that network stream * buffering is handled upstream, before data is passed to it. - * - * * * decodebin3 is still experimental API and a technology preview. * Its behaviour and exposed API is subject to change. @@ -115,7 +109,6 @@ * * STREAM_START : * a new stream is starting => link it further if needed * - * * 3) Gradual replacement * * If the caps change at any point in decodebin (input sink pad, demuxer output, @@ -133,8 +126,6 @@ * b.1) The new CAPS are accepted, keep current configuration * b.2) The new CAPS are not accepted, remove following elements then do a) * - * - * * Components: * * MultiQ Output diff --git a/gst/playback/gstparsebin.c b/gst/playback/gstparsebin.c index 26d8769cf1..ce3c3174a5 100644 --- a/gst/playback/gstparsebin.c +++ b/gst/playback/gstparsebin.c @@ -27,6 +27,7 @@ /** * SECTION:element-parsebin + * @title: parsebin * * #GstBin that auto-magically constructs a parsing pipeline * using available parsers and demuxers via auto-plugging. @@ -648,11 +649,9 @@ gst_parse_bin_class_init (GstParseBinClass * klass) * This signal is emitted whenever ParseBin finds a new stream. It is * emitted before looking for any elements that can handle that stream. * - * - * Invocation of signal handlers stops after the first signal handler - * returns #FALSE. Signal handlers are invoked in the order they were - * connected in. - * + * > Invocation of signal handlers stops after the first signal handler + * > returns #FALSE. Signal handlers are invoked in the order they were + * > connected in. * * Returns: #TRUE if you wish ParseBin to look for elements that can * handle the given @caps. If #FALSE, those caps will be considered as @@ -680,11 +679,9 @@ gst_parse_bin_class_init (GstParseBinClass * klass) * If this function returns an empty array, the pad will be considered as * having an unhandled type media type. * - * - * Only the signal handler that is connected first will ever by invoked. - * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this - * signal, they will never be invoked! - * + * > Only the signal handler that is connected first will ever by invoked. + * > Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * > signal, they will never be invoked! * * Returns: a #GValueArray* with a list of factories to try. The factories are * by default tried in the returned order or based on the index returned by @@ -712,13 +709,11 @@ gst_parse_bin_class_init (GstParseBinClass * klass) * The callee should copy and modify @factories or return #NULL if the * order should not change. * - * - * Invocation of signal handlers stops after one signal handler has - * returned something else than #NULL. Signal handlers are invoked in - * the order they were connected in. - * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this - * signal, they will never be invoked! - * + * > Invocation of signal handlers stops after one signal handler has + * > returned something else than #NULL. Signal handlers are invoked in + * > the order they were connected in. + * > Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * > signal, they will never be invoked! * * Returns: A new sorted array of #GstElementFactory objects. */ @@ -752,13 +747,11 @@ gst_parse_bin_class_init (GstParseBinClass * klass) * A value of #GST_AUTOPLUG_SELECT_SKIP will skip @factory and move to the * next factory. * - * - * The signal handler will not be invoked if any of the previously - * registered signal handlers (if any) return a value other than - * GST_AUTOPLUG_SELECT_TRY. Which also means that if you return - * GST_AUTOPLUG_SELECT_TRY from one signal handler, handlers that get - * registered next (again, if any) can override that decision. - * + * > The signal handler will not be invoked if any of the previously + * > registered signal handlers (if any) return a value other than + * > GST_AUTOPLUG_SELECT_TRY. Which also means that if you return + * > GST_AUTOPLUG_SELECT_TRY from one signal handler, handlers that get + * > registered next (again, if any) can override that decision. * * Returns: a #GST_TYPE_AUTOPLUG_SELECT_RESULT that indicates the required * operation. the default handler will always return diff --git a/gst/playback/gstplaybin2.c b/gst/playback/gstplaybin2.c index b990be1ad7..397b8f6f81 100644 --- a/gst/playback/gstplaybin2.c +++ b/gst/playback/gstplaybin2.c @@ -22,43 +22,26 @@ /** * SECTION:element-playbin + * @title: playbin * * Playbin provides a stand-alone everything-in-one abstraction for an * audio and/or video player. * * Playbin can handle both audio and video files and features - * - * - * automatic file type recognition and based on that automatic - * selection and usage of the right audio/video/subtitle demuxers/decoders - * - * - * visualisations for audio files - * - * - * subtitle support for video files. Subtitles can be store in external - * files. - * - * - * stream selection between different video/audio/subtitles streams - * - * - * meta info (tag) extraction - * - * - * easy access to the last video sample - * - * - * buffering when playing streams over a network - * - * - * volume control with mute option - * - * * - * - * Usage - * + * * automatic file type recognition and based on that automatic + * selection and usage of the right audio/video/subtitle demuxers/decoders + * * visualisations for audio files + * * subtitle support for video files. Subtitles can be store in external + * files. + * * stream selection between different video/audio/subtitles streams + * * meta info (tag) extraction + * * easy access to the last video sample + * * buffering when playing streams over a network + * * volume control with mute option + * + * ## Usage + * * A playbin element can be created just like any other element using * gst_element_factory_make(). The file/URI to play should be set via the #GstPlayBin:uri * property. This must be an absolute URI, relative file paths are not allowed. @@ -94,11 +77,9 @@ * via gst_element_query_position() and gst_element_query_duration() and * setting the format passed to GST_FORMAT_TIME. If the query was successful, * the duration or position will have been returned in units of nanoseconds. - * - * - * - * Advanced Usage: specifying the audio and video sink - * + * + * ## Advanced Usage: specifying the audio and video sink + * * By default, if no audio sink or video sink has been specified via the * #GstPlayBin:audio-sink or #GstPlayBin:video-sink property, playbin will use the autoaudiosink * and autovideosink elements to find the first-best available output method. @@ -128,21 +109,17 @@ * It is also possible to 'suppress' audio and/or video output by using * 'fakesink' elements (or capture it from there using the fakesink element's * "handoff" signal, which, nota bene, is fired from the streaming thread!). - * - * - * - * Retrieving Tags and Other Meta Data - * + * + * ## Retrieving Tags and Other Meta Data + * * Most of the common meta data (artist, title, etc.) can be retrieved by * watching for TAG messages on the pipeline's bus (see above). * * Other more specific meta information like width/height/framerate of video * streams or samplerate/number of channels of audio streams can be obtained * from the negotiated caps on the sink pads of the sinks. - * - * - * - * Buffering + * + * ## Buffering * Playbin handles buffering automatically for the most part, but applications * need to handle parts of the buffering process as well. Whenever playbin is * buffering, it will post BUFFERING messages on the bus with a percentage @@ -161,20 +138,19 @@ * ... * } * ]| + * * Note that applications should keep/set the pipeline in the PAUSED state when * a BUFFERING message is received with a buffer percent value < 100 and set * the pipeline back to PLAYING state when a BUFFERING message with a value * of 100 percent is received (if PLAYING is the desired state, that is). - * - * - * Embedding the video window in your application + * + * ## Embedding the video window in your application * By default, playbin (or rather the video sinks used) will create their own * window. Applications will usually want to force output to a window of their * own, however. This can be done using the #GstVideoOverlay interface, which most * video sinks implement. See the documentation there for more details. - * - * - * Specifying which CD/DVD device to use + * + * ## Specifying which CD/DVD device to use * The device to use for CDs/DVDs needs to be set on the source element * playbin creates before it is opened. The most generic way of doing this * is to connect to playbin's "source-setup" (or "notify::source") signal, @@ -185,35 +161,35 @@ * elements involved if this will work or not. For example, for DVD menu * playback, the following syntax might work (if the resindvd plugin is used): * dvd://[/path/to/device] - * - * - * Handling redirects - * + * + * ## Handling redirects + * * Some elements may post 'redirect' messages on the bus to tell the * application to open another location. These are element messages containing * a structure named 'redirect' along with a 'new-location' field of string * type. The new location may be a relative or an absolute URI. Examples * for such redirects can be found in many quicktime movie trailers. - * - * - * - * Examples + * + * ## Examples * |[ * gst-launch-1.0 -v playbin uri=file:///path/to/somefile.mp4 - * ]| This will play back the given AVI video file, given that the video and + * ]| + * This will play back the given AVI video file, given that the video and * audio decoders required to decode the content are installed. Since no * special audio sink or video sink is supplied (via playbin's audio-sink or * video-sink properties) playbin will try to find a suitable audio and * video sink automatically using the autoaudiosink and autovideosink elements. * |[ * gst-launch-1.0 -v playbin uri=cdda://4 - * ]| This will play back track 4 on an audio CD in your disc drive (assuming + * ]| + * This will play back track 4 on an audio CD in your disc drive (assuming * the drive is detected automatically by the plugin). * |[ * gst-launch-1.0 -v playbin uri=dvd:// - * ]| This will play back the DVD in your disc drive (assuming + * ]| + * This will play back the DVD in your disc drive (assuming * the drive is detected automatically by the plugin). - * + * */ /* FIXME 0.11: suppress warnings for deprecated API such as GValueArray @@ -4656,7 +4632,7 @@ autoplug_select_cb (GstElement * decodebin, GstPad * pad, ave_list = g_list_prepend (ave_list, NULL); } - /* if it is a decoder and we don't have a fixed sink, then find out + /* if it is a decoder and we don't have a fixed sink, then find out * the matching audio/video sink from GstAVElements list */ for (l = ave_list; l; l = l->next) { gboolean created_sink = FALSE; @@ -4845,7 +4821,7 @@ autoplug_select_cb (GstElement * decodebin, GstPad * pad, } /* remember the sink in the group now, the element is floating, we take - * ownership now + * ownership now * * store the sink in the group, we will configure it later when we * reconfigure the sink */ diff --git a/gst/playback/gstplaybin3.c b/gst/playback/gstplaybin3.c index 51eb1edc9c..e1397ba80e 100644 --- a/gst/playback/gstplaybin3.c +++ b/gst/playback/gstplaybin3.c @@ -23,6 +23,7 @@ /** * SECTION:element-playbin3 + * @title: playbin3 * * playbin3 provides a stand-alone everything-in-one abstraction for an * audio and/or video player. It differs from the previous playbin (playbin2) @@ -33,41 +34,22 @@ * Its behaviour and exposed API is subject to change. * * playbin3 can handle both audio and video files and features - * - * - * automatic file type recognition and based on that automatic - * selection and usage of the right audio/video/subtitle demuxers/decoders - * - * - * auxilliary files - such as external subtitles and audio tracks - * - * - * visualisations for audio files - * - * - * subtitle support for video files. Subtitles can be store in external - * files. - * - * - * stream selection between different video/audio/subtitles streams - * - * - * meta info (tag) extraction - * - * - * easy access to the last video sample - * - * - * buffering when playing streams over a network - * - * - * volume control with mute option - * - * * - * - * Usage - * + * * automatic file type recognition and based on that automatic + * selection and usage of the right audio/video/subtitle demuxers/decoders + * + * * auxilliary files - such as external subtitles and audio tracks + * * visualisations for audio files + * * subtitle support for video files. Subtitles can be store in external + * files. + * * stream selection between different video/audio/subtitles streams + * * meta info (tag) extraction + * * easy access to the last video sample + * * buffering when playing streams over a network + * * volume control with mute option + * + * ## Usage + * * A playbin element can be created just like any other element using * gst_element_factory_make(). The file/URI to play should be set via the #GstPlayBin3:uri * property. This must be an absolute URI, relative file paths are not allowed. @@ -103,11 +85,9 @@ * via gst_element_query_position() and gst_element_query_duration() and * setting the format passed to GST_FORMAT_TIME. If the query was successful, * the duration or position will have been returned in units of nanoseconds. - * - * - * - * Advanced Usage: specifying the audio and video sink - * + * + * ## Advanced Usage: specifying the audio and video sink + * * By default, if no audio sink or video sink has been specified via the * #GstPlayBin3:audio-sink or #GstPlayBin3:video-sink property, playbin3 will use the autoaudiosink * and autovideosink elements to find the first-best available output method. @@ -137,21 +117,17 @@ * It is also possible to 'suppress' audio and/or video output by using * 'fakesink' elements (or capture it from there using the fakesink element's * "handoff" signal, which, nota bene, is fired from the streaming thread!). - * - * - * - * Retrieving Tags and Other Meta Data - * + * + * ## Retrieving Tags and Other Meta Data + * * Most of the common meta data (artist, title, etc.) can be retrieved by * watching for TAG messages on the pipeline's bus (see above). * * Other more specific meta information like width/height/framerate of video * streams or samplerate/number of channels of audio streams can be obtained * from the negotiated caps on the sink pads of the sinks. - * - * - * - * Buffering + * + * ## Buffering * Playbin3 handles buffering automatically for the most part, but applications * need to handle parts of the buffering process as well. Whenever playbin3 is * buffering, it will post BUFFERING messages on the bus with a percentage @@ -170,20 +146,19 @@ * ... * } * ]| + * * Note that applications should keep/set the pipeline in the PAUSED state when * a BUFFERING message is received with a buffer percent value < 100 and set * the pipeline back to PLAYING state when a BUFFERING message with a value * of 100 percent is received (if PLAYING is the desired state, that is). - * - * - * Embedding the video window in your application + * + * ## Embedding the video window in your application * By default, playbin3 (or rather the video sinks used) will create their own * window. Applications will usually want to force output to a window of their * own, however. This can be done using the #GstVideoOverlay interface, which most * video sinks implement. See the documentation there for more details. - * - * - * Specifying which CD/DVD device to use + * + * ## Specifying which CD/DVD device to use * The device to use for CDs/DVDs needs to be set on the source element * playbin3 creates before it is opened. The most generic way of doing this * is to connect to playbin3's "source-setup" (or "notify::source") signal, @@ -194,35 +169,35 @@ * elements involved if this will work or not. For example, for DVD menu * playback, the following syntax might work (if the resindvd plugin is used): * dvd://[/path/to/device] - * - * - * Handling redirects - * + * + * ## Handling redirects + * * Some elements may post 'redirect' messages on the bus to tell the * application to open another location. These are element messages containing * a structure named 'redirect' along with a 'new-location' field of string * type. The new location may be a relative or an absolute URI. Examples * for such redirects can be found in many quicktime movie trailers. - * - * - * - * Examples + * + * ## Examples * |[ * gst-launch-1.0 -v playbin3 uri=file:///path/to/somefile.mp4 - * ]| This will play back the given AVI video file, given that the video and + * ]| + * This will play back the given AVI video file, given that the video and * audio decoders required to decode the content are installed. Since no * special audio sink or video sink is supplied (via playbin3's audio-sink or * video-sink properties) playbin3 will try to find a suitable audio and * video sink automatically using the autoaudiosink and autovideosink elements. * |[ * gst-launch-1.0 -v playbin3 uri=cdda://4 - * ]| This will play back track 4 on an audio CD in your disc drive (assuming + * ]| + * This will play back track 4 on an audio CD in your disc drive (assuming * the drive is detected automatically by the plugin). * |[ * gst-launch-1.0 -v playbin3 uri=dvd:// - * ]| This will play back the DVD in your disc drive (assuming + * ]| + * This will play back the DVD in your disc drive (assuming * the drive is detected automatically by the plugin). - * + * */ /* FIXME 0.11: suppress warnings for deprecated API such as GValueArray diff --git a/gst/playback/gstsubtitleoverlay.c b/gst/playback/gstsubtitleoverlay.c index c4c3cd26de..6134330dab 100644 --- a/gst/playback/gstsubtitleoverlay.c +++ b/gst/playback/gstsubtitleoverlay.c @@ -19,6 +19,7 @@ /** * SECTION:element-subtitleoverlay + * @title: subtitleoverlay * * #GstBin that auto-magically overlays a video stream with subtitles by * autoplugging the required elements. @@ -26,12 +27,12 @@ * It supports raw, timestamped text, different textual subtitle formats and * DVD subpicture subtitles. * - * - * Examples + * ## Examples * |[ * gst-launch-1.0 -v filesrc location=test.mkv ! matroskademux name=demux ! video/x-h264 ! queue ! decodebin ! subtitleoverlay name=overlay ! videoconvert ! autovideosink demux. ! subpicture/x-dvd ! queue ! overlay. - * ]| This will play back the given Matroska file with h264 video and dvd subpicture style subtitles. - * + * ]| + * This will play back the given Matroska file with h264 video and dvd subpicture style subtitles. + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/playback/gsturidecodebin.c b/gst/playback/gsturidecodebin.c index d5c03078b3..45e92511b0 100644 --- a/gst/playback/gsturidecodebin.c +++ b/gst/playback/gsturidecodebin.c @@ -19,6 +19,7 @@ /** * SECTION:element-uridecodebin + * @title: uridecodebin * * Decodes data from a URI into raw media. It selects a source element that can * handle the given #GstURIDecodeBin:uri scheme and connects it to a decodebin. @@ -470,7 +471,7 @@ gst_uri_decode_bin_class_init (GstURIDecodeBinClass * klass) * If set to %FALSE, then only the streams that can be decoded to the final * caps (see 'caps' property) will have a pad exposed. Streams that do not * match those caps but could have been decoded will not have decoder plugged - * in internally and will not have a pad exposed. + * in internally and will not have a pad exposed. * * Since: 0.10.30 */ @@ -520,11 +521,9 @@ gst_uri_decode_bin_class_init (GstURIDecodeBinClass * klass) * This signal is emitted whenever uridecodebin finds a new stream. It is * emitted before looking for any elements that can handle that stream. * - * - * Invocation of signal handlers stops after the first signal handler - * returns #FALSE. Signal handlers are invoked in the order they were - * connected in. - * + * > Invocation of signal handlers stops after the first signal handler + * > returns #FALSE. Signal handlers are invoked in the order they were + * > connected in. * * Returns: #TRUE if you wish uridecodebin to look for elements that can * handle the given @caps. If #FALSE, those caps will be considered as @@ -553,11 +552,9 @@ gst_uri_decode_bin_class_init (GstURIDecodeBinClass * klass) * If this function returns an empty array, the pad will be considered as * having an unhandled type media type. * - * - * Only the signal handler that is connected first will ever by invoked. - * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this - * signal, they will never be invoked! - * + * > Only the signal handler that is connected first will ever by invoked. + * > Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * > signal, they will never be invoked! * * Returns: a #GValueArray* with a list of factories to try. The factories are * by default tried in the returned order or based on the index returned by @@ -585,13 +582,11 @@ gst_uri_decode_bin_class_init (GstURIDecodeBinClass * klass) * The callee should copy and modify @factories or return #NULL if the * order should not change. * - * - * Invocation of signal handlers stops after one signal handler has - * returned something else than #NULL. Signal handlers are invoked in - * the order they were connected in. - * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this - * signal, they will never be invoked! - * + * > Invocation of signal handlers stops after one signal handler has + * > returned something else than #NULL. Signal handlers are invoked in + * > the order they were connected in. + * > Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * > signal, they will never be invoked! * * Returns: A new sorted array of #GstElementFactory objects. * @@ -627,13 +622,11 @@ gst_uri_decode_bin_class_init (GstURIDecodeBinClass * klass) * A value of #GST_AUTOPLUG_SELECT_SKIP will skip @factory and move to the * next factory. * - * - * The signal handler will not be invoked if any of the previously - * registered signal handlers (if any) return a value other than - * GST_AUTOPLUG_SELECT_TRY. Which also means that if you return - * GST_AUTOPLUG_SELECT_TRY from one signal handler, handlers that get - * registered next (again, if any) can override that decision. - * + * > The signal handler will not be invoked if any of the previously + * > registered signal handlers (if any) return a value other than + * > GST_AUTOPLUG_SELECT_TRY. Which also means that if you return + * > GST_AUTOPLUG_SELECT_TRY from one signal handler, handlers that get + * > registered next (again, if any) can override that decision. * * Returns: a #GST_TYPE_AUTOPLUG_SELECT_RESULT that indicates the required * operation. The default handler will always return diff --git a/gst/playback/gsturisourcebin.c b/gst/playback/gsturisourcebin.c index 6bd6e101b7..715f861f14 100644 --- a/gst/playback/gsturisourcebin.c +++ b/gst/playback/gsturisourcebin.c @@ -20,6 +20,7 @@ /** * SECTION:element-urisourcebin + * @title: urisourcebin * * urisourcebin is an element for accessing URIs in a uniform manner. * @@ -524,11 +525,9 @@ gst_uri_source_bin_class_init (GstURISourceBinClass * klass) * This signal is emitted whenever urisourcebin finds a new stream. It is * emitted before looking for any elements that can handle that stream. * - * - * Invocation of signal handlers stops after the first signal handler - * returns #FALSE. Signal handlers are invoked in the order they were - * connected in. - * + * > Invocation of signal handlers stops after the first signal handler + * > returns #FALSE. Signal handlers are invoked in the order they were + * > connected in. * * Returns: #TRUE if you wish urisourcebin to look for elements that can * handle the given @caps. If #FALSE, those caps will be considered as @@ -557,11 +556,9 @@ gst_uri_source_bin_class_init (GstURISourceBinClass * klass) * If this function returns an empty array, the pad will be considered as * having an unhandled type media type. * - * - * Only the signal handler that is connected first will ever by invoked. - * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this - * signal, they will never be invoked! - * + * > Only the signal handler that is connected first will ever by invoked. + * > Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * > signal, they will never be invoked! * * Returns: a #GValueArray* with a list of factories to try. The factories are * by default tried in the returned order or based on the index returned by @@ -589,13 +586,11 @@ gst_uri_source_bin_class_init (GstURISourceBinClass * klass) * The callee should copy and modify @factories or return #NULL if the * order should not change. * - * - * Invocation of signal handlers stops after one signal handler has - * returned something else than #NULL. Signal handlers are invoked in - * the order they were connected in. - * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this - * signal, they will never be invoked! - * + * > Invocation of signal handlers stops after one signal handler has + * > returned something else than #NULL. Signal handlers are invoked in + * > the order they were connected in. + * > Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * > signal, they will never be invoked! * * Returns: A new sorted array of #GstElementFactory objects. * @@ -631,13 +626,11 @@ gst_uri_source_bin_class_init (GstURISourceBinClass * klass) * A value of #GST_AUTOPLUG_SELECT_SKIP will skip @factory and move to the * next factory. * - * - * The signal handler will not be invoked if any of the previously - * registered signal handlers (if any) return a value other than - * GST_AUTOPLUG_SELECT_TRY. Which also means that if you return - * GST_AUTOPLUG_SELECT_TRY from one signal handler, handlers that get - * registered next (again, if any) can override that decision. - * + * > The signal handler will not be invoked if any of the previously + * > registered signal handlers (if any) return a value other than + * > GST_AUTOPLUG_SELECT_TRY. Which also means that if you return + * > GST_AUTOPLUG_SELECT_TRY from one signal handler, handlers that get + * > registered next (again, if any) can override that decision. * * Returns: a #GST_TYPE_AUTOPLUG_SELECT_RESULT that indicates the required * operation. The default handler will always return diff --git a/gst/rawparse/gstrawaudioparse.c b/gst/rawparse/gstrawaudioparse.c index d6578a3ad5..1df015865f 100644 --- a/gst/rawparse/gstrawaudioparse.c +++ b/gst/rawparse/gstrawaudioparse.c @@ -19,6 +19,7 @@ /** * SECTION:element-rawaudioparse + * @title: rawaudioparse * * This element parses incoming data as raw audio samples and timestamps it. * It also handles seek queries in said raw audio data, and ensures that output @@ -52,23 +53,24 @@ * GStreamer positioning is used. This property is also useful for swapping left * and right in a stereo signal for example. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 souphttpsrc http://my-dlna-server/track.l16 \ * rawaudioparse ! audioconvert ! audioresample ! autoaudiosink - * ]| Receive L16 data from a DLNA server, parse and timestamp it with + * ]| + * Receive L16 data from a DLNA server, parse and timestamp it with * rawaudioparse, and play it. use-sink-caps is set to true since souphttpsrc * will set its source pad's caps to audio/x-unaligned-raw for the L16 stream. * |[ * gst-launch-1.0 filesrc location=audio.raw ! rawaudioparse use-sink-caps=false \ * format=pcm pcm-format=s16le sample-rate=48000 num-channels=2 \ * audioconvert ! audioresample ! autoaudiosink - * ]| Read raw data from a local file and parse it as PCM data with 48000 Hz sample + * ]| + * Read raw data from a local file and parse it as PCM data with 48000 Hz sample * rate, signed 16 bit integer samples, and 2 channels. use-sink-caps is set to * false to ensure the property information is used and the parser does not expect * audio/x-raw or audio/x-unaligned-raw caps. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/rawparse/gstrawvideoparse.c b/gst/rawparse/gstrawvideoparse.c index 38fc5589ad..03baec2435 100644 --- a/gst/rawparse/gstrawvideoparse.c +++ b/gst/rawparse/gstrawvideoparse.c @@ -19,6 +19,7 @@ /** * SECTION:element-rawvideoparse + * @title: rawvideoparse * * This element parses incoming data as raw video frames and timestamps these. * It also handles seek queries in said raw video data, and ensures that output @@ -43,7 +44,7 @@ * plane-array properties. * * The frame stride property is useful in cases where there is extra data between - * the frames (for example, trailing metadata, or headers). The parser calculates + * the frames (for example, trailing metadata, or headers). The parser calculates * the actual frame size out of the other properties and compares it with this * frame-stride value. If the frame stride is larger than the calculated size, * then the extra bytes after the end of the frame are skipped. For example, with @@ -57,21 +58,22 @@ * no duration set. The first output buffer will have a PTS 0, all subsequent ones * an unset PTS. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 filesrc location=video.raw ! rawvideoparse use-sink-caps=false \ * width=500 height=400 format=y444 ! autovideosink - * ]| Read raw data from a local file and parse it as video data with 500x400 pixels + * ]| + * Read raw data from a local file and parse it as video data with 500x400 pixels * and Y444 video format. * |[ * gst-launch-1.0 filesrc location=video.raw ! queue ! "video/x-raw, width=320, \ * height=240, format=I420, framerate=1/1" ! rawvideoparse \ * use-sink-caps=true ! autovideosink - * ]| Read raw data from a local file and parse it as video data with 320x240 pixels + * ]| + * Read raw data from a local file and parse it as video data with 320x240 pixels * and I420 video format. The queue element here is to force push based scheduling. * See the documentation in #GstRawBaseParse for the reason why. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/tcp/gstmultifdsink.c b/gst/tcp/gstmultifdsink.c index 2b1b44dd71..095195d715 100644 --- a/gst/tcp/gstmultifdsink.c +++ b/gst/tcp/gstmultifdsink.c @@ -21,17 +21,18 @@ /** * SECTION:element-multifdsink + * @title: multifdsink * @see_also: tcpserversink * * This plugin writes incoming data to a set of file descriptors. The - * file descriptors can be added to multifdsink by emitting the #GstMultiFdSink::add signal. + * file descriptors can be added to multifdsink by emitting the #GstMultiFdSink::add signal. * For each descriptor added, the #GstMultiFdSink::client-added signal will be called. * * The multifdsink element needs to be set into READY, PAUSED or PLAYING state * before operations such as adding clients are possible. * * A client can also be added with the #GstMultiFdSink::add-full signal - * that allows for more control over what and how much data a client + * that allows for more control over what and how much data a client * initially receives. * * Clients can be removed from multifdsink by emitting the #GstMultiFdSink::remove signal. For @@ -45,7 +46,7 @@ * Note that multifdsink still has a reference to the file descriptor when the * #GstMultiFdSink::client-removed signal is emitted, so that "get-stats" can be performed on * the descriptor; it is therefore not safe to close the file descriptor in - * the #GstMultiFdSink::client-removed signal handler, and you should use the + * the #GstMultiFdSink::client-removed signal handler, and you should use the * #GstMultiFdSink::client-fd-removed signal to safely close the fd. * * Multifdsink internally keeps a queue of the incoming buffers and uses a @@ -54,34 +55,34 @@ * speeds. * * When adding a client to multifdsink, the #GstMultiFdSink:sync-method property will define - * which buffer in the queued buffers will be sent first to the client. Clients - * can be sent the most recent buffer (which might not be decodable by the - * client if it is not a keyframe), the next keyframe received in + * which buffer in the queued buffers will be sent first to the client. Clients + * can be sent the most recent buffer (which might not be decodable by the + * client if it is not a keyframe), the next keyframe received in * multifdsink (which can take some time depending on the keyframe rate), or the - * last received keyframe (which will cause a simple burst-on-connect). + * last received keyframe (which will cause a simple burst-on-connect). * Multifdsink will always keep at least one keyframe in its internal buffers * when the sync-mode is set to latest-keyframe. * * There are additional values for the #GstMultiFdSink:sync-method * property to allow finer control over burst-on-connect behaviour. By selecting * the 'burst' method a minimum burst size can be chosen, 'burst-keyframe' - * additionally requires that the burst begin with a keyframe, and + * additionally requires that the burst begin with a keyframe, and * 'burst-with-keyframe' attempts to burst beginning with a keyframe, but will * prefer a minimum burst size even if it requires not starting with a keyframe. * * Multifdsink can be instructed to keep at least a minimum amount of data - * expressed in time or byte units in its internal queues with the + * expressed in time or byte units in its internal queues with the * #GstMultiFdSink:time-min and #GstMultiFdSink:bytes-min properties respectively. - * These properties are useful if the application adds clients with the + * These properties are useful if the application adds clients with the * #GstMultiFdSink::add-full signal to make sure that a burst connect can - * actually be honored. + * actually be honored. * * When streaming data, clients are allowed to read at a different rate than * the rate at which multifdsink receives data. If the client is reading too * fast, no data will be send to the client until multifdsink receives more - * data. If the client, however, reads too slowly, data for that client will be - * queued up in multifdsink. Two properties control the amount of data - * (buffers) that is queued in multifdsink: #GstMultiFdSink:buffers-max and + * data. If the client, however, reads too slowly, data for that client will be + * queued up in multifdsink. Two properties control the amount of data + * (buffers) that is queued in multifdsink: #GstMultiFdSink:buffers-max and * #GstMultiFdSink:buffers-soft-max. A client that falls behind by * #GstMultiFdSink:buffers-max is removed from multifdsink forcibly. * @@ -93,8 +94,8 @@ * RESYNC_KEYFRAME positions the client at the most recent keyframe in the * buffer queue. * - * multifdsink will by default synchronize on the clock before serving the - * buffers to the clients. This behaviour can be disabled by setting the sync + * multifdsink will by default synchronize on the clock before serving the + * buffers to the clients. This behaviour can be disabled by setting the sync * property to FALSE. Multifdsink will by default not do QoS and will never * drop late buffers. */ diff --git a/gst/tcp/gstmultihandlesink.c b/gst/tcp/gstmultihandlesink.c index 70f313ec30..439fdb66dd 100644 --- a/gst/tcp/gstmultihandlesink.c +++ b/gst/tcp/gstmultihandlesink.c @@ -23,14 +23,15 @@ /** * SECTION:element-multihandlesink + * @title: multihandlesink * @see_also: tcpserversink * * This plugin writes incoming data to a set of file descriptors. The - * file descriptors can be added to multihandlesink by emitting the #GstMultiHandleSink::add signal. + * file descriptors can be added to multihandlesink by emitting the #GstMultiHandleSink::add signal. * For each descriptor added, the #GstMultiHandleSink::client-added signal will be called. * * A client can also be added with the #GstMultiHandleSink::add-full signal - * that allows for more control over what and how much data a client + * that allows for more control over what and how much data a client * initially receives. * * Clients can be removed from multihandlesink by emitting the #GstMultiHandleSink::remove signal. For @@ -44,7 +45,7 @@ * Note that multihandlesink still has a reference to the file descriptor when the * #GstMultiHandleSink::client-removed signal is emitted, so that "get-stats" can be performed on * the descriptor; it is therefore not safe to close the file descriptor in - * the #GstMultiHandleSink::client-removed signal handler, and you should use the + * the #GstMultiHandleSink::client-removed signal handler, and you should use the * #GstMultiHandleSink::client-fd-removed signal to safely close the fd. * * Multisocketsink internally keeps a queue of the incoming buffers and uses a @@ -53,34 +54,34 @@ * speeds. * * When adding a client to multihandlesink, the #GstMultiHandleSink:sync-method property will define - * which buffer in the queued buffers will be sent first to the client. Clients - * can be sent the most recent buffer (which might not be decodable by the - * client if it is not a keyframe), the next keyframe received in + * which buffer in the queued buffers will be sent first to the client. Clients + * can be sent the most recent buffer (which might not be decodable by the + * client if it is not a keyframe), the next keyframe received in * multihandlesink (which can take some time depending on the keyframe rate), or the - * last received keyframe (which will cause a simple burst-on-connect). + * last received keyframe (which will cause a simple burst-on-connect). * Multisocketsink will always keep at least one keyframe in its internal buffers * when the sync-mode is set to latest-keyframe. * * There are additional values for the #GstMultiHandleSink:sync-method * property to allow finer control over burst-on-connect behaviour. By selecting * the 'burst' method a minimum burst size can be chosen, 'burst-keyframe' - * additionally requires that the burst begin with a keyframe, and + * additionally requires that the burst begin with a keyframe, and * 'burst-with-keyframe' attempts to burst beginning with a keyframe, but will * prefer a minimum burst size even if it requires not starting with a keyframe. * * Multisocketsink can be instructed to keep at least a minimum amount of data - * expressed in time or byte units in its internal queues with the + * expressed in time or byte units in its internal queues with the * #GstMultiHandleSink:time-min and #GstMultiHandleSink:bytes-min properties respectively. - * These properties are useful if the application adds clients with the + * These properties are useful if the application adds clients with the * #GstMultiHandleSink::add-full signal to make sure that a burst connect can - * actually be honored. + * actually be honored. * * When streaming data, clients are allowed to read at a different rate than * the rate at which multihandlesink receives data. If the client is reading too * fast, no data will be send to the client until multihandlesink receives more - * data. If the client, however, reads too slowly, data for that client will be - * queued up in multihandlesink. Two properties control the amount of data - * (buffers) that is queued in multihandlesink: #GstMultiHandleSink:buffers-max and + * data. If the client, however, reads too slowly, data for that client will be + * queued up in multihandlesink. Two properties control the amount of data + * (buffers) that is queued in multihandlesink: #GstMultiHandleSink:buffers-max and * #GstMultiHandleSink:buffers-soft-max. A client that falls behind by * #GstMultiHandleSink:buffers-max is removed from multihandlesink forcibly. * @@ -92,8 +93,8 @@ * RESYNC_KEYFRAME positions the client at the most recent keyframe in the * buffer queue. * - * multihandlesink will by default synchronize on the clock before serving the - * buffers to the clients. This behaviour can be disabled by setting the sync + * multihandlesink will by default synchronize on the clock before serving the + * buffers to the clients. This behaviour can be disabled by setting the sync * property to FALSE. Multisocketsink will by default not do QoS and will never * drop late buffers. */ diff --git a/gst/tcp/gstmultihandlesink.h b/gst/tcp/gstmultihandlesink.h index 5647965789..9dfabee880 100644 --- a/gst/tcp/gstmultihandlesink.h +++ b/gst/tcp/gstmultihandlesink.h @@ -78,7 +78,7 @@ typedef enum * @GST_SYNC_METHOD_NEXT_KEYFRAME : client receives next keyframe * @GST_SYNC_METHOD_LATEST_KEYFRAME : client receives latest keyframe (burst) * @GST_SYNC_METHOD_BURST : client receives specific amount of data - * @GST_SYNC_METHOD_BURST_KEYFRAME : client receives specific amount of data + * @GST_SYNC_METHOD_BURST_KEYFRAME : client receives specific amount of data * starting from latest keyframe * @GST_SYNC_METHOD_BURST_WITH_KEYFRAME : client receives specific amount of data from * a keyframe, or if there is not enough data after diff --git a/gst/tcp/gstmultisocketsink.c b/gst/tcp/gstmultisocketsink.c index 2f1a9ae19a..e47cfb8e8c 100644 --- a/gst/tcp/gstmultisocketsink.c +++ b/gst/tcp/gstmultisocketsink.c @@ -23,14 +23,15 @@ /** * SECTION:element-multisocketsink + * @title: multisocketsink * @see_also: tcpserversink * * This plugin writes incoming data to a set of file descriptors. The - * file descriptors can be added to multisocketsink by emitting the #GstMultiSocketSink::add signal. + * file descriptors can be added to multisocketsink by emitting the #GstMultiSocketSink::add signal. * For each descriptor added, the #GstMultiSocketSink::client-added signal will be called. * * A client can also be added with the #GstMultiSocketSink::add-full signal - * that allows for more control over what and how much data a client + * that allows for more control over what and how much data a client * initially receives. * * Clients can be removed from multisocketsink by emitting the #GstMultiSocketSink::remove signal. For @@ -44,7 +45,7 @@ * Note that multisocketsink still has a reference to the file descriptor when the * #GstMultiSocketSink::client-removed signal is emitted, so that "get-stats" can be performed on * the descriptor; it is therefore not safe to close the file descriptor in - * the #GstMultiSocketSink::client-removed signal handler, and you should use the + * the #GstMultiSocketSink::client-removed signal handler, and you should use the * #GstMultiSocketSink::client-fd-removed signal to safely close the fd. * * Multisocketsink internally keeps a queue of the incoming buffers and uses a @@ -53,34 +54,34 @@ * speeds. * * When adding a client to multisocketsink, the #GstMultiSocketSink:sync-method property will define - * which buffer in the queued buffers will be sent first to the client. Clients - * can be sent the most recent buffer (which might not be decodable by the - * client if it is not a keyframe), the next keyframe received in + * which buffer in the queued buffers will be sent first to the client. Clients + * can be sent the most recent buffer (which might not be decodable by the + * client if it is not a keyframe), the next keyframe received in * multisocketsink (which can take some time depending on the keyframe rate), or the - * last received keyframe (which will cause a simple burst-on-connect). + * last received keyframe (which will cause a simple burst-on-connect). * Multisocketsink will always keep at least one keyframe in its internal buffers * when the sync-mode is set to latest-keyframe. * * There are additional values for the #GstMultiSocketSink:sync-method * property to allow finer control over burst-on-connect behaviour. By selecting * the 'burst' method a minimum burst size can be chosen, 'burst-keyframe' - * additionally requires that the burst begin with a keyframe, and + * additionally requires that the burst begin with a keyframe, and * 'burst-with-keyframe' attempts to burst beginning with a keyframe, but will * prefer a minimum burst size even if it requires not starting with a keyframe. * * Multisocketsink can be instructed to keep at least a minimum amount of data - * expressed in time or byte units in its internal queues with the + * expressed in time or byte units in its internal queues with the * #GstMultiSocketSink:time-min and #GstMultiSocketSink:bytes-min properties respectively. - * These properties are useful if the application adds clients with the + * These properties are useful if the application adds clients with the * #GstMultiSocketSink::add-full signal to make sure that a burst connect can - * actually be honored. + * actually be honored. * * When streaming data, clients are allowed to read at a different rate than * the rate at which multisocketsink receives data. If the client is reading too * fast, no data will be send to the client until multisocketsink receives more - * data. If the client, however, reads too slowly, data for that client will be - * queued up in multisocketsink. Two properties control the amount of data - * (buffers) that is queued in multisocketsink: #GstMultiSocketSink:buffers-max and + * data. If the client, however, reads too slowly, data for that client will be + * queued up in multisocketsink. Two properties control the amount of data + * (buffers) that is queued in multisocketsink: #GstMultiSocketSink:buffers-max and * #GstMultiSocketSink:buffers-soft-max. A client that falls behind by * #GstMultiSocketSink:buffers-max is removed from multisocketsink forcibly. * @@ -92,8 +93,8 @@ * RESYNC_KEYFRAME positions the client at the most recent keyframe in the * buffer queue. * - * multisocketsink will by default synchronize on the clock before serving the - * buffers to the clients. This behaviour can be disabled by setting the sync + * multisocketsink will by default synchronize on the clock before serving the + * buffers to the clients. This behaviour can be disabled by setting the sync * property to FALSE. Multisocketsink will by default not do QoS and will never * drop late buffers. */ diff --git a/gst/tcp/gstsocketsrc.c b/gst/tcp/gstsocketsrc.c index e22c0712f8..0372f91a3b 100644 --- a/gst/tcp/gstsocketsrc.c +++ b/gst/tcp/gstsocketsrc.c @@ -23,6 +23,7 @@ /** * SECTION:element-socketsrc + * @title: socketsrc * * Receive data from a socket. * diff --git a/gst/tcp/gsttcpclientsink.c b/gst/tcp/gsttcpclientsink.c index 5e96e76743..5e41e98c31 100644 --- a/gst/tcp/gsttcpclientsink.c +++ b/gst/tcp/gsttcpclientsink.c @@ -22,18 +22,19 @@ /** * SECTION:element-tcpclientsink + * @title: tcpclientsink * @see_also: #tcpclientsink * - * - * Example launch line + * ## Example launch line * |[ * # server: * nc -l -p 3000 * # client: * gst-launch-1.0 fdsink fd=1 ! tcpclientsink port=3000 - * ]| everything you type in the client is shown on the server (fd=1 means + * ]| + * everything you type in the client is shown on the server (fd=1 means * standard input which is the command line input file descriptor) - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/tcp/gsttcpclientsrc.c b/gst/tcp/gsttcpclientsrc.c index 756b479eb2..e5e029980e 100644 --- a/gst/tcp/gsttcpclientsrc.c +++ b/gst/tcp/gsttcpclientsrc.c @@ -22,19 +22,20 @@ /** * SECTION:element-tcpclientsrc + * @title: tcpclientsrc * @see_also: #tcpclientsink * - * - * Example launch line + * ## Example launch line * |[ * # server: * nc -l -p 3000 * # client: * gst-launch-1.0 tcpclientsrc port=3000 ! fdsink fd=2 - * ]| everything you type in the server is shown on the client. + * ]| + * everything you type in the server is shown on the client. * If you want to detect network failures and/or limit the time your tcp client * keeps waiting for data from server setting a timeout value can be useful. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/tcp/gsttcpserversink.c b/gst/tcp/gsttcpserversink.c index cb43d2d7bb..ef1a805d23 100644 --- a/gst/tcp/gsttcpserversink.c +++ b/gst/tcp/gsttcpserversink.c @@ -20,17 +20,17 @@ /** * SECTION:element-tcpserversink + * @title: tcpserversink * @see_also: #multifdsink * - * - * Example launch line + * ## Example launch line * |[ * # server: * gst-launch-1.0 fdsrc fd=1 ! tcpserversink port=3000 * # client: * gst-launch-1.0 tcpclientsrc port=3000 ! fdsink fd=2 - * ]| - * + * ]| + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/tcp/gsttcpserversrc.c b/gst/tcp/gsttcpserversrc.c index 6ac29a7816..fa9fe9bac1 100644 --- a/gst/tcp/gsttcpserversrc.c +++ b/gst/tcp/gsttcpserversrc.c @@ -22,17 +22,17 @@ /** * SECTION:element-tcpserversrc + * @title: tcpserversrc * @see_also: #tcpserversink * - * - * Example launch line + * ## Example launch line * |[ * # server: * gst-launch-1.0 tcpserversrc port=3000 ! fdsink fd=2 * # client: * gst-launch-1.0 fdsrc fd=1 ! tcpclientsink port=3000 - * ]| - * + * ]| + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/videoconvert/gstvideoconvert.c b/gst/videoconvert/gstvideoconvert.c index 292c6c611c..5f66c6fb4c 100644 --- a/gst/videoconvert/gstvideoconvert.c +++ b/gst/videoconvert/gstvideoconvert.c @@ -22,17 +22,18 @@ /** * SECTION:element-videoconvert + * @title: videoconvert * * Convert video frames between a great variety of video formats. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 -v videotestsrc ! video/x-raw,format=YUY2 ! videoconvert ! autovideosink - * ]| This will output a test video (generated in YUY2 format) in a video + * ]| + * This will output a test video (generated in YUY2 format) in a video * window. If the video sink selected does not support YUY2 videoconvert will * automatically convert the video to a format understood by the video sink. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/videorate/gstvideorate.c b/gst/videorate/gstvideorate.c index e7ffc74299..c15a89324c 100644 --- a/gst/videorate/gstvideorate.c +++ b/gst/videorate/gstvideorate.c @@ -19,6 +19,7 @@ /** * SECTION:element-videorate + * @title: videorate * * This element takes an incoming stream of timestamped video frames. * It will produce a perfect stream that matches the source pad's framerate. @@ -56,20 +57,22 @@ * certain factor. It must not be confused with framerate. Think of rate as * speed and framerate as flow. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v uridecodebin uri=file:///path/to/video.ogg ! videoconvert ! videoscale ! videorate ! video/x-raw,framerate=15/1 ! autovideosink - * ]| Decode a video file and adjust the framerate to 15 fps before playing. + * ]| + * Decode a video file and adjust the framerate to 15 fps before playing. * To create a test Ogg/Theora file refer to the documentation of theoraenc. * |[ * gst-launch-1.0 -v v4l2src ! videorate ! video/x-raw,framerate=25/2 ! theoraenc ! oggmux ! filesink location=recording.ogg - * ]| Capture video from a V4L device, and adjust the stream to 12.5 fps before + * ]| + * Capture video from a V4L device, and adjust the stream to 12.5 fps before * encoding to Ogg/Theora. * |[ * gst-launch-1.0 -v uridecodebin uri=file:///path/to/video.ogg ! videoconvert ! videoscale ! videorate ! video/x-raw,framerate=1/5 ! jpegenc ! multifilesink location=snapshot-%05d.jpg - * ]| Decode a video file and save a snapshot every 5 seconds as consecutively numbered jpeg file. - * + * ]| + * Decode a video file and save a snapshot every 5 seconds as consecutively numbered jpeg file. + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/videoscale/gstvideoscale.c b/gst/videoscale/gstvideoscale.c index 6238cbd4d2..c4cc4379c3 100644 --- a/gst/videoscale/gstvideoscale.c +++ b/gst/videoscale/gstvideoscale.c @@ -20,6 +20,7 @@ /** * SECTION:element-videoscale + * @title: videoscale * @see_also: videorate, videoconvert * * This element resizes video frames. By default the element will try to @@ -31,18 +32,19 @@ * RGB formats and is therefore generally able to operate anywhere in a * pipeline. * - * - * Example pipelines + * ## Example pipelines * |[ * gst-launch-1.0 -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoconvert ! videoscale ! autovideosink - * ]| Decode an Ogg/Theora and display the video. If the video sink chosen + * ]| + * Decode an Ogg/Theora and display the video. If the video sink chosen * 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-1.0 -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoconvert ! videoscale ! video/x-raw,width=100 ! autovideosink - * ]| Decode an Ogg/Theora and display the video with a width of 100. - * + * ]| + * Decode an Ogg/Theora and display the video with a width of 100. + * */ /* diff --git a/gst/videotestsrc/gstvideotestsrc.c b/gst/videotestsrc/gstvideotestsrc.c index 422b0f277e..c6b520af84 100644 --- a/gst/videotestsrc/gstvideotestsrc.c +++ b/gst/videotestsrc/gstvideotestsrc.c @@ -20,17 +20,18 @@ /** * SECTION:element-videotestsrc + * @title: videotestsrc * * The videotestsrc element is used to produce test video data in a wide variety * of formats. The video test data produced can be controlled with the "pattern" * property. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 -v videotestsrc pattern=snow ! video/x-raw,width=1280,height=720 ! autovideosink - * ]| Shows random noise in a video window. - * + * ]| + * Shows random noise in a video window. + * */ #ifdef HAVE_CONFIG_H diff --git a/gst/volume/gstvolume.c b/gst/volume/gstvolume.c index d439e9be3c..3b3d2f3726 100644 --- a/gst/volume/gstvolume.c +++ b/gst/volume/gstvolume.c @@ -24,17 +24,18 @@ /** * SECTION:element-volume + * @title: volume * * The volume element changes the volume of the audio data. * - * - * Example launch line + * ## Example launch line * |[ * gst-launch-1.0 -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. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/sys/ximage/ximagesink.c b/sys/ximage/ximagesink.c index 748dcd5dcb..cf5f19c33f 100644 --- a/sys/ximage/ximagesink.c +++ b/sys/ximage/ximagesink.c @@ -19,6 +19,7 @@ /** * SECTION:element-ximagesink + * @title: 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 @@ -26,27 +27,24 @@ * drawable. If no Window ID was provided by the application, the element will * create its own internal window and render into it. * - * - * Scaling - * + * ## Scaling + * * As standard XImage rendering to a drawable is not scaled, XImageSink will use * reverse caps negotiation to try to get scaled video frames for the drawable. * This is accomplished by asking the peer pad if it accepts some different caps * which in most cases implies that there is a scaling element in the pipeline, - * or that an element generating the video frames can generate them with a + * 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 #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 - * + * + * ## Events + * * XImageSink 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 + * 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... @@ -54,49 +52,48 @@ * 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 - * + * + * ## Pixel aspect ratio + * * When changing state to GST_STATE_READY, XImageSink will open a connection to * 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 + * 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 - * video sink will set the calculated pixel aspect ratio on the caps to make + * video sink will set the calculated pixel aspect ratio on the caps to make * 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 * #GstXImageSink:pixel-aspect-ratio property. - * - * - * - * Examples + * + * ## Examples * |[ * gst-launch-1.0 -v videotestsrc ! queue ! ximagesink - * ]| A pipeline to test reverse negotiation. When the test video signal appears + * ]| + * 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-1.0 -v videotestsrc ! navigationtest ! videoconvert ! ximagesink - * ]| A pipeline to test navigation events. + * ]| + * 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 + * 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.) * |[ * gst-launch-1.0 -v videotestsrc ! video/x-raw, 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 + * 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 + * (from 320x240 to 320x180 in this case). Note that you might have to escape * some characters for your shell like '\(fraction\)'. - * + * */ #ifdef HAVE_CONFIG_H diff --git a/sys/ximage/ximagesink.h b/sys/ximage/ximagesink.h index cc9c2224ad..b16c7fb254 100644 --- a/sys/ximage/ximagesink.h +++ b/sys/ximage/ximagesink.h @@ -152,7 +152,7 @@ struct _GstXWindow * @pool_lock: used to protect the buffer pool * @buffer_pool: a list of #GstXImageBuffer that could be reused at next buffer * allocation call - * @synchronous: used to store if XSynchronous should be used or not (for + * @synchronous: used to store if XSynchronous should be used or not (for * debugging purpose only) * @keep_aspect: used to remember if reverse negotiation scaling should respect * aspect ratio diff --git a/sys/xvimage/xvimagesink.c b/sys/xvimage/xvimagesink.c index e008d09a0a..9cd0da1a4d 100644 --- a/sys/xvimage/xvimagesink.c +++ b/sys/xvimage/xvimagesink.c @@ -20,6 +20,7 @@ /** * SECTION:element-xvimagesink + * @title: xvimagesink * * XvImageSink renders video frames to a drawable (XWindow) on a local display * using the XVideo extension. Rendering to a remote display is theoretically @@ -30,20 +31,17 @@ * application, the element will create its own internal window and render * into it. * - * - * Scaling - * + * ## 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 #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 - * + * + * ## 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 @@ -53,11 +51,9 @@ * 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 - * + * + * ## Pixel aspect ratio + * * When changing state to GST_STATE_READY, XvImageSink will open a connection to * the display specified in the #GstXvImageSink:display property or the * default display if nothing specified. Once this connection is open it will @@ -68,26 +64,27 @@ * Sometimes the calculated pixel aspect ratio can be wrong, it is * then possible to enforce a specific pixel aspect ratio using the * #GstXvImageSink:pixel-aspect-ratio property. - * - * - * - * Examples + * + * ## Examples * |[ * gst-launch-1.0 -v videotestsrc ! xvimagesink - * ]| A pipeline to test hardware scaling. + * ]| + * 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). By default * the image will never be distorted when scaled, instead black borders will * be added if needed. * |[ * gst-launch-1.0 -v videotestsrc ! xvimagesink force-aspect-ratio=false - * ]| Same pipeline with #GstXvImageSink:force-aspect-ratio property set to + * ]| + * Same pipeline with #GstXvImageSink:force-aspect-ratio property set to * false. You can observe that no borders are drawn around the scaled image * now and it will be distorted to fill the entire frame instead of respecting * the aspect ratio. * |[ * gst-launch-1.0 -v videotestsrc ! navigationtest ! xvimagesink - * ]| A pipeline to test navigation events. + * ]| + * 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 @@ -99,15 +96,17 @@ * image area * |[ * gst-launch-1.0 -v videotestsrc ! video/x-raw, pixel-aspect-ratio=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). * |[ * gst-launch-1.0 -v videotestsrc ! xvimagesink hue=100 saturation=-100 brightness=100 - * ]| Demonstrates how to use the colorbalance interface. - * + * ]| + * Demonstrates how to use the colorbalance interface. + * */ /* for developers: there are two useful tools : xvinfo and xvattr */