Upstream negotiation's primary use is to renegotiate (part of) an already-negotiated pipeline to a new format. Some practical examples include to select a different video size because the size of the video window changed, and the video output itself is not capable of rescaling, or because the audio channel configuration changed.
Upstream caps renegotiation is requested by sending a GST_EVENT_RECONFIGURE event upstream. The idea is that it will instruct the upstream element to reconfigure its caps by doing a new query for the allowed caps and then choosing a new caps. The element that sends out the RECONFIGURE event would influence the selection of the new caps by returning the new preferred caps from its GST_QUERY_CAPS query function. The RECONFIGURE event will set the GST_PAD_FLAG_NEED_RECONFIGURE on all pads that it travels over.
It is important to note here that different elements actually have different responsibilities here:
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 preferred 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 the section called “Transform negotiation” pass the RECONFIGURE event upstream. Because these elements simply do a fixed transform based on the upstream caps, they need to send the event upstream so that it can select a new format.
Elements that operate in fixed negotiation (the section called “Fixed negotiation”) drop the RECONFIGURE event. These elements can't reconfigure and their output caps don't depend on the upstream caps so the event can be dropped.
Elements that can be reconfigured on the source pad (source pads
implementing dynamic negotiation in
the section called “Dynamic negotiation”) should check its
NEED_RECONFIGURE flag with
gst_pad_check_reconfigure ()
and it should
start renegotiation when the function returns TRUE.