From 1df2e623b530d553a5cd39f81d1462995fec2bd6 Mon Sep 17 00:00:00 2001
From: Wim Taymans <wim.taymans@collabora.co.uk>
Date: Thu, 25 Apr 2013 13:19:35 +0200
Subject: [PATCH] docs: add some pay/depayloaders

See https://bugzilla.gnome.org/show_bug.cgi?id=551631
---
 docs/plugins/gst-plugins-good-plugins-docs.sgml    |   8 ++
 docs/plugins/gst-plugins-good-plugins-sections.txt | 120 +++++++++++++++++++++
 gst/rtp/gstrtpL16depay.c                           |  18 ++++
 gst/rtp/gstrtpL16pay.c                             |  18 ++++
 gst/rtp/gstrtpac3depay.c                           |  18 ++++
 gst/rtp/gstrtpac3pay.c                             |  18 ++++
 gst/rtp/gstrtpamrdepay.c                           |  31 ++++--
 gst/rtp/gstrtpamrpay.c                             |  42 +++++---
 gst/rtp/gstrtpbvdepay.c                            |  10 ++
 gst/rtp/gstrtpbvpay.c                              |  10 ++
 10 files changed, 274 insertions(+), 19 deletions(-)

diff --git a/docs/plugins/gst-plugins-good-plugins-docs.sgml b/docs/plugins/gst-plugins-good-plugins-docs.sgml
index 315d1b7..148c639 100644
--- a/docs/plugins/gst-plugins-good-plugins-docs.sgml
+++ b/docs/plugins/gst-plugins-good-plugins-docs.sgml
@@ -128,6 +128,14 @@
     <xi:include href="xml/element-rgvolume.xml" />
     <xi:include href="xml/element-rippletv.xml" />
     <xi:include href="xml/element-rtpdec.xml" />
+    <xi:include href="xml/element-rtpac3depay.xml" />
+    <xi:include href="xml/element-rtpac3pay.xml" />
+    <xi:include href="xml/element-rtpamrdepay.xml" />
+    <xi:include href="xml/element-rtpamrpay.xml" />
+    <xi:include href="xml/element-rtpbvdepay.xml" />
+    <xi:include href="xml/element-rtpbvpay.xml" />
+    <xi:include href="xml/element-rtpL16depay.xml" />
+    <xi:include href="xml/element-rtpL16pay.xml" />
     <xi:include href="xml/element-rtpj2kpay.xml" />
     <xi:include href="xml/element-rtpjpegpay.xml" />
     <xi:include href="xml/element-rtpsbcpay.xml" />
diff --git a/docs/plugins/gst-plugins-good-plugins-sections.txt b/docs/plugins/gst-plugins-good-plugins-sections.txt
index d7a7fe7..86ecacb 100644
--- a/docs/plugins/gst-plugins-good-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-good-plugins-sections.txt
@@ -1625,6 +1625,126 @@ GstRTPDTMFEventType
 </SECTION>
 
 <SECTION>
