Add documentation and unit test for x264enc.

Original commit message from CVS:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-bad-plugins-docs.sgml:
* docs/plugins/gst-plugins-bad-plugins-sections.txt:
* ext/x264/gstx264enc.c:
* tests/check/Makefile.am:
* tests/check/elements/x264enc.c: (setup_x264enc),
(cleanup_x264enc), (GST_START_TEST), (x264enc_suite), (main):
Add documentation and unit test for x264enc.

7 files changed, 271 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index df8771b0..9727b6be 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2008-08-12  Mark Nauwelaerts  <mark.nauwelaerts@collabora.co.uk>
+
+	* docs/plugins/Makefile.am:
+	* docs/plugins/gst-plugins-bad-plugins-docs.sgml:
+	* docs/plugins/gst-plugins-bad-plugins-sections.txt:
+	* ext/x264/gstx264enc.c:
+	* tests/check/Makefile.am:
+	* tests/check/elements/x264enc.c: (setup_x264enc),
+	(cleanup_x264enc), (GST_START_TEST), (x264enc_suite), (main):
+	Add documentation and unit test for x264enc.
+
 2008-08-11  Mark Nauwelaerts  <mark.nauwelaerts@collabora.co.uk>
 
 	* ext/x264/gstx264enc.c: (gst_x264_enc_init),
diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index b1cf7859..5a4c69ab 100644
--- a/docs/plugins/Makefile.am
+++ b/docs/plugins/Makefile.am
@@ -116,6 +116,7 @@ EXTRA_HFILES = \
 	$(top_srcdir)/ext/timidity/gsttimidity.h \
 	$(top_srcdir)/ext/timidity/gstwildmidi.h \
 	$(top_srcdir)/ext/twolame/gsttwolame.h \
+	$(top_srcdir)/ext/x264/gstx264enc.h \
 	$(top_srcdir)/gst/deinterlace/gstdeinterlace.h \
 	$(top_srcdir)/gst/dvdspu/gstdvdspu.h \
 	$(top_srcdir)/gst/festival/gstfestival.h \
diff --git a/docs/plugins/gst-plugins-bad-plugins-docs.sgml b/docs/plugins/gst-plugins-bad-plugins-docs.sgml
index 3ddbefa2..edf3714b 100644
--- a/docs/plugins/gst-plugins-bad-plugins-docs.sgml
+++ b/docs/plugins/gst-plugins-bad-plugins-docs.sgml
@@ -55,6 +55,7 @@
     <xi:include href="xml/element-videomark.xml" />
     <xi:include href="xml/element-videoparse.xml" />
     <xi:include href="xml/element-wildmidi.xml" />
+    <xi:include href="xml/element-x264enc.xml" />
     <xi:include href="xml/element-y4menc.xml" />
   </chapter>
 
diff --git a/docs/plugins/gst-plugins-bad-plugins-sections.txt b/docs/plugins/gst-plugins-bad-plugins-sections.txt
index 288c5f61..e0462f92 100644
--- a/docs/plugins/gst-plugins-bad-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-bad-plugins-sections.txt
@@ -701,6 +701,19 @@ GST_TYPE_WILDMIDI
 </SECTION>
 
 <SECTION>
+<FILE>element-x264enc</FILE>
+<TITLE>x264enc</TITLE>
+GstX264Enc
+<SUBSECTION Standard>
+GstX264EncClass
+GST_X264_ENC
+GST_X264_ENC_CLASS
+GST_IS_X264_ENC
+GST_IS_X264_ENC_CLASS
+GST_TYPE_X264_ENC
+</SECTION>
+
+<SECTION>
 <FILE>element-y4menc</FILE>
 <TITLE>y4menc</TITLE>
 GstY4mEncode
