audio: Add documentation for the new functions

diff --git a/gst-libs/gst/audio/audio.c b/gst-libs/gst/audio/audio.c
index ac7c7930bc38414001a53356475b5bcdee59b26c..8e0de022aa2354ef6779c8cb5bb3bab9093691a3 100644 (file)
--- a/gst-libs/gst/audio/audio.c
+++ b/gst-libs/gst/audio/audio.c
@@ -922,6 +922,86 @@ gst_audio_buffer_clip (GstBuffer * buffer, GstSegment * segment, gint rate,
   return ret;
 }
 
+/**
+ * gst_audio_reorder_channels:
+ * @data: The pointer to the memory.
+ * @size: The size of the memory.
+ * @format: The %GstAudioFormat of the buffer.
+ * @channels: The number of channels.
+ * @from: The channel positions in the buffer.
+ * @to: The channel positions to convert to.
+ *
+ * Reorders @data from the channel positions @from to the channel
+ * positions @to. @from and @to must contain the same number of
+ * positions and the same positions, only in a different order.
+ *
+ * Returns: %TRUE if the reordering was possible.
+ */
+gboolean
+gst_audio_reorder_channels (gpointer data, gsize size, GstAudioFormat format,
+    gint channels, const GstAudioChannelPosition * from,
+    const GstAudioChannelPosition * to)
+{
+  const GstAudioFormatInfo *info;
+  gint i, j, n;
+  gint reorder_map[64] = { 0, };
+  guint8 *ptr;
+  gint bpf, bps;
+  guint8 tmp[64 * 8];
+
+  info = gst_audio_format_get_info (format);
+
+  g_return_val_if_fail (data != NULL, FALSE);
+  g_return_val_if_fail (from != NULL, FALSE);
+  g_return_val_if_fail (to != NULL, FALSE);
+  g_return_val_if_fail (info != NULL && info->width > 0, FALSE);
+  g_return_val_if_fail (info->width > 0, FALSE);
+  g_return_val_if_fail (info->width <= 8 * 64, FALSE);
+  g_return_val_if_fail (size % ((info->width * channels) / 8) != 0, FALSE);
+  g_return_val_if_fail (channels > 0, FALSE);
+  g_return_val_if_fail (channels <= 64, FALSE);
+
+  if (size == 0)
+    return TRUE;
+
+  if (memcmp (from, to, channels * sizeof (from[0])) == 0)
+    return TRUE;
+
+  if (!gst_audio_get_channel_reorder_map (channels, from, to, reorder_map))
+    return FALSE;
+
+  bps = info->width / 8;
+  bpf = bps * channels;
+  ptr = data;
+
+  n = size / bpf;
+  for (i = 0; i < n; i++) {
+
+    memcpy (tmp, ptr, bpf);
+    for (j = 0; j < channels; j++)
+      memcpy (ptr + reorder_map[j] * bps, tmp + j * bps, bps);
+
+    ptr += bpf;
+  }
+
+  return TRUE;
+}
+
+/**
+ * gst_audio_buffer_reorder_channels:
+ * @buffer: The buffer to reorder.
+ * @format: The %GstAudioFormat of the buffer.
+ * @channels: The number of channels.
+ * @from: The channel positions in the buffer.
+ * @to: The channel positions to convert to.
+ *
+ * Reorders @buffer from the channel positions @from to the channel
+ * positions @to. @from and @to must contain the same number of
+ * positions and the same positions, only in a different order.
+ * @buffer must be writable.
+ *
+ * Returns: %TRUE if the reordering was possible.
+ */
 gboolean
 gst_audio_buffer_reorder_channels (GstBuffer * buffer,
     GstAudioFormat format, gint channels,
@@ -932,6 +1012,7 @@ gst_audio_buffer_reorder_channels (GstBuffer * buffer,
   gboolean ret;
 
   g_return_val_if_fail (GST_IS_BUFFER (buffer), FALSE);
+  g_return_val_if_fail (gst_buffer_is_writable (buffer), FALSE);
 
   data = gst_buffer_map (buffer, &size, NULL, GST_MAP_READ | GST_MAP_WRITE);
 
@@ -942,6 +1023,18 @@ gst_audio_buffer_reorder_channels (GstBuffer * buffer,
   return ret;
 }
 
+/**
+ * gst_audio_check_valid_channel_positions:
+ * @position: The %GstAudioChannelPositions to check.
+ * @channels: The number of channels.
+ * @force_order: Only consider the GStreamer channel order.
+ *
+ * Checks if @position contains valid channel positions for
+ * @channels channels. If @force_order is %TRUE it additionally
+ * checks if the channels are in the order required by GStreamer.
+ *
+ * Returns: %TRUE if the channel positions are valid.
+ */
 gboolean
 gst_audio_check_valid_channel_positions (const GstAudioChannelPosition *
     position, gint channels, gboolean force_order)
@@ -949,6 +1042,25 @@ gst_audio_check_valid_channel_positions (const GstAudioChannelPosition *
   return check_valid_channel_positions (position, channels, force_order, NULL);
 }
 
+/**
+ * gst_audio_get_channel_reorder_map:
+ * @channels: The number of channels.
+ * @from: The channel positions to reorder from.
+ * @to: The channel positions to reorder to.
+ * @reorder_map: Pointer to the reorder map.
+ *
+ * Returns a reorder map for @from to @to that can be used in
+ * custom channel reordering code, e.g. to convert from or to the
+ * GStreamer channel order. @from and @to must contain the same
+ * number of positions and the same positions, only in a
+ * different order.
+ *
+ * The resulting @reorder_map can be used for reordering by assigning
+ * channel i of the input to channel reorder_map[i] of the output.
+ *
+ * Returns: %TRUE if the channel positions are valid and reordering
+ * is possible.
+ */
 gboolean
 gst_audio_get_channel_reorder_map (gint channels,
     const GstAudioChannelPosition * from, const GstAudioChannelPosition * to,
@@ -991,53 +1103,3 @@ gst_audio_get_channel_reorder_map (gint channels,
 
   return TRUE;
 }
-
-gboolean
-gst_audio_reorder_channels (gpointer data, gsize size, GstAudioFormat format,
-    gint channels, const GstAudioChannelPosition * from,
-    const GstAudioChannelPosition * to)
-{
-  const GstAudioFormatInfo *info;
-  gint i, j, n;
-  gint reorder_map[64] = { 0, };
-  guint8 *ptr;
-  gint bpf, bps;
-  guint8 tmp[64 * 8];
-
-  info = gst_audio_format_get_info (format);
-
-  g_return_val_if_fail (data != NULL, FALSE);
-  g_return_val_if_fail (from != NULL, FALSE);
-  g_return_val_if_fail (to != NULL, FALSE);
-  g_return_val_if_fail (info != NULL && info->width > 0, FALSE);
-  g_return_val_if_fail (info->width > 0, FALSE);
-  g_return_val_if_fail (info->width <= 8 * 64, FALSE);
-  g_return_val_if_fail (size % ((info->width * channels) / 8) != 0, FALSE);
-  g_return_val_if_fail (channels > 0, FALSE);
-  g_return_val_if_fail (channels <= 64, FALSE);
-
-  if (size == 0)
-    return TRUE;
-
-  if (memcmp (from, to, channels * sizeof (from[0])) == 0)
-    return TRUE;
-
-  if (!gst_audio_get_channel_reorder_map (channels, from, to, reorder_map))
-    return FALSE;
-
-  bps = info->width / 8;
-  bpf = bps * channels;
-  ptr = data;
-
-  n = size / bpf;
-  for (i = 0; i < n; i++) {
-
-    memcpy (tmp, ptr, bpf);
-    for (j = 0; j < channels; j++)
-      memcpy (ptr + reorder_map[j] * bps, tmp + j * bps, bps);
-
-    ptr += bpf;
-  }
-
-  return TRUE;
-}