further detail planning for the builder

wiki/renderengine.html

@@ -570,28 +570,42 @@ For every Asset we generate a __Ident tuple__ and a long ID (hash) derived from
 [img[how to implement Automation|uml/fig129669.png]]
 </pre>
 </div>
-<div title="BasicBuildingOperations" modifier="Ichthyostega" modified="200712040413" created="200712040334" tags="design dynamic def" changecount="5">
+<div title="BasicBuildingOperations" modifier="Ichthyostega" modified="200712080348" created="200712040334" tags="design dynamic def" changecount="14">
 <pre>Starting out from the concepts of Objects, Placement to Tracks, Ports and connection properties (&amp;rarr; see [[here|TrackPortEDL]]) within the EDL, we can identify the elementary operations occuring within the Builder. Overall, the Builder is organized as application of //visiting tools// to a collection of objects, so finally we have to consider some object kind appearing in the working function of the given builder tool, which holds at this moment some //context//. The job now is to organize this context such as to create a predictable build process from this //event driven// approach.
 
 !Builder working Situations
-# any ''Clip'' (which is at this point already reduced to a part of single elementary media stream)
+# any ''Clip'' (which at this point has been reduced already to a part of a simple elementary media stream &amp;rarr; see [[Fixture]])
 ## yields a source reading node
 ## which needs to be augmented by the underlying media's [[processing pattern|ProcPatt]]
 ##* thus inserting codec(s) and source transformations
 ##* effectively this is an application of effects
+## at this point we have to process (and maybe generate on-the-fly) the [[source port of this clip|ClipSourcePort]]
+##* the output of the source reading and preprocessing defined thus far is delivered as input to this port, which is done by a ~WiringRequest (see below)
+##* as every port, the source port has a processing pattern, normally inserting the camera (transformation effect) at this point
 ## followed by the application of effects
 ##* separately for every effect chain rooted (placed) directly onto the clip
 ##* and regarding the chaining order
 ## next we have to assess the [[ports|Port]] to which the clip has been placed
-## producing a WiringRequest for every pair {{{(chainEndpoint, port)}}}
+## producing a [[wiring request|WiringRequest]] for every pair {{{(chainEndpoint, port)}}}
 # attaching an ''Effect'' is actually always an //insertion operation// which is done by //prepending// to the previously built nodes
-# treating an ''~WiringRequest'' means
+# treating an ''wiring request'' means
 ## detecting possible and impossible connections
-## deriving additional possible &quot;placement dimensions&quot; generated by executing such an connection (e.g. connecting a mono source to a spacial sound system bus creates panning possibilities)
+## deriving additional possible &quot;placement dimensions&quot; generated by executing such an connection (e.g. connecting a mono source to a spatial sound system bus creates panning possibilities)
 ##* deriving parameter sources for this additional degrees of freedom
 ##* fire off insertion of the necessary effects to satisfy this connection request and implement the additional &quot;placement dimensions&quot; (pan, layer order, overlay mode, MIDI channel selection...)
-# processing effects and further placements ''attached to a Port'' behaves identical to the processing done with all attachements to individual clips.
+# processing effects and further placements ''attached to a Port'' behaves identical to the processing done with all attachments to individual clips.
+# ''Transitions'' are to be handled differently according to their placement (&amp;rarr; more on [[Transitions|TransitionsHandling]])
+#* when placed normally to two (or N) clips, they are inserted at the exit node of the clip's complete effect chain.
+#* otherwise, when placed to the source port(s) or when placed to some other ports they are inserted at the exit side of those ports effect chains. (Note: this puts additional requirements on the transition processor, so not every transition can be placed this way)
 After consuming all input objects and satisfying all wiring requests, the result is a set of [[exit nodes|ExitNode]] ready for pulling data. We call the network reachable from such an exit node a [[Processor]], together all processors of all segments and output data types comprise the render engine.
