mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-09-01 09:43:55 +00:00
Code Issues 1 Projects Releases Wiki Activity

context: Update documentation

Browse source
This commit is contained in:
Sebastian Dröge 2013-09-17 13:33:33 +02:00
parent 4d367dc1b0
commit 2ae9809ae8
2 changed files with 20 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
docs/design/part-context.txt
View file

@ -1,14 +1,15 @@
Context Context
------- -------
GstContext is a container object, containing a generic GstStructure. GstContext is a container object, containing a type string and a
It is used to store and propagate context information in a pipeline, generic GstStructure. It is used to store and propagate context
like device handles, display server connections and other information information in a pipeline, like device handles, display server
that should be shared between multiple elements in a pipeline. connections and other information that should be shared between
multiple elements in a pipeline.
For sharing context objects and distributing them between application For sharing context objects and distributing them between application
and elements in a pipeline, there are downstream queries, downstream and elements in a pipeline, there are downstream queries, upstream
events, messages and functions to set a context on a complete pipeline. queries, messages and functions to set a context on a complete pipeline.
Context types Context types
@ -24,19 +25,21 @@ Elements that need a specific context for their operation would
do the following steps until one succeeds: do the following steps until one succeeds:
1) Check if the element already has a context of the specific type, 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() i.e. it was previoulsy set via gst_element_set_context().
2) Query downstream with GST_QUERY_CONTEXT for the context and check if 2) Query downstream with GST_QUERY_CONTEXT for the context and check if
downstream already has a context of the specific type downstream already has a context of the specific type
3) Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required 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 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 as in 1). The message could be handled by the parent bins of the
element and the application. element and the application.
4) Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message 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 on the bus.
context information at this time.
Bins will propagate any context that is set on them via Bins will propagate any context that is set on them via
@ -58,10 +61,6 @@ create a context of the requested type or pass an already existing
context to the element (or the complete pipeline). context to the element (or the complete pipeline).
Whenever an element creates a context internally it will post a Whenever an element creates a context internally it will post a
GST_MESSAGE_HAVE_CONTEXT message on the bus. Applications should store GST_MESSAGE_HAVE_CONTEXT message on the bus. Bins will cache these
the context of these messages, for example by creating a GstContext contexts and pass them to any future elements that request them.
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.

12
gst/gstcontext.c
View file

@ -39,17 +39,15 @@
* order until one step succeeds: * order until one step succeeds:
* 1) Check if the element already has a context * 1) Check if the element already has a context
* 2) Query downstream with GST_QUERY_CONTEXT for the context * 2) Query downstream with GST_QUERY_CONTEXT for the context
* 2) Query upstream with GST_QUERY_CONTEXT for the context
* 3) Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required * 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 * context types and afterwards check if a usable context was set now
* 4) Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message * 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 * on the bus.
* context information at this time.
* *
* Applications should catch the GST_MESSAGE_HAVE_CONTEXT messages and remember * Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously
* any content from it unless it has a custom version of a specific context. If * known context on the element that asks for it if possible. Otherwise the
* later an element is posting a GST_MESSAGE_NEED_CONTEXT message for a specific * application should provide one if it can.
* context that was created by an element before, the application should pass it
* to the element or the complete pipeline.
* *
* Since: 1.2 * Since: 1.2
*/ */