audioconvert: cleanups and add some docs

Add docs for the internal audioconvert object before moving it to the
audio library.
Remove get_sizes and implement the trivial logic in the element.
Remove some unused orc functions

5 files changed, 65 insertions, 58 deletions

diff --git a/gst/audioconvert/audioconvert.c b/gst/audioconvert/audioconvert.c
index d7807036f..0b33673a8 100644
--- a/gst/audioconvert/audioconvert.c
+++ b/gst/audioconvert/audioconvert.c
@@ -1,7 +1,8 @@
 /* GStreamer
  * Copyright (C) 2005 Wim Taymans <wim at fluendo dot com>
+ *           (C) 2015 Wim Taymans <wim.taymans@gmail.com>
  *
- * audioconvert.c: Convert audio to different audio formats automatically
+ * audioconverter.c: Convert audio to different audio formats automatically
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -30,6 +31,28 @@
 #include "audioconvert.h"
 #include "gstaudioconvertorc.h"
 
+/**
+ * SECTION:audioconverter
+ * @short_description: Generic audio conversion
+ *
+ * <refsect2>
+ * <para>
+ * This object is used to convert audio samples from one format to another.
+ * The object can perform conversion of:
+ * <itemizedlist>
+ *  <listitem><para>
+ *    audio format with optional dithering and noise shaping
+ *  </para></listitem>
+ *  <listitem><para>
+ *    audio samplerate
+ *  </para></listitem>
+ *  <listitem><para>
+ *    audio channels and channel layout
+ *  </para></listitem>
+ * </para>
+ * </refsect2>
+ */
+
 typedef void (*AudioConvertFunc) (gpointer dst, const gpointer src, gint count);
 
 /**
@@ -160,9 +183,19 @@ gst_audio_converter_get_config (GstAudioConverter * convert)
   return convert->config;
 }
 
-
 /**
+ * gst_audio_converter_new: (skip)
+ * @in: a source #GstAudioInfo
+ * @out: a destination #GstAudioInfo
+ * @config: (transfer full): a #GstStructure with configuration options
+ *
+ * Create a new #GstAudioConverter that is able to convert between @in and @out
+ * audio formats.
  *
+ * @config contains extra configuration options, see #GST_VIDEO_CONVERTER_OPT_*
+ * parameters for details about the options and values.
+ *
+ * Returns: a #GstAudioConverter or %NULL if conversion is not possible.
  */
 GstAudioConverter *
 gst_audio_converter_new (GstAudioInfo * in, GstAudioInfo * out,
@@ -289,6 +322,12 @@ unpositioned:
   }
 }
 
+/**
+ * gst_audio_converter_free:
+ * @convert: a #GstAudioConverter
+ *
+ * Free a previously allocated @convert instance.
+ */
 void
 gst_audio_converter_free (GstAudioConverter * convert)
 {
@@ -308,20 +347,18 @@ gst_audio_converter_free (GstAudioConverter * convert)
   g_slice_free (GstAudioConverter, convert);
 }
 
-gboolean
-gst_audio_converter_get_sizes (GstAudioConverter * convert, gint samples,
-    gint * srcsize, gint * dstsize)
-{
-  g_return_val_if_fail (convert != NULL, FALSE);
-
-  if (srcsize)
-    *srcsize = samples * convert->in.bpf;
-  if (dstsize)
-    *dstsize = samples * convert->out.bpf;
-
-  return TRUE;
-}
-
+/**
+ * gst_audio_converter_samples:
+ * @convert: a #GstAudioConverter
+ * @flags: extra #GstAudioConverterFlags
+ * @src: source samples
+ * @dst: output samples
+ * @samples: number of samples
+ *
+ * Perform the conversion @src to @dst using @convert.
+ *
+ * Returns: %TRUE is the conversion could be performed.
+ */
 gboolean
 gst_audio_converter_samples (GstAudioConverter * convert,
     GstAudioConverterFlags flags, gpointer src, gpointer dst, gint samples)
