/* GStreamer

 * Copyright (C) 2009 Axis Communications <dev-gstreamer at axis dot com>

 * @author Jonas Holmberg <jonas dot holmberg at axis dot com>

 *

 * gstbufferlist.c: Buffer list

 *

 * 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.

 */

/**

 * SECTION:gstbufferlist

 * @short_description: Grouped scatter data buffer type for data-passing

 * @see_also: #GstPad, #GstMiniObject

 *

 * Buffer lists are units of grouped scatter/gather data transfer in

 * GStreamer.

 *

 * Buffer lists are created with gst_buffer_list_new() and filled with data

 * using a #GstBufferListIterator. The iterator has no current buffer; its

 * cursor position lies between buffers, immediately before the buffer that

 * would be returned by gst_buffer_list_iterator_next(). After iterating to the

 * end of a group the iterator must be advanced to the next group by a call to

 * gst_buffer_list_iterator_next_group() before any further calls to

 * gst_buffer_list_iterator_next() can return buffers again. The cursor position

 * of a newly created iterator lies before the first group; a call to

 * gst_buffer_list_iterator_next_group() is necessary before calls to

 * gst_buffer_list_iterator_next() can return buffers.

 *

 * <informalexample>

 *   <programlisting>

 *      +--- group0 ----------------------+--- group1 ------------+

 *      |   buffer0   buffer1   buffer2   |   buffer3   buffer4   |

 *    ^   ^         ^         ^         ^   ^         ^         ^

 *    Iterator positions

 *   </programlisting>

 * </informalexample>

 *

 * The gst_buffer_list_iterator_remove(), gst_buffer_list_iterator_steal(),

 * gst_buffer_list_iterator_take(), gst_buffer_list_iterator_do() and

 * gst_buffer_list_iterator_do_data() functions are not defined in terms of the

 * cursor position; they operate on the last element returned from

 * gst_buffer_list_iterator_next().

 *

 * The basic use pattern of creating a buffer list with an iterator is as

 * follows:

 *

 * <example>

 * <title>Creating a buffer list</title>

 *   <programlisting>

 *    GstBufferList *list;

 *    GstBufferListIterator *it;

 *

 *    list = gst_buffer_list_new ();

 *    it = gst_buffer_list_iterate (list);

 *    gst_buffer_list_iterator_add_group (it);

 *    gst_buffer_list_iterator_add (it, header1);

 *    gst_buffer_list_iterator_add (it, data1);

 *    gst_buffer_list_iterator_add_group (it);

 *    gst_buffer_list_iterator_add (it, header2);

 *    gst_buffer_list_iterator_add (it, data2);

 *    gst_buffer_list_iterator_add_group (it);

 *    gst_buffer_list_iterator_add (it, header3);

 *    gst_buffer_list_iterator_add (it, data3);

 *    ...

 *    gst_buffer_list_iterator_free (it);

 *   </programlisting>

 * </example>

 *

 * The basic use pattern of iterating over a buffer list is as follows:

 *

 * <example>

 * <title>Iterating a buffer list</title>

 *   <programlisting>

 *    GstBufferListIterator *it;

 *

 *    it = gst_buffer_list_iterate (list);

 *    while (gst_buffer_list_iterator_next_group (it)) {

 *      while ((buffer = gst_buffer_list_iterator_next (it)) != NULL) {

 *        do_something_with_buffer (buffer);

 *      }

 *    }

 *    gst_buffer_list_iterator_free (it);

 *   </programlisting>

 * </example>

 *

 * The basic use pattern of modifying a buffer in a list is as follows:

 *

 * <example>

 * <title>Modifying the data of the first buffer in a list</title>

 *   <programlisting>

 *    GstBufferListIterator *it;

 *

 *    list = gst_buffer_list_make_writable (list);

 *    it = gst_buffer_list_iterate (list);

 *    if (gst_buffer_list_iterator_next_group (it)) {

 *      GstBuffer *buf

 *

 *      buf = gst_buffer_list_iterator_next (it);

 *      if (buf != NULL) {

 *        buf = gst_buffer_list_iterator_do (it,

 *            (GstBufferListDoFunction) gst_mini_object_make_writable, NULL);

 *        modify_data (GST_BUFFER_DATA (buf));

 *      }

 *    }

 *    gst_buffer_list_iterator_free (it);

 *   </programlisting>

 * </example>

 *

 * Since: 0.10.24

 */

#include "gst_private.h"

#include "gstbuffer.h"

#include "gstbufferlist.h"

#ifdef __SYMBIAN32__

