GstCapsFeatures: GStreamer 1.0 Core Reference Manual

## GstCapsFeatures GstCapsFeatures — A set of features in caps |

## Functions

GstCapsFeatures * | gst_caps_features_new ()
GstCapsFeatures * | gst_caps_features_new_empty ()
GstCapsFeatures * | gst_caps_features_new_any ()
GstCapsFeatures * | gst_caps_features_new_id ()
GstCapsFeatures * | gst_caps_features_new_id_valist ()
GstCapsFeatures * | gst_caps_features_new_valist ()
GstCapsFeatures * | gst_caps_features_copy ()
void | gst_caps_features_free ()
GstCapsFeatures * | gst_caps_features_from_string ()
gchar * | gst_caps_features_to_string ()
gboolean | gst_caps_features_set_parent_refcount ()
gboolean | gst_caps_features_is_equal ()
gboolean | gst_caps_features_is_any ()
gboolean | gst_caps_features_contains ()
gboolean | gst_caps_features_contains_id ()
guint | gst_caps_features_get_size ()
const gchar * | gst_caps_features_get_nth ()
GQuark | gst_caps_features_get_nth_id ()
void | gst_caps_features_add ()
void | gst_caps_features_add_id ()
void | gst_caps_features_remove ()
void | gst_caps_features_remove_id ()

## Types and Values

| GstCapsFeatures
#define | GST_CAPS_FEATURES_ANY
#define | GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY
#define | GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY

## Object Hierarchy

        GBoxed
        ╰── GstCapsFeatures

## Includes

    #include <gst/gst.h>

## Description

GstCapsFeatures can optionally be set on a GstCaps to add requirements for additional features for a specific GstStructure. Caps structures with the same name but with a non-equal set of caps features are not compatible. If a pad supports multiple sets of features it has to add multiple equal structures with different feature sets to the caps.

Empty GstCapsFeatures are equivalent with the GstCapsFeatures that only contain GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY. ANY GstCapsFeatures as created by `gst_caps_features_new_any()` are equal to any other GstCapsFeatures and can be used to specify that any GstCapsFeatures would be supported, e.g. for elements that don't touch buffer memory. GstCaps with ANY GstCapsFeatures are considered non-fixed and during negotiation some GstCapsFeatures have to be selected.

Examples for caps features would be the requirement of a specific GstMemory types or the requirement of having a specific GstMeta on the buffer. Features are given as a string of the format "memory:GstMemoryTypeName" or "meta:GstMetaAPIName".

## Functions

### gst_caps_features_new ()

    GstCapsFeatures *
    gst_caps_features_new (const gchar *feature1,
                           ...);

Creates a new GstCapsFeatures with the given features. The last argument must be `NULL`.

Free-function: gst_caps_features_free

#### Parameters

feature1 | name of first feature to set |
... | additional features |

#### Returns

a new, empty GstCapsFeatures.

[transfer full]

Since: 1.2

### gst_caps_features_new_empty ()

    GstCapsFeatures *
    gst_caps_features_new_empty (void);

Creates a new, empty GstCapsFeatures.

Free-function: gst_caps_features_free

#### Returns

a new, empty GstCapsFeatures.

[transfer full]

Since: 1.2

### gst_caps_features_new_any ()

    GstCapsFeatures *
    gst_caps_features_new_any (void);

Creates a new, ANY GstCapsFeatures. This will be equal to any other GstCapsFeatures but caps with these are unfixed.

Free-function: gst_caps_features_free

#### Returns

a new, ANY GstCapsFeatures.

[transfer full]

Since: 1.2

### gst_caps_features_new_id ()

    GstCapsFeatures *
    gst_caps_features_new_id (GQuark feature1,
                              ...);

Creates a new GstCapsFeatures with the given features. The last argument must be 0.

Free-function: gst_caps_features_free

#### Parameters

feature1 | name of first feature to set |
... | additional features |

#### Returns

a new, empty GstCapsFeatures.

[transfer full]

Since: 1.2

### gst_caps_features_new_id_valist ()

    GstCapsFeatures *
    gst_caps_features_new_id_valist (GQuark feature1,
                                     va_list varargs);

Creates a new GstCapsFeatures with the given features.

Free-function: gst_caps_features_free

#### Parameters

feature1 | name of first feature to set |
varargs | variable argument list |

#### Returns

a new, empty GstCapsFeatures.

[transfer full]

Since: 1.2

### gst_caps_features_new_valist ()

    GstCapsFeatures *
    gst_caps_features_new_valist (const gchar *feature1,
                                  va_list varargs);

Creates a new GstCapsFeatures with the given features.

Free-function: gst_caps_features_free

#### Parameters

feature1 | name of first feature to set |
varargs | variable argument list |

#### Returns

a new, empty GstCapsFeatures.

[transfer full]

Since: 1.2

### gst_caps_features_copy ()

    GstCapsFeatures *
    gst_caps_features_copy (const GstCapsFeatures *features);

Duplicates a GstCapsFeatures and all its values.

Free-function: gst_caps_features_free

#### Parameters

features | a GstCapsFeatures to duplicate |

#### Returns

a new GstCapsFeatures.

[transfer full]

Since: 1.2

### gst_caps_features_free ()

    void
    gst_caps_features_free (GstCapsFeatures *features);

Frees a GstCapsFeatures and all its values. The caps features must not have a parent when this function is called.

#### Parameters

features | the GstCapsFeatures to free. | [in][transfer full]

