mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-23 16:50:47 +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
-------
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.
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, downstream
events, messages and functions to set a context on a complete pipeline.
and elements in a pipeline, there are downstream queries, upstream
queries, messages and functions to set a context on a complete pipeline.
Context types
@ -24,19 +25,21 @@ 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()
i.e. it was previoulsy 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) 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
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.
on the bus.
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).
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.
GST_MESSAGE_HAVE_CONTEXT message on the bus. Bins will cache these
contexts and pass them to any future elements that request them.

12
gst/gstcontext.c
View file

@ -39,17 +39,15 @@
* order until one step succeeds:
* 1) Check if the element already has a 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
* 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
* and send a GST_EVENT_CONTEXT event downstream, containing the complete
* context information at this time.
* on the bus.
*
* Applications should catch the GST_MESSAGE_HAVE_CONTEXT messages and remember
* any content from it unless it has a custom version of a specific context. If
* later an element is posting a GST_MESSAGE_NEED_CONTEXT message for a specific
* context that was created by an element before, the application should pass it
* to the element or the complete pipeline.
* Bins will catch GST_MESSAGE_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.
*
* Since: 1.2
*/