diff --git a/gst/audioconvert/audioconvert.h b/gst/audioconvert/audioconvert.h
index 8c3f778c2..b0a91654c 100644
--- a/gst/audioconvert/audioconvert.h
+++ b/gst/audioconvert/audioconvert.h
@@ -80,10 +80,6 @@ gboolean             gst_audio_converter_set_config     (GstAudioConverter * con
 const GstStructure * gst_audio_converter_get_config     (GstAudioConverter * convert);
 
 
-gboolean             gst_audio_converter_get_sizes      (GstAudioConverter * convert,
-                                                         gint samples,
-                                                         gint * srcsize, gint * dstsize);
-
 gboolean             gst_audio_converter_samples        (GstAudioConverter * convert,
                                                          GstAudioConverterFlags flags,
                                                          gpointer src, gpointer dst,
diff --git a/gst/audioconvert/gstaudioconvert.c b/gst/audioconvert/gstaudioconvert.c
index 29cab90e6..92a79fb48 100644
--- a/gst/audioconvert/gstaudioconvert.c
+++ b/gst/audioconvert/gstaudioconvert.c
@@ -198,7 +198,8 @@ gst_audio_convert_dispose (GObject * obj)
 {
   GstAudioConvert *this = GST_AUDIO_CONVERT (obj);
 
-  gst_audio_converter_free (this->convert);
+  if (this->convert)
+    gst_audio_converter_free (this->convert);
 
   G_OBJECT_CLASS (parent_class)->dispose (obj);
 }
@@ -708,9 +709,8 @@ gst_audio_convert_transform (GstBaseTransform * base, GstBuffer * inbuf,
 
   /* get in/output sizes, to see if the buffers we got are of correct
    * sizes */
-  if (!gst_audio_converter_get_sizes (this->convert, samples, &insize,
-          &outsize))
-    goto error;
+  insize = samples * this->in_info.bpf;
+  outsize = samples * this->out_info.bpf;
 
   if (insize == 0 || outsize == 0)
     return GST_FLOW_OK;
@@ -752,12 +752,6 @@ done:
   return ret;
 
   /* ERRORS */
-error:
-  {
-    GST_ELEMENT_ERROR (this, STREAM, FORMAT,
-        (NULL), ("cannot get input/output sizes for %d samples", samples));
-    return GST_FLOW_ERROR;
-  }
 wrong_size:
   {
     GST_ELEMENT_ERROR (this, STREAM, FORMAT,
diff --git a/gst/audioconvert/gstaudioconvertorc.orc b/gst/audioconvert/gstaudioconvertorc.orc
index a5a0939d0..57b826ddc 100644
--- a/gst/audioconvert/gstaudioconvertorc.orc
+++ b/gst/audioconvert/gstaudioconvertorc.orc
@@ -13,24 +13,3 @@ divd d1, t1, 2147483648.0L
 
 muld t1, s1, 2147483648.0L
 convdl d1, t1
-
-.function audio_convert_orc_int_bias
-.dest 4 d1 gint32
-.source 4 s1 gint32
-.param 4 bias gint32
-.param 4 mask gint32
-.temp 4 t1
-
-addssl t1, s1, bias
-andl d1, t1, mask
-
-.function audio_convert_orc_int_dither
-.dest 4 d1 gint32
-.source 4 s1 gint32
-.source 4 dither gint32
-.param 4 mask gint32
-.temp 4 t1
-
-addssl t1, s1, dither
-andl d1, t1, mask
-
diff --git a/gst/audioconvert/gstchannelmix.c b/gst/audioconvert/gstchannelmix.c
index 34304dfcc..4bd9d47c3 100644
--- a/gst/audioconvert/gstchannelmix.c
+++ b/gst/audioconvert/gstchannelmix.c
@@ -818,14 +818,15 @@ gst_channel_mix_mix_double (GstChannelMix * mix,
 
 /**
  * gst_channel_mix_mix:
- * @mix:
- * @format:
- * @layout:
- * @in_data:
- * @out_data:
- * @samples:
+ * @mix: a #GstChannelMix
+ * @format: a #GstAudioFormat
+ * @layout: a #GstAudioLayout
+ * @in_data: input samples
+ * @out_data: output samples
+ * @samples: number of samples
  *
- * Perform channel mixing
+ * Perform channel mixing on @in_data and write the result to @out_data.
+ * @in_data and @out_data need to be in @format and @layout.
  */
 void
 gst_channel_mix_mix (GstChannelMix * mix, GstAudioFormat format,