From 138c2b7cf9b713b5d6e56ac7934e228703bfc9f5 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Mon, 16 Jun 2008 07:03:58 +0000 Subject: [PATCH] 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. --- 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 ++++----- 6 files changed, 100 insertions(+), 153 deletions(-) diff --git a/gst/rtpmanager/gstrtpbin.c b/gst/rtpmanager/gstrtpbin.c index 0906a8d..44b2235 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 faa493d..2fccbfd 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 8f87668..771684c 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 a3014b2..9f3545e 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 a90cbbe..facbaaf 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 0dcc1a9..e5b989f 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 -- 2.7.4