docs/design/part-negotiation.txt

   1 Negotiation
   2 -----------
   3
   4 Capabilities negotiation is the process of deciding on an adequate
   5 format for dataflow within a GStreamer pipeline. Ideally, negotiation
   6 (also known as "capsnego") transfers information from those parts of the
   7 pipeline that have information to those parts of the pipeline that are
   8 flexible, constrained by those parts of the pipeline that are not
   9 flexible.
  10
  11 GStreamer's two scheduling modes, push mode and pull mode, lend
  12 themselves to different mechanisms to achieve this goal. As it is more
  13 common we describe push mode negotiation first.
  14
  15 Push-mode negotiation
  16 ~~~~~~~~~~~~~~~~~~~~~
  17
  18 Push-mode negotiation happens when elements want to push buffers and
  19 need to decide on the format. This is called downstream negotiation
  20 because the upstream element decides the format for the downstream
  21 element. This is the most common case.
  22
  23 Negotiation can also happen when a downstream element wants to receive
  24 another data format from an upstream element. This is called upstream
  25 negotiation.
  26
  27 The basics of negotiation are as follows:
  28
  29  - GstCaps (see part-caps.txt) are refcounted before they are pushed as
  30    an event to describe the contents of the following buffer.
  31
  32  - An element should reconfigure itself to the new format received as a CAPS
  33    event before processing the following buffers. If the data type in the
  34    caps event is not acceptable, the element should refuse the buffer by
  35    returning an appropriate GST_FLOW_NOT_NEGOTIATED return value from the
  36    chain function.
  37
  38  - Upstream elements can request a format change of the stream by sending a
  39    RECONFIGURE event upstream. Upstream elements will renegotiate a new format
  40    when they receive a RECONFIGURE event.
  41
  42 The general flow for a source pad starting the negotiation.
  43
  44              src              sink
  45               |                 |
  46               |  accepts?       |
  47   type A      |---------------->|
  48               |      yes        |
  49               |< - - - - - - - -|
  50               |                 |
  51               |  send_event()   |
  52  send CAPS    |---------------->| Receive type A, reconfigure to
  53  event A      |                 | process type A.
  54               |                 |
  55               |  push           |
  56  push buffer  |---------------->| Process buffer of type A
  57               |                 |
  58
  59  One possible implementation in pseudo code:
  60
  61  [element wants to create a buffer]
  62  if not format
  63    # see what the peer can do
  64    peercaps = gst_pad_peer_get_caps (srcpad)
  65    # see what we can do
  66    ourcaps = gst_pad_get_caps (srcpad)
  67
  68    # get common formats
  69    candidates = gst_caps_intersect (peercaps, ourcaps)
  70
  71    foreach candidate in candidates
  72      # make sure the caps is fixed
  73      fixedcaps = gst_pad_fixate_caps (srcpad, candidate)
  74
  75      # see if the peer accepts it
  76      if gst_pad_peer_accept_caps (srcpad, fixedcaps)
  77        # store the caps as the negotiated caps, this will
  78        # call the setcaps function on the pad
  79        gst_pad_push_event (srcpad, gst_event_new_caps (fixedcaps))
  80        break
  81      endif
  82    done
  83  endif
  84
  85  buffer = gst_buffer_new_and_alloc (size);
  86  [fill buffer and push]
  87
  88
  89 The general flow for a sink pad starting a renegotiation.
  90
  91              src              sink
  92               |                 |
  93               |  accepts?       |
  94               |<----------------| type B
  95               |      yes        |
  96               |- - - - - - - - >|-.
  97               |                 | | suggest B caps next
  98               |                 |<'
  99               |                 |
 100               |   push_event()  |
 101   mark      .-|<----------------| send RECONFIGURE event
 102  renegotiate| |                 |
 103             '>|                 |
 104               |   get_caps()    |
 105  renegotiate  |---------------->|
 106               |  suggest B      |
 107               |< - - - - - - - -|
 108               |                 |
 109               |  send_event()   |
 110  send CAPS    |---------------->| Receive type B, reconfigure to
 111  event B      |                 | process type B.
 112               |                 |
 113               |  push           |
 114  push buffer  |---------------->| Process buffer of type B
 115               |                 |
 116
 117
 118 Use case:
 119
 120
 121 videotestsrc ! xvimagesink
 122
 123   1) Who decides what format to use?
 124    - src pad always decides, by convention. sinkpad can suggest a format
 125      by putting it high in the getcaps function GstCaps.
 126    - since the src decides, it can always choose something that it can do,
 127      so this step can only fail if the sinkpad stated it could accept
 128      something while later on it couldn't.
 129
 130   2) When does negotiation happen?
 131    - before srcpad does a push, it figures out a type as stated in 1), then
 132      it pushes a caps event with the type. The sink checks the media type and
 133      configures itself for this type.
 134    - the source then usually does an ALLOCATION query to negotiate a bufferpool
 135      with the sink. It then allocates a buffer from the pool and pushes it to
 136      the sink. since the sink accepted the caps, it can create a pool for the
 137      format.
 138    - since the sink stated in 1) it could accept the type, it will be able to
 139      handle it.
 140
 141   3) How can sink request another format?
 142    - sink asks if new format is possible for the source.
 143    - sink pushes RECONFIGURE event upstream
 144    - src receives the RECONFIGURE event and marks renegotiation
 145    - On the next buffer push, the source renegotiates the caps and the
 146      bufferpool. The sink will put the new new prefered format high in the list
 147      of caps it returns from its getcaps function.
 148
 149 videotestsrc ! queue ! xvimagesink
 150
 151   - queue proxies all accept and getcaps to the other peer pad.
 152   - queue proxies the bufferpool
 153   - queue proxies the RECONFIGURE event
 154   - queue stores CAPS event in the queue. This means that the queue can contain
 155     buffers with different types.
 156
 157
 158 Pull-mode negotiation
 159 ~~~~~~~~~~~~~~~~~~~~~
 160
 161 Rationale
 162 ^^^^^^^^^
 163
 164 A pipeline in pull mode has different negotiation needs than one
 165 activated in push mode. Push mode is optimized for two use cases:
 166
 167  * Playback of media files, in which the demuxers and the decoders are
 168    the points from which format information should disseminate to the
 169    rest of the pipeline; and
 170
 171  * Recording from live sources, in which users are accustomed to putting
 172    a capsfilter directly after the source element; thus the caps
 173    information flow proceeds from the user, through the potential caps
 174    of the source, to the sinks of the pipeline.
 175
 176 In contrast, pull mode has other typical use cases:
 177
 178  * Playback from a lossy source, such as RTP, in which more knowledge
 179    about the latency of the pipeline can increase quality; or
 180
 181  * Audio synthesis, in which audio APIs are tuned to producing only the
 182    necessary number of samples, typically driven by a hardware interrupt
 183    to fill a DMA buffer or a Jack[0] port buffer.
 184
 185  * Low-latency effects processing, whereby filters should be applied as
 186    data is transferred from a ring buffer to a sink instead of
 187    beforehand. For example, instead of using the internal alsasink
 188    ringbuffer thread in push-mode wavsrc ! volume ! alsasink, placing
 189    the volume inside the sound card writer thread via wavsrc !
 190    audioringbuffer ! volume ! alsasink.
 191
 192 [0] http://jackit.sf.net
 193
 194 The problem with pull mode is that the sink has to know the format in
 195 order to know how many bytes to pull via gst_pad_pull_range(). This
 196 means that before pulling, the sink must initiate negotation to decide
 197 on a format.
 198
 199 Recalling the principles of capsnego, whereby information must flow from
 200 those that have it to those that do not, we see that the two named use
 201 cases have different negotiation requirements:
 202
 203  * RTP and low-latency playback are both like the normal playback case,
 204    in which information flows downstream.
 205
 206  * In audio synthesis, the part of the pipeline that has the most
 207    information is the sink, constrained by the capabilities of the graph
 208    that feeds it. However the caps are not completely specified; at some
 209    point the user has to intervene to choose the sample rate, at least.
 210    This can be done externally to gstreamer, as in the jack elements, or
 211    internally via a capsfilter, as is customary with live sources.
 212
 213 Given that sinks potentially need the input of sources, as in the RTP
 214 case and at least as a filter in the synthesis case, there must be a
 215 negotiation phase before the pull thread is activated. Also, given the
 216 low latency offered by pull mode, we want to avoid capsnego from within
 217 the pulling thread, in case it causes us to miss our scheduling
 218 deadlines.
 219
 220 The pull thread is usually started in the PAUSED->PLAYING state change. We must
 221 be able to complete the negotiation before this state change happens.
 222
 223 The time to do capsnego, then, is after the SCHEDULING query has succeeded,
 224 but before the sink has spawned the pulling thread.
 225
 226
 227 Mechanism
 228 ^^^^^^^^^
 229
 230 The sink determines that the upstream elements support pull based scheduling by
 231 doing a SCHEDULING query.
 232
 233 The sink initiates the negotiation process by intersecting the results
 234 of gst_pad_get_caps() on its sink pad and its peer src pad. This is the
 235 operation performed by gst_pad_get_allowed_caps(). In the simple
 236 passthrough case, the peer pad's getcaps() function should return the
 237 intersection of calling get_allowed_caps() on all of its sink pads. In
 238 this way the sink element knows the capabilities of the entire pipeline.
 239
 240 The sink element then fixates the resulting caps, if necessary,
 241 resulting in the flow caps.  From now on, the getcaps function
 242 of the sinkpad will only return these fixed caps meaning that upstream elements
 243 will only be able to produce this format.
 244
 245 If the sink element could not set caps on its sink pad, it should post
 246 an error message on the bus indicating that negotiation was not
 247 possible.
 248
 249 When negotiation succeeded, the sinkpad and all upstream internally linked pads
 250 are activated in pull mode. Typically, this operation will trigger negotiation
 251 on the downstream elements, which will now be forced to negotiation to the
 252 final fixed desired caps of the sinkpad.
 253
 254 After these steps, the sink element returns ASYNC from the state change
 255 function. The state will commit to PAUSED when the first buffer is received in
 256 the sink. This is needed to provide a consistent API to the applications that
 257 expect ASYNC return values from sinks but it also allows us to perform the
 258 remainder of the negotiation outside of the context of the pulling thread.