4 GhostPads are used to build complex compound elements out of
5 existing elements. They are used to expose internal element pads
6 on the complex element.
8 Some design requirements
10 - Must look like a real GstPad on both sides.
11 - target of Ghostpad must be changeable
12 - target can be initially NULL
14 * a GhostPad is implemented using a private GstProxyPad class:
28 (------------------) -\
30 |------------------| |
31 | GstPad *target | > GstProxyPad
32 |------------------| |
33 | GstPad *internal | |
34 |------------------| -/
38 A GstGhostPad (X) is _always_ created together with a GstProxyPad (Y).
39 The internal pad pointers are set to point to the eachother. The
40 GstProxyPad pairs have opposite directions, the GstGhostPad has the same
41 direction as the (future) ghosted pad (target).
58 Which we will abbreviate to:
62 | target *--------->//
69 The GstGhostPad (X) is also set as the parent of the GstProxyPad (Y).
71 The target is a pointer to the internal pads peer. It is an optimisation to
72 quickly get to the peer of a ghostpad without having to dereference the
75 Some use case follow with a description of how the datastructure
79 * Creating a ghostpad with a target:
81 gst_ghost_pad_new (char *name, GstPad *target)
83 1) create new GstGhostPad X + GstProxyPad Y
84 2) X name set to @name
85 3) X direction is the same as the target, Y is opposite.
86 4) the target of X is set to @target
87 5) Y is linked to @target
88 6) link/unlink and activate functions are set up
95 | target *------------------> | sink |
96 (------------) -------> |------)
98 (- Y --------) / (pad link)
102 - Automatically takes same direction as target.
103 - target is filled in automatically.
106 * Creating a ghostpad without a target
108 gst_ghost_pad_new_no_target (char *name, GstPadDirection dir)
110 1) create new GstGhostPad X + GstProxyPad Y
111 2) X name set to @name
112 3) X direction is @dir
113 5) link/unlink and activate functions are set up
118 | target *--------->//
125 - allows for setting the target later
128 * Setting target on an untargetted unlinked ghostpad
130 gst_ghost_pad_set_target (char *name, GstPad *newtarget)
134 | target *--------->//
141 1) assert direction of newtarget == X direction
142 2) target is set to newtarget
143 3) internal pad Y is linked to newtarget
148 | target *------------------> | sink |
149 (------------) -------> |------)
151 (- Y --------) / (pad link)
155 * Setting target on a targetted unlinked ghostpad
157 gst_ghost_pad_set_target (char *name, GstPad *newtarget)
162 | target *------------------> | sink1 |
163 (------------) -------> |-------)
165 (- Y --------) / (pad link)
169 1) assert direction of newtarget (sink2) == X direction
170 2) unlink internal pad Y and oldtarget
171 3) target is set to newtarget (sink2)
172 4) internal pad Y is linked to newtarget
177 | target *------------------> | sink2 |
178 (------------) -------> |-------)
180 (- Y --------) / (pad link)
184 * Linking a pad to an untargetted ghostpad:
186 gst_pad_link (src, X)
190 | target *--------->//
203 X is a sink GstGhostPad without a target. The internal GstProxyPad Y has
204 the same direction as the src pad (peer).
206 1) link function is called
207 a) Y direction is same as @src
208 b) Y target is set to @src
209 c) Y is activated in the same mode as X
210 d) core makes link from @src to X
220 -------) / / (----------)
228 * Linking a pad to a targetted ghostpad:
230 gst_pad_link (src, X)
235 | target *------------->| sink |
236 (------------) >|------)
240 -------) | / (real pad link)
243 | src | //<----* target |
248 1) link function is called
249 a) Y direction is same as @src
250 b) Y target is set to @src
251 c) Y is activated in the same mode as X
252 d) core makes link from @src to X
257 | target *------------->| sink |
258 >(------------) >|------)
259 (real pad link) / | / (--------
262 -------) / | / (real pad link)
265 | src |<-------------* target |
270 * Setting target on untargetted linked ghostpad:
272 gst_ghost_pad_set_target (char *name, GstPad *newtarget)
285 | src |<-------------* target |
289 1) assert direction of @newtarget == X direction
290 2) X target is set to @newtarget
291 3) Y is linked to @newtarget
296 | target *------------->| sink |
297 >(------------) >|------)
298 (real pad link) / | / (--------
301 -------) / | / (real pad link)
304 | src |<-------------* target |
308 * Setting target on targetted linked ghostpad:
310 gst_ghost_pad_set_target (char *name, GstPad *newtarget)
315 | target *------------->| sink1 |
316 >(------------) >|-------)
317 (real pad link) / | / (--------
320 -------) / | / (real pad link)
323 | src |<-------------* target |
327 1) assert direction of @newtarget == X direction
328 2) Y and X target are unlinked
329 2) X target is set to @newtarget
330 3) Y is linked to @newtarget
335 | target *------------->| sink2 |
336 >(------------) >|-------)
337 (real pad link) / | / (--------
340 -------) / | / (real pad link)
343 | src |<-------------* target |
351 Sometimes ghost pads should proxy activation functions. This thingie
352 attempts to explain how it should work in the different cases.
354 +---+ +----+ +----+ +----+
355 | A +-----+ B | | C |-------+ D |
356 +---+ +---=+ +=---+ +----+
357 +--=-----------------------------=-+
358 | +=---+ +----+ +----+ +---=+ |
359 | | a +---+ b ==== c +--+ d | |
360 | +----+ +----+ +----+ +----+ |
362 +----------------------------------+
363 state change goes from right to left
364 <-----------------------------------------------------------
366 All of the labeled boxes are pads. The dashes (---) show pad links, and
367 the double-lines (===) are internal connections. The box around a, b, c,
368 and d is a bin. B and C are ghost pads, and a and d are proxy pads. The
369 arrow represents the direction of a state change algorithm. Not counting
370 the bin, there are three elements involved here -- the parent of D, the
371 parent of A, and the parent of b and c.
373 Now, in the state change from READY to PAUSED, assuming the pipeline
374 does not have a live source, all of the pads will end up activated at
375 the end. There are 4 possible activation modes:
377 1) AD and ab in PUSH, cd and CD in PUSH
378 2) AD and ab in PUSH, cd and CD in PULL
379 3) AD and ab in PULL, cd and CD in PUSH
380 4) AD and ab in PULL, cd and CD in PULL
382 When activating (1), the state change algorithm will first visit the
383 parent of D and activate D in push mode. Then it visits the bin. The bin
384 will first change the state of its child before activating its pads.
385 That means c will be activated in push mode. [*] At this point, d and C
386 should also be active in push mode, because it could be that activating
387 c in push mode starts a thread, which starts pushing to pads which
388 aren't ready yet. Then b is activated in push mode. Then, the bin
389 activates C in push mode, which should already be in push mode, so
390 nothing is done. It then activates B in push mode, which activates b in
391 push mode, but it's already there, then activates a in push mode as
392 well. The order of activating a and b does not matter in this case.
393 Then, finally, the state change algorithm moves to the parent of A,
394 activates A in push mode, and dataflow begins.
396 [*] Not yet implemented.
398 Activation mode (2) is implausible, so we can ignore it for now. That
399 leaves us with the rest.
401 (3) is the same as (1) until you get to activating b. Activating b will
402 proxy directly to activating a, which will activate B and A as well.
403 Then when the state change algorithm gets to B and A it sees that they
404 are already active, so it ignores them.
406 Similarly in (4), activating D will cause the activation of all of the
407 rest of the pads, in this order: C d c b a B A. Then when the state
408 change gets to the other elements they are already active, and in fact
409 data flow is already occurring.
411 So, from these scenarios, we can distill how ghost pad activation
412 functions should work:
414 Ghost source pads (e.g. C):
416 called by: element state change handler
417 behavior: just return TRUE
419 called by: peer's activatepull
420 behavior: change the internal pad, which proxies to its peer e.g. C
421 changes d which changes c.
423 Internal sink pads (e.g. d):
425 called by: nobody (doesn't seem possible)
429 behavior: proxy to peer first
431 Internal src pads (e.g. a):
434 behavior: activate peer in push mode
436 called by: peer's activatepull
437 behavior: proxy to ghost pad, which proxies to its peer (e.g. a
438 calls B which calls A)
440 Ghost sink pads (e.g. B):
442 called by: element state change handler
443 behavior: change the internal pad, which proxies to peer (e.g. B
444 changes a which changes b)
446 called by: internal pad
447 behavior: proxy to peer
450 It doesn't really make sense to have activation functions on proxy pads
451 that aren't part of a ghost pad arrangement.