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 (X is parent of 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 (X is parent of 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 |
           (-----|            (----------)
          -------)