/* GStreamer

 * Copyright (C) <2003> David A. Schleef <ds@schleef.org>

 *

 * 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:gstcaps

 * @short_description: Structure describing sets of media formats

 * @see_also: #GstStructure

 *

 * Caps (capabilities) are lighweight refcounted objects describing media types.

 * They are composed of an array of #GstStructure.

 *

 * Caps are exposed on #GstPadTemplate to describe all possible types a

 * given pad can handle. They are also stored in the #GstRegistry along with

 * a description of the #GstElement.

 *

 * Caps are exposed on the element pads using the gst_pad_get_caps() pad

 * function. This function describes the possible types that the pad can

 * handle or produce at runtime.

 *

 * Caps are also attached to buffers to describe to content of the data

 * pointed to by the buffer with gst_buffer_set_caps(). Caps attached to

 * a #GstBuffer allow for format negotiation upstream and downstream.

 *

 * A #GstCaps can be constructed with the following code fragment:

 *

 * <example>

 *  <title>Creating caps</title>

 *  <programlisting>

 *  GstCaps *caps;

 *  caps = gst_caps_new_simple ("video/x-raw-yuv",

 *       "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),

 *       "framerate", GST_TYPE_FRACTION, 25, 1,

 *       "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,

 *       "width", G_TYPE_INT, 320,

 *       "height", G_TYPE_INT, 240,

 *       NULL);

 *  </programlisting>

 * </example>

 *

 * A #GstCaps is fixed when it has no properties with ranges or lists. Use

 * gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be

 * set on a #GstPad or #GstBuffer.

 *

 * Various methods exist to work with the media types such as subtracting

 * or intersecting.

 *

 * Last reviewed on 2007-02-13 (0.10.10)

 */

#ifdef HAVE_CONFIG_H

#include "config.h"

#endif

#include <string.h>

#include <signal.h>

#include "gst_private.h"

#include <gst/gst.h>

#ifdef __SYMBIAN32__

#include <glib_global.h>

#endif

#define DEBUG_REFCOUNT

#define CAPS_POISON(caps) G_STMT_START{ \

  if (caps) { \

    GstCaps *_newcaps = gst_caps_copy (caps); \

    gst_caps_unref(caps); \

    caps = _newcaps; \

  } \

} G_STMT_END

#define STRUCTURE_POISON(structure) G_STMT_START{ \

  if (structure) { \

    GstStructure *_newstruct = gst_structure_copy (structure); \

    gst_structure_free(structure); \

    structure = _newstruct; \

  } \

} G_STMT_END

#define IS_WRITABLE(caps) \

  (g_atomic_int_get (&(caps)->refcount) == 1)

/* quick way to get a caps structure at an index without doing a type or array

 * length check */

#define gst_caps_get_structure_unchecked(caps, index) \

     ((GstStructure *)g_ptr_array_index ((caps)->structs, (index)))

/* lock to protect multiple invocations of static caps to caps conversion */

G_LOCK_DEFINE_STATIC (static_caps_lock);

static void gst_caps_transform_to_string (const GValue * src_value,

    GValue * dest_value);

static gboolean gst_caps_from_string_inplace (GstCaps * caps,

    const gchar * string);

static GstCaps *gst_caps_copy_conditional (GstCaps * src);

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GType

gst_caps_get_type (void)

{

  static GType gst_caps_type = 0;

  if (G_UNLIKELY (gst_caps_type == 0)) {

    gst_caps_type = g_boxed_type_register_static ("GstCaps",

        (GBoxedCopyFunc) gst_caps_copy_conditional,

        (GBoxedFreeFunc) gst_caps_unref);

    g_value_register_transform_func (gst_caps_type,

        G_TYPE_STRING, gst_caps_transform_to_string);

  }

  return gst_caps_type;

}

/* creation/deletion */

