diff --git a/doc/design/index.txt b/doc/design/index.txt index f42c91ac8..c8d96320a 100644 --- a/doc/design/index.txt +++ b/doc/design/index.txt @@ -13,16 +13,15 @@ Lumiera Design Documents Lumiera is to be a professional tool for video editing on GNU/Linux systems. The vision of the development team defines a modern design for the core of a Non-Linear Editing software. A key aspect of Lumiera -is strong separation between the user interface and the processing core. -Lumiera will have a GTK GUI but that will not be -exclusive; other GUIs can be written, even by users, -as well as scripts to drive the core. -This is made possible by an ongoing effort to decrease coupling. Each major +is the strong separation between the user interface and the processing core. +We are developing Lumiera with a GTK GUI but that will in no way be exclusive; +other GUIs can be written, as well as scripts to drive the core. +This becomes possible by an ongoing effort to decrease coupling. Each major component in the application strives to be open to extensions, but closed against external modification. The presentation, the model and the ``performing'' of the model are separate and self-contained parts of the application. Lumiera as a processing core will be able to perform any conceivable -task on video and audio, even some unrelated to video editing. +task on video and audio, maybe even tasks entirely unrelated to video editing. .Workflow ***************** @@ -48,8 +47,8 @@ Graphical User Interface User interfaces are implemented as plug-ins. As a consequence, it is possible to interface with Lumiera through scripts. It is also possible to create specialised GUIs. The interface is the component that is closest to the user. It -provides purely visual interaction with the user. There the user manipulates, -organizes, loads, configures all sorts of data, especially MObjects (media +provides purely visual interaction with the user. Within this work environment, the user +manipulates, organizes, loads, configures all sorts of data, especially MObjects (media objects) and Assets. These elements are contained within a structure called the Session. + -> link:gui/index.html[GUI design documents] @@ -57,16 +56,16 @@ objects) and Assets. These elements are contained within a structure called the The Processing Layer ~~~~~~~~~~~~~~~~~~~~ -The processing layer (``Proc-layer'' or ``proc'') has several closely related aspects. -When the user works with the GUI, all the clips, effects and other components presented -there are actually stored within the _Session model_ (``high-level model''). Any editing -operations initiated by the user are actually performed there. Next, after each change, -a component known as _the Builder_ assembles the contents of this model and transforms -them to form a network of nodes, which can be _performed_ efficiently for rendering. +The processing layer (``Proc-layer'' or ``proc'') covers several closely related aspects. +When the user works with the GUI, all the clips, effects and other visually presented +components are actually stored within the _Session model_ (``high-level model''). Any editing +operation initiated by the user is actually _executed_ in the context of the session. Next, +after each change, a component known as _the Builder_ assembles the contents of this session model +to transform them into a network of nodes, which can be efficiently _performed_ for rendering. Often, we refer to this node structure as the ``low-level model''. On rendering or -playback, the Proc-layer is responsible for accessing this node structure to +playback, the Proc-layer is responsible for accessing this low-level node structure to generate individual _frame render jobs,_ ready to be handed over to the backend, which -performs the actual rendering calculations. + +finally initiates the actual rendering calculations. + -> more about the link:model/index.html[Model] + -> design of the link:engine/index.html[Engine] subsystem @@ -75,8 +74,8 @@ performs the actual rendering calculations. + The Backend ~~~~~~~~~~~ -The backend uses the low-level model and the _render jobs_ generated by Proc. -It actually performs the rendering operations and makes heavy use of the +The backend attaches to the low-level model and the _render jobs_ generated by Proc. +It actually conducts the rendering operations and makes heavy use of the Input/Output System for accessing media content and sending generated data to the screen or to external output. + -> link:backend/index.html[Backend design level documents] + diff --git a/doc/devel/DIR_INFO b/doc/devel/DIR_INFO index 27f8206c5..a9ea7e85c 100644 --- a/doc/devel/DIR_INFO +++ b/doc/devel/DIR_INFO @@ -1,3 +1 @@ developer documentation, extra sources, doxygen - -dir uml: html documentation generated by BOUML diff --git a/doc/devel/transcript/DIR_INFO b/doc/devel/transcript/DIR_INFO new file mode 100644 index 000000000..894dc3180 --- /dev/null +++ b/doc/devel/transcript/DIR_INFO @@ -0,0 +1 @@ +transcripts of relevant IRC discussions diff --git a/doc/technical/infra/MenuGen.txt b/doc/technical/infra/MenuGen.txt index 060f178e4..d83e4f7c9 100644 --- a/doc/technical/infra/MenuGen.txt +++ b/doc/technical/infra/MenuGen.txt @@ -133,15 +133,15 @@ configuration example [source,python] -------------------------------------------------------------------------- def addPredefined(): - root = Node(TREE_ROOT, label='Lumiera') <1> - proj = root.linkChild('project') <2> + root = Node(TREE_ROOT, label='Lumiera') # <1> + proj = root.linkChild('project') # <2> proj.linkChild('faq') - proj.prependChild ('screenshots') <3> + proj.prependChild ('screenshots') # <3> proj.putChildLast ('press') - proj.putChildAfter('faq', refPoint=Node('screenshots')) <4> + proj.putChildAfter('faq', refPoint=Node('screenshots')) # <4> - proj.link('http://issues.lumiera.org/roadmap', label="Roadmap (Trac)") <5> + proj.link('http://issues.lumiera.org/roadmap', label="Roadmap (Trac)") # <5> Node('rfc').sortChildren() -------------------------------------------------------------------------- <1> the _root node_ by convention uses a special ID token. Additional diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index b82a4656d..ccbc9fd77 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -424,7 +424,18 @@ rendering... [[builder]] builder ^^^^^^^ -[red]#to be written# +The inner workings of Lumiera exhibit some striking similarities to the implementation +of a programming language compiler. On one side, there is a tree-like data structure +which represents the high-level meaning of the edit currently in the works. We call +this data structure the ``high-level model'' -- it is comprised of timelines and +sequences, tracks, bins, clips and effects. On the other side, the render engine +requires a properly wired network of low-level processing nodes, where every connection +has been made explicit, and any indirection has been resolved. + +The *Builder* is the entity performing the translation between these both flip sides +of the coin: it creates the low-level processing graphs by traversing and evaluating +the relevant parts of the high-level-model. Indirections will be resolved and +connections will be made explicit by querying the _rules system_. rules system ^^^^^^^^^^^^ @@ -492,13 +503,14 @@ libraries. A library is used in an application by _linking_ the library into the application. (There are other things to be done, but we'll call these 'details', which wont concern us here.) There are different ways to _link_ a library -into an application: statically linking and dynamically linking. +into an application: linking statically and linking dynamically. -_Statically Linking_ is done while the application is being built, or -compiled. It is performed by the linker. The linker can perform some checks -(mostly checks on syntax) and warn the user that some particular feature is -being used incorrectly. The user can then correct the offending code, and -recompile. +_Static Linking_ is done while the application is being built, or +compiled. It is performed by the linker, which executes as the last step +of the compilation process. The linker can perform some sanity checks +(mostly checks regarding formally correct function invocation) and warn the user +hat some particular feature is being used incorrectly. The user can then correct +the offending code, and recompile. + There are a number of disadvantages associated with static linking. Features and libraries are being constantly improved. If the application wants to use new features, it will have to be recompiled with the new library which provides the @@ -531,11 +543,11 @@ How are Plugins Implemented? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We can view Lumiera itself as being a slender application with many of the bells -and whistles being supplied __directly_ by external FOSS tools. Such tools will +and whistles being supplied _directly_ by external FOSS tools. Such tools will be made available to the Lumiera code base via the Lumiera Plugin Interface (LPI). -As LPI will be used throughout most layers of Lumiera--from the low-level -backend, right up to the GUI--the interface will have to be compatible to both C +As LPI will be used throughout most layers of Lumiera -- from the low-level +backend, right up to the GUI -- the interface will have to be compatible to both C and C++. In effect, this means that LPI will be implemented in C. Using LPI a plugin interface can be defined for each external library. The diff --git a/src/lib/bool-checkable.hpp b/src/lib/bool-checkable.hpp index 4f03c2773..d6e54b2de 100644 --- a/src/lib/bool-checkable.hpp +++ b/src/lib/bool-checkable.hpp @@ -21,34 +21,6 @@ */ -/** @file bool-checkable.hpp - ** When working with generic function objects and function pointers typed to - ** arbitrary signatures, often there is the necessity to hold onto such a functor - ** while hiding the actual signature behind an common interface ("type erasure"). - ** The usual solution based on subclassing has the downside of requiring separate - ** storage for the concrete functor object, which might become problematic when - ** dealing with lots of functor objects. - ** - ** Especially when dealing with tr1::function objects, all of the type differences - ** are actually encoded into 3 internal pointers, thus yielding the same size for - ** all various types of functors. Building on this observation, we can create an - ** common container object to store the varying functors inline, while hiding the - ** actual signature. - ** - ** There remains the problem of re-accessing the concrete functor later on. As - ** C++ has only rudimental introspection capabilities, we can only rely on the - ** usage context to provide the correct function signature; only when using a - ** virtual function for the re-access, we can perform at least a runtime-check. - ** - ** Thus there are various flavours for actually implementing this idea, and the - ** picking a suitable implementation depends largely on the context. Thus we - ** provide a common and expect the client code to pick an implementation policy. - ** - ** @see control::Mutation usage example - ** @see function-erasure-test.cpp - ** - */ - #ifndef LIB_BOOL_CHECKABLE_H #define LIB_BOOL_CHECKABLE_H @@ -63,7 +35,7 @@ namespace lib { } - /* + /** * Provide an implicit conversion to "bool". * Inherit (mix-in) from this template by providing the * concrete subclass type ("CRTP"). Additionally, to implement