From bbcdafa05fd18dff4d0c963f41a5c796df027bc5 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Mon, 15 Oct 2012 13:44:51 +0200 Subject: [PATCH] pwg: improve negotiation documentation some more --- docs/pwg/advanced-negotiation.xml | 251 ++++++++++++++++---------------------- 1 file changed, 106 insertions(+), 145 deletions(-) diff --git a/docs/pwg/advanced-negotiation.xml b/docs/pwg/advanced-negotiation.xml index 77ac5a4..7cc7fd8 100644 --- a/docs/pwg/advanced-negotiation.xml +++ b/docs/pwg/advanced-negotiation.xml @@ -296,161 +296,102 @@ gst_my_filter_sink_event (GstPad *pad, Like with the transform negotiation in , dynamic negotiation will perform a transformation on the downstream/upstream caps. Unlike the - transform - negotiation, this transform will convert fixed caps to unfixed caps. This - means that the sink pad input caps can be converted into unfixed (multiple) - formats. The source pad will have to choose a format from all the - possibilities. It would usually like to choose a format that requires the - least amount of effort to produce but it does not have to be. The selection - of the format should also depend on the caps that can be accepted downstream + transform negotiation, this transform will convert fixed caps to + unfixed caps. This means that the sink pad input caps can be converted + into unfixed (multiple) formats. The source pad will have to choose a + format from all the possibilities. It would usually like to choose a + format that requires the least amount of effort to produce but it does + not have to be. The selection of the format should also depend on the + caps that can be accepted downstream (see a QUERY_CAPS function in + ). - - - - - Pull-mode Caps negotiation - - - - - - - - Downstream caps negotiation - - Downstream negotiation takes place when a format needs to be set on a - source pad to configure the output format, but this element allows - renegotiation because its format is configured on the sinkpad caps, - or because it supports multiple formats. The requirements for doing - the actual negotiation differ slightly. - - - - Negotiating caps embedded in input caps - There may also be cases where the filter actually is able to - change the format of the stream. In those cases, - it will negotiate a new format. Obviously, the element should first - attempt to configure pass-through, which means that - it does not change the stream's format. However, if that fails, - then it should call gst_pad_get_allowed_caps () - on its sourcepad to get a list of supported formats on the outputs, - and pick the first. The return value of that function is guaranteed - to be a subset of the template caps or NULL when there is no peer. + A typical flow goes like this: + + + + + Caps are received on the sink pad of the element. + + + + + If the element prefers to operate in passthrough mode, check + if downstream accepts the caps with the ACCEPT_CAPS query. + + + + + Calculate the possible caps for the source pad. + + + + + Query the downstream peer pad for the list of possible + caps. + + + + + Select from the downstream list the first caps that you can + transform to and set this as the output caps. + + + + + Examples of this type of elements include: + + + + Converter elements such as videoconvert, audioconvert, audioresample, + videoscale, ... + + + + + Source elements such as audiotestsrc, videotestsrc, v4l2src, + pulsesrc, ... + + + Let's look at the example of an element that can convert between samplerates, so where input and output samplerate don't have to be the same: - - + +sinkpad, caps)) { + filter->passthrough = TRUE; } else { GstCaps *othercaps, *newcaps; GstStructure *s = gst_caps_get_structure (caps, 0), *others; /* no passthrough, setup internal conversion */ - gst_structure_get_int (s, "channels", &filter->channels); - othercaps = gst_pad_get_allowed_caps (filter->srcpad); + gst_structure_get_int (s, "channels", &filter->channels); + othercaps = gst_pad_get_allowed_caps (filter->srcpad); others = gst_caps_get_structure (othercaps, 0); gst_structure_set (others, - "channels", G_TYPE_INT, filter->channels, NULL); + "channels", G_TYPE_INT, filter->channels, NULL); /* now, the samplerate value can optionally have multiple values, so * we "fixate" it, which means that one fixed value is chosen */ newcaps = gst_caps_copy_nth (othercaps, 0); gst_caps_unref (othercaps); - gst_pad_fixate_caps (filter->srcpad, newcaps); - if (!gst_pad_set_caps (filter->srcpad, newcaps)) + gst_pad_fixate_caps (filter->srcpad, newcaps); + if (!gst_pad_set_caps (filter->srcpad, newcaps)) return FALSE; /* we are now set up, configure internally */ - filter->passthrough = FALSE; - gst_structure_get_int (s, "rate", &filter->from_samplerate); + filter->passthrough = FALSE; + gst_structure_get_int (s, "rate", &filter->from_samplerate); others = gst_caps_get_structure (newcaps, 0); - gst_structure_get_int (others, "rate", &filter->to_samplerate); + gst_structure_get_int (others, "rate", &filter->to_samplerate); } return TRUE; @@ -469,7 +410,7 @@ gst_my_filter_sink_event (GstPad *pad, { GstCaps *caps; - gst_event_parse_caps (event, &caps); + gst_event_parse_caps (event, &caps); ret = gst_my_filter_setcaps (filter, caps); break; } @@ -489,23 +430,26 @@ gst_my_filter_chain (GstPad *pad, GstBuffer *out; /* push on if in passthrough mode */ - if (filter->passthrough) - return gst_pad_push (filter->srcpad, buf); + if (filter->passthrough) + return gst_pad_push (filter->srcpad, buf); /* convert, push */ out = gst_my_filter_convert (filter, buf); gst_buffer_unref (buf); - return gst_pad_push (filter->srcpad, out); + return gst_pad_push (filter->srcpad, out); } - - +]]> + + + Pull-mode Caps negotiation + + + + Upstream caps (re)negotiation @@ -532,19 +476,36 @@ gst_my_filter_chain (GstPad *pad, - Elements that can be reconfigured on the srcpad should check its - NEED_RECONFIGURE flag with - gst_pad_check_reconfigure () and it should - start renegotiation when the function returns TRUE. + Elements that want to propose a new format upstream need to first + check if the new caps are acceptable upstream with an ACCEPT_CAPS + query. Then they would send a RECONFIGURE event and be prepared to + answer the CAPS query with the new prefered format. It should be + noted that when there is no upstream element that can (or wants) + to renegotiate, the element needs to deal with the currently + configured format. - Elements that want to propose a new format upstream need to send - a RECONFIGURE event and be prepared to answer the CAPS query with - the new prefered format. It should be noted that when there is no - upstream element that can (or wants) to renegotiate, the element - needs to deal with the currently configured format. + Elements that operate in transform negotiation according to + pass the RECONFIGURE + event upstream. + + + + + Elements that operate in fixed negotiation + () drop the RECONFIGURE event. + + + + + Elements that can be reconfigured on the source pad (source pads + implementing dynamic negotiation in + ) should check its + NEED_RECONFIGURE flag with + gst_pad_check_reconfigure () and it should + start renegotiation when the function returns TRUE. -- 2.7.4