+<FILE>element-rtpac3depay</FILE>
+<TITLE>rtpac3depay</TITLE>
+GstRtpAC3Depay
+<SUBSECTION Standard>
+GstRtpAC3DepayClass
+GST_RTP_AC3_DEPAY
+GST_IS_RTP_AC3_DEPAY
+GST_TYPE_RTP_AC3_DEPAY
+GST_RTP_AC3_DEPAY_CLASS
+GST_IS_RTP_AC3_DEPAY_CLASS
+gst_rtp_ac3_depay_plugin_init
+gst_rtp_ac3_depay_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpac3pay</FILE>
+<TITLE>rtpac3pay</TITLE>
+GstRtpAC3Pay
+<SUBSECTION Standard>
+GstRtpAC3PayClass
+GST_RTP_AC3_PAY
+GST_IS_RTP_AC3_PAY
+GST_TYPE_RTP_AC3_PAY
+GST_RTP_AC3_PAY_CLASS
+GST_IS_RTP_AC3_PAY_CLASS
+gst_rtp_ac3_pay_plugin_init
+gst_rtp_ac3_pay_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpamrdepay</FILE>
+<TITLE>rtpamrdepay</TITLE>
+GstRtpAMRDepay
+<SUBSECTION Standard>
+GstRtpAMRDepayClass
+GST_RTP_AMR_DEPAY
+GST_IS_RTP_AMR_DEPAY
+GST_TYPE_RTP_AMR_DEPAY
+GST_RTP_AMR_DEPAY_CLASS
+GST_IS_RTP_AMR_DEPAY_CLASS
+gst_rtp_amr_depay_plugin_init
+gst_rtp_amr_depay_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpamrpay</FILE>
+<TITLE>rtpamrpay</TITLE>
+GstRtpAMRPay
+<SUBSECTION Standard>
+GstRtpAMRPayClass
+GST_RTP_AMR_PAY
+GST_IS_RTP_AMR_PAY
+GST_TYPE_RTP_AMR_PAY
+GST_RTP_AMR_PAY_CLASS
+GST_IS_RTP_AMR_PAY_CLASS
+gst_rtp_amr_pay_plugin_init
+gst_rtp_amr_pay_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpbvdepay</FILE>
+<TITLE>rtpbvdepay</TITLE>
+GstRtpBVDepay
+<SUBSECTION Standard>
+GstRtpBVDepayClass
+GST_RTP_BV_DEPAY
+GST_IS_RTP_BV_DEPAY
+GST_TYPE_RTP_BV_DEPAY
+GST_RTP_BV_DEPAY_CLASS
+GST_IS_RTP_BV_DEPAY_CLASS
+gst_rtp_bv_depay_plugin_init
+gst_rtp_bv_depay_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpbvpay</FILE>
+<TITLE>rtpbvpay</TITLE>
+GstRtpBVPay
+<SUBSECTION Standard>
+GstRtpBVPayClass
+GST_RTP_BV_PAY
+GST_IS_RTP_BV_PAY
+GST_TYPE_RTP_BV_PAY
+GST_RTP_BV_PAY_CLASS
+GST_IS_RTP_BV_PAY_CLASS
+gst_rtp_bv_pay_plugin_init
+gst_rtp_bv_pay_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpL16depay</FILE>
+<TITLE>rtpL16depay</TITLE>
+GstRtpL16Depay
+<SUBSECTION Standard>
+GstRtpL16DepayClass
+GST_RTP_L16_DEPAY
+GST_IS_RTP_L16_DEPAY
+GST_TYPE_RTP_L16_DEPAY
+GST_RTP_L16_DEPAY_CLASS
+GST_IS_RTP_L16_DEPAY_CLASS
+gst_rtp_L16_depay_plugin_init
+gst_rtp_L16_depay_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-rtpL16pay</FILE>
+<TITLE>rtpL16pay</TITLE>
+GstRtpL16Pay
+<SUBSECTION Standard>
+GstRtpL16PayClass
+GST_RTP_L16_PAY
+GST_IS_RTP_L16_PAY
+GST_TYPE_RTP_L16_PAY
+GST_RTP_L16_PAY_CLASS
+GST_IS_RTP_L16_PAY_CLASS
+gst_rtp_L16_pay_plugin_init
+gst_rtp_L16_pay_get_type
+</SECTION>
+
+<SECTION>
 <FILE>element-rtpj2kpay</FILE>
 <TITLE>rtpj2kpay</TITLE>
 GstRtpJ2KPay
