59
59
In order for caps negotiation on non-fixed links to work correctly,
60
pads can optionally implement a function that tells peer elements what
61
formats it supports and/or prefers. When upstream renegotiation is
60
pads can optionally implement a query function that tells peer elements
61
what formats it supports and/or prefers. When upstream renegotiation is
62
62
triggered, this becomes important.
65
Downstream elements are notified of a newly set caps only when data
66
is actually passing their pad. This is because caps is attached to
67
buffers during data flow. So when the vorbis decoder sets a caps on
65
Downstream elements are notified of a newly set caps with a
66
GST_EVENT_CAPS on the sinkpad. So when the vorbis decoder sets a caps on
68
67
its source pad (to configure the output format), the converter will
69
not yet be notified. Instead, the converter will only be notified
70
when the decoder pushes a buffer over its source pad to the converter.
71
Right before calling the chain-function in the converter, &GStreamer;
72
will check whether the format that was previously negotiated still
73
applies to this buffer. If not, it first calls the setcaps-function
74
of the converter to configure it for the new format. Only after that
75
will it call the chain function of the converter.
69
When an element receives a buffer, it should check if it has received
70
all needed format information in a CAPS event previously. If it hasn't,
71
it should return an error from the chain function.
100
96
caps = gst_caps_new_simple ("audio/x-raw",
101
97
"format", G_TYPE_STRING, GST_AUDIO_NE(F32),
102
"buffer-frames", G_TYPE_INT, <bytes-per-frame>,
103
98
"rate", G_TYPE_INT, <samplerate>,
104
99
"channels", G_TYPE_INT, <num-channels>, NULL);
105
100
if (!gst_pad_set_caps (pad, caps)) {
159
154
Many elements, particularly effects and converters, will be able
160
155
to parse the format of the stream from their input caps, and decide
161
the output format right at that time already. When renegotiation
162
takes place, some may merely need to "forward" the renegotiation
163
backwards upstream (more on that later). For those elements, all
164
(downstream) caps negotiation can be done in something that we
165
call the <function>_setcaps ()</function> function. This function is
166
called when a buffer is pushed over a pad, but the format on this
167
buffer is not the same as the format that was previously negotiated
168
(or, similarly, no format was negotiated yet so far).
156
the output format right at that time already. For those elements, all
157
(downstream) caps negotiation can be done from the
158
<function>_event ()</function> function when a GST_EVENT_CAPS is
159
received on the sinkpad. This CAPS event is received whenever the
160
format changes or when no format was negotiated yet. It will always
161
be called before you receive the buffer in the format specified in
171
In the <function>_setcaps ()</function>-function, the element can
172
forward the caps to the next element and, if that pad accepts the
165
In the <function>_event ()</function>-function, the element can
166
forward the CAPS event to the next element and, if that pad accepts the
173
167
format too, the element can parse the relevant parameters from the
174
168
caps and configure itself internally. The caps passed to this function
175
169
is <emphasis>always</emphasis> a subset of the template caps, so
187
181
--><!-- example-end forwardcaps.c a -->
188
182
<!-- example-begin forwardcaps.c b -->
190
gst_my_filter_setcaps (GstPad *pad,
184
gst_my_filter_sink_event (GstPad *pad,
193
GstMyFilter *filter = GST_MY_FILTER (GST_OBJECT_PARENT (pad));
196
/* forward-negotiate */
197
if (!gst_pad_set_caps (filter->srcpad, caps))
200
/* negotiation succeeded, so now configure ourselves */
201
s = gst_caps_get_structure (caps, 0);
202
gst_structure_get_int (s, "rate", &filter->samplerate);
203
gst_structure_get_int (s, "channels", &filter->channels);
189
GstMyFilter *filter = GST_MY_FILTER (parent);
191
switch (GST_EVENT_TYPE (event)) {
197
gst_event_parse_caps (event, &caps);
199
/* forward-negotiate */
200
ret = gst_pad_set_caps (filter->srcpad, caps);
204
/* negotiation succeeded, so now configure ourselves */
205
s = gst_caps_get_structure (caps, 0);
206
gst_structure_get_int (s, "rate", &filter->samplerate);
207
gst_structure_get_int (s, "channels", &filter->channels);
211
ret = gst_pad_event_default (pad, parent, event);
207
216
<!-- example-end forwardcaps.c b -->
208
217
<!-- example-begin forwardcaps.c c --><!--
219
228
then it should call <function>gst_pad_get_allowed_caps ()</function>
220
229
on its sourcepad to get a list of supported formats on the outputs,
221
230
and pick the first. The return value of that function is guaranteed
222
to be a subset of the template caps.
231
to be a subset of the template caps or NULL when there is no peer.
225
234
Let's look at the example of an element that can convert between
246
255
--><!-- example-end convertcaps.c a -->
247
256
<!-- example-begin convertcaps.c b -->
249
gst_my_filter_setcaps (GstPad *pad,
258
gst_my_filter_setcaps (GstMyFilter *filter,
252
GstMyFilter *filter = GST_MY_FILTER (GST_OBJECT_PARENT (pad));
254
261
if (gst_pad_set_caps (filter->sinkpad, caps)) {
255
262
filter->passthrough = TRUE;
293
gst_my_filter_sink_event (GstPad *pad,
298
GstMyFilter *filter = GST_MY_FILTER (parent);
300
switch (GST_EVENT_TYPE (event)) {
305
gst_event_parse_caps (event, &caps);
306
ret = gst_my_filter_setcaps (filter, caps);
310
ret = gst_pad_event_default (pad, parent, event);
285
316
static GstFlowReturn
286
317
gst_my_filter_chain (GstPad *pad,
289
GstMyFilter *filter = GST_MY_FILTER (GST_OBJECT_PARENT (pad));
321
GstMyFilter *filter = GST_MY_FILTER (parent);
292
324
/* push on if in passthrough mode */
322
354
Fortunately, the code required to do so is very similar to the last
323
355
code example in <xref linkend="section-nego-downstream-embed"/>, with
324
356
the difference being that the caps is selected in the <function>_chain
325
()</function>-function rather than in the <function>_setcaps
357
()</function>-function rather than in the <function>_event
326
358
()</function>-function. The rest, as for getting all allowed caps from
327
359
the source pad, fixating and such, is all the same. Re-negotiation,
328
360
which will be handled in the next section, is very different for such
341
373
or because the audio channel configuration changed.
344
Upstream caps renegotiation is done in the <function>gst_pad_alloc_buffer
345
()</function>-function. The idea here is that an element requesting a
346
buffer from downstream, has to specify the type of that buffer. If
347
renegotiation is to take place, this type will no longer apply, and the
348
downstream element will set a new caps on the provided buffer. The element
349
should then reconfigure itself to push buffers with the returned caps. The
350
source pad's setcaps will be called once the buffer is pushed.
376
Upstream caps renegotiation is requested by sending a GST_EVENT_RECONFIGURE
377
event upstream. The idea is that it will instruct the upstream element
378
to reconfigure its caps by doing a new query for the allowed caps and then
379
choosing a new caps. The element that sends out the RECONFIGURE event
380
would influence the selection of the new caps by returning the new
381
prefered caps from its GST_QUERY_CAPS query function. The RECONFIGURE
382
event will set the GST_PAD_FLAG_NEED_RECONFIGURE on all pads that it
353
386
It is important to note here that different elements actually have
359
Elements should implement a <quote>padalloc</quote>-function in
360
order to be able to change format on renegotiation. This is also
361
true for filters and converters.
366
Elements should allocate new buffers using
367
<function>gst_pad_alloc_buffer ()</function>.
372
Elements that are renegotiable should implement a
373
<quote>setcaps</quote>-function on their sourcepad as well.
392
Elements that can be reconfigured on the srcpad should check its
393
NEED_RECONFIGURE flag with
394
<function>gst_pad_check_reconfigure ()</function> and it should
395
start renegotiation when the function returns TRUE.
400
Elements that want to propose a new format upstream need to send
401
a RECONFIGURE event and be prepared to answer the CAPS query with
402
the new prefered format. It should be noted that when there is no
403
upstream element that can (or wants) to renegotiate, the element
404
needs to deal with the currently configured format.
378
Unfortunately, not all details here have been worked out yet, so this
379
documentation is incomplete. FIXME.
383
<sect1 id="section-nego-getcaps" xreflabel="Implementing a getcaps function">
384
<title>Implementing a getcaps function</title>
410
<sect1 id="section-nego-getcaps" xreflabel="Implementing a CAPS query function">
411
<title>Implementing a CAPS query function</title>
386
A <function>_getcaps ()</function>-function is called when a peer
387
element would like to know which formats this element supports, and
388
in what order of preference. The return value should be all formats
389
that this elements supports, taking into account limitations of peer
390
elements further downstream or upstream, sorted by order of preference,
391
highest preference first.
413
A <function>_query ()</function>-function with the GST_QUERY_CAPS query
414
type is called when a peer element would like to know which formats
415
this pad supports, and in what order of preference. The return value
416
should be all formats that this elements supports, taking into account
417
limitations of peer elements further downstream or upstream, sorted by
418
order of preference, highest preference first.
396
423
#include "init.func"
397
424
--><!-- example-end getcaps.c a -->
398
425
<!-- example-begin getcaps.c b -->
400
gst_my_filter_getcaps (GstPad *pad)
427
gst_my_filter_query (GstPad *pad, GstObject * parent, GstQuery * query)
402
GstMyFilter *filter = GST_MY_FILTER (GST_OBJECT_PARENT (pad));
403
GstPad *otherpad = (pad == filter->srcpad) ? filter->sinkpad :
405
GstCaps *othercaps = gst_pad_get_allowed_caps (otherpad), *caps;
408
/* We support *any* samplerate, indifferent from the samplerate
409
* supported by the linked elements on both sides. */
410
for (i = 0; i < gst_caps_get_size (othercaps); i++) {
411
GstStructure *structure = gst_caps_get_structure (othercaps, i);
413
gst_structure_remove_field (structure, "rate");
430
GstMyFilter *filter = GST_MY_FILTER (parent);
432
switch (GST_QUERY_TYPE (query)) {
436
GstCaps *temp, *caps, *filter, *tcaps;
439
otherpad = (pad == filter->srcpad) ? filter->sinkpad :
441
caps = gst_pad_get_allowed_caps (otherpad);
443
gst_query_parse_caps (query, &filter);
445
/* We support *any* samplerate, indifferent from the samplerate
446
* supported by the linked elements on both sides. */
447
for (i = 0; i < gst_caps_get_size (caps); i++) {
448
GstStructure *structure = gst_caps_get_structure (caps, i);
450
gst_structure_remove_field (structure, "rate");
453
/* make sure we only return results that intersect our
455
tcaps = gst_pad_get_pad_template_caps (pad);
457
temp = gst_caps_intersect (caps, tcaps);
458
gst_caps_unref (caps);
459
gst_caps_unref (tcaps);
462
/* filter against the query filter when needed */
464
temp = gst_caps_intersect (caps, filter);
465
gst_caps_unref (caps);
468
gst_query_set_caps_result (query, caps);
469
gst_caps_unref (caps);
474
ret = gst_pad_query_default (pad, parent, query);
415
caps = gst_caps_intersect (othercaps, gst_pad_get_pad_template_caps (pad));
416
gst_caps_unref (othercaps);
420
479
<!-- example-end getcaps.c b -->
421
480
<!-- example-begin getcaps.c c --><!--
added
removed
docs/pwg/advanced-negotiation.xml
