docs/random/negotiation

   1
   2 Some notes on pad negotiation
   3
   4
   5 A "pad link" is a connection between two pads.  It can be in one of
   6 two states, "negotiated" or "not negotiated".  Pad links are created
   7 by gst_pad_link().
   8
   9 A "pad link" is created when two pads are linked using gst_pad_link().
  10 When initially created, the link only specifies a src pad, a sink pad,
  11 and optionally a filter caps provided by the application.
  12
  13 In order to pass data through a link, the peer pads must decide on
  14 what data format to use.  This is called negotiation.  Pads
  15 describe acceptable data formats by using a combination of  pad
  16 template caps and (optionally) a pad->getcaps function.
  17
  18
  19 Negotiation can happen in one of two forms, directed or undirected.
  20 Directed negotiation happens when one element has decided (usually
  21 during negotiation on another pad) to ask for a specific format on
  22 a pad.  This happens when a pad calls gst_pad_try_set_caps().
  23 Undirected negotiation happens when the core decides to negotiate
  24 a link, either due to a state change or a specific application
  25 request.
  26
  27 Steps in undirected negotiation (core view):
  28
  29  - core checks that both pad's parent elements are in the READY or
  30    higher state.
  31
  32  - core calls gst_pad_get_caps() on each pad, intersects the two caps,
  33    and intersects again with the filter caps.  If the intersection is
  34    empty, then the pads have no formats in common, and the link fails.
  35
  36  - If the intersection caps is not fixed, there are multiple possible
  37    formats that the link could use.  If this is the case, fixate
  38    functions are called until the caps are fixed.  The fixate functions
  39    are called by priority -- src application fixate function, sink
  40    application fixate function, src and sink fixate functions, and
  41    the default core fixate function.  The application fixate functions
  42    are implemented by the "fixate" signal on each pad.  The core
  43    loops through the fixate functions until a fixed caps is decided
  44    on.
  45
  46  - Each pad may have a pad_link function, which is called with the
  47    fixed caps.  The pad_link function has the option of accepting,
  48    rejecting, or delaying the negotiation.
  49
  50  - If both pads accept the caps, the link is then negotiated.
  51
  52 Steps in directed negotiation (gst_pad_try_set_caps):
  53
  54  - the originator is the pad that gst_pad_try_set_caps() is called
  55    on.
  56
  57  - the elements owning both pads are assumed to be in a non-NULL state
  58
  59  - the caps argument of try_set_caps() must be fixed.
  60
  61  - gst_pad_get_caps() is called on the peer pad, and intersected with
  62    the originating pad's pad template caps and the filter caps.  The
  63    caps argument is checked to be a subset of the intersection.  (It's
  64    important that this intersection uses the pad _template_ caps.)
  65
  66  - Fixate functions don't need to be called, since the caps are
  67    already fixed.
  68
  69  - The peer's pad_link function is called.
  70
  71  - If the peer's pad_link function accepts the caps, the link is then
  72    negotiated.
  73
  74  - If the peer's pad_link function refuses the caps, and the link had
  75    already been negotiated, the peer's pad_link function is called
  76    with the caps of the old negotiation.
  77
  78  - Note: the originator's pad_link function is _not_ called.  The
  79    originator must take appropriate alternative steps.
  80
  81
  82 Notes about renegotiation:
  83
  84  - same as negotiation.  Note that get_caps() functions should always
  85    ignore the currently negotiated caps of a link.
  86
  87  - if renegotiation fails, the previous negotiation is still in effect.
  88    If the renegotiation fails in the last pad_link step, the pad_link
  89    functions are called with the previously negotiated caps.
  90
  91
  92 Notes for sources and sinks:
  93
  94  - sources and sinks that talk to hardware may not be able to fully
  95    describe their available formats, and thus need to rely on pad_link
  96    functions to test a particular format.  FIXME: currently, the core
  97    completely fails negotiation if a pad_link function refuses a caps,
  98    instead of attempting with an alternate caps.
  99
 100    Example: Assume osssink advertises rate=(int)[8000,48000], but
 101    the device cannot actually handle rate=44100 (unknown to osssink).
 102    Assume that the pad_link function is called with rate=44100 --
 103    ideally, the pad_link function should return GST_PAD_LINK_DELAYED,
 104    and future calls to getcaps should return {[8000,44099],[44101,
 105    48000]}.  I don't know how to make this easy and/or work well.
 106
 107
 108 Notes for decoders/demuxers:
 109
 110  - Decoders will typically negotiate a sink pad, receive some data,
 111    determine the output format, and call try_set_caps() with the given
 112    format.  If the output format is non-fixed, gst_pad_renegotiate()
 113    may be used instead, in order to have the fixate functions choose
 114    the optimal format.  Note that this requires communication so that
 115    the pad's getcaps function returns the correct caps.
 116
 117 Notes for converters:
 118
 119  - Converters change one or more properties of the format of a data
 120    stream.  A typical converter's getcaps function will call
 121    gst_pad_get_allowed_caps() for the opposite pad in the element,
 122    change one or more fields in the caps, and return the result.
 123
 124  - getcaps function:
 125
 126    - call gst_pad_get_allowed_caps() on the other pad in the element
 127
 128    - for each possible format ("A") in the allowed caps, determine all
 129      the formats ("B") that your converter could convert the original
 130      format (A) to.  The union of all these formats (all the B's) is
 131      the caps that should be returned.  (This is how to do it
 132      _theoretically_, but an optimal implementation will probably be
 133      quite different.)
 134      For example, a simple way to do this for an element that can convert
 135      a given field of the caps is to remove the field(s) from the structure,
 136      then intersect with the pad template.
 137
 138    - As an example, videoscale can convert any sized video to any other
 139      sized video.  Its getcaps function iterates over each structure in
 140      the caps, and replaces the width and height with the range
 141      [1,MAXINT].
 142
 143  - pad_link function:
 144
 145    - the "otherpad" is the opposite pad in the element.
 146
 147    - extract fields from the caps that are relevant for your converter
 148      handling the format.  Store these in _local_ variables.  (E.g,
 149      things like video size, sample rate, etc.)
 150
 151    - If it's possible to pass buffers through without modifying them
 152      (passthrough), you should call gst_try_set_caps() with the caps
 153      that was specified as the parameter to the pad_link function.  If
 154      this is successful, save the local variables to the element
 155      structure, perform whatever other setup is necessary for your
 156      element, and return GST_PAD_LINK_OK.
 157
 158    - Otherwise, you're not using passthrough, and may need to
 159      change the caps on the otherpad to match the given format.
 160
 161    - If the otherpad is not negotiated (!gst_pad_is_negotiated()),
 162      you shouldn't attempt to set a format on it.  It will eventually
 163      be negotiated.  Save the local variables to the element structure,
 164      perform whatever other setup is necessary, and return
 165      GST_PAD_LINK_OK.
 166
 167    - At this point, the other pad is already negotiated, but won't
 168      accept the passthrough format, so you should combine the existing
 169      negotiated caps on the otherpad and the caps that was the pad link
 170      argument.  This can either be done using existing information in the
 171      element that was saved during a previous pad_link call, or you can
 172      get the information from the negotiated caps
 173      (gst_pad_get_negotiated_caps()).
 174
 175      As an example, consider the videoscale element.  Assume that
 176      videoscale.src has already negotiated "video/x-raw-yuv,
 177      format=(fourcc)I420, width=320, height=240", and that the sink
 178      pad's link function is called with "video/x-raw-yuv,
 179      format=(fourcc)YUY2, width=640, height=480".  Since it's the
 180      videoscale element, we can have different width and height
 181      fields on the pads, but the format must be the same.  So we'll
 182      use the existing negotiated size (640x480), and the new format,
 183      and call gst_pad_try_set_caps() with "video/x-raw-yuv,
 184      format=(fourcc)I420, width=640, height=480".
 185
 186      This may seem overkill, but most of the time, you'll end up
 187      calling try_set_caps() with the same caps that are currently
 188      negotiated -- try_set_caps() just returns GST_PAD_LINK_OK in
 189      this case.
 190
 191    - If gst_pad_try_set_caps() returns GST_PAD_LINK_OK, save the
 192      local variables to the element structure.  In any case, return
 193      the return value of gst_pad_try_set_caps().
 194
 195
 196 Notes for filters:
 197
 198  - Filters can almost always use gst_pad_proxy_getcaps() as the
 199    getcaps function.  This just returns gst_pad_get_allowed_caps()
 200    on the otherpad.
 201
 202  - You may be able to use gst_pad_proxy_pad_link() as the pad link
 203    function, but only if you don't need to extract parameters from
 204    the caps.
 205
 206
 207 Notes for encoders/muxers:
 208
 209  - Encoders and muxers should roughly work like converters.  Many
 210    converters are symmetric; encoders and muxers obvious are not,
 211    thus it may make the code clearer to have separate src and sink
 212    getcaps and pad_link functions.
 213
 214  - Encoders and muxers should handle multiple negotiations until
 215    the first buffer has been passed.  After this point, it's unlikely
 216    that additional negotiations will happen in well-constructed
 217    pipelines, but it may be wise to "lock" the caps after the
 218    muxer has committed to a format.  (FIXME: it's still unclear to
 219    me when the caps should get "unlocked".  Obviously at EOS or
 220    PAUSED->READY transitions.  Any others?)
 221
 222  - Locking caps can be done by adding (near the top) of the getcaps
 223    function:
 224
 225    if (my_element->lock_caps) {
 226      return gst_pad_get_negotiated_caps (pad);
 227    }
 228
 229
 230 Explicit caps:
 231
 232  - There's a hack in the core to make the code for decoder elements
 233    a lot simpler.  This hack can be used only for src pads of elements
 234    that get their srcpad capabilities directly from the data stream,
 235    i.e., decoders, demuxers, and typefind.  This hack overrides the
 236    pad's getcaps() and pad_link() function, so that they work correctly
 237    in all decoder states.
 238
 239  - To enable this hack on a pad, call gst_pad_use_explicit_caps().
 240
 241  - To indicate that a decoder has found the format of the stream, call
 242    gst_pad_set_explicit_caps(pad,caps) with the caps of the stream.
 243    This caps must be fixed.
 244
 245  - To indicate that a decoder has lost the format of the stream, i.e.,
 246    there's been a NEW_MEDIA event, call gst_pad_set_explicit_caps(pad,
 247    NULL).
 248
 249  - If the explicit caps are set, the getcaps function will return that
 250    caps, and the pad_link function will return GST_PAD_LINK_OK.  If
 251    the explicit caps are not set, the getcaps function returns the pad
 252    template caps, and the pad_link function returns GST_PAD_LINK_DELAYED.
 253
 254
 255
 256 Other junk:
 257
 258  - negotiation can happen at any time
 259
 260  - negotiation can happen multiple times/often happens multiple times
 261
 262  - initial negotiation can lead to strange caps
 263
 264  - directed negotiation can happen in either direction (src to sink or
 265    sink to src)
 266
 267  - Other considerations ignored, every pad should have a getcaps function.
 268
 269  - If a pad's getcaps function returns the same caps in every
 270    circumstance, the getcaps function can be omitted.
 271
 272  - If you use gst_pad_use_explicit_caps(), the getcaps function must
 273    be ommitted.
 274
 275  - fixate functions are a method for applications to exert influence
 276    on how a format is chosen from a caps.  It's also used as a hack to
 277    allow elements to do the same.  Element fixate functions are _not_
 278    intended to give good results for applications -- they're intended
 279    to give non-disgusting results in gst-launch.  Don't attempt to
 280    make them do more than they're capable of.
 281
 282  - Fixate functions should not be implemented on anything except source
 283    and sink elements.
 284
 285
 286