## GstCaps

GstCaps — Structure describing sets of media formats

## Synopsis

    #include <gst/gst.h>

    #define     GST_CAPS_FLAGS_ANY
    #define     GST_CAPS_ANY
    #define     GST_CAPS_NONE
    #define     GST_STATIC_CAPS_ANY
    #define     GST_STATIC_CAPS_NONE
    #define     GST_CAPS_IS_SIMPLE              (caps)
    #define     gst_caps_is_simple              (caps)
    #define     GST_DEBUG_CAPS                  (string, caps)
    #define     GST_STATIC_CAPS                 (string)
                GstCaps;
                GstStaticCaps;
    GstCaps*    gst_caps_new_empty              (void);
    GstCaps*    gst_caps_new_any                (void);
    GstCaps*    gst_caps_new_simple             (const char *media_type,
                                                 const char *fieldname,
                                                 ...);
    GstCaps*    gst_caps_new_full               (GstStructure *struct1,
                                                 ...);
    GstCaps*    gst_caps_new_full_valist        (GstStructure *structure,
                                                 va_list var_args);
    GstCaps*    gst_caps_copy                   (const GstCaps *caps);
    void        gst_caps_free                   (GstCaps *caps);
    const GstCaps* gst_static_caps_get          (GstStaticCaps *static_caps);
    void        gst_caps_append                 (GstCaps *caps1,
                                                 GstCaps *caps2);
    void        gst_caps_append_structure       (GstCaps *caps,
                                                 GstStructure *structure);
    GstCaps*    gst_caps_split_one              (GstCaps *caps);
    int         gst_caps_get_size               (const GstCaps *caps);
    GstStructure* gst_caps_get_structure        (const GstCaps *caps,
                                                 int index);
    GstCaps*    gst_caps_copy_1                 (const GstCaps *caps);
    void        gst_caps_set_simple             (GstCaps *caps,
                                                 char *field,
                                                 ...);
    void        gst_caps_set_simple_valist      (GstCaps *caps,
                                                 char *field,
                                                 va_list varargs);
    gboolean    gst_caps_is_any                 (const GstCaps *caps);
    gboolean    gst_caps_is_empty               (const GstCaps *caps);
    gboolean    gst_caps_is_chained             (const GstCaps *caps);
    gboolean    gst_caps_is_fixed               (const GstCaps *caps);
    gboolean    gst_caps_is_equal               (const GstCaps *caps1,
                                                 const GstCaps *caps2);
    gboolean    gst_caps_is_equal_fixed         (const GstCaps *caps1,
                                                 const GstCaps *caps2);
    gboolean    gst_caps_is_always_compatible   (const GstCaps *caps1,
                                                 const GstCaps *caps2);
    gboolean    gst_caps_is_subset              (const GstCaps *subset,
                                                 const GstCaps *superset);
    GstCaps*    gst_caps_intersect              (const GstCaps *caps1,
                                                 const GstCaps *caps2);
    GstCaps*    gst_caps_union                  (const GstCaps *caps1,
                                                 const GstCaps *caps2);
    GstCaps*    gst_caps_normalize              (const GstCaps *caps);
    GstCaps*    gst_caps_simplify               (const GstCaps *caps);
    gboolean    gst_caps_do_simplify            (GstCaps *caps);
    xmlNodePtr  gst_caps_save_thyself           (const GstCaps *caps,
                                                 xmlNodePtr parent);
    GstCaps*    gst_caps_load_thyself           (xmlNodePtr parent);
    void        gst_caps_replace                (GstCaps **caps,
                                                 GstCaps *newcaps);
    gchar*      gst_caps_to_string              (const GstCaps *caps);
    GstCaps*    gst_caps_from_string            (const gchar *string);
    gboolean    gst_caps_structure_fixate_field_nearest_int
                                                (GstStructure *structure,
                                                 const char *field_name,
                                                 int target);
    gboolean    gst_caps_structure_fixate_field_nearest_double
                                                (GstStructure *structure,
                                                 const char *field_name,
                                                 double target);
    GstCaps*    gst_caps_subtract               (const GstCaps *minuend,
                                                 const GstCaps *subtrahend);

## Description

## Details

### GST_CAPS_FLAGS_ANY

    #define GST_CAPS_FLAGS_ANY	  (1 << 0)

Flags that this caps has no specific content, but can contain anything.

### GST_CAPS_ANY

    #define GST_CAPS_ANY              gst_caps_new_any()

Means that the element/pad can output 'anything'. Useful for elements that output unknown media, such as filesrc.

### GST_CAPS_NONE

    #define GST_CAPS_NONE             gst_caps_new_empty()

The opposite of GST_CAPS_ANY: it means that the pad/element outputs an undefined media type that can not be detected.

