--- /dev/null
+Ghostpads
+---------
+
+ GhostPads are used to build complex compound elements out of
+ existing elements. They are used to expose internal element pads
+ on the complex element.
+
+ Some design requirements
+
+ - Must look like a real GstPad on both sides.
+ - target of Ghostpad must be changeable
+
+
+* a GhostPad is implemented using a smaller GstProxyPad class:
+
+
+ GstProxyPad
+ (------------------)
+ | GstPad |
+ |------------------|
+ | GstPad *target |
+ (------------------)
+
+
+ GstGhostPad
+ (------------------) -\
+ | GstPad | |
+ |------------------| > GstProxyPad
+ | GstPad *target | |
+ |------------------| -/
+ | GstPad *internal |
+ (------------------)
+
+
+ Some use case follow with a description of how the datastructure
+ is modified.
+
+
+* Creating a ghostpad with a target:
+
+ gst_ghost_pad_new (char *name, GstPad *target)
+
+ 1) create new GstGhostPad X
+ 2) X name set to @name
+ 3) X direction is the same as the target
+ 4) the target is set to @target
+ 5) internal is NULL
+ 6) link/unlink and activate functions are set up
+ on GstGhostPad.
+
+
+ (--------------
+ (- X --------) |
+ | | |------)
+ | target *------------------> | sink |
+ |------------| |------)
+ | internal *---->// (--------------
+ (------------)
+
+ - Automatically takes same direction as target.
+ - target is filled in automatically.
+
+
+* Creating a ghostpad without a target
+
+ gst_ghost_pad_new_notarget (char *name, GstPadDirection dir)
+
+ 1) create new GstGhostPad X
+ 2) X name set to @name
+ 3) X direction is @dir
+ 4) internal is NULL
+ 5) link/unlink and activate functions are set up
+ on GstGhostPad.
+
+
+ (- X --------)
+ | |
+ | target *------>//
+ |------------|
+ | internal *---->//
+ (------------)
+
+ - allows for setting the target later
+
+
+* Setting target on an untargetted unlinked ghostpad
+
+ gst_ghost_pad_set_target (char *name, GstPad *newtarget)
+
+ (- X --------)
+ | |
+ | target *------>//
+ |------------|
+ | internal *---->//
+ (------------)
+
+ 1) assert direction of newtarget == X direction
+ 2) target is set to newtarget
+
+ (--------
+ (- X --------) |
+ | | |------)
+ | target *------------->| sink |
+ |------------| |------)
+ | internal *--->// (--------
+ (------------)
+
+
+* Setting target on an targetted unlinked ghostpad
+
+ gst_ghost_pad_set_target (char *name, GstPad *newtarget)
+
+ (--------
+ (- X --------) |
+ | | |------)
+ | target *------------->| sink |
+ |------------| |------)
+ | internal *--->// (--------
+ (------------)
+
+ 1) assert direction of newtarget == X direction
+ 2) target is set to newtarget
+
+ (--------
+ (- X --------) |
+ | | |------)
+ | target *------------->| sink |
+ |------------| |------)
+ | internal *--->// (--------
+ (------------)
+
+
+* Linking a pad to an untargetted ghostpad:
+
+ gst_pad_link (src, X)
+
+
+ (- X --------)
+ | |
+ | target *------>//
+ |------------|
+ | internal *---->//
+ (------------)
+ -------)
+ |
+ (-----|
+ | src |
+ (-----|
+ -------)
+
+
+ 1) link function is called
+ a) new GstProxyPad Y is created
+ b) Y direction is same as peer
+ c) Y target is set to peer
+ d) X internal pad is set to Y
+ e) Y is activated in the same mode as X
+ f) core makes link from src to X
+
+
+ (- X --------)
+ | |
+ | target *----->//
+ >|------------|
+ (real pad link) / | internal * |
+ / (----------|-)
+ / |
+ -------) / V
+ | / (- Y ------)
+ (-----|/ | |
+ | src |<-------------* target |
+ (-----| (----------)
+ -------)
+
+
+* Linking a pad to a targetted ghostpad:
+
+ gst_pad_link (src, X)
+
+ (--------
+ (- X --------) |
+ | | |------)
+ | target *------------->| sink |
+ |------------| |------)
+ | internal *--->// (--------
+ (------------)
+ -------)
+ |
+ (-----|
+ | src |
+ (-----|
+ -------)
+
+
+ 1) link function is called
+ a) new GstProxyPad Y is created
+ b) Y direction is same as peer
+ c) Y target is set to peer
+ d) X internal pad is set to Y
+ e) link is made from Y to X target (sink)
+ f) Y is activated in the same mode as X
+ g) core makes link from src to X
+
+ (--------
+ (- X --------) |
+ | | |------)
+ | target *------------->| sink |
+ >|------------| >|------)
+ (real pad link) / | internal * | / (--------
+ / (----------|-) /
+ / | /
+ -------) / V / (real pad link)
+ | / (- Y ------) /
+ (-----|/ | |/
+ | src |<-------------* target |
+ (-----| (----------)
+ -------)
+
+
+* Setting target on untargetted linked ghostpad:
+
+ gst_ghost_pad_set_target (char *name, GstPad *newtarget)
+
+
+ (- X --------)
+ | |
+ | target *----->//
+ >|------------|
+ (real pad link) / | internal * |
+ / (----------|-)
+ / |
+ -------) / V
+ | / (- Y ------)
+ (-----|/ | |
+ | src |<-------------* target |
+ (-----| (----------)
+ -------)
+
+ 1) assert direction of newtarget == X direction
+ 2) X target is set to newtarget
+ 3) Y (X internal) is linked to newtarget
+
+
+ (--------
+ (- X --------) |
+ | | |------)
+ | target *------------->| sink |
+ >|------------| >|------)
+ (real pad link) / | internal * | / (--------
+ / (----------|-) /
+ / | /
+ -------) / V / (real pad link)
+ | / (- Y ------) /
+ (-----|/ | |/
+ | src |<-------------* target |
+ (-----| (----------)
+ -------)
+
+
+* Setting target on targetted linked ghostpad:
+
+ gst_ghost_pad_set_target (char *name, GstPad *newtarget)
+
+
+ (--------
+ (- X --------) |
+ | | |------)
+ | target *------------->| sink |
+ >|------------| >|------)
+ (real pad link) / | internal * | / (--------
+ / (----------|-) /
+ / | /
+ -------) / V / (real pad link)
+ | / (- Y ------) /
+ (-----|/ | |/
+ | src |<-------------* target |
+ (-----| (----------)
+ -------)
+
+ 1) assert direction of newtarget == X direction
+ 2) Y and X target are unlinked
+ 2) X target is set to newtarget
+ 3) Y (X internal) is linked to newtarget
+
+
+ (--------
+ (- X --------) |
+ | | |------)
+ | target *------------->| sink |
+ >|------------| >|------)
+ (real pad link) / | internal * | / (--------
+ / (----------|-) /
+ / | /
+ -------) / V / (real pad link)
+ | / (- Y ------) /
+ (-----|/ | |/
+ | src |<-------------* target |
+ (-----| (----------)
+ -------)
+
+