| 1 |
Linking Scripts |
| 2 |
=============== |
| 3 |
|
| 4 |
These scripts contain all the logic for creating links between nodes. |
| 5 |
This involves, to a large extent, deciding which links to create. |
| 6 |
|
| 7 |
Hooks |
| 8 |
----- |
| 9 |
|
| 10 |
The hooks in this section are organized in 3 sub-categories. The first category |
| 11 |
includes hooks that are triggered by changes in the graph. Some of them are tasked |
| 12 |
to schedule a "rescan-for-linking" event, which is the lowest priority linking event and |
| 13 |
its purpose is to scan through all the linkable session items and link them |
| 14 |
to a particular target. The "rescan-for-linking" event is always scheduled to run |
| 15 |
once for all the graph changes in a cycle. This is achieved by flagging the event |
| 16 |
as already scheduled in the module-standard-event-source; this flag is then cleared |
| 17 |
by a hook that runs on this event. |
| 18 |
|
| 19 |
Selecting a target for each linkable and linking to it is deferred to another |
| 20 |
set of hooks by pushing a "select-target" event for each linkable. This event |
| 21 |
is the highest priority event and therefore no other changes in the graph are |
| 22 |
processed while targets are being selected. |
| 23 |
|
| 24 |
.. list-table:: Hooks triggered by changes in the graph |
| 25 |
:header-rows: 1 |
| 26 |
|
| 27 |
* - Hook name |
| 28 |
- File |
| 29 |
- Triggered by |
| 30 |
- Action |
| 31 |
|
| 32 |
* - linking/rescan-trigger |
| 33 |
- rescan.lua |
| 34 |
- linkable SI added|removed or metadata-changed |
| 35 |
- schedules rescan-for-linking event |
| 36 |
|
| 37 |
* - linking/linkable-removed |
| 38 |
- rescan.lua |
| 39 |
- linkable SI removed |
| 40 |
- destroys links related to the removed linkable |
| 41 |
|
| 42 |
* - linking/follow |
| 43 |
- move-follow.lua |
| 44 |
- metadata-changed |
| 45 |
- schedules rescan-for-linking when the configured default sources/sinks are changed by the user |
| 46 |
|
| 47 |
* - linking/move |
| 48 |
- move-follow.lua |
| 49 |
- metadata-changed |
| 50 |
- schedules rescan-for-linking when node target metadata properties are changed |
| 51 |
|
| 52 |
* - linking/rescan-media-role-links |
| 53 |
- rescan-media-role-links.lua |
| 54 |
- link SI added, removed or metadata-changed |
| 55 |
- activates or deactivates role-based links based on role priorities and actions |
| 56 |
|
| 57 |
.. list-table:: rescan-for-linking hooks, in order of execution |
| 58 |
:header-rows: 1 |
| 59 |
:width: 100% |
| 60 |
:widths: 20 20 60 |
| 61 |
|
| 62 |
* - Hook name |
| 63 |
- File |
| 64 |
- Description |
| 65 |
|
| 66 |
* - m-standard-event-source/rescan-done |
| 67 |
- module-standard-event-source.c |
| 68 |
- clears the rescan_scheduled flag |
| 69 |
|
| 70 |
* - linking/rescan |
| 71 |
- rescan.lua |
| 72 |
- schedules select-target for each linkable session item |
| 73 |
|
| 74 |
.. list-table:: select-target hooks, in order of execution |
| 75 |
:header-rows: 1 |
| 76 |
:width: 100% |
| 77 |
:widths: 20 20 60 |
| 78 |
|
| 79 |
* - Hook name |
| 80 |
- File |
| 81 |
- Description |
| 82 |
|
| 83 |
* - linking/find-defined-target |
| 84 |
- find-defined-target.lua |
| 85 |
- Select the target that has been defined explicitly by the 'target.object' property or metadata |
| 86 |
|
| 87 |
* - linking/find-filter-target |
| 88 |
- find-filter-target.lua |
| 89 |
- Select the target of a filter node, if the subject is a filter node |
| 90 |
|
| 91 |
* - linking/find-media-role-target |
| 92 |
- find-media-role-target.lua |
| 93 |
- Select the target based on the stream's media.role and the target's device.intended-roles |
| 94 |
|
| 95 |
* - linking/find-default-target |
| 96 |
- find-default-target.lua |
| 97 |
- Select the default source/sink as target |
| 98 |
|
| 99 |
* - linking/find-best-target |
| 100 |
- find-best-target.lua |
| 101 |
- Select target based on priority.session |
| 102 |
|
| 103 |
* - linking/get-filter-from-target |
| 104 |
- get-filter-from-target.lua |
| 105 |
- Translate the found target to a filter target that should be linked instead |
| 106 |
|
| 107 |
* - linking/prepare-link |
| 108 |
- prepare-link.lua |
| 109 |
- Break existing link if needed, check if the target is available for linking; send error to the client if needed |
| 110 |
|
| 111 |
* - linking/link-target |
| 112 |
- link-target.lua |
| 113 |
- Create si-standard-link session item to create links between the subject linkable and the selected target |