:right-sidebar: True

CapsFeatures
===================================================================

.. currentmodule:: gi.repository.Gst


.. versionadded:: 1.2




.. class:: CapsFeatures(*args, **kwargs)
   :no-contents-entry:






:obj:`~gi.repository.Gst.CapsFeatures` can optionally be set on a :obj:`~gi.repository.Gst.Caps` to add requirements
for additional features for a specific :obj:`~gi.repository.Gst.Structure`\. 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 :obj:`~gi.repository.Gst.CapsFeatures` are equivalent with the :obj:`~gi.repository.Gst.CapsFeatures` that only
contain ``GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY``. ANY :obj:`~gi.repository.Gst.CapsFeatures` as
created by :func:`~gi.repository.Gst.CapsFeatures.new_any` are equal to any other :obj:`~gi.repository.Gst.CapsFeatures`
and can be used to specify that any :obj:`~gi.repository.Gst.CapsFeatures` would be supported, e.g.
for elements that don't touch buffer memory. :obj:`~gi.repository.Gst.Caps` with ANY :obj:`~gi.repository.Gst.CapsFeatures`
are considered non-fixed and during negotiation some :obj:`~gi.repository.Gst.CapsFeatures` have
to be selected.

Examples for caps features would be the requirement of a specific :obj:`~gi.repository.Gst.Memory`
types or the requirement of having a specific :obj:`~gi.repository.Gst.Meta` on the buffer. Features
are given as a string of the format ``memory:GstMemoryTypeName`` or
``meta:GstMetaAPIName``\.


Constructors
------------

.. rst-class:: interim-class

.. class:: CapsFeatures
   :no-index:


   .. classmethod:: new_any() -> ~gi.repository.Gst.CapsFeatures

      Creates a new, ANY :obj:`~gi.repository.Gst.CapsFeatures`\. This will be equal
      to any other :obj:`~gi.repository.Gst.CapsFeatures` but caps with these are
      unfixed.


      .. versionadded:: 1.2








   .. classmethod:: new_empty() -> ~gi.repository.Gst.CapsFeatures

      Creates a new, empty :obj:`~gi.repository.Gst.CapsFeatures`\.


      .. versionadded:: 1.2








   .. classmethod:: new_single(feature: str) -> ~gi.repository.Gst.CapsFeatures

      Creates a new :obj:`~gi.repository.Gst.CapsFeatures` with a single feature.


      .. versionadded:: 1.20





      :param feature: The feature








Methods
-------

.. rst-class:: interim-class

.. class:: CapsFeatures
   :no-index:


   .. method:: add(feature: str) -> None

      Adds ``feature`` to ``features``\.


      .. versionadded:: 1.2





      :param feature: a feature.




   .. method:: add_id(feature: int) -> None

      Adds ``feature`` to ``features``\.


      .. versionadded:: 1.2





      :param feature: a feature.




   .. method:: contains(feature: str) -> bool

      Checks if ``features`` contains ``feature``\.


      .. versionadded:: 1.2





      :param feature: a feature




   .. method:: contains_id(feature: int) -> bool

      Checks if ``features`` contains ``feature``\.


      .. versionadded:: 1.2





      :param feature: a feature




   .. method:: free() -> None

      Frees a :obj:`~gi.repository.Gst.CapsFeatures` and all its values. The caps features must not
      have a parent when this function is called.


      .. versionadded:: 1.2








   .. classmethod:: from_string() -> ~gi.repository.Gst.CapsFeatures | None

      Creates a :obj:`~gi.repository.Gst.CapsFeatures` from a string representation.


      .. versionadded:: 1.2








   .. method:: get_nth(i: int) -> str | None

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


      .. versionadded:: 1.2





      :param i: index of the feature




   .. method:: get_nth_id(i: int) -> int

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


      .. versionadded:: 1.2





      :param i: index of the feature




   .. method:: get_size() -> int

      Returns the number of features in ``features``\.


      .. versionadded:: 1.2








   .. method:: is_any() -> bool

      Checks if ``features`` is %GST_CAPS_FEATURES_ANY.


      .. versionadded:: 1.2








   .. method:: is_equal(features2: ~gi.repository.Gst.CapsFeatures) -> bool

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


      .. versionadded:: 1.2





      :param features2: a :obj:`~gi.repository.Gst.CapsFeatures`\.




   .. method:: remove(feature: str) -> None

      Removes ``feature`` from ``features``\.


      .. versionadded:: 1.2





      :param feature: a feature.




   .. method:: remove_id(feature: int) -> None

      Removes ``feature`` from ``features``\.


      .. versionadded:: 1.2





      :param feature: a feature.




   .. method:: set_parent_refcount(refcount: int) -> bool

      Sets the parent_refcount field of :obj:`~gi.repository.Gst.CapsFeatures`\. 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 :obj:`~gi.repository.Gst.CapsFeatures`\, as described in
      `the MT refcounting design document <additional/design/MT-refcounting.md>`__\.


      .. versionadded:: 1.2





      :param refcount: a pointer to the parent's refcount




   .. method:: to_string() -> str

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

      For debugging purposes its easier to do something like this:


      .. code-block::  C
          :dedent:

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

      This prints the features in human readable form.


      .. versionadded:: 1.2