From 68993006c374a92474db6e908f7d3c13981bfed9 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Mon, 16 Jun 2008 07:03:58 +0000 Subject: gst/: More doc updates. More xrefs. Original commit message from CVS: * gst/deinterlace/gstdeinterlace.c: * gst/rtpmanager/gstrtpbin.c: * gst/rtpmanager/gstrtpclient.c: * gst/rtpmanager/gstrtpjitterbuffer.c: * gst/rtpmanager/gstrtpptdemux.c: * gst/rtpmanager/gstrtpsession.c: * gst/rtpmanager/gstrtpssrcdemux.c: * gst/sdp/gstsdpdemux.c: More doc updates. More xrefs. --- ChangeLog | 12 ++++++ gst/deinterlace/gstdeinterlace.c | 4 +- gst/rtpmanager/gstrtpbin.c | 74 ++++++++++++++-------------------- gst/rtpmanager/gstrtpclient.c | 15 +++---- gst/rtpmanager/gstrtpjitterbuffer.c | 32 ++++++--------- gst/rtpmanager/gstrtpptdemux.c | 34 +++++++--------- gst/rtpmanager/gstrtpsession.c | 79 ++++++++++++++----------------------- gst/rtpmanager/gstrtpssrcdemux.c | 19 ++++----- gst/sdp/gstsdpdemux.c | 18 +++------ 9 files changed, 120 insertions(+), 167 deletions(-) diff --git a/ChangeLog b/ChangeLog index 2c6d6b54..c2a6e46f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +2008-06-16 Stefan Kost + + * gst/deinterlace/gstdeinterlace.c: + * gst/rtpmanager/gstrtpbin.c: + * gst/rtpmanager/gstrtpclient.c: + * gst/rtpmanager/gstrtpjitterbuffer.c: + * gst/rtpmanager/gstrtpptdemux.c: + * gst/rtpmanager/gstrtpsession.c: + * gst/rtpmanager/gstrtpssrcdemux.c: + * gst/sdp/gstsdpdemux.c: + More doc updates. More xrefs. + 2008-06-14 Julien Moutte * gst/flv/gstflvdemux.c: (gst_flv_demux_cleanup), diff --git a/gst/deinterlace/gstdeinterlace.c b/gst/deinterlace/gstdeinterlace.c index da4b978b..70fe1420 100644 --- a/gst/deinterlace/gstdeinterlace.c +++ b/gst/deinterlace/gstdeinterlace.c @@ -134,7 +134,7 @@ gst_deinterlace_class_init (GstDeinterlaceClass * klass) * When set to true, only areas affected by the deinterlacing are output, * making it easy to see which regions are being modified. * - * See Also: #GstDeinterlace::ni-area-only + * See Also: #GstDeinterlace:ni-area-only */ g_object_class_install_property (gobject_class, ARG_DI_ONLY, g_param_spec_boolean ("di-area-only", "di-area-only", @@ -146,7 +146,7 @@ gst_deinterlace_class_init (GstDeinterlaceClass * klass) * When set to true, only areas unaffected by the deinterlacing are output, * making it easy to see which regions are being preserved intact. * - * See Also: #GstDeinterlace::di-area-only + * See Also: #GstDeinterlace:di-area-only */ g_object_class_install_property (gobject_class, ARG_NI_ONLY, g_param_spec_boolean ("ni-area-only", "ni-area-only", diff --git a/gst/rtpmanager/gstrtpbin.c b/gst/rtpmanager/gstrtpbin.c index 0906a8de..44b2235e 100644 --- a/gst/rtpmanager/gstrtpbin.c +++ b/gst/rtpmanager/gstrtpbin.c @@ -21,61 +21,50 @@ * SECTION:element-gstrtpbin * @see_also: gstrtpjitterbuffer, gstrtpsession, gstrtpptdemux, gstrtpssrcdemux * - * - * - * RTP bin combines the functions of gstrtpsession, gstrtpssrcdemux, gstrtpjitterbuffer - * and gstrtpptdemux in one element. It allows for multiple RTP sessions that will - * be synchronized together using RTCP SR packets. - * - * - * gstrtpbin is configured with a number of request pads that define the - * functionality that is activated, similar to the gstrtpsession element. - * - * - * To use gstrtpbin as an RTP receiver, request a recv_rtp_sink_%%d pad. The session + * RTP bin combines the functions of #GstRtpSession, #GstRtpsSrcDemux, + * #GstRtpJitterBuffer and #GstRtpPtDemux in one element. It allows for multiple + * RTP sessions that will be synchronized together using RTCP SR packets. + * + * #GstRtpBin is configured with a number of request pads that define the + * functionality that is activated, similar to the #GstRtpSession element. + * + * To use #GstRtpBin as an RTP receiver, request a recv_rtp_sink_%%d pad. The session * number must be specified in the pad name. * Data received on the recv_rtp_sink_%%d pad will be processed in the gstrtpsession - * manager and after being validated forwarded on gstrtpssrcdemuxer element. Each - * RTP stream is demuxed based on the SSRC and send to a gstrtpjitterbuffer. After + * manager and after being validated forwarded on #GstRtpsSrcDemux element. Each + * RTP stream is demuxed based on the SSRC and send to a #GstRtpJitterBuffer. After * the packets are released from the jitterbuffer, they will be forwarded to a - * gstrtpptdemuxer element. The gstrtpptdemuxer element will demux the packets based + * #GstRtpsSrcDemux element. The #GstRtpsSrcDemux element will demux the packets based * on the payload type and will create a unique pad recv_rtp_src_%%d_%%d_%%d on * gstrtpbin with the session number, SSRC and payload type respectively as the pad * name. - * - * - * To also use gstrtpbin as an RTCP receiver, request a recv_rtcp_sink_%%d pad. The + * + * To also use #GstRtpBin as an RTCP receiver, request a recv_rtcp_sink_%%d pad. The * session number must be specified in the pad name. - * - * + * * If you want the session manager to generate and send RTCP packets, request * the send_rtcp_src_%%d pad with the session number in the pad name. Packet pushed * on this pad contain SR/RR RTCP reports that should be sent to all participants * in the session. - * - * - * To use gstrtpbin as a sender, request a send_rtp_sink_%%d pad, which will + * + * To use #GstRtpBin as a sender, request a send_rtp_sink_%%d pad, which will * automatically create a send_rtp_src_%%d pad. If the session number is not provided, * the pad from the lowest available session will be returned. The session manager will modify the * SSRC in the RTP packets to its own SSRC and wil forward the packets on the * send_rtp_src_%%d pad after updating its internal state. - * - * + * * The session manager needs the clock-rate of the payload types it is handling - * and will signal the GstRtpSession::request-pt-map signal when it needs such a - * mapping. One can clear the cached values with the GstRtpSession::clear-pt-map + * and will signal the #GstRtpSession::request-pt-map signal when it needs such a + * mapping. One can clear the cached values with the #GstRtpSession::clear-pt-map * signal. - * + * + * * Example pipelines - * - * + * |[ * gst-launch udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink_0 \ * gstrtpbin ! rtptheoradepay ! theoradec ! xvimagesink - * - * Receive RTP data from port 5000 and send to the session 0 in gstrtpbin. - * - * - * + * ]| Receive RTP data from port 5000 and send to the session 0 in gstrtpbin. + * |[ * gst-launch gstrtpbin name=rtpbin \ * v4l2src ! ffmpegcolorspace ! ffenc_h263 ! rtph263ppay ! rtpbin.send_rtp_sink_0 \ * rtpbin.send_rtp_src_0 ! udpsink port=5000 \ @@ -85,8 +74,7 @@ * rtpbin.send_rtp_src_1 ! udpsink port=5002 \ * rtpbin.send_rtcp_src_1 ! udpsink port=5003 sync=false async=false \ * udpsrc port=5007 ! rtpbin.recv_rtcp_sink_1 - * - * Encode and payload H263 video captured from a v4l2src. Encode and payload AMR + * ]| Encode and payload H263 video captured from a v4l2src. Encode and payload AMR * audio generated from audiotestsrc. The video is sent to session 0 in rtpbin * and the audio is sent to session 1. Video packets are sent on UDP port 5000 * and audio packets on port 5002. The video RTCP packets for session 0 are sent @@ -95,10 +83,8 @@ * is received on port 5007. Since RTCP packets from the sender should be sent * as soon as possible and do not participate in preroll, sync=false and * async=false is configured on udpsink - * - * - * - * gst-launch -v gstrtpbin name=rtpbin \ + * |[ + * gst-launch -v gstrtpbin name=rtpbin \ * udpsrc caps="application/x-rtp,media=(string)video,clock-rate=(int)90000,encoding-name=(string)H263-1998" \ * port=5000 ! rtpbin.recv_rtp_sink_0 \ * rtpbin. ! rtph263pdepay ! ffdec_h263 ! xvimagesink \ @@ -109,8 +95,7 @@ * rtpbin. ! rtpamrdepay ! amrnbdec ! alsasink \ * udpsrc port=5003 ! rtpbin.recv_rtcp_sink_1 \ * rtpbin.send_rtcp_src_1 ! udpsink port=5007 sync=false async=false - * - * Receive H263 on port 5000, send it through rtpbin in session 0, depayload, + * ]| Receive H263 on port 5000, send it through rtpbin in session 0, depayload, * decode and display the video. * Receive AMR on port 5002, send it through rtpbin in session 1, depayload, * decode and play the audio. @@ -119,7 +104,6 @@ * synchronisation. * Send RTCP reports for session 0 on port 5005 and RTCP reports for session 1 * on port 5007. - * * * * Last reviewed on 2007-08-30 (0.10.6) @@ -1200,7 +1184,7 @@ gst_rtp_bin_class_init (GstRtpBinClass * klass) * @rtpbin: the object which received the signal * * Clear all previously cached pt-mapping obtained with - * GstRtpBin::request-pt-map. + * #GstRtpBin::request-pt-map. */ gst_rtp_bin_signals[SIGNAL_CLEAR_PT_MAP] = g_signal_new ("clear-pt-map", G_TYPE_FROM_CLASS (klass), diff --git a/gst/rtpmanager/gstrtpclient.c b/gst/rtpmanager/gstrtpclient.c index faa493d1..2fccbfd7 100644 --- a/gst/rtpmanager/gstrtpclient.c +++ b/gst/rtpmanager/gstrtpclient.c @@ -21,20 +21,17 @@ * SECTION:element-gstrtpclient * @see_also: gstrtpjitterbuffer, gstrtpbin, gstrtpsession * - * - * * This element handles RTP data from one client. It accepts multiple RTP streams that * should be synchronized together. - * - * + * * Normally the SSRCs that map to the same CNAME (as given in the RTCP SDES messages) * should be synchronized. - * + * + * * Example pipelines - * - * - * - * + * |[ + * FIXME: gst-launch + * ]| FIXME: describe * * * Last reviewed on 2007-04-02 (0.10.5) diff --git a/gst/rtpmanager/gstrtpjitterbuffer.c b/gst/rtpmanager/gstrtpjitterbuffer.c index 8f876680..771684c8 100644 --- a/gst/rtpmanager/gstrtpjitterbuffer.c +++ b/gst/rtpmanager/gstrtpjitterbuffer.c @@ -26,34 +26,28 @@ /** * SECTION:element-gstrtpjitterbuffer * - * - * * This element reorders and removes duplicate RTP packets as they are received * from a network source. It will also wait for missing packets up to a - * configurable time limit using the ::latency property. Packets arriving too - * late are considered to be lost packets. - * - * - * This element acts as a live element and so adds ::latency to the pipeline. - * - * + * configurable time limit using the #GstRtpJitterBuffer:latency property. + * Packets arriving too late are considered to be lost packets. + * + * This element acts as a live element and so adds #GstRtpJitterBuffer:latency + * to the pipeline. + * * The element needs the clock-rate of the RTP payload in order to estimate the * delay. This information is obtained either from the caps on the sink pad or, - * when no caps are present, from the ::request-pt-map signal. To clear the - * previous pt-map use the ::clear-pt-map signal. - * - * + * when no caps are present, from the #GstRtpJitterBuffer::request-pt-map signal. + * To clear the previous pt-map use the #GstRtpJitterBuffer::clear-pt-map signal. + * * This element will automatically be used inside gstrtpbin. - * + * + * * Example pipelines - * - * + * |[ * gst-launch rtspsrc location=rtsp://192.168.1.133:8554/mpeg1or2AudioVideoTest ! gstrtpjitterbuffer ! rtpmpvdepay ! mpeg2dec ! xvimagesink - * - * Connect to a streaming server and decode the MPEG video. The jitterbuffer is + * ]| Connect to a streaming server and decode the MPEG video. The jitterbuffer is * inserted into the pipeline to smooth out network jitter and to reorder the * out-of-order RTP packets. - * * * * Last reviewed on 2007-05-28 (0.10.5) diff --git a/gst/rtpmanager/gstrtpptdemux.c b/gst/rtpmanager/gstrtpptdemux.c index a3014b2b..9f3545ec 100644 --- a/gst/rtpmanager/gstrtpptdemux.c +++ b/gst/rtpmanager/gstrtpptdemux.c @@ -26,29 +26,25 @@ /** * SECTION:element-gstrtpptdemux * - * - * - * gstrtpptdemux acts as a demuxer for RTP packets based on the payload type of the - * packets. Its main purpose is to allow an application to easily receive and - * decode an RTP stream with multiple payload types. - * - * + * gstrtpptdemux acts as a demuxer for RTP packets based on the payload type of + * the packets. Its main purpose is to allow an application to easily receive + * and decode an RTP stream with multiple payload types. + * * For each payload type that is detected, a new pad will be created and the - * ::new-payload-type signal will be emitted. When the payload for the RTP - * stream changes, the ::payload-type-change signal will be emitted. - * - * + * #GstRtpPtDemux::new-payload-type signal will be emitted. When the payload for + * the RTP stream changes, the #GstRtpPtDemux::payload-type-change signal will be + * emitted. + * * The element will try to set complete and unique application/x-rtp caps on the - * outgoing buffers and pads based on the result of the ::request-pt-map signal. - * + * outgoing buffers and pads based on the result of the + * #GstRtpPtDemux::request-pt-map signal. + * + * * Example pipelines - * - * + * |[ * gst-launch udpsrc caps="application/x-rtp" ! gstrtpptdemux ! fakesink - * - * Takes an RTP stream and send the RTP packets with the first detected payload - * type to fakesink, discarding the other payload types. - * + * ]| Takes an RTP stream and send the RTP packets with the first detected + * payload type to fakesink, discarding the other payload types. * * * Last reviewed on 2007-05-28 (0.10.5) diff --git a/gst/rtpmanager/gstrtpsession.c b/gst/rtpmanager/gstrtpsession.c index a90cbbed..facbaaf7 100644 --- a/gst/rtpmanager/gstrtpsession.c +++ b/gst/rtpmanager/gstrtpsession.c @@ -21,14 +21,11 @@ * SECTION:element-gstrtpsession * @see_also: gstrtpjitterbuffer, gstrtpbin, gstrtpptdemux, gstrtpssrcdemux * - * - * * The RTP session manager models one participant with a unique SSRC in an RTP * session. This session can be used to send and receive RTP and RTCP packets. * Based on what REQUEST pads are requested from the session manager, specific * functionality can be activated. - * - * + * * The session manager currently implements RFC 3550 including: * * @@ -44,84 +41,68 @@ * Scheduling of RR/SR RTCP packets. * * - * - * + * * The gstrtpsession will not demux packets based on SSRC or payload type, nor will - * it correct for packet reordering and jitter. Use gstrtpssrcdemux, gstrtpptdemux and - * gstrtpjitterbuffer in addition to gstrtpsession to perform these tasks. It is - * usually a good idea to use gstrtpbin, which combines all these features in one - * element. - * - * - * To use gstrtpsession as an RTP receiver, request a recv_rtp_sink pad, which will + * it correct for packet reordering and jitter. Use #GstRtpsSrcDemux, + * #GstRtpPtDemux and GstRtpJitterBuffer in addition to #GstRtpSession to + * perform these tasks. It is usually a good idea to use #GstRtpBin, which + * combines all these features in one element. + * + * To use #GstRtpSession as an RTP receiver, request a recv_rtp_sink pad, which will * automatically create recv_rtp_src pad. Data received on the recv_rtp_sink pad * will be processed in the session and after being validated forwarded on the * recv_rtp_src pad. - * - * - * To also use gstrtpsession as an RTCP receiver, request a recv_rtcp_sink pad, + * + * To also use #GstRtpSession as an RTCP receiver, request a recv_rtcp_sink pad, * which will automatically create a sync_src pad. Packets received on the RTCP * pad will be used by the session manager to update the stats and database of * the other participants. SR packets will be forwarded on the sync_src pad * so that they can be used to perform inter-stream synchronisation when needed. - * - * + * * If you want the session manager to generate and send RTCP packets, request * the send_rtcp_src pad. Packet pushed on this pad contain SR/RR RTCP reports * that should be sent to all participants in the session. - * - * - * To use gstrtpsession as a sender, request a send_rtp_sink pad, which will + * + * To use #GstRtpSession as a sender, request a send_rtp_sink pad, which will * automatically create a send_rtp_src pad. The session manager will modify the * SSRC in the RTP packets to its own SSRC and wil forward the packets on the * send_rtp_src pad after updating its internal state. - * - * + * * The session manager needs the clock-rate of the payload types it is handling - * and will signal the GstRtpSession::request-pt-map signal when it needs such a - * mapping. One can clear the cached values with the GstRtpSession::clear-pt-map + * and will signal the #GstRtpSession::request-pt-map signal when it needs such a + * mapping. One can clear the cached values with the #GstRtpSession::clear-pt-map * signal. - * + * + * * Example pipelines - * - * + * |[ * gst-launch udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink gstrtpsession .recv_rtp_src ! rtptheoradepay ! theoradec ! xvimagesink - * - * Receive theora RTP packets from port 5000 and send them to the depayloader, + * ]| Receive theora RTP packets from port 5000 and send them to the depayloader, * decoder and display. Note that the application/x-rtp caps on udpsrc should be * configured based on some negotiation process such as RTSP for this pipeline * to work correctly. - * - * - * + * |[ * gst-launch udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink gstrtpsession name=session \ * .recv_rtp_src ! rtptheoradepay ! theoradec ! xvimagesink \ * udpsrc port=5001 caps="application/x-rtcp" ! session.recv_rtcp_sink - * - * Receive theora RTP packets from port 5000 and send them to the depayloader, + * ]| Receive theora RTP packets from port 5000 and send them to the depayloader, * decoder and display. Receive RTCP packets from port 5001 and process them in * the session manager. * Note that the application/x-rtp caps on udpsrc should be * configured based on some negotiation process such as RTSP for this pipeline * to work correctly. - * - * - * + * |[ * gst-launch videotestsrc ! theoraenc ! rtptheorapay ! .send_rtp_sink gstrtpsession .send_rtp_src ! udpsink port=5000 - * - * Send theora RTP packets through the session manager and out on UDP port 5000. - * - * - * + * ]| Send theora RTP packets through the session manager and out on UDP port + * 5000. + * |[ * gst-launch videotestsrc ! theoraenc ! rtptheorapay ! .send_rtp_sink gstrtpsession name=session .send_rtp_src \ * ! udpsink port=5000 session.send_rtcp_src ! udpsink port=5001 - * - * Send theora RTP packets through the session manager and out on UDP port 5000. - * Send RTCP packets on port 5001. Note that this pipeline will not preroll + * ]| Send theora RTP packets through the session manager and out on UDP port + * 5000. Send RTCP packets on port 5001. Note that this pipeline will not preroll * correctly because the second udpsink will not preroll correctly (no RTCP * packets are sent in the PAUSED state). Applications should manually set and - * keep (see #gst_element_set_locked_state()) the RTCP udpsink to the PLAYING state. - * + * keep (see gst_element_set_locked_state()) the RTCP udpsink to the PLAYING state. * * * Last reviewed on 2007-05-28 (0.10.5) @@ -492,7 +473,7 @@ gst_rtp_session_class_init (GstRtpSessionClass * klass) * GstRtpSession::clear-pt-map: * @sess: the object which received the signal * - * Clear the cached pt-maps requested with GstRtpSession::request-pt-map. + * Clear the cached pt-maps requested with #GstRtpSession::request-pt-map. */ gst_rtp_session_signals[SIGNAL_CLEAR_PT_MAP] = g_signal_new ("clear-pt-map", G_TYPE_FROM_CLASS (klass), diff --git a/gst/rtpmanager/gstrtpssrcdemux.c b/gst/rtpmanager/gstrtpssrcdemux.c index 0dcc1a95..e5b989f7 100644 --- a/gst/rtpmanager/gstrtpssrcdemux.c +++ b/gst/rtpmanager/gstrtpssrcdemux.c @@ -22,24 +22,19 @@ /** * SECTION:element-gstrtpssrcdemux * - * - * * gstrtpssrcdemux acts as a demuxer for RTP packets based on the SSRC of the * packets. Its main purpose is to allow an application to easily receive and * decode an RTP stream with multiple SSRCs. - * - * + * * For each SSRC that is detected, a new pad will be created and the - * ::new-ssrc-pad signal will be emitted. - * + * #GstRtpSsrcDemux::new-ssrc-pad signal will be emitted. + * + * * Example pipelines - * - * + * |[ * gst-launch udpsrc caps="application/x-rtp" ! gstrtpssrcdemux ! fakesink - * - * Takes an RTP stream and send the RTP packets with the first detected SSRC + * ]| Takes an RTP stream and send the RTP packets with the first detected SSRC * to fakesink, discarding the other SSRCs. - * * * * Last reviewed on 2007-05-28 (0.10.5) @@ -133,7 +128,7 @@ static gboolean gst_rtp_ssrc_demux_src_query (GstPad * pad, GstQuery * query); static guint gst_rtp_ssrc_demux_signals[LAST_SIGNAL] = { 0 }; -/** +/* * Item for storing GstPad <-> SSRC pairs. */ struct _GstRtpSsrcDemuxPad diff --git a/gst/sdp/gstsdpdemux.c b/gst/sdp/gstsdpdemux.c index 45cdc3a8..949d2fab 100644 --- a/gst/sdp/gstsdpdemux.c +++ b/gst/sdp/gstsdpdemux.c @@ -19,31 +19,25 @@ /** * SECTION:element-sdpdemux * - * - * * sdpdemux currently understands SDP as the input format of the session description. * For each stream listed in the SDP a new rtp_stream%d pad will be created * with caps derived from the SDP media description. This is a caps of mime type * "application/x-rtp" that can be connected to any available RTP depayloader * element. - * - * + * * sdpdemux will internally instantiate an RTP session manager element * that will handle the RTCP messages to and from the server, jitter removal, * packet reordering along with providing a clock for the pipeline. - * - * + * * sdpdemux acts like a live element and will therefore only generate data in the * PLAYING state. - * + * + * * Example launch line - * - * + * |[ * gst-launch gnomevfssrc location=http://some.server/session.sdp ! sdpdemux ! fakesink - * - * Establish a connection to an HTTP server that contains an SDP session description + * ]| Establish a connection to an HTTP server that contains an SDP session description * that gets parsed by sdpdemux and send the raw RTP packets to a fakesink. - * * * * Last reviewed on 2007-10-01 (0.10.6) -- cgit v1.2.1