Caps Negotiation
================


Definitions
-----------

- GstCaps is a structure that holds a mimetype and a set of properties. The properties are
  either fixed or non-fixed, they contain ranges or lists.

- filter caps: caps set by the application to constrain a link to a specific GstCaps.

- allowed caps: caps calculated when connecting elements, these are the types that are
  possible on this connection. If no types are possible, the link is refused.

- pad template caps: caps put on padtemplates to describe the possible media types of
  the pad.

- pad caps: the caps of the pad as it is currently negotiated.


General overview
----------------

Caps negotiation is the process of two pads agreeing on a common fixed GstCaps structure
that describes the media type that will be exchanged between those pads.

We define that caps negotiation only happens in the PLAYING state, when there is actual
dataflow and elements thus know what kind of data they are dealing with, or when 
linking elements.

Caps negotiation is first performed when linking elements. If the elements can agree
on a media type at link time then negotiation will not have to be performed at runtime.
Usually this is not possible, so the pads remain unnegotiated until at runtime.

Caps negotiation is initiated by an element that wants to send data on a non-negotiated
pad, thus the source pad. The core only provides a policy and convenience methods to aid 
the element in performing the negotiation. The core does not keep track of what pads
are negotiated or not, this is a task of the pads.

Caps negotiation is normally started by the source element right before it sends out 
data (case 1).
Caps negotiation can also be redone by a sink element that wants to receive another 
format from a downstream element (case 2).

There are two functions handling the negotiation, the link function and the do_link
function. The link function is always called first and must eventually call do_link on
the peer pad.  The link function must figure out a compatible format for the connection
and then call the do_link function on the peer pad. The do_link function can only 
accept or refuse the provided caps.

For autopluggers it is important to know when the pad is ready to start the negotiation.
It is also inportant to know when the negotiation failed and it must be possible to 
restart the negotiation with another element. This functionality will be provided
with signals.

Pad functions
-------------

!
! const GstCaps* gst_pad_iterate_caps (GstPad *pad, gint position);
!
Returns the nth possible caps that describes the media type that can flow over
this pad. This function should not return static caps but caps that are 
dependent of the media type and the peer connections of the element.

This function can be called at any time so that an autoplugger can know the
exact types of the pads at any time.

!
! gboolean gst_pad_accept_caps (GstPad *pad, GstCaps *caps);
!
Checks that a given caps is acceptable for this pad. Returns FALSE if the
pad cannot handle the caps.

!
! gboolean gst_pad_link (GstPad *pad, GstPad *peer, GstCaps *caps);
!
Tells the pad to start negotiation with the given filtercaps. The
caps need not be fixed and serves as a filter for performing the negotiation
with the peerpad. 

!
! gboolean gst_pad_do_link (GstPad *pad, GstPad *peer, GstCaps *caps);
!
Configures the pad to accept data with the given caps.  The caps must be fixed. 

!
! const GstCaps* gst_pad_get_negotiated_caps (GstPad *pad);
!
Get the negotiated caps of a pad or NULL if the pad is not negotiated.


Linking Elements
----------------

When linking elements with the gst_pad_link function, the core will call
the link function on the srcpad. If that pad returns GST_PAD_LINK_OK,
the link is established, else the link fails.

Since the link function of the pad will call the do_link function of
the peerpad, the caps will be set on both pads.

It is not required to decide on a caps at link time, a plugin can choose to
dynamically renegotiate at runtime.

When a link fails, the core emits a signal link_failed, which the application
can catch to try to establish a new link with another element, for example.

!
! def gst_pad_link_filtered (pad1, pad2, filtercaps):
!
!   ... get srcpad and sinkpad ...
!   srcpad  = (pad1 == GST_PAD_SRC ? pad1 : pad2);
!   sinkpad = (pad1 == GST_PAD_SINK ? pad1 : pad2);
!
!   ... more checks to see if the pads are of different types and
!   ... that they live in the same scheduler etc...
!
!   res = gst_pad_link (srcpad, sinkpad, filtercaps)
!   if (res == GST_PAD_LINK_OK)
!     ... perform other setup ...
!   else
!     res = signal_emit (srcpad, "link_failed")
!
!   return res
!

Pad link is just a convenience function that passes a NULL filtercaps:
! 
! def gst_pad_link (pad1, pad2):
!   gst_pad_link_filtered (pad1, pad2, NULL)
!


Dynamic renegotiation
---------------------

Dynamic renegotiation happens at runtime when the element knows the exact media
type it is handling.

