gstreamer/docs/design/part-gstghostpad.txt

302 lines
9.2 KiB
Text
Raw Normal View History

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 |
(-----| (----------)
-------)