### GST_STATIC_CAPS_ANY

    #define GST_STATIC_CAPS_ANY       GST_STATIC_CAPS("ANY")

Creates a static caps that matches anything. This can be used in pad templates.

Returns : | a new GstCaps instance

### GST_STATIC_CAPS_NONE

    #define GST_STATIC_CAPS_NONE      GST_STATIC_CAPS("NONE")

Creates a static caps that matches nothing. This can be used in pad templates.

Returns : | a new GstCaps instance

### GST_CAPS_IS_SIMPLE()

    #define GST_CAPS_IS_SIMPLE(caps) (gst_caps_get_size(caps) == 1)

Convinience macro that checks if the number of structures in the gives caps is exactly one.

`caps` : | the GstCaps instance to check

### gst_caps_is_simple()

    #define gst_caps_is_simple(caps) GST_CAPS_IS_SIMPLE(caps)

`caps` : |

### GST_DEBUG_CAPS()

    #define     GST_DEBUG_CAPS(string, caps)

### Warning

`GST_DEBUG_CAPS` is deprecated and should not be used in newly-written code.

Convinience macro for prining out the contents of caps with `GST_DEBUG()`.

`string` : | a string the should be prepend to the caps data.
`caps` : | the caps to print

### GST_STATIC_CAPS()

    #define     GST_STATIC_CAPS(string)

Creates a static caps from an input string. This can be used in pad templates.

`string` : | the string describing the caps.
Returns : | a new GstCaps instance

### GstCaps

    typedef struct {
      GType type;

      guint16 flags;
      GPtrArray *structs;

      gpointer _gst_reserved[GST_PADDING];
    } GstCaps;

### GstStaticCaps

    typedef struct {
      GstCaps caps;
      const char *string;
      gpointer _gst_reserved[GST_PADDING];
    } GstStaticCaps;

### gst_caps_new_empty ()

    GstCaps*    gst_caps_new_empty              (void);

Creates a new GstCaps that is empty. That is, the returned GstCaps contains no media formats.

Returns : | the new GstCaps

### gst_caps_new_any ()

    GstCaps*    gst_caps_new_any                (void);

Creates a new GstCaps that indicates that it is compatible with any media format.

Returns : | the new GstCaps

### gst_caps_new_simple ()

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

Creates a new GstCaps that contains one GstStructure. The structure is defined by the arguments, which have the same format as @`gst_structure_new()`.

`media_type` : | the media type of the structure
`fieldname` : | first field to set
`...` : | additional arguments
Returns : | the new GstCaps

### gst_caps_new_full ()

    GstCaps*    gst_caps_new_full               (GstStructure *struct1,
                                                 ...);

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.

`struct1` : | the first structure to add
`...` : | additional structures to add
Returns : | the new GstCaps

### gst_caps_new_full_valist ()

    GstCaps*    gst_caps_new_full_valist        (GstStructure *structure,
                                                 va_list var_args);

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.

`structure` : | the first structure to add
`var_args` : | additional structures to add
Returns : | the new GstCaps

### gst_caps_copy ()

    GstCaps*    gst_caps_copy                   (const GstCaps *caps);

Deeply copies a GstCaps, including all structures and all the structures' values.

`caps` : | the GstCaps to copy
Returns : | the new GstCaps

### gst_caps_free ()

    void        gst_caps_free                   (GstCaps *caps);

Frees a GstCaps and all its structures and the structures' values.

`caps` : | the GstCaps to free

### gst_static_caps_get ()

    const GstCaps* gst_static_caps_get          (GstStaticCaps *static_caps);

Converts a GstStaticCaps to a GstCaps.

`static_caps` : | the GstStaticCaps to convert
Returns : | the new GstCaps

### gst_caps_append ()

    void        gst_caps_append                 (GstCaps *caps1,
                                                 GstCaps *caps2);

Appends the structures contained in `caps2` to `caps1`. The structures in `caps2` are not copied -- they are transferred to `caps1`, and then `caps2` is freed.

`caps1` : | the GstCaps that will be appended to
`caps2` : | the GstCaps to append

### gst_caps_append_structure ()

    void        gst_caps_append_structure       (GstCaps *caps,
                                                 GstStructure *structure);

Appends `structure` to `caps`. The structure is not copied; `caps` becomes the owner of `structure`.

`caps` : | the GstCaps that will be appended to
`structure` : | the GstStructure to append

### gst_caps_split_one ()

    GstCaps*    gst_caps_split_one              (GstCaps *caps);

### Warning

`gst_caps_split_one` is deprecated and should not be used in newly-written code.

This function is not implemented.

`caps` : | a GstCaps
Returns : | NULL

### gst_caps_get_size ()

    int         gst_caps_get_size               (const GstCaps *caps);