#include <glib_global.h>

#endif

#define GST_CAT_DEFAULT GST_CAT_BUFFER_LIST

#define GROUP_START NULL

static const gpointer STOLEN = "";

/**

 * GstBufferList:

 * @mini_object: the parent structure

 *

 * Opaque list of grouped buffers.

 */

struct _GstBufferList

{

  GstMiniObject mini_object;

  GList *buffers;

};

struct _GstBufferListClass

{

  GstMiniObjectClass mini_object_class;

};

/**

 * GstBufferListIterator:

 *

 * Opaque iterator for a #GstBufferList.

 */

struct _GstBufferListIterator

{

  GstBufferList *list;

  GList *next;

  GList *last_returned;

};

static GType _gst_buffer_list_type = 0;

static GstMiniObjectClass *parent_class = NULL;

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

_gst_buffer_list_initialize (void)

{

  g_type_class_ref (gst_buffer_list_get_type ());

}

static void

gst_buffer_list_init (GTypeInstance * instance, gpointer g_class)

{

  GstBufferList *list;

  list = (GstBufferList *) instance;

  list->buffers = NULL;

  GST_LOG ("init %p", list);

}

static void

gst_buffer_list_finalize (GstBufferList * list)

{

  GList *tmp;

  g_return_if_fail (list != NULL);

  GST_LOG ("finalize %p", list);

  tmp = list->buffers;

  while (tmp) {

    if (tmp->data != GROUP_START && tmp->data != STOLEN) {

      gst_buffer_unref (GST_BUFFER_CAST (tmp->data));

    }

    tmp = tmp->next;

  }

  g_list_free (list->buffers);

  parent_class->finalize (GST_MINI_OBJECT_CAST (list));

}

static GstBufferList *

_gst_buffer_list_copy (GstBufferList * list)

{

  GstBufferList *list_copy;

  GList *tmp;

  g_return_val_if_fail (list != NULL, NULL);

  list_copy = gst_buffer_list_new ();

  /* shallow copy of list and pointers */

  list_copy->buffers = g_list_copy (list->buffers);

  /* ref all buffers in the list */

  tmp = list_copy->buffers;

  while (tmp) {

    if (tmp->data != GROUP_START && tmp->data != STOLEN) {

      tmp->data = gst_buffer_ref (GST_BUFFER_CAST (tmp->data));

    }

    tmp = g_list_next (tmp);

  }

  return list_copy;

}

static void

gst_buffer_list_class_init (gpointer g_class, gpointer class_data)

{

  GstBufferListClass *list_class = GST_BUFFER_LIST_CLASS (g_class);

  parent_class = g_type_class_peek_parent (g_class);

  list_class->mini_object_class.copy =

      (GstMiniObjectCopyFunction) _gst_buffer_list_copy;

  list_class->mini_object_class.finalize =

      (GstMiniObjectFinalizeFunction) gst_buffer_list_finalize;

}

/**

 * gst_buffer_list_new:

 *

 * Creates a new, empty #GstBufferList. The caller is responsible for unreffing

 * the returned #GstBufferList.

 *

 * Returns: the new #GstBufferList. gst_buffer_list_unref() after usage.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstBufferList *

gst_buffer_list_new (void)

{

  GstBufferList *list;

  list = (GstBufferList *) gst_mini_object_new (_gst_buffer_list_type);

  GST_LOG ("new %p", list);

  return list;

}

/**

 * gst_buffer_list_n_groups:

 * @list: a #GstBufferList

 *

 * Returns the number of groups in @list.

 *

 * Returns: the number of groups in the buffer list

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

guint

gst_buffer_list_n_groups (GstBufferList * list)

{

  GList *tmp;

  guint n;

  g_return_val_if_fail (list != NULL, 0);

  tmp = list->buffers;

  n = 0;

  while (tmp) {

    if (tmp->data == GROUP_START) {

      n++;

    }

    tmp = g_list_next (tmp);

  }

  return n;

}

/**

 * gst_buffer_list_foreach:

 * @list: a #GstBufferList

 * @func: a #GstBufferListFunc to call

 * @user_data: user data passed to @func

 *

 * Call @func with @data for each buffer in @list.

 *

 * @func can modify the passed buffer pointer or its contents. The return value

 * of @func define if this function returns or if the remaining buffers in a

 * group should be skipped.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func,

    gpointer user_data)

{

  GList *tmp, *next;

  guint group, idx;

  GstBufferListItem res;

  g_return_if_fail (list != NULL);

  g_return_if_fail (func != NULL);

  next = list->buffers;

  group = idx = 0;

  while (next) {

    GstBuffer *buffer;

    tmp = next;

    next = g_list_next (tmp);

    buffer = tmp->data;

    if (buffer == GROUP_START) {

      group++;

      idx = 0;

      continue;

    } else if (buffer == STOLEN)

      continue;

    else

      idx++;

    /* need to decrement the indices */

    res = func (&buffer, group - 1, idx - 1, user_data);

    if (G_UNLIKELY (buffer != tmp->data)) {

      /* the function changed the buffer */

      if (buffer == NULL) {

        /* we were asked to remove the item */

        list->buffers = g_list_delete_link (list->buffers, tmp);

        idx--;

      } else {

        /* change the buffer */

        tmp->data = buffer;

      }

    }

    switch (res) {

      case GST_BUFFER_LIST_CONTINUE:

        break;

      case GST_BUFFER_LIST_SKIP_GROUP:

        while (next && next->data != GROUP_START)

          next = g_list_next (next);

        break;

      case GST_BUFFER_LIST_END:

        return;

    }

  }

}

