:right-sidebar: True

Context
===================================================================

.. currentmodule:: gi.repository.Gst


.. versionadded:: 1.2




.. class:: Context(**kwargs)
   :no-contents-entry:






:obj:`~gi.repository.Gst.Context` is a container object used to store contexts like a device
context, a display server connection and similar concepts that should
be shared between multiple elements.

Applications can set a context on a complete pipeline by using
:func:`~gi.repository.Gst.Element.set_context`, which will then be propagated to all
child elements. Elements can handle these in :obj:`~gi.repository.Gst.ElementClass`\::set_context
and merge them with the context information they already have.

When an element needs a context it will do the following actions in this
order until one step succeeds:

- Check if the element already has a context
- Query downstream with :const:`~gi.repository.Gst.QueryType.CONTEXT` for the context
- Query upstream with :const:`~gi.repository.Gst.QueryType.CONTEXT` for the context
- Post a :const:`~gi.repository.Gst.MessageType.NEED_CONTEXT` message on the bus with the required
   context types and afterwards check if a usable context was set now
- Create a context by itself and post a :const:`~gi.repository.Gst.MessageType.HAVE_CONTEXT` message
   on the bus.


Bins will catch :const:`~gi.repository.Gst.MessageType.NEED_CONTEXT` messages and will set any previously
known context on the element that asks for it if possible. Otherwise the
application should provide one if it can.

:obj:`~gi.repository.Gst.Context` can be persistent.
A persistent :obj:`~gi.repository.Gst.Context` is kept in elements when they reach
:const:`~gi.repository.Gst.State.NULL`, non-persistent ones will be removed.
Also, a non-persistent context won't override a previous persistent
context set to an element.


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

.. rst-class:: interim-class

.. class:: Context
   :no-index:


   .. classmethod:: new(context_type: str, persistent: bool) -> ~gi.repository.Gst.Context

      Creates a new context.


      .. versionadded:: 1.2





      :param context_type: Context type

      :param persistent: Persistent context








Methods
-------

.. rst-class:: interim-class

.. class:: Context
   :no-index:


   .. method:: get_context_type() -> str

      Gets the type of ``context``\.



      .. versionadded:: 1.2








   .. method:: get_structure() -> ~gi.repository.Gst.Structure

      Accesses the structure of the context.



      .. versionadded:: 1.2








   .. method:: get_task_pool() -> tuple[bool, ~gi.repository.Gst.TaskPool | None]

      Gets the task pool from ``context``\.



      .. versionadded:: 1.28








   .. method:: has_context_type(context_type: str) -> bool

      Checks if ``context`` has ``context_type``\.



      .. versionadded:: 1.2





      :param context_type: Context type to check.




   .. method:: is_persistent() -> bool

      Checks if ``context`` is persistent.



      .. versionadded:: 1.2








   .. method:: is_writable() -> bool

      Tests if you can safely modify ``context``\. It is only safe to modify context when
      there is only one owner of the context - ie, the object is writable.










   .. method:: make_writable() -> ~gi.repository.Gst.Context

      Returns a writable copy of ``context``\.

      If there is only one reference count on ``context``\, the caller must be the owner,
      and so this function will return the context object unchanged. If on the other
      hand there is more than one reference on the object, a new context object will
      be returned. The caller's reference on ``context`` will be removed, and instead the
      caller will own a reference to the returned object.

      In short, this function unrefs the context in the argument and refs the context
      that it returns. Don't access the argument after calling this function. See
      also: :func:`~gi.repository.Gst.Context.ref`.










   .. classmethod:: replace(old_context: ~gi.repository.Gst.Context, new_context: ~gi.repository.Gst.Context | None = None) -> tuple[bool, ~gi.repository.Gst.Context]

      Modifies a pointer to a :obj:`~gi.repository.Gst.Context` to point to a different :obj:`~gi.repository.Gst.Context`\. The
      modification is done atomically (so this is useful for ensuring thread safety
      in some cases), and the reference counts are updated appropriately (the old
      context is unreffed, the new one is reffed).

      Either ``new_context`` or the :obj:`~gi.repository.Gst.Context` pointed to by ``old_context`` may be :const:`None`.



      .. versionadded:: 1.2





      :param old_context: pointer to a pointer to a :obj:`~gi.repository.Gst.Context`
         to be replaced.

      :param new_context: pointer to a :obj:`~gi.repository.Gst.Context` that will
         replace the context pointed to by ``old_context``\.




   .. method:: set_task_pool(pool: ~gi.repository.Gst.TaskPool | None = None) -> None

      Sets ``pool`` on ``context`` as the task pool to be shared between elements.
      If ``pool`` is :const:`None`, any previously set task pool will be removed from
      the context.



      .. versionadded:: 1.28





      :param pool: a :obj:`~gi.repository.Gst.TaskPool` or :const:`None` to unset




   .. method:: writable_structure() -> ~gi.repository.Gst.Structure

      Gets a writable version of the structure.



      .. versionadded:: 1.2