Gets the number of structures contained in `caps`.

`caps` : | a GstCaps
Returns : | the number of structures that `caps` contains

### gst_caps_get_structure ()

    GstStructure* gst_caps_get_structure        (const GstCaps *caps,
                                                 int index);

Finds the structure in `caps` that has the index `index`, and returns it.

WARNING: This function takes a const GstCaps *, but returns a non-const GstStructure *. This is for programming convenience -- the caller should be aware that structures inside a constant `GstCaps` should not be modified.

`caps` : | a GstCaps
`index` : | the index of the structure
Returns : | a pointer to the GstStructure corresponding to `index`

### gst_caps_copy_1 ()

    GstCaps*    gst_caps_copy_1                 (const GstCaps *caps);

### Warning

`gst_caps_copy_1` is deprecated and should not be used in newly-written code.

Creates a new `GstCaps` and appends a copy of the first structure contained in `caps`.

`caps` : | the `GstCaps` to copy
Returns : | the new `GstCaps`

### gst_caps_set_simple ()

    void        gst_caps_set_simple             (GstCaps *caps,
                                                 char *field,
                                                 ...);

Sets fields in a simple GstCaps. A simple GstCaps is one that only has one structure. The arguments must be passed in the same manner as @`gst_structure_set()`, and be NULL-terminated.

`caps` : | the `GstCaps` to set
`field` : | first field to set
`...` : | additional parameters

### gst_caps_set_simple_valist ()

    void        gst_caps_set_simple_valist      (GstCaps *caps,
                                                 char *field,
                                                 va_list varargs);

Sets fields in a simple GstCaps. A simple GstCaps is one that only has one structure. The arguments must be passed in the same manner as @`gst_structure_set()`, and be NULL-terminated.

`caps` : | the `GstCaps` to copy
`field` : | first field to set
`varargs` : | additional parameters

### gst_caps_is_any ()

    gboolean    gst_caps_is_any                 (const GstCaps *caps);

Determines if `caps` represents any media format.

`caps` : | the `GstCaps` to test
Returns : | TRUE if `caps` represents any format.

### gst_caps_is_empty ()

    gboolean    gst_caps_is_empty               (const GstCaps *caps);

Determines if `caps` represents no media formats.

`caps` : | the `GstCaps` to test
Returns : | TRUE if `caps` represents no formats.

### gst_caps_is_chained ()

    gboolean    gst_caps_is_chained             (const GstCaps *caps);

### Warning

`gst_caps_is_chained` is deprecated and should not be used in newly-written code.

Determines if `caps` contains multiple GstStructures.

This function is deprecated, and should not be used in new code. Use #`gst_caps_is_simple()` instead.

`caps` : | the `GstCaps` to test
Returns : | TRUE if `caps` contains more than one structure

### gst_caps_is_fixed ()

    gboolean    gst_caps_is_fixed               (const GstCaps *caps);

Fixed `GstCaps` describe exactly one format, that is, they have exactly one structure, and each field in the structure describes a fixed type. Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.

`caps` : | the `GstCaps` to test
Returns : | TRUE if `caps` is fixed

### gst_caps_is_equal ()

    gboolean    gst_caps_is_equal               (const GstCaps *caps1,
                                                 const GstCaps *caps2);

Checks if the given caps represent the same set of caps.

### Note

This function does not work reliably if optional properties for caps are included on one caps and omitted on the other.

`caps1` : | a GstCaps
`caps2` : | another GstCaps
Returns : | TRUE if both caps are equal

### gst_caps_is_equal_fixed ()

    gboolean    gst_caps_is_equal_fixed         (const GstCaps *caps1,
                                                 const GstCaps *caps2);

### Warning

`gst_caps_is_equal_fixed` is deprecated and should not be used in newly-written code.

Tests if two GstCaps are equal. This function only works on fixed GstCaps.

`caps1` : | the GstCaps to test
`caps2` : | the GstCaps to test
Returns : | TRUE if the arguments represent the same format

### gst_caps_is_always_compatible ()

    gboolean    gst_caps_is_always_compatible   (const GstCaps *caps1,
                                                 const GstCaps *caps2);

A given GstCaps structure is always compatible with another if every media format that is in the first is also contained in the second. That is, `caps1` is a subset of `caps2`.

`caps1` : | the GstCaps to test
`caps2` : | the GstCaps to test
Returns : | TRUE if `caps1` is a subset of `caps2`.

### gst_caps_is_subset ()

    gboolean    gst_caps_is_subset              (const GstCaps *subset,
                                                 const GstCaps *superset);

Checks if all caps represented by `subset` are also represented by `superset`

### Note

This function does not work reliably if optional properties for caps are included on one caps and omitted on the other.