/**

 * gst_buffer_list_get:

 * @list: a #GstBufferList

 * @group: the group

 * @idx: the index in @group

 *

 * Get the buffer at @idx in @group.

 *

 * Note that this function is not efficient for iterating over the entire list.

 * Use an iterator or gst_buffer_list_foreach() instead.

 *

 * Returns: the buffer at @idx in @group or NULL when there is no buffer. The

 * buffer remains valid as long as @list is valid.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstBuffer *

gst_buffer_list_get (GstBufferList * list, guint group, guint idx)

{

  GList *tmp;

  guint cgroup, cidx;

  g_return_val_if_fail (list != NULL, NULL);

  tmp = list->buffers;

  cgroup = 0;

  while (tmp) {

    if (tmp->data == GROUP_START) {

      if (cgroup == group) {

        /* we found the group */

        tmp = g_list_next (tmp);

        cidx = 0;

        while (tmp && tmp->data != GROUP_START) {

          if (tmp->data != STOLEN) {

            if (cidx == idx)

              return GST_BUFFER_CAST (tmp->data);

            else

              cidx++;

          }

          tmp = g_list_next (tmp);

        }

        break;

      } else {

        cgroup++;

        if (cgroup > group)

          break;

      }

    }

    tmp = g_list_next (tmp);

  }

  return NULL;

}

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GType

gst_buffer_list_get_type (void)

{

  if (G_UNLIKELY (_gst_buffer_list_type == 0)) {

    static const GTypeInfo buffer_list_info = {

      sizeof (GstBufferListClass),

      NULL,

      NULL,

      gst_buffer_list_class_init,

      NULL,

      NULL,

      sizeof (GstBufferList),

      0,

      gst_buffer_list_init,

      NULL

    };

    _gst_buffer_list_type = g_type_register_static (GST_TYPE_MINI_OBJECT,

        "GstBufferList", &buffer_list_info, 0);

  }

  return _gst_buffer_list_type;

}

/**

 * gst_buffer_list_iterate:

 * @list: a #GstBufferList

 *

 * Iterate the buffers in @list. The owner of the iterator must also be the

 * owner of a reference to @list while the returned iterator is in use.

 *

 * Returns: a new #GstBufferListIterator of the buffers in @list.

 * gst_buffer_list_iterator_free() after usage

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstBufferListIterator *

gst_buffer_list_iterate (GstBufferList * list)

{

  GstBufferListIterator *it;

  g_return_val_if_fail (list != NULL, NULL);

  it = g_slice_new (GstBufferListIterator);

  it->list = list;

  it->next = list->buffers;

  it->last_returned = NULL;

  return it;

}

/**

 * gst_buffer_list_iterator_free:

 * @it: the #GstBufferListIterator to free

 *

 * Free the iterator.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_buffer_list_iterator_free (GstBufferListIterator * it)

{

  g_return_if_fail (it != NULL);

  g_slice_free (GstBufferListIterator, it);

}

/**

 * gst_buffer_list_iterator_n_buffers:

 * @it: a #GstBufferListIterator

 *

 * Returns the number of buffers left to iterate in the current group. I.e. the

 * number of calls that can be made to gst_buffer_list_iterator_next() before

 * it returns NULL.

 *

 * This function will not move the implicit cursor or in any other way affect

 * the state of the iterator @it.

 *

 * Returns: the number of buffers left to iterate in the current group

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

guint

gst_buffer_list_iterator_n_buffers (const GstBufferListIterator * it)

{