markdown/design/context.md

   1 # Context
   2
   3 `GstContext` is a container object, containing a type string and a generic
   4 `GstStructure`. It is used to store and propagate context information in a
   5 pipeline, like device handles, display server connections and other
   6 information that should be shared between multiple elements in a
   7 pipeline.
   8
   9 For sharing context objects and distributing them between application
  10 and elements in a pipeline, there are downstream queries, upstream
  11 queries, messages and functions to set a context on a complete pipeline.
  12
  13 ## Context types
  14
  15 Context type names should be unique and be put in appropriate
  16 namespaces, to prevent name conflicts, e.g. "gst.egl.EGLDisplay". Only
  17 one specific type is allowed per context type name.
  18
  19 ## Elements
  20
  21 Elements that need a specific context for their operation would do the
  22 following steps until one succeeds:
  23
  24 1) Check if the element already has a context of the specific type,
  25    i.e. it was previously set via `gst_element_set_context()`.
  26
  27 2) Query downstream with `GST_QUERY_CONTEXT` for the context and check if
  28    downstream already has a context of the specific type
  29
  30 3) Query upstream with `GST_QUERY_CONTEXT` for the context and check if
  31    upstream already has a context of the specific type
  32
  33 4) Post a `GST_MESSAGE_NEED_CONTEXT` message on the bus with the required
  34    context types and afterwards check if a usable context was set now
  35    as in 1). The message could be handled by the parent bins of the
  36    element and the application.
  37
  38 4) Create a context by itself and post a `GST_MESSAGE_HAVE_CONTEXT` message
  39        on the bus.
  40
  41 Bins will propagate any context that is set on them to their child
  42 elements via `gst_element_set_context()`. Even to elements added after
  43 a given context has been set.
  44
  45 Bins can handle the `GST_MESSAGE_NEED_CONTEXT` message, can filter both
  46 messages and can also set different contexts for different pipeline
  47 parts.
  48
  49 ## Applications
  50
  51 Applications can set a specific context on a pipeline or elements inside
  52 a pipeline with `gst_element_set_context()`.
  53
  54 If an element inside the pipeline needs a specific context, it will post
  55 a `GST_MESSAGE_NEED_CONTEXT` message on the bus. The application can
  56 now create a context of the requested type or pass an already existing
  57 context to the element (or to the complete pipeline).
  58
  59 Whenever an element creates a context internally it will post a
  60 `GST_MESSAGE_HAVE_CONTEXT` message on the bus. Bins will cache these
  61 contexts and pass them to any future element that requests them.