diff options
Diffstat (limited to 'docs/design/part-context.txt')
| -rw-r--r-- | docs/design/part-context.txt | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/docs/design/part-context.txt b/docs/design/part-context.txt new file mode 100644 index 0000000..ad2073b --- /dev/null +++ b/docs/design/part-context.txt @@ -0,0 +1,67 @@ +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. + |