2.0 beta init
[framework/multimedia/gstreamer0.10.git] / 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
30    are attached to a buffer to describe the contents of the buffer.
31    It is possible to add a NULL caps to a buffer, this means that the
32    buffer type did not change relative to the previous buffer. If no
33    previous buffer was received by a downstream element, it is free to
34    discard the buffer.
35
36  - Before receiving a buffer, an element must check if the datatype of
37    the buffer has changed. The element should reconfigure itself to the
38    new format before processing the buffer data. If the data type on
39    the buffer is not acceptable, the element should refuse the buffer by 
40    returning an appropriate GST_FLOW_NOT_NEGOTIATED return value from the
41    chain function.
42    The core will automatically call the set_caps function for this purpose
43    when it is installed on the sink or source pad.
44
45  - When requesting a buffer from a bufferpool, the preferred type should
46    be passed to the buffer allocation function. After receiving a buffer
47    from a bufferpool, the datatype should be checked again.
48
49  - A bufferpool allocation function should try to allocate a buffer of the
50    preferred type. If there is a good reason to choose another type, the
51    alloc function should see if that other type is accepted by the other
52    element, then allocate a buffer of that type and attach the type to the
53    buffer before returning it.
54
55
56 The general flow for a source pad starting the negotiation.
57
58              src              sink
59               |                 |
60               |  accepts?       |
61   type A      |---------------->|
62               |      yes        |
63               |<----------------|
64               |                 |
65  get buffer   |  alloc_buf      |
66  from pool    |---------------->| 
67  with type A  |                 | Create buffer of type A.
68               |                 |
69  check type   |<----------------|
70  and use A    |                 |
71               |  push           |
72  push buffer  |---------------->| Receive type A, reconfigure to
73  with new type|                 | process type A.
74               |                 |
75
76  One possible implementation in pseudo code:
77
78  [element wants to create a buffer]
79  if not format
80    # see what the peer can do
81    peercaps = gst_pad_peer_get_caps (srcpad)
82    # see what we can do
83    ourcaps = gst_pad_get_caps (srcpad)
84
85    # get common formats
86    candidates = gst_caps_intersect (peercaps, ourcaps)
87
88    foreach candidate in candidates
89      # make sure the caps is fixed
90      fixedcaps = gst_pad_fixate_caps (srcpad, candidate)
91
92      # see if the peer accepts it
93      if gst_pad_peer_accept_caps (srcpad, fixedcaps)
94        # store the caps as the negotiated caps, this will
95        # call the setcaps function on the pad
96        gst_pad_set_caps (srcpad, fixedcaps)
97        break
98      endif
99    done
100  endif
101
102  # if the type is different, the buffer will have different caps from
103  # the src pad -- setcaps will get called on the pad_push
104  buffer = gst_pad_alloc_buffer (srcpad, 0, size, GST_PAD_CAPS (fixedcaps));
105  if buffer
106    [fill buffer and push]
107  elseif
108    [no buffer, either no peer or no acceptable format found]
109  endif
110
111
112 The general flow for a sink pad starting a renegotiation.
113
114              src              sink
115               |                 |
116               |  accepts?       |
117               |<----------------| type B
118               |      yes        |
119               |---------------->|
120               |                 |
121  get buffer   |  alloc_buf      |
122  from pool    |---------------->| 
123  with type A  |                 | Create buffer of new type B.
124               |                 |
125  check type   |<----------------|
126  and          |                 |
127  reconfigure  |                 |
128               |  push           |
129  push buffer  |---------------->| Receive type B, reconfigure to
130  with new type|                 | process type B.
131               |                 |
132
133               
134
135 Use case:
136
137
138 videotestsrc ! xvimagesink
139
140   1) Who decides what format to use?
141    - src pad always decides, by convention. sinkpad can suggest a format
142      by putting it high in the getcaps function GstCaps. 
143    - since the src decides, it can always choose something that it can do,
144      so this step can only fail if the sinkpad stated it could accept
145      something while later on it couldn't.
146
147   2) When does negotiation happen?
148    - before srcpad does a push, it figures out a type as stated in 1), then 
149      it calls the pad alloc function with the type. The sinkpad has to 
150      create a buffer of that type, src fills the buffer and sends it to sink.
151    - since the sink stated in 1) it could accept the type, it will be able to
152      create a buffer of the type and handle it.
153    - sink checks media type of buffer and configures itself for this type.
154      
155   3) How can sink request another format?
156    - sink asks if new format is possible for the source.
157    - sink returns buffer with new type in allocfunction.
158    - src receives buffer with new type, reconfigures and pushes.
159    - sink can always select something it can create and handle since it takes
160      the initiative. src should be able to handle the new type since it said
161      it could accept it.
162
163 videotestsrc ! queue ! xvimagesink
164
165   - queue implements an allocfunction, proxying all calls to its srcpad peer.
166   - queue proxies all accept and getcaps to the other peer pad.
167   - queue contains buffers with different types.
168
169    
170 Pull-mode negotiation
171 ~~~~~~~~~~~~~~~~~~~~~
172
173 Rationale
174 ^^^^^^^^^
175
176 A pipeline in pull mode has different negotiation needs than one
177 activated in push mode. Push mode is optimized for two use cases:
178
179  * Playback of media files, in which the demuxers and the decoders are
180    the points from which format information should disseminate to the
181    rest of the pipeline; and
182
183  * Recording from live sources, in which users are accustomed to putting
184    a capsfilter directly after the source element; thus the caps
185    information flow proceeds from the user, through the potential caps
186    of the source, to the sinks of the pipeline.
187
188 In contrast, pull mode has other typical use cases:
189
190  * Playback from a lossy source, such as RTP, in which more knowledge
191    about the latency of the pipeline can increase quality; or
192
193  * Audio synthesis, in which audio APIs are tuned to producing only the
194    necessary number of samples, typically driven by a hardware interrupt
195    to fill a DMA buffer or a Jack[0] port buffer.
196
197  * Low-latency effects processing, whereby filters should be applied as
198    data is transferred from a ring buffer to a sink instead of
199    beforehand. For example, instead of using the internal alsasink
200    ringbuffer thread in push-mode wavsrc ! volume ! alsasink, placing
201    the volume inside the sound card writer thread via wavsrc !
202    audioringbuffer ! volume ! alsasink.
203
204 [0] http://jackit.sf.net
205
206 The problem with pull mode is that the sink has to know the format in
207 order to know how many bytes to pull via gst_pad_pull_range(). This
208 means that before pulling, the sink must initiate negotation to decide
209 on a format.
210
211 Recalling the principles of capsnego, whereby information must flow from
212 those that have it to those that do not, we see that the two named use
213 cases have different negotiation requirements:
214
215  * RTP and low-latency playback are both like the normal playback case,
216    in which information flows downstream.
217
218  * In audio synthesis, the part of the pipeline that has the most
219    information is the sink, constrained by the capabilities of the graph
220    that feeds it. However the caps are not completely specified; at some
221    point the user has to intervene to choose the sample rate, at least.
222    This can be done externally to gstreamer, as in the jack elements, or
223    internally via a capsfilter, as is customary with live sources.
224
225 Given that sinks potentially need the input of sources, as in the RTP
226 case and at least as a filter in the synthesis case, there must be a
227 negotiation phase before the pull thread is activated. Also, given the
228 low latency offered by pull mode, we want to avoid capsnego from within
229 the pulling thread, in case it causes us to miss our scheduling
230 deadlines.
231
232 The pull thread is usually started in the PAUSED->PLAYING state change. We must
233 be able to complete the negotiation before this state change happens.
234
235 The time to do capsnego, then, is after _check_pull_range() has succeeded,
236 but before the sink has spawned the pulling thread.
237
238
239 Mechanism
240 ^^^^^^^^^
241
242 The sink determines that the upstream elements support pull based scheduling by
243 calling gst_pad_check_pull_range().
244
245 The sink initiates the negotiation process by intersecting the results
246 of gst_pad_get_caps() on its sink pad and its peer src pad. This is the
247 operation performed by gst_pad_get_allowed_caps(). In the simple
248 passthrough case, the peer pad's getcaps() function should return the
249 intersection of calling get_allowed_caps() on all of its sink pads. In
250 this way the sink element knows the capabilities of the entire pipeline.
251
252 The sink element then fixates the resulting caps, if necessary,
253 resulting in the flow caps. It notifies the pipeline of the caps by
254 calling gst_pad_set_caps() on its sink pad. From now on, the getcaps function
255 of the sinkpad will only return these fixed caps meaning that upstream elements
256 will only be able to produce this format.
257
258 If the sink element could not set caps on its sink pad, it should post
259 an error message on the bus indicating that negotiation was not
260 possible.
261
262 When negotiation succeeded, the sinkpad and all upstream internally linked pads
263 are activated in pull mode. Typically, this operation will trigger negotiation
264 on the downstream elements, which will now be forced to negotiation to the
265 final fixed desired caps of the sinkpad.
266
267 After these steps, the sink element returns ASYNC from the state change
268 function. The state will commit to PAUSED when the first buffer is received in
269 the sink. This is needed to provide a consistent API to the applications that
270 expect ASYNC return values from sinks but it also allows us to perform the
271 remainder of the negotiation outside of the context of the pulling thread.
272
273 During dataflow, gst_pad_pull_range() checks the caps on the pulled
274 buffer. If they are different from the sink pad's caps, it will return
275 GST_FLOW_NOT_NEGOTIATED. Because of the low-latency requirements,
276 changing caps in an activate pull-mode pipeline is not supported, as it
277 might require e.g. the sound card to reconfigure its hardware buffers,
278 and start capsnego again.
279