context: Update documentation

diff --git a/docs/design/part-context.txt b/docs/design/part-context.txt
index ad2073b..ed07129 100644 (file)
--- 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 953f3ea..c251f64 100644 (file)
--- 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.
- *
- * 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.
+ *    on the bus.
+ *
+ * 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
  */