gstreamer/docs/design/draft-ghostpads.txt

Ghostpads
---------

Status:

  DRAFT.  DEPRECATED by better current implementation.


Purpose:

  To create compound elements that look and behave like real elements
  one needs to be able to expose pads on the element that are not
  implemented by the element itself but by one of its components.

  ex1:

    Consider an rtp receiver element. It uses 2 UDP input ports to
    capture RTP and RTCP messages using UDP. These messages are
    then processed by an rtpsession element, which will reorder, make
    statistics, and generate the RTP and RTCP messages.

    This element can be build from existing elements as shown in the
    figure below.

     +------------------------------------+
     | rtpsrc                             |
     |                                    |
     | +--------+ +---------+             |
     | | udpsrc | | rtpsess |             |
     | |  port1 ---         ----------------
     | +--------+ |         |             |
     | +--------+ |         | +---------+ |
     | | udpsrc | |         | | udpsink | |
     | |  port2 ---         ---  port3  | |
     | +--------+ +---------+ +---------+ |
     +------------------------------------+

    The element has one output pad that contains the raw RTP data. This
    pad will be connected to the next element that will decode the RTP
    data. Since this pad is actually from the rtpsession element, there
    has to be a way to expose this pad on the rtpsrc element.


Current implementation:

  Version 0.8 creates a new GstGhostPad type that extends GstPad and has
  a link to the real pad internally.

  Any operation on a pad potentially requires to check if this pad is a
  GhostPad and if so, follow the pointer to the real pad to perform the
  pad operation.


Current problem:

  - following the ghostpad to resolve the real pad adds code.
  - operations on pads are not performed on the ghostpad but on the
    real pad. This means:
      - pads are not linked to a ghostpad but to the real pad. For
        compound objects, the link is not really performed to the
	pad of the compound element but with some internal pad.
  - for state changes, it is hard to follow linked elements upstream
    bacause pads enter bins to the real element.


Proposal:

  - The pad still has one parent, the element that owns (has sinked) the
    pad. the GST_OBJECT_PARENT() is the real parent.

  - The pad receives a GList of ghostparents. Ghostparents are sorted by depth.

  - When a pad is ghostparented to another element, the element is added to
    the ghostparent list of the pad. The pad is added to the padlist of the
    element.

  - A pad cannot be ghostparented to an element that is not a parent of the
    pad parent element. this ensures that all ghostpads do not skip an hierarchy.

  - When a pad is removed from the parent element, it is also removed from all
    the ghostparents. This is easy to do as you can follow the ghostparent list of
    that pad.

  - When an element is removed from another element, all the elements pads 
    ghostparented to parents of the element are removed as well. This is easy
    to do with the sorted ghostparent list of the pad.


Consequences:

  - All pads are Real pads.
  - All operations are performed on the real pads. This improves performance
    and code simplicity
  - more checks can be done. Linking nested elements can be done sanely.
    compount elements that expose usable pads must ghostpad them before they
    can be linked. 
  - All linked pads have a common grandparent.


Issues:

  - Name of ghostpad cannot be changed and is the name of the element. This could
    be solved by temporarily renaming the pad when ghostpadding. This could then
    again result in the element being confused about the padnames or the
    element having two pads with the same name.