The element that wants to redecide on the data type of a connection just calls
gst_pad_relink on one of it's pads. The core will call unlink and link on the
pads again as if this were a new connection. Since the iterate_caps function
returns other values while linking, the new link will renegotiate to a new
format or the link will fail.

Prototype of the relink function:
!
! def gst_pad_relink_filtered (pad, filtercaps):
!   gst_pad_unlink (pad, peerpad)
!   gst_pad_link_filtered (pad, peerpad, filtercaps)
!

Again the relink function is a convenience function for not having to pass 
filtercaps.
!
! def gst_pad_relink (pad):
!   gst_pad_relink_filtered (pad, NULL)
!

The core, however, should optimize the relink function so that it does a minimal
amount of work, like not informing the scheduler about the unlink/link call in
case of success.

Error recovery
--------------

When a pad is ready to negotiate and it has no peer pad, it fires the "need-link"
signal. Autopluggers can use this signal to start plugging elements to the pad.

When a link fails because of a renegotiation, the "link-failed" signal is fired
so that autopluggers can try other elements.


Default implementations
-----------------------

!
! gst_pad_src_link_func (pad, peerpad, filtercaps) 
! {
!   srcpad->negotiated_caps = NULL;
!   gboolean possible = FALSE;
!
!   for (i=0; peercaps = gst_pad_iterate_caps (peerpad, i); i++) 
!   {
!     for (j=0; srccaps = gst_pad_iterate_caps (srcpad, j); j++) 
!     {
!       test = gst_caps_intersect (srccaps, peercaps, filtercaps);
!       if (test == GST_CAPS_EMPTY)
!         continue;
!
!       /* non empty caps, something is possible */
!       possible = TRUE;
!
!       if (!gst_caps_is_fixed (caps))
!         continue;
!
!       if (gst_pad_accepts_caps (peerpad, test))
!       {
!         if (gst_pad_do_link (peerpad, srcpad, test))
!         {
!           srcpad->negotiated_caps = test;
!           goto done;
!         }
!         else
!         {
!           /* weird, it accepted but did not want to link */
!         }
!       }
!       else
!       {
!         /* caps are not accepted by peer, try next */
!       }
!     }
!   }
! done:
!   if (!possible)
!     return GST_PAD_LINK_FAILED;
!   else
!     return GST_PAD_LINK_OK;
! }
!

gst_pad_iterate_caps returns caps in the following order:

 1) prefered caps (if any)
 2) negotiated caps (if any)
 3) profile caps (if any, filtered against caps of current media type)
 4) padtemplate caps (filtered against caps of current media type)

1 = a caps describing the media type that would result in optimal
    processing of the current media type
2 = a caps that it is currently handling
3 = a caps describing the user configured default values
4 = a caps describing all other possibilities that this pad can
    produce or consume given the current media type if any.


generic flow 1:

 Linkage

         src                         sink
          |                           |
          | <--- link(sink, A)        |
check if  |                           |
A is ok   |                           |
or filter |                           |
against   |                           |
allowed   |                           |
src caps  |                           |
          |  iterate_caps             |
if A not  +-------------------------> |
fixed     |                           |
          | <-------------------------+
filter    |                           |
against A |                           |
to get A' |                           |
          |  can_accept(A')           |
if A' fix +-------------------------> |
          |                           | check if A' is ok
          |        yes                |
          | <-------------------------+
          |                           |
if A' not |                           |
fixed,    |                           |
A'=null   |                           |
          |  do_link(src, A')         |
          +-------------------------> |
          |        ok                 | store src, A'
          | <-------------------------+
store     |                           |
sink, A'  |                           |


Unlink

         src                         sink
          |                           |
          | <--- unlink()             |
          |                           |
          |  unlink()                 |
          +-------------------------> |
unref     |                           | unref src, format
sink, fmt |                           |


  Dynamic negotiation of B

         src                         sink
          |  can_accept(B)            |
          +-------------------------> |
          |                           | check if B is ok
          |        yes                |
          | <-------------------------+
          |                           |
          |       do_link(B)          |
          +-------------------------> |
          |        ok                 | store B
          | <-------------------------+
store     |                           |
B         |                           |


TODO
-----

Write test objects to simulate different behaviour.


tests (in python):

   vts -> colorspace -> ximagsink

  relink with different colorspaces while running

  
   vts -> videoscale -> ximagesink

  relink to different sizes while running, scaling vts or ximagesink.

   sinesrc -> audiorate -> audiosink

  where audiosink only has one possible fixed caps.