From e3b39f23205a0987a1547ddead38d36b98278004 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Fri, 29 Jul 2005 11:29:52 +0000 Subject: [PATCH] docs/design/part-gstghostpad.txt: Overview of current GhostPad datastructures and use cases for changing the target. Original commit message from CVS: * docs/design/part-gstghostpad.txt: Overview of current GhostPad datastructures and use cases for changing the target. --- ChangeLog | 6 + docs/design/part-gstghostpad.txt | 301 +++++++++++++++++++++++++++++++ 2 files changed, 307 insertions(+) create mode 100644 docs/design/part-gstghostpad.txt diff --git a/ChangeLog b/ChangeLog index daf048f805..f595ffe8de 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2005-07-29 Wim Taymans + + * docs/design/part-gstghostpad.txt: + Overview of current GhostPad datastructures and use + cases for changing the target. + 2005-07-28 Wim Taymans * 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 index 0000000000..2b23abcbc5 --- /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 | + (-----| (----------) + -------) + +