diff --git a/ext/x264/gstx264enc.c b/ext/x264/gstx264enc.c
index 5182e84e..1439d111 100644
--- a/ext/x264/gstx264enc.c
+++ b/ext/x264/gstx264enc.c
@@ -19,6 +19,36 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-x264enc
+ * @see_also: faac
+ *
+ * This element encodes raw video into a H264 compressed data,
+ * also otherwise known as MPEG-4 AVC (Advanced Video Codec).
+ *
+ * The #GstX264Enc:pass-new property controls the type of encoding.  In case of Constant
+ * Bitrate Encoding (actually ABR), the #GstX264Enc:bitrate will determine the quality
+ * of the encoding.  This will similarly be the case if this target bitrate
+ * is to obtained in multiple (2 or 3) pass encoding.
+ * Alternatively, one may choose to perform Constant Quantizer or Quality encoding,
+ * in which case the #GstX264Enc:quantizer property controls much of the outcome.
+ *
+ * <refsect2>
+ * <title>Example pipeline</title>
+ * |[
+ * gst-launch -v videotestsrc num-buffers=1000 ! x264enc qp-min=18 ! \
+ *   avimux ! filesink location=videotestsrc.avi
+ * ]| This example pipeline will encode a test video source to H264 muxed in an
+ * AVI container, while ensuring a sane minimum quantization factor to avoid
+ * some (excessive) waste.
+ * |[
+ * gst-launch -v videotestsrc num-buffers=1000 ! x264enc pass-new=quant ! \
+ *   matroskamux ! filesink location=videotestsrc.avi
+ * ]| This example pipeline will encode a test video source to H264 using fixed
+ * quantization, and muxes it in a Matroska container.
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif
diff --git a/tests/check/Makefile.am b/tests/check/Makefile.am
index 24070fd8..eddeff20 100644
--- a/tests/check/Makefile.am
+++ b/tests/check/Makefile.am
@@ -57,10 +57,17 @@ else
 check_timidity=
 endif
 
+if USE_X264
+check_x264enc=elements/x264enc
+else
+check_x264enc=
+endif
+
 
 VALGRIND_TO_FIX = \
 	elements/mpeg2enc \
-	elements/mplex
+	elements/mplex \
+	elements/x264enc
 
 # valgrind testing
 VALGRIND_TESTS_DISABLE = \
@@ -73,6 +80,7 @@ check_PROGRAMS = \
 	$(check_neon)      \
 	$(check_ofa)        \
 	$(check_timidity)  \
+	$(check_x264enc)   \
 	elements/selector \
 	elements/y4menc
 