/**

 * gst_caps_new_empty:

 *

 * Creates a new #GstCaps that is empty.  That is, the returned

 * #GstCaps contains no media formats.

 * Caller is responsible for unreffing the returned caps.

 *

 * Returns: the new #GstCaps

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstCaps *

gst_caps_new_empty (void)

{

  GstCaps *caps = g_slice_new (GstCaps);

  caps->type = GST_TYPE_CAPS;

  caps->refcount = 1;

  caps->flags = 0;

  caps->structs = g_ptr_array_new ();

#ifdef DEBUG_REFCOUNT

  GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);

#endif

  return caps;

}

/**

 * gst_caps_new_any:

 *

 * Creates a new #GstCaps that indicates that it is compatible with

 * any media format.

 *

 * Returns: the new #GstCaps

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstCaps *

gst_caps_new_any (void)

{

  GstCaps *caps = gst_caps_new_empty ();

  caps->flags = GST_CAPS_FLAGS_ANY;

  return caps;

}

/**

 * gst_caps_new_simple:

 * @media_type: the media type of the structure

 * @fieldname: first field to set

 * @...: additional arguments

 *

 * Creates a new #GstCaps that contains one #GstStructure.  The

 * structure is defined by the arguments, which have the same format

 * as gst_structure_new().

 * Caller is responsible for unreffing the returned caps.

 *

 * Returns: the new #GstCaps

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstCaps *

gst_caps_new_simple (const char *media_type, const char *fieldname, ...)

{

  GstCaps *caps;

  GstStructure *structure;

  va_list var_args;

  caps = gst_caps_new_empty ();

  va_start (var_args, fieldname);

  structure = gst_structure_new_valist (media_type, fieldname, var_args);

  va_end (var_args);

  gst_caps_append_structure (caps, structure);

  return caps;

}

/**

 * gst_caps_new_full:

 * @struct1: the first structure to add

 * @...: additional structures to add

 *

 * Creates a new #GstCaps and adds all the structures listed as

 * arguments.  The list must be NULL-terminated.  The structures

 * are not copied; the returned #GstCaps owns the structures.

 *

 * Returns: the new #GstCaps

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstCaps *

gst_caps_new_full (GstStructure * struct1, ...)

{

  GstCaps *caps;

  va_list var_args;

  va_start (var_args, struct1);

  caps = gst_caps_new_full_valist (struct1, var_args);

  va_end (var_args);

  return caps;

}

/**

 * gst_caps_new_full_valist:

 * @structure: the first structure to add

 * @var_args: additional structures to add

 *

 * Creates a new #GstCaps and adds all the structures listed as

 * arguments.  The list must be NULL-terminated.  The structures

 * are not copied; the returned #GstCaps owns the structures.

 *

 * Returns: the new #GstCaps

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstCaps *

gst_caps_new_full_valist (GstStructure * structure, va_list var_args)

{

  GstCaps *caps;

  caps = gst_caps_new_empty ();

  while (structure) {

    gst_caps_append_structure (caps, structure);

    structure = va_arg (var_args, GstStructure *);

  }

  return caps;

}

/**

 * gst_caps_copy:

 * @caps: the #GstCaps to copy

 *

 * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a

 * refcount of 1, owned by the caller. The structures are copied as well.

 *

 * Note that this function is the semantic equivalent of a gst_caps_ref()

 * followed by a gst_caps_make_writable(). If you only want to hold on to a

 * reference to the data, you should use gst_caps_ref().

 *

 * When you are finished with the caps, call gst_caps_unref() on it.

 *

 * Returns: the new #GstCaps

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstCaps *

gst_caps_copy (const GstCaps * caps)

{

  GstCaps *newcaps;

  GstStructure *structure;

  guint i, n;

  g_return_val_if_fail (GST_IS_CAPS (caps), NULL);

  newcaps = gst_caps_new_empty ();

  newcaps->flags = caps->flags;

  n = caps->structs->len;

  for (i = 0; i < n; i++) {

    structure = gst_caps_get_structure_unchecked (caps, i);

    gst_caps_append_structure (newcaps, gst_structure_copy (structure));

  }

  return newcaps;

}

static void

_gst_caps_free (GstCaps * caps)

{

  GstStructure *structure;

  guint i, len;

  /* The refcount must be 0, but since we're only called by gst_caps_unref,

   * don't bother testing. */

  len = caps->structs->len;

  for (i = 0; i < len; i++) {

    structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);

    gst_structure_set_parent_refcount (structure, NULL);

    gst_structure_free (structure);

  }

  g_ptr_array_free (caps->structs, TRUE);

#ifdef USE_POISONING

  memset (caps, 0xff, sizeof (GstCaps));

#endif

#ifdef DEBUG_REFCOUNT

  GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);

#endif

  g_slice_free (GstCaps, caps);

}

