docs/design/part-gstghostpad.txt: Overview of current GhostPad datastructures and...

Original commit message from CVS:
* docs/design/part-gstghostpad.txt:
Overview of current GhostPad datastructures and use
cases for changing the target.

diff --git a/ChangeLog b/ChangeLog
index daf048f..f595ffe 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2005-07-29  Wim Taymans  <wim@fluendo.com>
+
+       * docs/design/part-gstghostpad.txt:
+       Overview of current GhostPad datastructures and use
+       cases for changing the target.
+
 2005-07-28  Wim Taymans  <wim@fluendo.com>
 
        * check/gst/gstbin.c: (GST_START_TEST), (gst_bin_suite):

diff --git a/docs/design/part-gstghostpad.txt b/docs/design/part-gstghostpad.txt
new file mode 100644 (file)
index 0000000..2b23abc
--- /dev/null
+++ b/docs/design/part-gstghostpad.txt
@@ -0,0 +1,301 @@
+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 |
+           (-----|            (----------)
+          -------)
+
+