gstreamer/markdown/additional/design/context.md

Context

GstContext is a container object, containing a type string and a generic GstStructure. It is used to store and propagate context information in a pipeline, like device handles, display server connections and other information that should be shared between multiple elements in a pipeline.

For sharing context objects and distributing them between application and elements in a pipeline, there are downstream queries, upstream queries, messages and functions to set a context on a complete pipeline.

Context types

Context type names should be unique and be put in appropriate namespaces, to prevent name conflicts, e.g. "gst.egl.EGLDisplay". Only one specific type is allowed per context type name.

Elements

Elements that need a specific context for their operation would do the following steps until one succeeds:

1. Check if the element already has a context of the specific type, i.e. it was previously set via gst_element_set_context().

2. Query downstream with GST_QUERY_CONTEXT for the context and check if downstream already has a context of the specific type

3. Query upstream with GST_QUERY_CONTEXT for the context and check if upstream already has a context of the specific type

4. Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required context types and afterwards check if a usable context was set now as in 1). The message could be handled by the parent bins of the element and the application.

5. Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message on the bus.

Bins will propagate any context that is set on them to their child elements via gst_element_set_context(). Even to elements added after a given context has been set.

Bins can handle the GST_MESSAGE_NEED_CONTEXT message, can filter both messages and can also set different contexts for different pipeline parts.

Applications

Applications can set a specific context on a pipeline or elements inside a pipeline with gst_element_set_context().

If an element inside the pipeline needs a specific context, it will post a GST_MESSAGE_NEED_CONTEXT message on the bus. The application can now create a context of the requested type or pass an already existing context to the element (or to the complete pipeline).

Whenever an element creates a context internally it will post a GST_MESSAGE_HAVE_CONTEXT message on the bus. Bins will cache these contexts and pass them to any future element that requests them.