diff --git a/tests/check/elements/x264enc.c b/tests/check/elements/x264enc.c
new file mode 100644
index 00000000..721f6e90
--- /dev/null
+++ b/tests/check/elements/x264enc.c
@@ -0,0 +1,206 @@
+/* GStreamer
+ *
+ * unit test for x264enc
+ *
+ * Copyright (C) <2008> Mark Nauwelaerts <mnauw@users.sf.net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#include <unistd.h>
+
+#include <gst/check/gstcheck.h>
+
+/* For ease of programming we use globals to keep refs for our floating
+ * src and sink pads we create; otherwise we always have to do get_pad,
+ * get_peer, and then remove references in every test function */
+static GstPad *mysrcpad, *mysinkpad;
+
+#define VIDEO_CAPS_STRING "video/x-raw-yuv, " \
+                           "format = (fourcc) I420, " \
+                           "width = (int) 384, " \
+                           "height = (int) 288, " \
+                           "framerate = (fraction) 25/1"
+
+#define MPEG_CAPS_STRING "video/x-h264, " \
+                           "width = (int) 384, " \
+                           "height = (int) 288, " \
+                           "framerate = (fraction) 25/1"
+
+static GstStaticPadTemplate sinktemplate = GST_STATIC_PAD_TEMPLATE ("sink",
+    GST_PAD_SINK,
+    GST_PAD_ALWAYS,
+    GST_STATIC_CAPS (MPEG_CAPS_STRING));
+
+static GstStaticPadTemplate srctemplate = GST_STATIC_PAD_TEMPLATE ("src",
+    GST_PAD_SRC,
+    GST_PAD_ALWAYS,
+    GST_STATIC_CAPS (VIDEO_CAPS_STRING));
+
+
+GstElement *
+setup_x264enc ()
+{
+  GstElement *x264enc;
+
+  GST_DEBUG ("setup_x264enc");
+  x264enc = gst_check_setup_element ("x264enc");
+  mysrcpad = gst_check_setup_src_pad (x264enc, &srctemplate, NULL);
+  mysinkpad = gst_check_setup_sink_pad (x264enc, &sinktemplate, NULL);
+  gst_pad_set_active (mysrcpad, TRUE);
+  gst_pad_set_active (mysinkpad, TRUE);
+
+  return x264enc;
+}
+
+void
+cleanup_x264enc (GstElement * x264enc)
+{
+  GST_DEBUG ("cleanup_x264enc");
+  gst_element_set_state (x264enc, GST_STATE_NULL);
+
+  gst_pad_set_active (mysrcpad, FALSE);
+  gst_pad_set_active (mysinkpad, FALSE);
+  gst_check_teardown_src_pad (x264enc);
+  gst_check_teardown_sink_pad (x264enc);
+  gst_check_teardown_element (x264enc);
+}
+
+GST_START_TEST (test_video_pad)
+{
+  GstElement *x264enc;
+  GstBuffer *inbuffer, *outbuffer;
+  GstCaps *caps;
+  int i, num_buffers;
+
+  x264enc = setup_x264enc ();
+  fail_unless (gst_element_set_state (x264enc,
+          GST_STATE_PLAYING) == GST_STATE_CHANGE_SUCCESS,
+      "could not set to playing");
+
+  /* corresponds to I420 buffer for the size mentioned in the caps */
+  inbuffer = gst_buffer_new_and_alloc (384 * 288 * 3 / 2);
+  /* makes valgrind's memcheck happier */
+  memset (GST_BUFFER_DATA (inbuffer), 0, GST_BUFFER_SIZE (inbuffer));
+  caps = gst_caps_from_string (VIDEO_CAPS_STRING);
+  gst_buffer_set_caps (inbuffer, caps);
+  gst_caps_unref (caps);
+  GST_BUFFER_TIMESTAMP (inbuffer) = 0;
+  ASSERT_BUFFER_REFCOUNT (inbuffer, "inbuffer", 1);
+  fail_unless (gst_pad_push (mysrcpad, inbuffer) == GST_FLOW_OK);
+
+  /* send eos to have all flushed if needed */
+  fail_unless (gst_pad_push_event (mysrcpad, gst_event_new_eos ()) == TRUE);
+
+  num_buffers = g_list_length (buffers);
+  fail_unless (num_buffers == 1);
+
+  /* clean up buffers */
+  for (i = 0; i < num_buffers; ++i) {
+    outbuffer = GST_BUFFER (buffers->data);
+    fail_if (outbuffer == NULL);
+
+    switch (i) {
+      case 0:
+      {
+        gint nsize, npos, j, type;
+        guint8 *data = GST_BUFFER_DATA (outbuffer);
+        gint size = GST_BUFFER_SIZE (outbuffer);
+
+        npos = 0;
+        j = 0;
+        /* loop through NALs */
+        while (npos < size) {
+          fail_unless (size - npos >= 4);
+          nsize = GST_READ_UINT32_BE (data + npos);
+          fail_unless (nsize > 0);
+          fail_unless (npos + 4 + nsize <= size);
+          type = data[npos + 4] & 0x1F;
+          /* check the first NALs, disregard AU (9) */
+          if (type != 9) {
+            switch (j) {
+              case 0:
+                /* SEI */
+                fail_unless (type == 6);
+                break;
+              case 1:
+                /* SPS */
+                fail_unless (type == 7);
+                break;
+              case 2:
+                /* PPS */
+                fail_unless (type == 8);
+                break;
+              case 3:
+                /* IDR */
+                fail_unless (type == 5);
+                break;
+              default:
+                break;
+            }
+            j++;
+          }
+          npos += nsize + 4;
+        }
+        /* should have reached the exact end */
+        fail_unless (npos == size);
+        break;
+      }
+      default:
+        break;
+    }
+    buffers = g_list_remove (buffers, outbuffer);
+
+    ASSERT_BUFFER_REFCOUNT (outbuffer, "outbuffer", 1);
+    gst_buffer_unref (outbuffer);
+    outbuffer = NULL;
+  }
+
+  cleanup_x264enc (x264enc);
+  g_list_free (buffers);
+  buffers = NULL;
+}
+
+GST_END_TEST;
+
+Suite *
+x264enc_suite (void)
+{
+  Suite *s = suite_create ("x264enc");
+  TCase *tc_chain = tcase_create ("general");
+
+  suite_add_tcase (s, tc_chain);
+  tcase_add_test (tc_chain, test_video_pad);
+
+  return s;
+}
+
+int
+main (int argc, char **argv)
+{
+  int nf;
+
+  Suite *s = x264enc_suite ();
+  SRunner *sr = srunner_create (s);
+
+  gst_check_init (&argc, &argv);
+
+  srunner_run_all (sr, CK_NORMAL);
+  nf = srunner_ntests_failed (sr);
+  srunner_free (sr);
+
+  return nf;
+}