Invocation: clarify further requirements for the Level-2 builder

...especially what is necessary to represent at this level and what information
is implicit; notably there will be an implicit default wiring, but we allow
for case-by-case deviations
This commit is contained in:
Fischlurch 2024-07-05 23:36:41 +02:00
parent 1f7ddbe5ec
commit 7c554caf08
3 changed files with 149 additions and 61 deletions

View file

@ -3,7 +3,7 @@
Copyright (C) Lumiera.org
2009, Hermann Vosseler <Ichthyostega@web.de>
2024 , Hermann Vosseler <Ichthyostega@web.de>
2024, Hermann Vosseler <Ichthyostega@web.de>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
@ -22,15 +22,48 @@
*/
/** @file node-builder.hpp
** Helper for defining the desired wiring and operation mode for a render node.
** During the Builder run, the render nodes network is wired up starting from the
** source (generating) nodes up to the exit nodes. As the wiring is implemented through
** a const engine::Connectivity, when a new node gets fabricated, all of the connections
** to its predecessors need to be completely settled; similarly, any information pertaining
** the desired operation mode of this node need to be available. Thus we use this temporary
** information record to assemble all these pieces of information.
** Specialised shorthand notation for building the Render Node network.
** During the Builder run, the render nodes network will be constructed by gradually
** refining the connectivity structure derived from interpreting the »high-level model«
** from the current Session. At some point, it is essentially clear what data streams
** must be produced and what media processing functionality from external libraries
** will be utilised to achieve this goal. This is when the fluent builder notation
** defined in this header comes into play, allowing to package the fine grained and
** in part quite confusing details of parameter wiring and invocation preparation into
** some goal oriented building blocks, that can be combined and directed with greater
** clarity by the control structure to govern the build process.
**
** @deprecated WIP-WIP-WIP 2024 Node-Invocation is reworked from ground up -- not clear yet what happens with the builder
** # Levels of connectivity building
**
** The actual node connectivity is established by a process of gradual refinement,
** operating over several levels of abstraction. Each of these levels uses its associated
** builder and descriptor records to collect information, which is then emitted by a
** _terminal invocation_ to produce the result; the higher levels thereby rely on the
** lower levels to fill in and elaborate the details.
** - Level-1 is the preparation of an actual frame processing operation; the Level-1-builder
** is in fact the implementation class sitting behind a Render Node's _Port._ It is called
** a _Turnout_ and contains a preconfigured »blue print« for the data structure layout
** used for the invocation; its purpose is to generate the actual data structure on the
** stack, holding all the necessary buffers and parameters ready for invoking the external
** library functions. Since the actual data processing is achieved by a _pull processing,_
** originating at the top level exit nodes and propagating down towards the data sources,
** all the data feeds at all levels gradually link together, forming a _TurnoutSystem._
** - Level-2 generates the actual network of Render Nodes, which in turn will have the
** Turnout instances for Level-1 embedded into its internal ports. Conceptually, a
** _Port_ is where data production can be requested, and the processing will then
** retrieve its prerequisite data from the ports of the _Leads,_ which are the
** prerequisite nodes situated one level below or one step closer to the source.
** - Level-3 establishes the processing steps and data retrieval links between them;
** at this level, thus the outline of possible processing pathways is established.
** After spelling out the desired connectivity at a high level, the so called »Level-3 build
** walk« is triggered by invoking the [terminal builder operation](\ref ProcBuilder::build()
** on the [processing builder](\ref ProcBuilder) corresponding to the topmost node. This
** build walk will traverse the connectivity graph depth-first, and then start invoking the
** Level-2 builder operations bottom-up to generate and wire up the corresponding Render Nodes.
**
** @todo WIP-WIP-WIP 7/2024 Node-Invocation is reworked from ground up -- some parts can not be
** spelled out completely yet, since we have to build this tightly interlocked system of
** code moving bottom up, and then filling in further details later working top-down.
**
** @see steam::engine::NodeFactory
** @see nodewiring.hpp
@ -101,18 +134,12 @@ namespace engine {
public:
NodeBuilder
inSlots (uint s)
addLead (ProcNode const& lead)
{
UNIMPLEMENTED ("define number of predecessor-source slots");
UNIMPLEMENTED ("append the given predecessor node to the sequence of leads");
return move(*this);
}
NodeBuilder
outSlots (uint r)
{
UNIMPLEMENTED ("define number of result slots");
return move(*this);
}
void //////////////////////////////////////////////////////////OOO return type
preparePort ()
@ -131,6 +158,16 @@ namespace engine {
}
};
/**
* Entrance point for building actual Render Node Connectivity (Level-2)
*/
inline auto
prepareNode()
{
UNIMPLEMENTED("start building a new Render Node at Level-2");
return NodeBuilder{};
}
class ProcBuilder
: util::MoveOnly
@ -176,14 +213,14 @@ namespace engine {
};
/**
* Entrance point for building node Connectivity
* Entrance point for defining data flows and processing steps.
*/
template<class ONT>
auto
buildPatternFor()
inline auto
retrieve(void* streamType)
{
UNIMPLEMENTED("instantiate Domain Ontology Facade and outfit the NodeWiringBuilder");
UNIMPLEMENTED("start a connectivity definition at Level-3");
return NodeBuilder{};
}