`subset` : | a GstCaps
`superset` : | a potentially greater GstCaps
Returns : | TRUE if `subset` is a subset of `superset`

### gst_caps_intersect ()

    GstCaps*    gst_caps_intersect              (const GstCaps *caps1,
                                                 const GstCaps *caps2);

Creates a new GstCaps that contains all the formats that are common to both `caps1` and `caps2`.

`caps1` : | a GstCaps to intersect
`caps2` : | a GstCaps to intersect
Returns : | the new GstCaps

### gst_caps_union ()

    GstCaps*    gst_caps_union                  (const GstCaps *caps1,
                                                 const GstCaps *caps2);

Creates a new GstCaps that contains all the formats that are in either `caps1` and `caps2`.

`caps1` : | a GstCaps to union
`caps2` : | a GstCaps to union
Returns : | the new GstCaps

### gst_caps_normalize ()

    GstCaps*    gst_caps_normalize              (const GstCaps *caps);

Creates a new GstCaps that represents the same set of formats as `caps`, but contains no lists. Each list is expanded into separate `GstStructures`.

`caps` : | a GstCaps to normalize
Returns : | the new GstCaps

### gst_caps_simplify ()

    GstCaps*    gst_caps_simplify               (const GstCaps *caps);

### Warning

`gst_caps_simplify` is deprecated and should not be used in newly-written code.

Creates a new GstCaps that represents the same set of formats as `caps`, but simpler. Component structures that are identical are merged. Component structures that have ranges or lists that can be merged are also merged.

`caps` : | a GstCaps to simplify
Returns : | the new GstCaps

### gst_caps_do_simplify ()

    gboolean    gst_caps_do_simplify            (GstCaps *caps);

Modifies the given `caps` inplace into a representation that represents the same set of formats, but in a simpler form. Component structures that are identical are merged. Component structures that have values that can be merged are also merged.

`caps` : | a GstCaps to simplify
Returns : | TRUE, if the caps could be simplified

### gst_caps_save_thyself ()

    xmlNodePtr  gst_caps_save_thyself           (const GstCaps *caps,
                                                 xmlNodePtr parent);

Serializes a GstCaps to XML and adds it as a child node of `parent`.

`caps` : | a GstCaps structure
`parent` : | a XML parent node
Returns : | a XML node pointer

### gst_caps_load_thyself ()

    GstCaps*    gst_caps_load_thyself           (xmlNodePtr parent);

Creates a GstCaps from its XML serialization.

`parent` : | a XML node
Returns : | a new GstCaps structure

### gst_caps_replace ()

    void        gst_caps_replace                (GstCaps **caps,
                                                 GstCaps *newcaps);

Replaces *caps with `newcaps`. Frees the GstCaps in the location pointed to by `caps`, if applicable, then modifies `caps` to point to `newcaps`.

`caps` : | a pointer to GstCaps
`newcaps` : | a GstCaps to replace *caps

### gst_caps_to_string ()

    gchar*      gst_caps_to_string              (const GstCaps *caps);

Converts `caps` to a string representation. This string representation can be converted back to a GstCaps by gst_caps_from_string.

`caps` : | a GstCaps
Returns : | a newly allocated string representing `caps`.

### gst_caps_from_string ()

    GstCaps*    gst_caps_from_string            (const gchar *string);

Converts `caps` from a string representation.

`string` : | a string to convert to GstCaps
Returns : | a newly allocated GstCaps

### gst_caps_structure_fixate_field_nearest_int ()

    gboolean    gst_caps_structure_fixate_field_nearest_int
                                                (GstStructure *structure,
                                                 const char *field_name,
                                                 int target);

Fixates a GstStructure by changing the given field to the nearest integer to `target` that is a subset of the existing field.

`structure` : | a GstStructure
`field_name` : | a field in `structure`
`target` : | the target value of the fixation
Returns : | TRUE if the structure could be fixated

### gst_caps_structure_fixate_field_nearest_double ()

    gboolean    gst_caps_structure_fixate_field_nearest_double
                                                (GstStructure *structure,
                                                 const char *field_name,
                                                 double target);

Fixates a GstStructure by changing the given field to the nearest double to `target` that is a subset of the existing field.

`structure` : | a GstStructure
`field_name` : | a field in `structure`
`target` : | the target value of the fixation
Returns : | TRUE if the structure could be fixated

### gst_caps_subtract ()

    GstCaps*    gst_caps_subtract               (const GstCaps *minuend,
                                                 const GstCaps *subtrahend);

Subtracts the `subtrahend` from the `minuend`.

### Note

This function does not work reliably if optional properties for caps are included on one caps and omitted on the other.

`minuend` : | GstCaps to substract from
`subtrahend` : | GstCaps to substract
Returns : | the resulting caps