/**

 * gst_caps_make_writable:

 * @caps: the #GstCaps to make writable

 *

 * Returns a writable copy of @caps.

 *

 * If there is only one reference count on @caps, the caller must be the owner,

 * and so this function will return the caps object unchanged. If on the other

 * hand there is more than one reference on the object, a new caps object will

 * be returned. The caller's reference on @caps will be removed, and instead the

 * caller will own a reference to the returned object.

 *

 * In short, this function unrefs the caps in the argument and refs the caps

 * that it returns. Don't access the argument after calling this function. See

 * also: gst_caps_ref().

 *

 * Returns: the same #GstCaps object.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstCaps *

gst_caps_make_writable (GstCaps * caps)

{

  GstCaps *copy;

  g_return_val_if_fail (caps != NULL, NULL);

  /* we are the only instance reffing this caps */

  if (g_atomic_int_get (&caps->refcount) == 1)

    return caps;

  /* else copy */

  copy = gst_caps_copy (caps);

  gst_caps_unref (caps);

  return copy;

}

/**

 * gst_caps_ref:

 * @caps: the #GstCaps to reference

 *

 * Add a reference to a #GstCaps object.

 *

 * From this point on, until the caller calls gst_caps_unref() or

 * gst_caps_make_writable(), it is guaranteed that the caps object will not

 * change. This means its structures won't change, etc. To use a #GstCaps

 * object, you must always have a refcount on it -- either the one made

 * implicitly by gst_caps_new(), or via taking one explicitly with this

 * function.

 *

 * Returns: the same #GstCaps object.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstCaps *

gst_caps_ref (GstCaps * caps)

{

  g_return_val_if_fail (caps != NULL, NULL);

#ifdef DEBUG_REFCOUNT

  GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p %d->%d", caps,

      GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) + 1);

#endif

  g_return_val_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0, NULL);

  g_atomic_int_inc (&caps->refcount);

  return caps;

}

/**

 * gst_caps_unref:

 * @caps: the #GstCaps to unref

 *

 * Unref a #GstCaps and and free all its structures and the

 * structures' values when the refcount reaches 0.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_caps_unref (GstCaps * caps)

{

  g_return_if_fail (caps != NULL);

#ifdef DEBUG_REFCOUNT

  GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p %d->%d", caps,

      GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) - 1);

#endif

  g_return_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0);

  /* if we ended up with the refcount at zero, free the caps */

  if (G_UNLIKELY (g_atomic_int_dec_and_test (&caps->refcount)))

    _gst_caps_free (caps);

}

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GType

gst_static_caps_get_type (void)

{

  static GType staticcaps_type = 0;

  if (G_UNLIKELY (staticcaps_type == 0)) {

    staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");

  }

  return staticcaps_type;

}

/**

 * gst_static_caps_get:

 * @static_caps: the #GstStaticCaps to convert

 *

 * Converts a #GstStaticCaps to a #GstCaps.

 *

 * Returns: A pointer to the #GstCaps. Unref after usage. Since the

 * core holds an additional ref to the returned caps,

 * use gst_caps_make_writable() on the returned caps to modify it.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstCaps *

gst_static_caps_get (GstStaticCaps * static_caps)

{

  GstCaps *caps;

  g_return_val_if_fail (static_caps != NULL, NULL);

  caps = (GstCaps *) static_caps;

  /* refcount is 0 when we need to convert */

  if (G_UNLIKELY (g_atomic_int_get (&caps->refcount) == 0)) {

    const char *string;

    GstCaps temp;

    G_LOCK (static_caps_lock);

    /* check if other thread already updated */

    if (G_UNLIKELY (g_atomic_int_get (&caps->refcount) > 0))

      goto done;

    string = static_caps->string;

    if (G_UNLIKELY (string == NULL))

      goto no_string;

    GST_CAT_LOG (GST_CAT_CAPS, "creating %p", static_caps);

    /* we construct the caps on the stack, then copy over the struct into our

     * real caps, refcount last. We do this because we must leave the refcount

     * of the result caps to 0 so that other threads don't run away with the

     * caps while we are constructing it. */

    temp.type = GST_TYPE_CAPS;

    temp.flags = 0;

    temp.structs = g_ptr_array_new ();

    /* initialize the caps to a refcount of 1 so the caps can be writable for

     * the next statement */

    temp.refcount = 1;

    /* convert to string */

    if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))

      g_critical ("Could not convert static caps \"%s\"", string);

    /* now copy stuff over to the real caps. */

    caps->type = temp.type;

    caps->flags = temp.flags;

    caps->structs = temp.structs;

    /* and bump the refcount so other threads can now read */

    g_atomic_int_set (&caps->refcount, 1);