diff --git a/gst/rtp/gstrtpL16depay.c b/gst/rtp/gstrtpL16depay.c
index 880451f..7e96d9d 100644
--- a/gst/rtp/gstrtpL16depay.c
+++ b/gst/rtp/gstrtpL16depay.c
@@ -17,6 +17,24 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:element-rtpL16depay
+ * @see_also: rtpL16pay
+ *
+ * Extract raw audio from RTP packets according to RFC 3551.
+ * For detailed information see: http://www.rfc-editor.org/rfc/rfc3551.txt
+ *
+ * <refsect2>
+ * <title>Example pipeline</title>
+ * |[
+ * gst-launch udpsrc caps='application/x-rtp, media=(string)audio, clock-rate=(int)44100, encoding-name=(string)L16, encoding-params=(string)1, channels=(int)1, payload=(int)96' ! rtpL16depay ! pulsesink
+ * ]| This example pipeline will depayload an RTP raw audio stream. Refer to
+ * the rtpL16pay example to create the RTP stream.
+ * </refsect2>
+ *
+ * Last reviewed on 2013-04-25 (1.1.0)
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst/rtp/gstrtpL16pay.c b/gst/rtp/gstrtpL16pay.c
index 16abf32..4a101ee 100644
--- a/gst/rtp/gstrtpL16pay.c
+++ b/gst/rtp/gstrtpL16pay.c
@@ -17,6 +17,24 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:element-rtpL16pay
+ * @see_also: rtpL16depay
+ *
+ * Payload raw audio into RTP packets according to RFC 3551.
+ * For detailed information see: http://www.rfc-editor.org/rfc/rfc3551.txt
+ *
+ * <refsect2>
+ * <title>Example pipeline</title>
+ * |[
+ * gst-launch -v audiotestsrc ! audioconvert ! rtpL16pay ! udpsink
+ * ]| This example pipeline will payload raw audio. Refer to
+ * the rtpL16depay example to depayload and play the RTP stream.
+ * </refsect2>
+ *
+ * Last reviewed on 2013-04-25 (1.1.0)
+ */
+
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif
diff --git a/gst/rtp/gstrtpac3depay.c b/gst/rtp/gstrtpac3depay.c
index 0a2a70c..fc79b5d 100644
--- a/gst/rtp/gstrtpac3depay.c
+++ b/gst/rtp/gstrtpac3depay.c
@@ -17,6 +17,24 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:element-rtpac3depay
+ * @see_also: rtpac3pay
+ *
+ * Extract AC3 audio from RTP packets according to RFC 4184.
+ * For detailed information see: http://www.rfc-editor.org/rfc/rfc4184.txt
+ *
+ * <refsect2>
+ * <title>Example pipeline</title>
+ * |[
+ * gst-launch-1.0 udpsrc caps='application/x-rtp, media=(string)audio, clock-rate=(int)44100, encoding-name=(string)AC3, payload=(int)96' ! rtpac3depay ! a52dec ! pulsesink
+ * ]| This example pipeline will depayload and decode an RTP AC3 stream. Refer to
+ * the rtpac3pay example to create the RTP stream.
+ * </refsect2>
+ *
+ * Last reviewed on 2013-04-25 (1.1.0)
+ */
+
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif
diff --git a/gst/rtp/gstrtpac3pay.c b/gst/rtp/gstrtpac3pay.c
index 0af1ea6..175d627 100644
--- a/gst/rtp/gstrtpac3pay.c
+++ b/gst/rtp/gstrtpac3pay.c
@@ -17,6 +17,24 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:element-rtpac3pay
+ * @see_also: rtpac3depay
+ *
+ * Payload AC3 audio into RTP packets according to RFC 4184.
+ * For detailed information see: http://www.rfc-editor.org/rfc/rfc4184.txt
+ *
+ * <refsect2>
+ * <title>Example pipeline</title>
+ * |[
+ * gst-launch -v audiotestsrc ! avenc_ac3 ! rtpac3pay ! udpsink
+ * ]| This example pipeline will encode and payload AC3 stream. Refer to
+ * the rtpac3depay example to depayload and decode the RTP stream.
+ * </refsect2>
+ *
+ * Last reviewed on 2013-04-25 (1.1.0)
+ */
+
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif
diff --git a/gst/rtp/gstrtpamrdepay.c b/gst/rtp/gstrtpamrdepay.c
index 25a4508..e1208bf 100644
--- a/gst/rtp/gstrtpamrdepay.c
+++ b/gst/rtp/gstrtpamrdepay.c
@@ -17,6 +17,30 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:element-rtpamrdepay
+ * @see_also: rtpamrpay
+ *
+ * Extract AMR audio from RTP packets according to RFC 3267.
+ * For detailed information see: http://www.rfc-editor.org/rfc/rfc3267.txt
+ *
+ * <refsect2>
+ * <title>Example pipeline</title>
+ * |[
+ * gst-launch-1.0 udpsrc caps='application/x-rtp, media=(string)audio, clock-rate=(int)8000, encoding-name=(string)AMR, encoding-params=(string)1, octet-align=(string)1, payload=(int)96' ! rtpamrdepay ! amrnbdec ! pulsesink
+ * ]| This example pipeline will depayload and decode an RTP AMR stream. Refer to
+ * the rtpamrpay example to create the RTP stream.
+ * </refsect2>
+ *
+ * Last reviewed on 2013-04-25 (1.1.0)
+ */
+
+/*
+ * RFC 3267 - Real-Time Transport Protocol (RTP) Payload Format and File
+ * Storage Format for the Adaptive Multi-Rate (AMR) and Adaptive Multi-Rate
+ * Wideband (AMR-WB) Audio Codecs.
+ *
+ */
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif
@@ -30,13 +54,6 @@
 GST_DEBUG_CATEGORY_STATIC (rtpamrdepay_debug);
 #define GST_CAT_DEFAULT (rtpamrdepay_debug)
 
