mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-11 10:56:38 +00:00
455 lines
14 KiB
Markdown
455 lines
14 KiB
Markdown
# 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
|
||
- target can be initially NULL
|
||
|
||
- a GhostPad is implemented using a private `GstProxyPad` class:
|
||
|
||
```
|
||
GstProxyPad
|
||
(------------------)
|
||
| GstPad |
|
||
|------------------|
|
||
| GstPad *target |
|
||
(------------------)
|
||
| GstPad *internal |
|
||
(------------------)
|
||
|
||
GstGhostPad
|
||
(------------------) -\
|
||
| GstPad | |
|
||
|------------------| |
|
||
| GstPad *target | > GstProxyPad
|
||
|------------------| |
|
||
| GstPad *internal | |
|
||
|------------------| -/
|
||
| <private data> |
|
||
(------------------)
|
||
```
|
||
|
||
A `GstGhostPad` (X) is _always_ created together with a `GstProxyPad` (Y).
|
||
The internal pad pointers are set to point to eachother. The
|
||
`GstProxyPad` pairs have opposite directions, the `GstGhostPad` has the same
|
||
direction as the (future) ghosted pad (target).
|
||
|
||
```
|
||
(- X --------)
|
||
| |
|
||
| target * |
|
||
|------------|
|
||
| internal *----+
|
||
(------------) |
|
||
^ V
|
||
| (- Y --------)
|
||
| | |
|
||
| | target * |
|
||
| |------------|
|
||
+----* internal |
|
||
(------------)
|
||
|
||
Which we will abbreviate to:
|
||
|
||
(- X --------)
|
||
| |
|
||
| target *--------->//
|
||
(------------)
|
||
|
|
||
(- Y --------)
|
||
| target *----->//
|
||
(------------)
|
||
```
|
||
|
||
The `GstGhostPad` (X) is also set as the parent of the `GstProxyPad` (Y).
|
||
|
||
The target is a pointer to the internal pads peer. It is an optimisation to
|
||
quickly get to the peer of a ghostpad without having to dereference the
|
||
internal->peer.
|
||
|
||
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 + GstProxyPad Y
|
||
2) X name set to @name
|
||
3) X direction is the same as the target, Y is opposite.
|
||
4) the target of X is set to @target
|
||
5) Y is linked to @target
|
||
6) link/unlink and activate functions are set up
|
||
on GstGhostPad.
|
||
|
||
```
|
||
(--------------
|
||
(- X --------) |
|
||
| | |------)
|
||
| target *------------------> | sink |
|
||
(------------) -------> |------)
|
||
| / (--------------
|
||
(- Y --------) / (pad link)
|
||
//<-----* target |/
|
||
(------------)
|
||
```
|
||
|
||
- Automatically takes same direction as target.
|
||
- target is filled in automatically.
|
||
|
||
## Creating a ghostpad without a target
|
||
|
||
```
|
||
gst_ghost_pad_new_no_target (char *name, GstPadDirection dir)
|
||
```
|
||
|
||
1) create new GstGhostPad X + GstProxyPad Y
|
||
2) X name set to @name
|
||
3) X direction is @dir
|
||
5) link/unlink and activate functions are set up on GstGhostPad.
|
||
|
||
```
|
||
(- X --------)
|
||
| |
|
||
| target *--------->//
|
||
(------------)
|
||
|
|
||
(- Y --------)
|
||
| target *----->//
|
||
(------------)
|
||
```
|
||
|
||
- allows for setting the target later
|
||
|
||
## Setting target on an untargetted unlinked ghostpad
|
||
|
||
```
|
||
gst_ghost_pad_set_target (char *name, GstPad *newtarget)
|
||
|
||
(- X --------)
|
||
| |
|
||
| target *--------->//
|
||
(------------)
|
||
|
|
||
(- Y --------)
|
||
| target *----->//
|
||
(------------)
|
||
```
|
||
|
||
1) assert direction of newtarget == X direction
|
||
2) target is set to newtarget
|
||
3) internal pad Y is linked to newtarget
|
||
|
||
```
|
||
(--------------
|
||
(- X --------) |
|
||
| | |------)
|
||
| target *------------------> | sink |
|
||
(------------) -------> |------)
|
||
| / (--------------
|
||
(- Y --------) / (pad link)
|
||
//<-----* target |/
|
||
(------------)
|
||
```
|
||
|
||
## Setting target on a targetted unlinked ghostpad
|
||
|
||
```
|
||
gst_ghost_pad_set_target (char *name, GstPad *newtarget)
|
||
|
||
(--------------
|
||
(- X --------) |
|
||
| | |-------)
|
||
| target *------------------> | sink1 |
|
||
(------------) -------> |-------)
|
||
| / (--------------
|
||
(- Y --------) / (pad link)
|
||
//<-----* target |/
|
||
(------------)
|
||
```
|
||
|
||
1) assert direction of newtarget (sink2) == X direction
|
||
2) unlink internal pad Y and oldtarget
|
||
3) target is set to newtarget (sink2)
|
||
4) internal pad Y is linked to newtarget
|
||
|
||
```
|
||
(--------------
|
||
(- X --------) |
|
||
| | |-------)
|
||
| target *------------------> | sink2 |
|
||
(------------) -------> |-------)
|
||
| / (--------------
|
||
(- Y --------) / (pad link)
|
||
//<-----* target |/
|
||
(------------)
|
||
```
|
||
|
||
- Linking a pad to an untargetted ghostpad:
|
||
|
||
```
|
||
gst_pad_link (src, X)
|
||
|
||
(- X --------)
|
||
| |
|
||
| target *--------->//
|
||
(------------)
|
||
|
|
||
(- Y --------)
|
||
| target *----->//
|
||
(------------)
|
||
-------)
|
||
|
|
||
(-----|
|
||
| src |
|
||
(-----|
|
||
-------)
|
||
```
|
||
|
||
X is a sink `GstGhostPad` without a target. The internal `GstProxyPad` Y has
|
||
the same direction as the src pad (peer).
|
||
|
||
1) link function is called
|
||
- Y direction is same as @src
|
||
- Y target is set to @src
|
||
- Y is activated in the same mode as X
|
||
- core makes link from @src to X
|
||
|
||
```
|
||
(- X --------)
|
||
| |
|
||
| target *----->//
|
||
>(------------)
|
||
(real pad link) / |
|
||
/ (- Y ------)
|
||
/ -----* target |
|
||
-------) / / (----------)
|
||
| / /
|
||
(-----|/ /
|
||
| src |<----
|
||
(-----|
|
||
-------)
|
||
```
|
||
|
||
## Linking a pad to a targetted ghostpad:
|
||
|
||
```
|
||
gst_pad_link (src, X)
|
||
|
||
(--------
|
||
(- X --------) |
|
||
| | |------)
|
||
| target *------------->| sink |
|
||
(------------) >|------)
|
||
| / (--------
|
||
| /
|
||
| /
|
||
-------) | / (real pad link)
|
||
| (- Y ------) /
|
||
(-----| | |/
|
||
| src | //<----* target |
|
||
(-----| (----------)
|
||
-------)
|
||
```
|
||
|
||
1) link function is called
|
||
- Y direction is same as @src
|
||
- Y target is set to @src
|
||
- Y is activated in the same mode as X
|
||
- core makes link from @src to X
|
||
|
||
```
|
||
(--------
|
||
(- X --------) |
|
||
| | |------)
|
||
| target *------------->| sink |
|
||
>(------------) >|------)
|
||
(real pad link) / | / (--------
|
||
/ | /
|
||
/ | /
|
||
-------) / | / (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) / |
|
||
/ |
|
||
/ |
|
||
-------) / |
|
||
| / (- Y ------)
|
||
(-----|/ | |
|
||
| src |<-------------* target |
|
||
(-----| (----------)
|
||
-------)
|
||
```
|
||
|
||
1) assert direction of @newtarget == X direction
|
||
2) X target is set to @newtarget
|
||
3) Y is linked to @newtarget
|
||
|
||
```
|
||
(--------
|
||
(- X --------) |
|
||
| | |------)
|
||
| target *------------->| sink |
|
||
>(------------) >|------)
|
||
(real pad link) / | / (--------
|
||
/ | /
|
||
/ | /
|
||
-------) / | / (real pad link)
|
||
| / (- Y ------) /
|
||
(-----|/ | |/
|
||
| src |<-------------* target |
|
||
(-----| (----------)
|
||
-------)
|
||
```
|
||
|
||
## Setting target on targetted linked ghostpad:
|
||
|
||
```
|
||
gst_ghost_pad_set_target (char *name, GstPad *newtarget)
|
||
|
||
(--------
|
||
(- X --------) |
|
||
| | |-------)
|
||
| target *------------->| sink1 |
|
||
>(------------) >|-------)
|
||
(real pad link) / | / (--------
|
||
/ | /
|
||
/ | /
|
||
-------) / | / (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 is linked to @newtarget
|
||
|
||
```
|
||
(--------
|
||
(- X --------) |
|
||
| | |-------)
|
||
| target *------------->| sink2 |
|
||
>(------------) >|-------)
|
||
(real pad link) / | / (--------
|
||
/ | /
|
||
/ | /
|
||
-------) / | / (real pad link)
|
||
| / (- Y ------) /
|
||
(-----|/ | |/
|
||
| src |<-------------* target |
|
||
(-----| (----------)
|
||
-------)
|
||
```
|
||
|
||
## Activation
|
||
|
||
Sometimes ghost pads should proxy activation functions. This thingie
|
||
attempts to explain how it should work in the different cases.
|
||
|
||
```
|
||
+---+ +----+ +----+ +----+
|
||
| A +-----+ B | | C |-------+ D |
|
||
+---+ +---=+ +=---+ +----+
|
||
+--=-----------------------------=-+
|
||
| +=---+ +----+ +----+ +---=+ |
|
||
| | a +---+ b ==== c +--+ d | |
|
||
| +----+ +----+ +----+ +----+ |
|
||
| |
|
||
+----------------------------------+
|
||
state change goes from right to left
|
||
<-----------------------------------------------------------
|
||
```
|
||
|
||
All of the labeled boxes are pads. The dashes (---) show pad links, and
|
||
the double-lines (===) are internal connections. The box around a, b, c,
|
||
and d is a bin. B and C are ghost pads, and a and d are proxy pads. The
|
||
arrow represents the direction of a state change algorithm. Not counting
|
||
the bin, there are three elements involved here — the parent of D, the
|
||
parent of A, and the parent of b and c.
|
||
|
||
Now, in the state change from READY to PAUSED, assuming the pipeline
|
||
does not have a live source, all of the pads will end up activated at
|
||
the end. There are 4 possible activation modes:
|
||
|
||
1) AD and ab in PUSH, cd and CD in PUSH
|
||
2) AD and ab in PUSH, cd and CD in PULL
|
||
3) AD and ab in PULL, cd and CD in PUSH
|
||
4) AD and ab in PULL, cd and CD in PULL
|
||
|
||
When activating (1), the state change algorithm will first visit the
|
||
parent of D and activate D in push mode. Then it visits the bin. The bin
|
||
will first change the state of its child before activating its pads.
|
||
That means c will be activated in push mode. \[\*\] At this point, d and
|
||
C should also be active in push mode, because it could be that
|
||
activating c in push mode starts a thread, which starts pushing to pads
|
||
which aren’t ready yet. Then b is activated in push mode. Then, the bin
|
||
activates C in push mode, which should already be in push mode, so
|
||
nothing is done. It then activates B in push mode, which activates b in
|
||
push mode, but it’s already there, then activates a in push mode as
|
||
well. The order of activating a and b does not matter in this case.
|
||
Then, finally, the state change algorithm moves to the parent of A,
|
||
activates A in push mode, and dataflow begins.
|
||
|
||
\[\*\] Not yet implemented.
|
||
|
||
Activation mode (2) is implausible, so we can ignore it for now. That
|
||
leaves us with the rest.
|
||
|
||
(3) is the same as (1) until you get to activating b. Activating b will
|
||
proxy directly to activating a, which will activate B and A as well.
|
||
Then when the state change algorithm gets to B and A it sees that they
|
||
are already active, so it ignores them.
|
||
|
||
Similarly in (4), activating D will cause the activation of all of the
|
||
rest of the pads, in this order: C d c b a B A. Then when the state
|
||
change gets to the other elements they are already active, and in fact
|
||
data flow is already occurring.
|
||
|
||
So, from these scenarios, we can distill how ghost pad activation
|
||
functions should work:
|
||
|
||
Ghost source pads (e.g. C): push: called by: element state change
|
||
handler behavior: just return TRUE pull: called by: peer’s activatepull
|
||
behavior: change the internal pad, which proxies to its peer e.g. C
|
||
changes d which changes c.
|
||
|
||
Internal sink pads (e.g. d): push: called by: nobody (doesn’t seem
|
||
possible) behavior: n/a pull: called by: ghost pad behavior: proxy to
|
||
peer first
|
||
|
||
Internal src pads (e.g. a): push: called by: ghost pad behavior:
|
||
activate peer in push mode pull: called by: peer’s activatepull
|
||
behavior: proxy to ghost pad, which proxies to its peer (e.g. a calls B
|
||
which calls A)
|
||
|
||
Ghost sink pads (e.g. B): push: called by: element state change handler
|
||
behavior: change the internal pad, which proxies to peer (e.g. B changes
|
||
a which changes b) pull: called by: internal pad behavior: proxy to peer
|
||
|
||
It doesn’t really make sense to have activation functions on proxy pads
|
||
that aren’t part of a ghost pad arrangement.
|