View file

@ -28,7 +28,7 @@
#include "lib/test/run.hpp"
#include "steam/engine/proc-node.hpp"
#include "steam/engine/node-builder.hpp"
#include "steam/engine/test-rand-ontology.hpp"
#include "steam/engine/test-rand-ontology.hpp" ///////////TODO
//#include "lib/util.hpp"
@ -69,7 +69,7 @@ namespace test {
void
build_connected_nodes()
{
auto con = buildPatternFor<TestRandOntology>()
auto con = prepareNode()
.build();
UNIMPLEMENTED ("build render nodes linked into a connectivity network");
}

View file

@ -1126,9 +1126,7 @@
<node CREATED="1504203643550" ID="ID_764647453" MODIFIED="1538263469663" TEXT="via InteractionDirector ansprechen"/>
<node CREATED="1504203694423" ID="ID_812129962" MODIFIED="1538263469663">
<richcontent TYPE="NODE"><html>
<head>
</head>
<head/>
<body>
<p>
Fehlerlog-Anzeige <i>vorl&#228;ufig irgendwo....</i>
@ -1978,9 +1976,7 @@
</node>
<node COLOR="#435e98" CREATED="1535554640586" FOLDED="true" ID="ID_1376241476" MODIFIED="1561827464613" TEXT="essentiell: passiert im Parent-Widget">
<richcontent TYPE="NOTE"><html>
<head>
</head>
<head/>
<body>
<p>...wesentliches Struktur-Element:</p>
<p>der Parent-Container ist f&#252;r das expand/collapse zust&#228;ndig</p>
@ -22816,9 +22812,7 @@
<node CREATED="1584889606544" ID="ID_298422140" MODIFIED="1584889621323" TEXT="und daher dann doch besser in einem eigenen Header"/>
<node CREATED="1584889621957" ID="ID_814318826" MODIFIED="1584889641912" TEXT="und ohne die Abh&#xe4;ngigkeit auf Gtk::Widget">
<richcontent TYPE="NOTE"><html>
<head>
</head>
<head/>
<body>
<p>
erleichtert das Testen
@ -23337,9 +23331,7 @@
</body>
</html></richcontent>
<richcontent TYPE="NOTE"><html>
<head>
</head>
<head/>
<body>
<p>
...und das ist wohl entstanden, weil ich urspr&#252;nglich einen generischen Visitor im Blick hatte; es hat sich aber dann gezeigt, da&#223; eine solche universelle &quot;Quer-Beweglichkeit&quot; weder notwendig noch w&#252;nschenswert ist
@ -23792,9 +23784,7 @@
<node CREATED="1480300645837" ID="ID_337010957" MODIFIED="1557498707225" TEXT="Interface"/>
<node CREATED="1480300649437" ID="ID_704277125" MODIFIED="1557498707225">
<richcontent TYPE="NODE"><html>
<head>
</head>
<head/>
<body>
<p>
interagiert mit den <b>Presentern</b>
@ -24205,9 +24195,7 @@
<icon BUILTIN="full-3"/>
<node CREATED="1480778622039" ID="ID_1007915114" MODIFIED="1518487921082">
<richcontent TYPE="NODE"><html>
<head>
</head>
<head/>
<body>
<p>
Betriebsart <i>&quot;partiell initialisiert&quot;</i>
@ -50048,9 +50036,7 @@
<node CREATED="1448683636672" ID="ID_1485949406" MODIFIED="1518487921087" TEXT="verhindert Wildwuchs"/>
<node CREATED="1448683475853" ID="ID_24599710" MODIFIED="1518487921087">
<richcontent TYPE="NODE"><html>
<head>
</head>
<head/>
<body>
<p>
Command und Verhaltensmuster
@ -51014,9 +51000,7 @@
<node CREATED="1485548856639" ID="ID_1677281474" MODIFIED="1518487921090" TEXT="spezifische Aktionen">
<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1485548894522" ID="ID_826011549" MODIFIED="1576282358002" TEXT="Problem: globale Aktionen">
<richcontent TYPE="NOTE"><html>
<head>
</head>
<head/>
<body>
<p>
Beispiel: Aktionen, die im globalen Men&#252; stehen.
@ -51784,9 +51768,7 @@
<node CREATED="1488937424996" ID="ID_1712367280" MODIFIED="1518487921092" TEXT="vorerst eigenes Front-End verwenden"/>
<node CREATED="1488937449896" ID="ID_1352702920" MODIFIED="1576282357995" TEXT="Idee klar">
<richcontent TYPE="NOTE"><html>
<head>
</head>
<head/>
<body>
<ul>
<li>
@ -52484,9 +52466,7 @@
<node CREATED="1492293499701" ID="ID_1165417078" MODIFIED="1492293504344" TEXT="voller Zyklus">
<node CREATED="1492293540943" ID="ID_432796112" MODIFIED="1492293561513">
<richcontent TYPE="NODE"><html>
<head>
</head>
<head/>
<body>
<p>
Instanz <i>&#246;ffnen</i>
@ -81902,9 +81882,58 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
<node CREATED="1719971327507" ID="ID_1941686244" MODIFIED="1720050731701" TEXT="Level-2">
<node CREATED="1719970302300" ID="ID_87633601" MODIFIED="1719970332019" TEXT="Prinzip: 1:1 als Default + explizite Abweichung">
<icon BUILTIN="yes"/>
<node CREATED="1720230200941" ID="ID_341794506" MODIFIED="1720230385165" TEXT="es gibt also eine 1:1 Verdrahtung als &#xbb;fall-back&#xab;">
<richcontent TYPE="NOTE"><html>
<head/>
<body>
<p>
...diese Verbindet alle definierten Elemente in der einfachst m&#246;glichen / am wenigsten &#252;berraschenden Weise
</p>
<ul>
<li>
es wird &#252;berall ein default-Buffertyp eingef&#252;llt
</li>
<li>
die Reihenfolge der Eingangs-Buffer entspricht der Reihenfolge der Leads
</li>
<li>
es wird alles stets auf die durchgehend gleiche Port-# gelegt (D.h. wenn wir grade Port-2 bauen, dann werden auch alle Vorg&#228;nger auf Port-2 gepullt)
</li>
</ul>
</body>
</html></richcontent>
</node>
<node CREATED="1720230391209" ID="ID_1183079593" MODIFIED="1720230406455" TEXT="man kann aber Zusatz-Regeln und Qualifikatoren angeben"/>
<node CREATED="1720230411535" ID="ID_346803250" MODIFIED="1720230565043">
<richcontent TYPE="NODE"><html>
<head/>
<body>
<p>
<i>ausgef&#252;hrt</i>&#160;wird die Verdrahtung erst in der Terminal-Operation
</p>
</body>
</html></richcontent>
<arrowlink COLOR="#5f6184" DESTINATION="ID_1204792955" ENDARROW="Default" ENDINCLINATION="486;31;" ID="Arrow_ID_197971585" STARTARROW="None" STARTINCLINATION="361;16;"/>
</node>
</node>
<node CREATED="1720143945014" ID="ID_1230383106" MODIFIED="1720143962663" TEXT="prepareNode()">
<node CREATED="1720143965823" ID="ID_1699834856" MODIFIED="1720144003274" TEXT="addLead(ProcNode&amp;)"/>
<node BACKGROUND_COLOR="#f0d5c5" COLOR="#990033" CREATED="1720232528215" ID="ID_1086974624" MODIFIED="1720232545701" TEXT="Brauchen wir eine Asset-ID auf diesem Level?">
<icon BUILTIN="help"/>
<node CREATED="1720232578816" ID="ID_707264481" MODIFIED="1720232594580">
<richcontent TYPE="NODE"><html>
<head/>
<body>
<p>
<i>mutma&#223;lich</i>&#160;<b>Nein</b>
</p>
</body>
</html></richcontent>
</node>
<node CREATED="1720232632552" ID="ID_1530888543" MODIFIED="1720232650114" TEXT="mit dem Proc-Asset steigen wir einen Level h&#xf6;her in einen Typ-Kontext ein"/>
<node CREATED="1720232650869" ID="ID_1972919364" MODIFIED="1720232679870" TEXT="dagegen auf diesem Level-2 hier werden nur noch explizite Einzeltypen konfiguriert"/>
<node CREATED="1720232681738" ID="ID_428670212" MODIFIED="1720232705387" TEXT="und darunter werden nur noch Pointer verarbeitet"/>
</node>
<node CREATED="1720146287602" ID="ID_1218472857" MODIFIED="1720146293047" TEXT="preparePort()">
<node CREATED="1720146294771" ID="ID_1809522763" MODIFIED="1720146303963" TEXT="nested Port builder"/>
<node CREATED="1719971113760" ID="ID_1114865524" MODIFIED="1719971122094" TEXT="Slot-Anzahl">
@ -81917,7 +81946,7 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
<node CREATED="1719970948270" ID="ID_1769935423" MODIFIED="1719970970119" TEXT="createInBuffers..."/>
<node CREATED="1719970957989" ID="ID_1864258437" MODIFIED="1719970999711" TEXT="createOutBuffers...."/>
</node>
<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1720146340213" ID="ID_1871545026" MODIFIED="1720146347108" TEXT="TODO: API f&#xfc;r Mapping">
<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1720146340213" ID="ID_1871545026" MODIFIED="1720230570516" TEXT="TODO: API f&#xfc;r Mapping">
<icon BUILTIN="flag-yellow"/>
<node CREATED="1720146352115" ID="ID_989391502" MODIFIED="1720146395401" TEXT="ausgangsseitig: einfach">
<richcontent TYPE="NOTE"><html>
@ -81936,7 +81965,9 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
</node>
<node CREATED="1720146396461" ID="ID_1630413077" MODIFIED="1720146404887" TEXT="Komplexit&#xe4;t steckt auf der Eingangsseite">
<node CREATED="1720146410589" ID="ID_105499454" MODIFIED="1720146420822" TEXT="Slots sind geordnet nach Pull-Reihenfolge"/>
<node CREATED="1720146571598" ID="ID_1359527790" MODIFIED="1720146598542" TEXT="zu jedem Slot wird auch die Info (Leed-#, Port-#) aufgezeichnet"/>
<node CREATED="1720146571598" ID="ID_1359527790" MODIFIED="1720146598542" TEXT="zu jedem Slot wird auch die Info (Leed-#, Port-#) aufgezeichnet">
<node CREATED="1720230093077" ID="ID_555331001" LINK="#ID_402221763" MODIFIED="1720230144654" TEXT="die FeedManifold braucht sp&#xe4;ter genau diese Info"/>
</node>
<node CREATED="1720146427025" ID="ID_1892940839" LINK="#ID_1041217509" MODIFIED="1720146484198" TEXT="Problem: diese Info soll direkt auf diesem Level komplett materialisiert werden"/>
<node CREATED="1720146648800" ID="ID_245906119" MODIFIED="1720146825265" TEXT="der Level dar&#xfc;ber sieht noch den StreamType">
<arrowlink COLOR="#c6dffd" DESTINATION="ID_1540907767" ENDARROW="Default" ENDINCLINATION="79;-31;" ID="Arrow_ID_851396319" STARTARROW="None" STARTINCLINATION="917;59;"/>
@ -82036,7 +82067,9 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
</p>
</body>
</html></richcontent>
<node CREATED="1720220989004" ID="ID_1204792955" MODIFIED="1720220996471" TEXT="linkt den neu definierten Port"/>
<node CREATED="1720220989004" ID="ID_1204792955" MODIFIED="1720220996471" TEXT="linkt den neu definierten Port">
<linktarget COLOR="#5f6184" DESTINATION="ID_1204792955" ENDARROW="Default" ENDINCLINATION="486;31;" ID="Arrow_ID_197971585" SOURCE="ID_346803250" STARTARROW="None" STARTINCLINATION="361;16;"/>
</node>
<node CREATED="1720220997038" ID="ID_1481586771" MODIFIED="1720221137187" TEXT="kehrt dann zum aufrufenden NodeBuilder zur&#xfc;ck">
<richcontent TYPE="NOTE"><html>
<head/>
@ -82058,15 +82091,17 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
</node>
<node CREATED="1719971317790" ID="ID_1077643019" MODIFIED="1720050731701" TEXT="Level-3">
<node CREATED="1719276025136" ID="ID_607906936" MODIFIED="1720141533940" TEXT="retrieve(StreamType)">
<node CREATED="1720141555165" ID="ID_719195906" MODIFIED="1720141895290" TEXT="(Port/Meta-Builder)">
<node CREATED="1720141555165" ID="ID_719195906" MODIFIED="1720226387459" TEXT="(Link/Meta-Builder)">
<linktarget COLOR="#928896" DESTINATION="ID_719195906" ENDARROW="Default" ENDINCLINATION="570;0;" ID="Arrow_ID_234747839" SOURCE="ID_805401685" STARTARROW="None" STARTINCLINATION="326;-28;"/>
<font NAME="SansSerif" SIZE="9"/>
</node>
<node CREATED="1720141562371" ID="ID_1619759685" MODIFIED="1720141573926" TEXT="from(ProcAsset)">
<node CREATED="1720141580754" ID="ID_1907959573" MODIFIED="1720141595988" TEXT="erzeugt Level-3-Builder"/>
<node CREATED="1720141580754" ID="ID_1907959573" MODIFIED="1720141595988" TEXT="erzeugt Level-3-Builder">
<arrowlink COLOR="#595f62" DESTINATION="ID_1431673545" ENDARROW="Default" ENDINCLINATION="114;-20;" ID="Arrow_ID_1235845998" STARTARROW="None" STARTINCLINATION="-99;12;"/>
</node>
<node CREATED="1720141660968" ID="ID_465932510" MODIFIED="1720141680498" TEXT="requiredSources() &#x27fc; Iteration Stream-Types">
<node CREATED="1720141682604" ID="ID_537478684" MODIFIED="1720141699286" TEXT="erlaubt rekursiven Abstieg"/>
<node CREATED="1720141700752" ID="ID_805401685" MODIFIED="1720141902187" TEXT="liefert wieder den Port/Meta-Builder">
<node CREATED="1720141700752" ID="ID_805401685" MODIFIED="1720226394434" TEXT="liefert wieder den Link/Meta-Builder">
<arrowlink COLOR="#928896" DESTINATION="ID_719195906" ENDARROW="Default" ENDINCLINATION="570;0;" ID="Arrow_ID_234747839" STARTARROW="None" STARTINCLINATION="326;-28;"/>
</node>
</node>
@ -82078,7 +82113,9 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
</node>
<node CREATED="1720179596269" ID="ID_849206696" MODIFIED="1720179598384" TEXT="Namen">
<node CREATED="1720179600628" ID="ID_108747409" MODIFIED="1720179623627" TEXT="LinkBuilder"/>
<node CREATED="1720179605723" ID="ID_1431673545" MODIFIED="1720179616718" TEXT="ProcBuilder"/>
<node CREATED="1720179605723" ID="ID_1431673545" MODIFIED="1720226292169" TEXT="ProcBuilder">
<linktarget COLOR="#595f62" DESTINATION="ID_1431673545" ENDARROW="Default" ENDINCLINATION="114;-20;" ID="Arrow_ID_1235845998" SOURCE="ID_1907959573" STARTARROW="None" STARTINCLINATION="-99;12;"/>
</node>
</node>
<node BACKGROUND_COLOR="#f0d5c5" COLOR="#990033" CREATED="1720142049315" ID="ID_1840404622" MODIFIED="1720142067263" TEXT="zu kl&#xe4;ren: wie wird gebaut?">
<icon BUILTIN="help"/>
@ -82204,6 +82241,20 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
<node CREATED="1720044986999" ID="ID_1458288447" MODIFIED="1720045032781" TEXT="welches dann die Processing-Function aufruft und die Daten durchreicht"/>
</node>
</node>
<node CREATED="1720232206395" ID="ID_52029141" MODIFIED="1720232465557" TEXT="Eingrenzung: was ist &#xbb;ein&#xab; Proc-Asset?">
<icon BUILTIN="yes"/>
<node CREATED="1720232239918" ID="ID_1308445825" MODIFIED="1720232282403" TEXT="Wunsch aus Sicht des Users: alle Operatoren die &#x201e;das Geleiche machen&#x201c;"/>
<node CREATED="1720232283819" ID="ID_610482773" MODIFIED="1720232294650" TEXT="ist aber praktisch nicht durchf&#xfc;hrbar">
<node CREATED="1720232296565" ID="ID_1742774748" MODIFIED="1720232305855" TEXT="denn es gibt keine universelle Domain-Ontologie"/>
<node CREATED="1720232307020" ID="ID_1382136842" MODIFIED="1720232320427" TEXT="sondern nur partielle &#xc4;hnlichkeiten zwischen Libraries"/>
<node CREATED="1720232321282" ID="ID_1818898193" MODIFIED="1720232337868" TEXT="und au&#xdf;erdem verschiedene Arten von Medien, die wenig gemein haben"/>
</node>
<node CREATED="1720232348479" ID="ID_234456027" MODIFIED="1720232362888" TEXT="trotzdem kann man eine gewisse Aggregation anstreben"/>
<node CREATED="1720232363596" ID="ID_508369900" MODIFIED="1720232380958" TEXT="also: unter einem Proc-Asset wird eine Familie von Funktionen zusammengefa&#xdf;t">
<node CREATED="1720232411174" ID="ID_932971685" MODIFIED="1720232418617" TEXT="und diese Zusammenfassung ist optional"/>
<node CREATED="1720232419349" ID="ID_767823563" MODIFIED="1720232429064" TEXT="sie liegt beim Implementator des Domain-Adapters"/>
</node>
</node>
<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1720045073507" ID="ID_1770114651" MODIFIED="1720045126936" TEXT="Analyse: Rolle der Domain-Ontologie in diesem Build-Proze&#xdf;">
<icon BUILTIN="info"/>
<node CREATED="1720045685664" ID="ID_853315049" MODIFIED="1720045717786" TEXT="zu jedem Proc-Asset l&#xe4;&#xdf;t sich eine Domain-Ontology-Fa&#xe7;ade beschaffen"/>