-/* references:
- *
- * RFC 3267 - Real-Time Transport Protocol (RTP) Payload Format and File
- * Storage Format for the Adaptive Multi-Rate (AMR) and Adaptive Multi-Rate
- * Wideband (AMR-WB) Audio Codecs.
- */
-
 /* RtpAMRDepay signals and args */
 enum
 {
diff --git a/gst/rtp/gstrtpamrpay.c b/gst/rtp/gstrtpamrpay.c
index 29c26de..defc7f4 100644
--- a/gst/rtp/gstrtpamrpay.c
+++ b/gst/rtp/gstrtpamrpay.c
@@ -17,18 +17,23 @@
  * Boston, MA 02110-1301, USA.
  */
 
-#ifdef HAVE_CONFIG_H
-#  include "config.h"
-#endif
-
-#include <string.h>
-
-#include <gst/rtp/gstrtpbuffer.h>
-
-#include "gstrtpamrpay.h"
-
-GST_DEBUG_CATEGORY_STATIC (rtpamrpay_debug);
-#define GST_CAT_DEFAULT (rtpamrpay_debug)
+/**
+ * SECTION:element-rtpamrpay
+ * @see_also: rtpamrdepay
+ *
+ * Payload AMR audio into RTP packets according to RFC 3267.
+ * For detailed information see: http://www.rfc-editor.org/rfc/rfc3267.txt
+ *
+ * <refsect2>
+ * <title>Example pipeline</title>
+ * |[
+ * gst-launch -v audiotestsrc ! amrnbenc ! rtpamrpay ! udpsink
+ * ]| This example pipeline will encode and payload an AMR stream. Refer to
+ * the rtpamrdepay example to depayload and decode the RTP stream.
+ * </refsect2>
+ *
+ * Last reviewed on 2013-04-25 (1.1.0)
+ */
 
 /* references:
  *
@@ -43,6 +48,19 @@ GST_DEBUG_CATEGORY_STATIC (rtpamrpay_debug);
  *                    (3GPP TS 26.201 version 6.0.0 Release 6)
  */
 
+#ifdef HAVE_CONFIG_H
+#  include "config.h"
+#endif
+
+#include <string.h>
+
+#include <gst/rtp/gstrtpbuffer.h>
+
+#include "gstrtpamrpay.h"
+
+GST_DEBUG_CATEGORY_STATIC (rtpamrpay_debug);
+#define GST_CAT_DEFAULT (rtpamrpay_debug)
+
 static GstStaticPadTemplate gst_rtp_amr_pay_sink_template =
     GST_STATIC_PAD_TEMPLATE ("sink",
     GST_PAD_SINK,
diff --git a/gst/rtp/gstrtpbvdepay.c b/gst/rtp/gstrtpbvdepay.c
index 67fbb0c..7b85558 100644
--- a/gst/rtp/gstrtpbvdepay.c
+++ b/gst/rtp/gstrtpbvdepay.c
@@ -17,6 +17,16 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:element-rtpbvdepay
+ * @see_also: rtpbvpay
+ *
+ * Extract BroadcomVoice audio from RTP packets according to RFC 4298.
+ * For detailed information see: http://www.rfc-editor.org/rfc/rfc4298.txt
+ *
+ * Last reviewed on 2013-04-25 (1.1.0)
+ */
+
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif
diff --git a/gst/rtp/gstrtpbvpay.c b/gst/rtp/gstrtpbvpay.c
index 4a0c263..be12b38 100644
--- a/gst/rtp/gstrtpbvpay.c
+++ b/gst/rtp/gstrtpbvpay.c
@@ -17,6 +17,16 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:element-rtpbvpay
+ * @see_also: rtpbvdepay
+ *
+ * Payload BroadcomVoice audio into RTP packets according to RFC 4298.
+ * For detailed information see: http://www.rfc-editor.org/rfc/rfc4298.txt
+ *
+ * Last reviewed on 2013-04-25 (1.1.0)
+ */
+
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif
-- 
2.7.4