From 2ae9809ae8b2da1ab92f34550f836884530b5d69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Tue, 17 Sep 2013 13:33:33 +0200 Subject: [PATCH] context: Update documentation --- docs/design/part-context.txt | 31 +++++++++++++++---------------- gst/gstcontext.c | 12 +++++------- 2 files changed, 20 insertions(+), 23 deletions(-) diff --git a/docs/design/part-context.txt b/docs/design/part-context.txt index ad2073bbf7..ed071292e5 100644 --- a/docs/design/part-context.txt +++ b/docs/design/part-context.txt @@ -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. diff --git a/gst/gstcontext.c b/gst/gstcontext.c index 953f3ea103..c251f64e8c 100644 --- a/gst/gstcontext.c +++ b/gst/gstcontext.c @@ -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 */