+
+!!!dependencies
+Ports need to be there first, as everything else will be placed to a port at some point. The same holds true for tracks. But, on the other hand, both are optional. We can have EDLs with ~MObjects without configuring ports (but won't be able to build any render processor of course). And we could have an EDL without any track, if we place every ~MObject within this EDL directly to some port.
+
+Effects can be attached only to already existing pipelines, starting out at some port or clip. Besides that, all further parts can be built in any order and independent of each other. This is made possible by using [[wiring requests|WiringRequest]], which can be resolved later on. So, as long as we start out with the tracks (to resolve any port they are placed to), and further, if we manage to get any effect placed to some clip-MO //after// treating the clip, we are fine and can do the building quasi event driven.
+
+!!!building and resolving
+Building the network for the individual objects thus creates a queue of wiring requests. Some of them may be immediately resolvable, but detecting this correctly can be nontrivial, and so it seems better to group all wiring requests based on the port and treat them groupwise. Because &amp;mdash; in the most general case &amp;mdash; connecting includes the use of transforming and joining nodes, which can create additional wiring requests (e.g. for automation parameter data connections). Finally, if the network is complete, we could perform [[optimisations|RenderNetworkOptimisation]]
 </pre>
 </div>
 <div title="BetterTimelineMacro" modifier="Saq" modified="200701030924" created="200607280926" tags="lewcidExtension systemConfig" server.type="file" server.host="file:///home/ct/.homepage/home.html" server.page.revision="200701030924">
@@ -2931,7 +2945,7 @@ function addKeyDownHandlers(e)
 
 </pre>
 </div>
-<div title="TrackPortEDL" modifier="Ichthyostega" modified="200712040319" created="200711300405" tags="design discuss def decision" changecount="8">
+<div title="TrackPortEDL" modifier="Ichthyostega" modified="200712080322" created="200711300405" tags="design discuss def decision" changecount="11">
 <pre>''towards a definition of »Track«''. We don't want to tie ourself to some naive and overly simplistic definition, just because it is convenient. For classical (analogue) media, tracks are physical entities dictated by the nature of the process by which the media works. Especially, Tape machines have read/writing heads, which creates fixed tracks to which to route the signals. This is a practical geometric necessity. For digital media, there is no such necessity. We are bound primarily by the editor's habits of working.
 
 !!!Assessment of Properties
@@ -2944,14 +2958,33 @@ This is to say we have //several degrees of freedom// within this organisational
 !!!do we really need Tracks?
 Starting with the assumption &quot;everything is just connected processing nodes&quot;, Tracks may seem superfluous. The problem with this approach is: it doesn't scale well. While it is fine to be able to connect clips and effects as we see fit (indeed, we want to build such a system), it is clearly not feasible to wire every clip manually to the output ports or add a panner effect to each and every audio sample. Because while editing, most of the time things are done in a fairly regular and systematic manner. Preferably we use the tracks as //preconfigured group setup// and just //place media onto them;// any such [[Placement]] can do the necessary wiring semi-automatic (rule-based).
 
+!!!the constant part
+there seems to be some non time-varying part in each EDL, that doesn't fit well with the simple model &quot;objects on a timeline&quot;. Tracks seen as an organisational grid fall into this category: they are a global property of the given EDL. They could be associated to the Session as a whole, but effectively this would subvert the concept of having several EDLs. On the other hand, 
+[[ports|Port]] for Video and Sound output are obviously a global property of the Session. There can be several global ports forming a matrix of subgroup busses. We could add ports to tracks as well, but we don't do this, because, again, this would run counter to our attempt of treating tracks as merely organisational entities. We have special [[source ports|ClipSourcePort]] on individual clips though, and we will have ports on meta-clips too.
+
 !Design
-__Tracks__ are just a structure used to organize the Media Objects within the EDL. They are a grid, and besides that, they have no special meaning. It seems convenient to make the tracks not just a list, but allow grouping (tree structure) right from start. __~MObjects__ are placed rather than wired. The wiring is derived from the __Placement__. Placing can happen in several dimensions:
+__Tracks__ are just a structure used to organize the Media Objects within the EDL. They form a grid, and besides that, they have no special meaning. It seems convenient to make the tracks not just a list, but allow grouping (tree structure) right from start. __~MObjects__ are placed rather than wired. The wiring is derived from the __Placement__. Placing can happen in several dimensions:
 * placing in time will define when to activate and show the object.
 * placing onto a track associates the ~MObject with this track; the GUI will show it on this track and the track may be used to resolve other properties of the object.
 * placing to a __Port__ brings the object in conjunction with this Port for the build process. It will be considered when building the render network for this port. Source-like objects (clips and exit nodes of effect chains) will be connected to the port, while transforming objects (effects) are inserted at the port.
-* depending on the nature of the port and the source, placing to some port may create additional degrees of freedom, demanding the object to be placed in this additional dimensions: Connecting to video out e.g. creates an overlay mode and a layer position, while connecting to a spatial sound system creates a pan position. Placing a mono clip onto a mono Port creates no additional properties though.
+* depending on the nature of the port and the source, placing to some port may create additional degrees of freedom, demanding the object to be placed in this new, additional dimensions: Connecting to video out e.g. creates an overlay mode and a layer position which need to be specified, while connecting to a spatial sound system creates the necessity of a pan position. On the other hand, placing a mono clip onto a mono Port creates no additional degrees of freedom.
 Placements are __resolved__ resulting in an ExplicitPlacement. In most cases this is just a gathering of properties, but as Placements can be incomplete and relative, there is room for real solving. The resolving mechanism tries to __derive missing properties__ from the __context__: When a clip isn't placed to some port but to a Track, than the Track and its parents will be inspected. If some of them has been placed to a port, the object will be connected to this port. Similar for layers and pan position. This is done by [[Placement]] and LocatingPin; as the [[Builder]] uses ~ExplicitPlacements, he isn't concerned with this resolving and uses just the data they deliver to drive the [[basic building operations|BasicBuildingOperations]]</pre>
 </div>
+<div title="TransitionsHandling" modifier="Ichthyostega" created="200712080417" tags="def design" changecount="1">
+<pre>Transitions combine the data from at least two processing chains and do this combining in a time varying fashion. So, any transition has
+* N input connections
+* either one or N output connections
+* temporal coordinates (time, length)
+* some control data connection to a ParamProvider, because in the most general case the controling curves are treated like automation
+
+!!!how much output ports?
+The standard case of a transition is sort of mixing together two input streams, like e.g. a simple dissolve. For this to be of any use, this input streams need to be connected to the same ouput port before and after the transition, i.e. the inputs and the transition share placement to the same output destination. In this case, when the transition starts, the direct connections can be suspended and the transition will switch in seamlessly.
+
+Using transitions is a very basic task and thus needs viable support by the GUI. Handling of transitions need to be very convienient, because it is so important. Because of this, it is compelling to subsume a more complicated situation and treat this more complicated case similar. This is the case, when two (or N) elements have to be combined in the way of a transition, but their further processing in the processing chain //after// the transition needs to be different, maybe they belong to differnent subgroups, have to appear on different layers or with different pan positions. Of courese, the workaround is simple, at least &quot;simple&quot; from the programmers point of view. It is //not// simple from the editor's point of view the moment the editor has to do this simple thing (changing the wiring and add manualy synced fade curves to the individual parts) a dozend or even a hundred times in some larger project.
+
+Because of this experience, ichthyo wants to support a more general case of transitions, which have N output connections, behave similar to their &quot;simple&quot; counterpart, but leave out the mixing step. As a plus, such transitions can be inserted at the source ports of N clips or between any intermediary or final output ports as well. Any transition processor capable of handling this situation should provide some flag, in order to decide if he can be placed in such a manner. (wichin the builder, encountering a  inconsistently placed transition is just an [[building error|BuildingError]])
+</pre>
+</div>
 <div title="VisitorUse" modifier="Ichthyostega" modified="200711280312" created="200711280302" tags="impl discuss" changecount="11">
 <pre>Using the ''Visitor Design Pattern'' is somewhat controversial, mainly because this pattern is rather complicated, requires certain circumstances to be usefull, and &amp;mdash; especially when used in the original form described by Gamma et al &amp;mdash; puts quite some burden on the implementor. This problems can be ameliorated by using library implementation techniques described by Robert Martin and implemented e.g. by Alexandrescu in the Loki library.