part-context: Write some design documentation about GstContext

docs/design/Makefile.am

@@ -7,6 +7,7 @@ EXTRA_DIST = \
 	part-buffering.txt \
 	part-caps.txt \
 	part-clocks.txt \
+	part-context.txt \
 	part-conventions.txt \
 	part-dynamic.txt \
 	part-element-sink.txt \

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.
+

gst/gstcontext.c

@@ -47,8 +47,8 @@
  * 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 complete pipeline.
+ * context that was created by an element before, the application should pass it
+ * to the element or the complete pipeline.
  *
  * Since: 1.2
  */