| Context |
| ------- |
| |
| GstContext is a container object, containing 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, downstream |
| events, messages and functions to set a context on a complete pipeline. |
| |
| |
| Context types |
| ~~~~~~~~~~~~~ |
| Context type names should be unique and be put in appropiate namespaces, |
| e.g. "gst.egl.EGLDisplay", go prevent name conflicts. 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. by checking the context returned by gst_element_get_context() |
| |
| 2) Query downstream with GST_QUERY_CONTEXT for the context and check if |
| downstream already has a context of the specific type |
| |
| 3) 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. |
| |
| 4) Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message |
| and send a GST_EVENT_CONTEXT event downstream, containing the complete |
| context information at this time. |
| |
| |
| Bins will propagate any context that is set on them via |
| gst_element_set_context() to their child elements, including newly added |
| elements after the context was 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 the complete pipeline). |
| |
| Whenever an element creates a context internally it will post a |
| GST_MESSAGE_HAVE_CONTEXT message on the bus. Applications should store |
| the context of these messages, for example by creating a GstContext |
| containing all the contexts of the pipeline by merging the structures. |
| Applications can also just set the context contained in the |
| GST_MESSAGE_HAVE_CONTEXT message on the complete pipeline to make sure it |
| is shared between all elements. |
| |