From 7c554caf080878601fea17fa262cc870cac64612 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Fri, 5 Jul 2024 23:36:41 +0200 Subject: [PATCH] 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 --- src/steam/engine/node-builder.hpp | 81 +++++++++--- tests/core/steam/engine/node-linkage-test.cpp | 4 +- wiki/thinkPad.ichthyo.mm | 125 ++++++++++++------ 3 files changed, 149 insertions(+), 61 deletions(-) diff --git a/src/steam/engine/node-builder.hpp b/src/steam/engine/node-builder.hpp index 708f58e73..883eb916e 100644 --- a/src/steam/engine/node-builder.hpp +++ b/src/steam/engine/node-builder.hpp @@ -3,7 +3,7 @@ Copyright (C) Lumiera.org 2009, Hermann Vosseler - 2024 , Hermann Vosseler + 2024, Hermann Vosseler 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 - 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{}; } diff --git a/tests/core/steam/engine/node-linkage-test.cpp b/tests/core/steam/engine/node-linkage-test.cpp index 8851ef92b..68008ef3a 100644 --- a/tests/core/steam/engine/node-linkage-test.cpp +++ b/tests/core/steam/engine/node-linkage-test.cpp @@ -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() + auto con = prepareNode() .build(); UNIMPLEMENTED ("build render nodes linked into a connectivity network"); } diff --git a/wiki/thinkPad.ichthyo.mm b/wiki/thinkPad.ichthyo.mm index 55ed69e35..228a4c2fe 100644 --- a/wiki/thinkPad.ichthyo.mm +++ b/wiki/thinkPad.ichthyo.mm @@ -1126,9 +1126,7 @@ - - - +

Fehlerlog-Anzeige vorläufig irgendwo.... @@ -1978,9 +1976,7 @@ - - - +

...wesentliches Struktur-Element:

der Parent-Container ist für das expand/collapse zuständig

@@ -22816,9 +22812,7 @@ - - - +

erleichtert das Testen @@ -23337,9 +23331,7 @@ - - - +

...und das ist wohl entstanden, weil ich ursprünglich einen generischen Visitor im Blick hatte; es hat sich aber dann gezeigt, daß eine solche universelle "Quer-Beweglichkeit" weder notwendig noch wünschenswert ist @@ -23792,9 +23784,7 @@ - - - +

interagiert mit den Presentern @@ -24205,9 +24195,7 @@ - - - +

Betriebsart "partiell initialisiert" @@ -50048,9 +50036,7 @@ - - - +

Command und Verhaltensmuster @@ -51014,9 +51000,7 @@ - - - +

Beispiel: Aktionen, die im globalen Menü stehen. @@ -51784,9 +51768,7 @@ - - - +

  • @@ -52484,9 +52466,7 @@ - - - +

    Instanz öffnen @@ -81902,9 +81882,58 @@ Date:   Thu Apr 20 18:53:17 2023 +0200
    + + + + +

    + ...diese Verbindet alle definierten Elemente in der einfachst möglichen / am wenigsten überraschenden Weise +

    +
      +
    • + es wird überall ein default-Buffertyp eingefüllt +
      • +
    • + die Reihenfolge der Eingangs-Buffer entspricht der Reihenfolge der Leads +
      • +
    • + es wird alles stets auf die durchgehend gleiche Port-# gelegt (D.h. wenn wir grade Port-2 bauen, dann werden auch alle Vorgänger auf Port-2 gepullt) +
      • +
    + +     +     + + + + + +

    + ausgeführt wird die Verdrahtung erst in der Terminal-Operation +

    + +     + +         + + + + + + +

    + mutmaßlich Nein +

    + +     +     + + + + @@ -81917,7 +81946,7 @@ Date:   Thu Apr 20 18:53:17 2023 +0200
    - + @@ -81936,7 +81965,9 @@ Date:   Thu Apr 20 18:53:17 2023 +0200
     - + + + @@ -82036,7 +82067,9 @@ Date:   Thu Apr 20 18:53:17 2023 +0200

    - + + + @@ -82058,15 +82091,17 @@ Date:   Thu Apr 20 18:53:17 2023 +0200
     - + - + + + - + @@ -82078,7 +82113,9 @@ Date:   Thu Apr 20 18:53:17 2023 +0200
     - + + + @@ -82204,6 +82241,20 @@ Date:   Thu Apr 20 18:53:17 2023 +0200
     + + + + + + + + + + + + + +