Since: 1.2

### gst_caps_features_from_string ()

    GstCapsFeatures *
    gst_caps_features_from_string (const gchar *features);

Creates a GstCapsFeatures from a string representation.

Free-function: gst_caps_features_free

#### Parameters

features | a string representation of a GstCapsFeatures. |

#### Returns

a new GstCapsFeatures or `NULL` when the string could not be parsed. Free with `gst_caps_features_free()` after use.

[transfer full][nullable]

Since: 1.2

### gst_caps_features_to_string ()

    gchar *
    gst_caps_features_to_string (const GstCapsFeatures *features);

Converts `features` to a human-readable string representation.

For debugging purposes its easier to do something like this:

    1
    GST_LOG ("features is %" GST_PTR_FORMAT, features);

This prints the features in human readable form.

Free-function: g_free

#### Parameters

features | a GstCapsFeatures |

#### Returns

a pointer to string allocated by `g_malloc()`. `g_free()` after usage.

[transfer full]

Since: 1.2

### gst_caps_features_set_parent_refcount ()

    gboolean
    gst_caps_features_set_parent_refcount (GstCapsFeatures *features,
                                           gint *refcount);

Sets the parent_refcount field of GstCapsFeatures. This field is used to determine whether a caps features is mutable or not. This function should only be called by code implementing parent objects of GstCapsFeatures, as described in the MT Refcounting section of the design documents.

#### Parameters

features | a GstCapsFeatures |
refcount | a pointer to the parent's refcount. | [in]

#### Returns

`TRUE` if the parent refcount could be set.

Since: 1.2

### gst_caps_features_is_equal ()

    gboolean
    gst_caps_features_is_equal (const GstCapsFeatures *features1,
                                const GstCapsFeatures *features2);

Check if `features1` and `features2` are equal.

#### Parameters

features1 | a GstCapsFeatures. |
features2 | a GstCapsFeatures. |

#### Returns

`TRUE` if `features1` and `features2` are equal.

Since: 1.2

### gst_caps_features_is_any ()

    gboolean
    gst_caps_features_is_any (const GstCapsFeatures *features);

Check if `features` is `GST_CAPS_FEATURES_ANY`.

#### Parameters

features | a GstCapsFeatures. |

#### Returns

`TRUE` if `features` is `GST_CAPS_FEATURES_ANY`.

Since: 1.2

### gst_caps_features_contains ()

    gboolean
    gst_caps_features_contains (const GstCapsFeatures *features,
                                const gchar *feature);

Check if `features` contains `feature` .

#### Parameters

features | a GstCapsFeatures. |
feature | a feature |

#### Returns

`TRUE` if `features` contains `feature` .

Since: 1.2

### gst_caps_features_contains_id ()

    gboolean
    gst_caps_features_contains_id (const GstCapsFeatures *features,
                                   GQuark feature);

Check if `features` contains `feature` .

#### Parameters

features | a GstCapsFeatures. |
feature | a feature |

#### Returns

`TRUE` if `features` contains `feature` .

Since: 1.2

### gst_caps_features_get_size ()

    guint
    gst_caps_features_get_size (const GstCapsFeatures *features);

Returns the number of features in `features` .

#### Parameters

features | a GstCapsFeatures. |

#### Returns

The number of features in `features` .

Since: 1.2

### gst_caps_features_get_nth ()

    const gchar *
    gst_caps_features_get_nth (const GstCapsFeatures *features,
                               guint i);

Returns the `i` -th feature of `features` .

#### Parameters

features | a GstCapsFeatures. |
i | index of the feature |

#### Returns

The `i` -th feature of `features` .

[nullable]

Since: 1.2

### gst_caps_features_get_nth_id ()

    GQuark
    gst_caps_features_get_nth_id (const GstCapsFeatures *features,
                                  guint i);

Returns the `i` -th feature of `features` .

#### Parameters

features | a GstCapsFeatures. |
i | index of the feature |

#### Returns

The `i` -th feature of `features` .

Since: 1.2

### gst_caps_features_add ()

    void
    gst_caps_features_add (GstCapsFeatures *features,
                           const gchar *feature);

Adds `feature` to `features` .

#### Parameters

features | a GstCapsFeatures. |
feature | a feature. |

Since: 1.2

### gst_caps_features_add_id ()

    void
    gst_caps_features_add_id (GstCapsFeatures *features,
                              GQuark feature);

Adds `feature` to `features` .

#### Parameters

features | a GstCapsFeatures. |
feature | a feature. |

Since: 1.2

### gst_caps_features_remove ()

    void
    gst_caps_features_remove (GstCapsFeatures *features,
                              const gchar *feature);

Removes `feature` from `features` .

#### Parameters

features | a GstCapsFeatures. |
feature | a feature. |

Since: 1.2

### gst_caps_features_remove_id ()

    void
    gst_caps_features_remove_id (GstCapsFeatures *features,
                                 GQuark feature);

Removes `feature` from `features` .

#### Parameters

features | a GstCapsFeatures. |
feature | a feature. |

Since: 1.2

## Types and Values

### GstCapsFeatures

    typedef struct _GstCapsFeatures GstCapsFeatures;

### GST_CAPS_FEATURES_ANY

    #define GST_CAPS_FEATURES_ANY (_gst_caps_features_any)

### GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY

    #define GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY (_gst_caps_features_memory_system_memory)

### GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY

    #define GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY "memory:SystemMemory"

## See Also

GstCaps