From 8462f587d65c1847551ca4e2b8af0104814bc7ab Mon Sep 17 00:00:00 2001 From: Benny Date: Thu, 31 Mar 2011 18:57:25 +0200 Subject: [PATCH 01/47] Compile error fixed --- src/lib/time/digxel.hpp | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/lib/time/digxel.hpp b/src/lib/time/digxel.hpp index 53aac3456..61bf2ab3e 100644 --- a/src/lib/time/digxel.hpp +++ b/src/lib/time/digxel.hpp @@ -74,6 +74,9 @@ #include #include +#include +#include + using std::string; From 203f1693ed7db0e630832eac113444a141533d88 Mon Sep 17 00:00:00 2001 From: Lumiera Project Date: Sat, 20 Aug 2011 19:31:26 +0100 Subject: [PATCH 02/47] fix a grammar error --- README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README b/README index 3d62663eb..0e0f938aa 100644 --- a/README +++ b/README @@ -42,7 +42,7 @@ The Application can be installed and started to bring up an GTK GUI outline, but the GUI is very preliminary and not connected to core functionality. The video processing pipeline is still not complete. -See the http://issues.lumiera.org/roadmap[Project roadmap] +See http://issues.lumiera.org/roadmap[Project roadmap] Build Requirements From 77dc4af36f666983529912b509d2dde5cddd10c7 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Fri, 27 Jul 2012 20:49:14 +0100 Subject: [PATCH 03/47] Section: Plugins/Interfaces; introductory text, initial draft. First piece of introductory text for the Plugins/Interfaces section. Only a somewhat long introduction of what plugins are. TODO: discussed the 'what' of plugins, and possibly a little of the 'why' of plugins, still require the 'how'. --- doc/user/intro/intro.txt | 48 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index dcbf377ab..16f92ebb9 100644 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -355,11 +355,51 @@ Configuration Plugins/Interfaces ~~~~~~~~~~~~~~~~~~ -[red]#to be written# +A Plug-in is a kind of generalisation of a library. -// explain whats it is -// portability -// versioning +All applications use, to varying degrees of intensity, libraries. A programmer +will not reinvent the wheel each time he sits down to programme an +application. A programmer will typically borrow and use features and +functionality from other programmers---or even borrow from himself, stuff +written long ago in the past. Such features are collected together in +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. + +_Staticall 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. +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 +new features. + +_Dynamic Linking_ helps rectify the the necessity of having to recompile. If a +new, improved library becomes available, all the user has to do is to install +the new library onto the operating system, restart the application and the new +features can be used by the application. The features provided by a dynamic +library are loaded when the application starts to run. + +However both methods exibit a number of shortcomings. Wouldn't it be better if +all features could be loaded only when needed? If features could be loaded only +when needed, then they could also be unloaded when not required, thus saving +memory and possibly increasing performance. This scheme of making features +available to an application is known as run-time linking, aka plug-ins. +Plug-ins offer other benifits: the application can continue to use both the old +features and the new features together, side-by-side, by using the version +number associated with the plug-in. This saves the application from considerable +headaches associated with other linking methods, havocked library versiojn +incompatibility. + +Most modern applications use plug-ins, some are heavily dependent on plug-ins +and only provide limited functionality without any plug-ins. +Lumiera will not reinvent the wheel. One major goal is to provide considerable +functionality via well-designed, external code supplied to Lumiera by plug-ins. From 130fc1bf26016aa7216d65a014d50bd8e4bb4ba8 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sat, 28 Jul 2012 22:08:22 +0100 Subject: [PATCH 04/47] Section Plugins/Interfaces: subsections added and text corrected. --- doc/user/intro/intro.txt | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 16f92ebb9..1e846a3f1 100644 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -355,6 +355,11 @@ Configuration Plugins/Interfaces ~~~~~~~~~~~~~~~~~~ + + +What are Plugins? +^^^^^^^^^^^^^^^^^ + A Plug-in is a kind of generalisation of a library. All applications use, to varying degrees of intensity, libraries. A programmer @@ -379,7 +384,7 @@ 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 new features. -_Dynamic Linking_ helps rectify the the necessity of having to recompile. If a +_Dynamic Linking_ helps rectify the necessity of having to recompile. If a new, improved library becomes available, all the user has to do is to install the new library onto the operating system, restart the application and the new features can be used by the application. The features provided by a dynamic @@ -393,7 +398,7 @@ available to an application is known as run-time linking, aka plug-ins. Plug-ins offer other benifits: the application can continue to use both the old features and the new features together, side-by-side, by using the version number associated with the plug-in. This saves the application from considerable -headaches associated with other linking methods, havocked library versiojn +headaches associated with other linking methods, havocked library version incompatibility. Most modern applications use plug-ins, some are heavily dependent on plug-ins @@ -403,6 +408,8 @@ functionality via well-designed, external code supplied to Lumiera by plug-ins. + + Rendering Video --------------- [red]#to be written# From acec8ad71ccff9c7c23575c47d7322b60c107f2a Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:17:46 +0100 Subject: [PATCH 05/47] Glossery terms sorted --- doc/user/intro/Glossary.txt | 335 ++++++++++++++++++------------------ 1 file changed, 170 insertions(+), 165 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 9f5f7c2ea..aa9834231 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -5,6 +5,108 @@ Glossary 'NOTE Draft, please help rephrase/review and sort this terms, shorten explanations, the long explanation is the topic of the document above..' + anchor:AssetsView[] link:#AssetsView[->]Assets View:: + The windows showing and managing the available things to work with. + This are the ingested footage, already composed Clips, available + Sub-Projects, Effects, Transitions and internal artefacts. + + anchor:Builder[] link:#Builder[->]Builder:: + A kind of compiler which creates Low Level/Processing Graphs, by + traversing and evaluating the relevant parts of the high-level-model + and using the Rules System. + + anchor:Busses[] link:#Busses[->]Busses:: + A list of 'global Pipes' representing the possible outputs (master + busses) similar to audio mixing desk. A bus defines the properties of + the rendered output (Framerate, Resolution, Colorformat and so on). + Busses are part of a Timeline. + + anchor:ConfigSystem_Preferences[] link:#ConfigSystem_Preferences[->]Config System/Preferences:: + TODO: agree on one term here + Provides defaults for all kinds of application configurations. These + include machine specific configurations for performance + characteristics, File and Plugins Paths and configuration data and so + on. Note that this only provides defaults for otherwise not yet set + data. Many settings will then be stored within the project and the + Config/Preferences becomes overridden by that. + + anchor:ControllerGui[] link:#ControllerGui[->]Controller Gui:: + This can be either a full Software implementation for a Transport + control (Widgets for Start/Stop/Rev/Ffw etc) or some Gui managing an + Input Device. They share some feature to attach them to controllable + gui-entities (Viewers, Timeline Views) + + anchor:Cursor[] link:#Cursor[->]Cursor:: + playback- or edit position + + anchor:Focus[] link:#Focus[->]Focus:: + TBD + + anchor:HighLevelModel[] link:#HighLevelModel[->]High Level Model:: + All the session content to be edited and manipulated by the user + through the GUI. The high-level-model will be translated by the + Builder into the Low Level Model for rendering. + + anchor:InputDevice[] link:#InputDevice[->]Input Device:: + some hardware controler, like a extra Keyboard, Midi Mixer, Jog, .. + TODO: decide if the main keyboard as special (global) state. + + anchor:LowLevelModel[] link:#LowLevelModel[->]Low Level Model:: + The generated Processing Graph, to be ``performed'' within the engine + to yield rendered output + + anchor:MediaStream[] link:#MediaStream[->]MediaStream:: + Media data is supposed to appear structured as stream(s) over time. + While there may be an inherent internal structuring, at a given + perspective any stream is a unit and homogeneous. In the context of + digital media data processing, streams are always quantized, which means + they appear as a temporal sequence of data chunks called frames. + + anchor:OutputDesignation[] link:#OutputDesignation[->]OutputDesignation:: + A specification denoting where to connect the output of a pipe. + It might either be given _absoulutely_, i.e as Pipe-ID, + or by an _relative_ or _indirect_ specification + + anchor:OutputManager[] link:#OutputManager[->]OutputManager:: + manages all external outputs of the application and provides output + slots targetting these. + + anchor:OutputMapping[] link:#OutputMapping[->]OutputMapping:: + translates one output designation into another one, e.g. when hooking + up a sequence as virtual clip within another sequence + + anchor:OutputSlot[] link:#OutputSlot[->]OutputSlot:: + opaque descriptor for an output facility, ready to dispose frames + of data to be output. + + anchor:Pipe[] link:#Pipe[->]Pipe:: + Conceptual building block of the high-level model. It can be thought + off as simple linear processing chain. A stream can be 'sent to' a + pipe, in which case it will be mixed in at the input, and you can + 'plug' the output of a pipe to another destination. Further, effects + or processors can be attached to the pipe. Besides the global pipes + (busses) in each Timeline, each clip automatically creates N pipes + (one for each distinct content stream. Typically N=2, for video and + audio) + + anchor:Placement[] link:#Placement[->]Placement:: + A Placement represents a relation: it is always linked to a Subject + (this being a Media Object) and has the meaning to place this Subject + in some manner, either relatively to other Media Objects, by some + Constraint or simply absolute at (time, output). Placements are used + to stitch together the objects in the high-level-model. Placements + thus are organised hierarchically and need to be _resolved_ to obtain + a specific value (time point, output routing, layering, fade,...) + + anchor:PlayController[] link:#PlayController[->]PlayController:: + coordinating playback, cueing and rewinding of a playback position, + visible as 'Playhead' cursor in the GUI. When in play state, a + PlayController requests and directs a render process to deliver the + media data needed for playback. + + anchor:ProcessingGraph[] link:#ProcessingGraph[->]Processing Graph:: + Rendering is expressed as detailed network of Nodes, each defining a + processing step. anchor:Project[] link:#Project[->]Project:: the top-level context in which all edit work is done over an extended @@ -12,12 +114,80 @@ explanations, the long explanation is the topic of the document above..' comprised of the collection of all things the user is working on, it contains all informations, assets, state and objects to be edited. + anchor:RenderTask[] link:#RenderTask[->]RenderTask:: + basically a PlayController, but collecting output directly, without + moving a PlayheadCursor (maybe a progress indicator) and not operating + in a timed fashion, but freewheeling or in background mode + + anchor:RulesSystem[] link:#RulesSystem[->]Rules System:: + Translating the Timeline to the underlying Processing Graphs involves + some logic and knowledge about handling/converting data. This may be + configued with this Rules System. Typically Lumiera will provide sane + defaults for most purposes but may extended/refined for site specific + things. + + anchor:Sequence[] link:#Sequence[->]Sequence:: + A collection of *Media Objects* (clips, effects, transitions, labels, + automation) placed onto a tree of tracks. By means of this placement, + the objects could be anchored relative to each other, relative to + external objects, absolute in time. A sequence can connect to the + global pipes when used as top-level sequence within a timeline, or + alternatively it can act as a virtual-media when used within a + meta-clip (nested sequence). In the default configuration, a Sequence + contains just a single root track and sends directly to the master bus + of the timeline. + anchor:Session[] link:#Session[->]Session:: the current in-memory representation of the Project when opened within an instance of Lumiera. This is an implementation-internal term. For the GUI and the users POV we should always prefer the term "Project" for the general concept. + anchor:StreamType[] link:#StreamType[->]StreamType:: + Classification of a media stream. StreamType is a descriptor record. + While external media processing libraries usually do provide some kind + of classification already, within lumiera we rely on an uniform yet + abstract classification which is owned by the project and geared to + fit the internal needs, especially for the wiring and connecting. + A Lumiera stream type is comprised of the parts + - media kind (Video, Image, Audio, MIDI, Text,... ) + - prototype (open ended collection of semantical kinds of media, + examples being stereoscopic, periphonic, monaural, binaural, + film quality, TV, youtube). + - implementation type (e.g. 96kHz 24bit PCM, 2 channels muxed) + - intention tag (Source, Raw, Intermediary and Target) + + anchor:TimeAxis[] link:#TimeAxis[->]Time Axis:: + An entity defining the temporal properties of a timeline. A time axis + defines the time base, kind of timecode and absolute anchor point. + Besides, it manages a set of frame quantisation grids, corresponding + to the outputs configured for this timeline (through the global + busses). The GUI representation is a time ruler with configurable time + ticks showed on top of the timeline view + + anchor:Timeline[] link:#Timeline[->]Timeline:: + the top level element(s) within the Project. It is visible within a + 'timeline view' in the GUI and represents the effective (resulting) + arrangement of media objects, resolved to a finite time axis, to be + rendered for output or viewed in a Monitor (viewer window). + Timeline(s) are top-level and may not be further combined. A timeline + is comprised of: + * Time axis, defining the time base + * Play Controller (WIP: discussion if thats belongs to the timeline + and if we want a 1:N relation here). Note by Ichthyo: yes, our + current discussion showed us that a play controller rather gets + allocated to a timeline, but isn't contained therein. + * global pipes, i.e. global busses like in a mixing desk + * exactly one top level Sequence + + anchor:TimelineSegment[] link:#TimelineSegment[->]Timeline Segment:: + A range in the timeline which yields in one Processing graph, commonly + the range between cut points (which require a reconfiguration of the + graph). + +// Note by Ichthyo: "Extent" sounds somewhat cool, just it didn't occur to me as a term. +// We may well agree on it, if "extent" communicates the meaning better. Up to now, I called it "segment" + anchor:TimelineView[] link:#TimelineView[->]Timeline View:: A view in the GUI featuring a given Timeline. There might be multiple views of the same timeline, all sharing the same PlayController. A @@ -38,120 +208,6 @@ explanations, the long explanation is the topic of the document above..' patchbay, that is not the main purpose and they can do things beyond that.. - anchor:Timeline[] link:#Timeline[->]Timeline:: - the top level element(s) within the Project. It is visible within a - 'timeline view' in the GUI and represents the effective (resulting) - arrangement of media objects, resolved to a finite time axis, to be - rendered for output or viewed in a Monitor (viewer window). - Timeline(s) are top-level and may not be further combined. A timeline - is comprised of: - * Time axis, defining the time base - * Play Controller (WIP: discussion if thats belongs to the timeline - and if we want a 1:N relation here). Note by Ichthyo: yes, our - current discussion showed us that a play controller rather gets - allocated to a timeline, but isn't contained therein. - * global pipes, i.e. global busses like in a mixing desk - * exactly one top level Sequence - - anchor:TimeAxis[] link:#TimeAxis[->]Time Axis:: - An entity defining the temporal properties of a timeline. A time axis - defines the time base, kind of timecode and absolute anchor point. - Besides, it manages a set of frame quantisation grids, corresponding - to the outputs configured for this timeline (through the global - busses). The GUI representation is a time ruler with configurable time - ticks showed on top of the timeline view - - anchor:Busses[] link:#Busses[->]Busses:: - A list of 'global Pipes' representing the possible outputs (master - busses) similar to audio mixing desk. A bus defines the properties of - the rendered output (Framerate, Resolution, Colorformat and so on). - Busses are part of a Timeline. - - anchor:Sequence[] link:#Sequence[->]Sequence:: - A collection of *Media Objects* (clips, effects, transitions, labels, - automation) placed onto a tree of tracks. By means of this placement, - the objects could be anchored relative to each other, relative to - external objects, absolute in time. A sequence can connect to the - global pipes when used as top-level sequence within a timeline, or - alternatively it can act as a virtual-media when used within a - meta-clip (nested sequence). In the default configuration, a Sequence - contains just a single root track and sends directly to the master bus - of the timeline. - - anchor:Placement[] link:#Placement[->]Placement:: - A Placement represents a relation: it is always linked to a Subject - (this being a Media Object) and has the meaning to place this Subject - in some manner, either relatively to other Media Objects, by some - Constraint or simply absolute at (time, output). Placements are used - to stitch together the objects in the high-level-model. Placements - thus are organised hierarchically and need to be _resolved_ to obtain - a specific value (time point, output routing, layering, fade,...) - - anchor:Pipe[] link:#Pipe[->]Pipe:: - Conceptual building block of the high-level model. It can be thought - off as simple linear processing chain. A stream can be 'sent to' a - pipe, in which case it will be mixed in at the input, and you can - 'plug' the output of a pipe to another destination. Further, effects - or processors can be attached to the pipe. Besides the global pipes - (busses) in each Timeline, each clip automatically creates N pipes - (one for each distinct content stream. Typically N=2, for video and - audio) - - anchor:MediaStream[] link:#MediaStream[->]MediaStream:: - Media data is supposed to appear structured as stream(s) over time. - While there may be an inherent internal structuring, at a given - perspective any stream is a unit and homogeneous. In the context of - digital media data processing, streams are always quantized, which means - they appear as a temporal sequence of data chunks called frames. - - anchor:StreamType[] link:#StreamType[->]StreamType:: - Classification of a media stream. StreamType is a descriptor record. - While external media processing libraries usually do provide some kind - of classification already, within lumiera we rely on an uniform yet - abstract classification which is owned by the project and geared to - fit the internal needs, especially for the wiring and connecting. - A Lumiera stream type is comprised of the parts - - media kind (Video, Image, Audio, MIDI, Text,... ) - - prototype (open ended collection of semantical kinds of media, - examples being stereoscopic, periphonic, monaural, binaural, - film quality, TV, youtube). - - implementation type (e.g. 96kHz 24bit PCM, 2 channels muxed) - - intention tag (Source, Raw, Intermediary and Target) - - anchor:OutputDesignation[] link:#OutputDesignation[->]OutputDesignation:: - A specification denoting where to connect the output of a pipe. - It might either be given _absoulutely_, i.e as Pipe-ID, - or by an _relative_ or _indirect_ specification - - anchor:OutputMapping[] link:#OutputMapping[->]OutputMapping:: - translates one output designation into another one, e.g. when hooking - up a sequence as virtual clip within another sequence - - anchor:OutputSlot[] link:#OutputSlot[->]OutputSlot:: - opaque descriptor for an output facility, ready to dispose frames - of data to be output. - - anchor:OutputManager[] link:#OutputManager[->]OutputManager:: - manages all external outputs of the application and provides output - slots targetting these. - - anchor:PlayController[] link:#PlayController[->]PlayController:: - coordinating playback, cueing and rewinding of a playback position, - visible as 'Playhead' cursor in the GUI. When in play state, a - PlayController requests and directs a render process to deliver the - media data needed for playback. - - anchor:RenderTask[] link:#RenderTask[->]RenderTask:: - basically a PlayController, but collecting output directly, without - moving a PlayheadCursor (maybe a progress indicator) and not operating - in a timed fashion, but freewheeling or in background mode - - anchor:ControllerGui[] link:#ControllerGui[->]Controller Gui:: - This can be either a full Software implementation for a Transport - control (Widgets for Start/Stop/Rev/Ffw etc) or some Gui managing an - Input Device. They share some feature to attach them to controllable - gui-entities (Viewers, Timeline Views) - anchor:Viewer[] link:#Viewer[->]Viewer:: the display destination showing video frame and possibly some effect overlays (masking etc.). When attached to a timeline, a viewer @@ -164,59 +220,8 @@ explanations, the long explanation is the topic of the document above..' mere control for sending video to a dedicated monitor (separate X display or firewire) - anchor:HighLevelModel[] link:#HighLevelModel[->]High Level Model:: - All the session content to be edited and manipulated by the user - through the GUI. The high-level-model will be translated by the - Builder into the Low Level Model for rendering. - anchor:LowLevelModel[] link:#LowLevelModel[->]Low Level Model:: - The generated Processing Graph, to be ``performed'' within the engine - to yield rendered output - anchor:Builder[] link:#Builder[->]Builder:: - A kind of compiler which creates Low Level/Processing Graphs, by - traversing and evaluating the relevant parts of the high-level-model - and using the Rules System. - anchor:TimelineSegment[] link:#TimelineSegment[->]Timeline Segment:: - A range in the timeline which yields in one Processing graph, commonly - the range between cut points (which require a reconfiguration of the - graph). -// Note by Ichthyo: "Extent" sounds somewhat cool, just it didn't occur to me as a term. -// We may well agree on it, if "extent" communicates the meaning better. Up to now, I called it "segment" - anchor:AssetsView[] link:#AssetsView[->]Assets View:: - The windows showing and managing the available things to work with. - This are the ingested footage, already composed Clips, available - Sub-Projects, Effects, Transitions and internal artefacts. - - anchor:RulesSystem[] link:#RulesSystem[->]Rules System:: - Translating the Timeline to the underlying Processing Graphs involves - some logic and knowledge about handling/converting data. This may be - configued with this Rules System. Typically Lumiera will provide sane - defaults for most purposes but may extended/refined for site specific - things. - - anchor:ProcessingGraph[] link:#ProcessingGraph[->]Processing Graph:: - Rendering is expressed as detailed network of Nodes, each defining a - processing step. - - anchor:ConfigSystem_Preferences[] link:#ConfigSystem_Preferences[->]Config System/Preferences:: - TODO: agree on one term here - Provides defaults for all kinds of application configurations. These - include machine specific configurations for performance - characteristics, File and Plugins Paths and configuration data and so - on. Note that this only provides defaults for otherwise not yet set - data. Many settings will then be stored within the project and the - Config/Preferences becomes overridden by that. - - anchor:InputDevice[] link:#InputDevice[->]Input Device:: - some hardware controler, like a extra Keyboard, Midi Mixer, Jog, .. - TODO: decide if the main keyboard as special (global) state. - - anchor:Focus[] link:#Focus[->]Focus:: - TBD - - anchor:Cursor[] link:#Cursor[->]Cursor:: - playback- or edit position From 9e1f0145f59bb955c75e9befd54ad1e4f215c676 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:24:43 +0100 Subject: [PATCH 06/47] AssetsView corrected: syntax only. Only changes here are English, sense should be the same. --- doc/user/intro/Glossary.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index aa9834231..df1742e91 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -2,13 +2,15 @@ Glossary ======== -'NOTE Draft, please help rephrase/review and sort this terms, shorten +'NOTE Draft, please help rephrase/review and shorten explanations, the long explanation is the topic of the document above..' anchor:AssetsView[] link:#AssetsView[->]Assets View:: - The windows showing and managing the available things to work with. - This are the ingested footage, already composed Clips, available - Sub-Projects, Effects, Transitions and internal artefacts. + Windows displaying and managing various things that can be edited, + worked on, etc are collectively known as the Assets View. + Ingested footager, clips that have already been composed, available + sub-projects, effects, transitions and internal artifacts are typical + examples. anchor:Builder[] link:#Builder[->]Builder:: A kind of compiler which creates Low Level/Processing Graphs, by From 2b948d14b4e14cbcae3e4df8f3c1e691bfdfeaac Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:28:29 +0100 Subject: [PATCH 07/47] Builder corrected: english syntax only. --- doc/user/intro/Glossary.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index df1742e91..30623cfc5 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -13,8 +13,8 @@ explanations, the long explanation is the topic of the document above..' examples. anchor:Builder[] link:#Builder[->]Builder:: - A kind of compiler which creates Low Level/Processing Graphs, by - traversing and evaluating the relevant parts of the high-level-model + This is a kind of compiler that creates low-level, or processing, graphs + by traversing and evaluating the relevant parts of the high-level-model and using the Rules System. anchor:Busses[] link:#Busses[->]Busses:: From 3dbf128026915375a03ae3a09082b7edcad9c314 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:33:06 +0100 Subject: [PATCH 08/47] ConfigSystem_Prefences: english syntax corrected. --- doc/user/intro/Glossary.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 30623cfc5..9b7e73bd2 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -28,9 +28,9 @@ explanations, the long explanation is the topic of the document above..' Provides defaults for all kinds of application configurations. These include machine specific configurations for performance characteristics, File and Plugins Paths and configuration data and so - on. Note that this only provides defaults for otherwise not yet set - data. Many settings will then be stored within the project and the - Config/Preferences becomes overridden by that. + on. Note that this only provides defaults for data that has not already + been set. Many settings will then be stored within the project which + override Config/Preferences. anchor:ControllerGui[] link:#ControllerGui[->]Controller Gui:: This can be either a full Software implementation for a Transport From 37e2075a862b82c3cbe500f81046c75b3a824313 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:34:27 +0100 Subject: [PATCH 09/47] Cursor: upper/lower case change --- doc/user/intro/Glossary.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 9b7e73bd2..e3f1354c2 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -39,7 +39,7 @@ explanations, the long explanation is the topic of the document above..' gui-entities (Viewers, Timeline Views) anchor:Cursor[] link:#Cursor[->]Cursor:: - playback- or edit position + Playback- or edit position anchor:Focus[] link:#Focus[->]Focus:: TBD From 5885a4db580e427143d2cec9e5ec540930e9e84c Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:36:13 +0100 Subject: [PATCH 10/47] InputDevice: english corrected --- doc/user/intro/Glossary.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index e3f1354c2..5c3083817 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -50,8 +50,8 @@ explanations, the long explanation is the topic of the document above..' Builder into the Low Level Model for rendering. anchor:InputDevice[] link:#InputDevice[->]Input Device:: - some hardware controler, like a extra Keyboard, Midi Mixer, Jog, .. - TODO: decide if the main keyboard as special (global) state. + Some hardware controler, like an extra keyboard, midi mixer, Jog, .. + TODO: decide on whether the main keyboard is in a special (global) state. anchor:LowLevelModel[] link:#LowLevelModel[->]Low Level Model:: The generated Processing Graph, to be ``performed'' within the engine From d305d2ea2d09ba821124ab16664b856b6779edf4 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:37:58 +0100 Subject: [PATCH 11/47] OutputDesignation: english corrected --- doc/user/intro/Glossary.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 5c3083817..203c3df83 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -66,8 +66,8 @@ explanations, the long explanation is the topic of the document above..' anchor:OutputDesignation[] link:#OutputDesignation[->]OutputDesignation:: A specification denoting where to connect the output of a pipe. - It might either be given _absoulutely_, i.e as Pipe-ID, - or by an _relative_ or _indirect_ specification + It might either be given _absoulutely_, i.e as a Pipe-ID, + or by a _relative_ or an _indirect_ specification anchor:OutputManager[] link:#OutputManager[->]OutputManager:: manages all external outputs of the application and provides output From 3d70e4c68c9410bb51144431c8899435231872da Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:38:35 +0100 Subject: [PATCH 12/47] OutputManager: english corrected --- doc/user/intro/Glossary.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 203c3df83..4c7442a12 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -70,7 +70,7 @@ explanations, the long explanation is the topic of the document above..' or by a _relative_ or an _indirect_ specification anchor:OutputManager[] link:#OutputManager[->]OutputManager:: - manages all external outputs of the application and provides output + Manages all external outputs of the application and provides output slots targetting these. anchor:OutputMapping[] link:#OutputMapping[->]OutputMapping:: From 79e764c55bcdb2cd868711b9afb6aba9bb6c6279 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:39:41 +0100 Subject: [PATCH 13/47] OutputMapping: english corrected --- doc/user/intro/Glossary.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 4c7442a12..4dc66b742 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -74,8 +74,8 @@ explanations, the long explanation is the topic of the document above..' slots targetting these. anchor:OutputMapping[] link:#OutputMapping[->]OutputMapping:: - translates one output designation into another one, e.g. when hooking - up a sequence as virtual clip within another sequence + Diverts one output designation into another designation, e.g. when hooking + up a sequence as a virtual clip within another sequence. anchor:OutputSlot[] link:#OutputSlot[->]OutputSlot:: opaque descriptor for an output facility, ready to dispose frames From 4156c6de5906facb5095b99a2c60b83f2a2e9a43 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:40:25 +0100 Subject: [PATCH 14/47] OutputSlot: upper/lower case corrected --- doc/user/intro/Glossary.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 4dc66b742..db6cdb816 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -78,7 +78,7 @@ explanations, the long explanation is the topic of the document above..' up a sequence as a virtual clip within another sequence. anchor:OutputSlot[] link:#OutputSlot[->]OutputSlot:: - opaque descriptor for an output facility, ready to dispose frames + Opaque descriptor for an output facility, ready to dispose frames of data to be output. anchor:Pipe[] link:#Pipe[->]Pipe:: From e4584acbea4431a50bd2b8a7793faa60784d8f0d Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:42:07 +0100 Subject: [PATCH 15/47] Pipes: english corrected --- doc/user/intro/Glossary.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index db6cdb816..1e0554b3f 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -83,10 +83,10 @@ explanations, the long explanation is the topic of the document above..' anchor:Pipe[] link:#Pipe[->]Pipe:: Conceptual building block of the high-level model. It can be thought - off as simple linear processing chain. A stream can be 'sent to' a + of as simple linear processing chain. A stream can be 'sent to' a pipe, in which case it will be mixed in at the input, and you can - 'plug' the output of a pipe to another destination. Further, effects - or processors can be attached to the pipe. Besides the global pipes + 'plug' the output of a pipe to another destination. Furthermore, effects + or processors can be attached to the pipe. In addition to global pipes (busses) in each Timeline, each clip automatically creates N pipes (one for each distinct content stream. Typically N=2, for video and audio) From 0df1bbc57e32f7be57b3d6314ae5b8d54eaea9f8 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 17:46:58 +0100 Subject: [PATCH 16/47] Sequence: english corrected --- doc/user/intro/Glossary.txt | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 1e0554b3f..ae51cdc21 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -132,12 +132,11 @@ explanations, the long explanation is the topic of the document above..' A collection of *Media Objects* (clips, effects, transitions, labels, automation) placed onto a tree of tracks. By means of this placement, the objects could be anchored relative to each other, relative to - external objects, absolute in time. A sequence can connect to the - global pipes when used as top-level sequence within a timeline, or + external objects, absolute in time. A sequence can connect to + global pipes when used as a top-level sequence within a timeline, or alternatively it can act as a virtual-media when used within a - meta-clip (nested sequence). In the default configuration, a Sequence - contains just a single root track and sends directly to the master bus - of the timeline. + meta-clip (nested sequence). A Sequence by default contains just a + single root track and directly sends to the master bus of the Timeline. anchor:Session[] link:#Session[->]Session:: the current in-memory representation of the Project when opened within @@ -211,7 +210,7 @@ explanations, the long explanation is the topic of the document above..' that.. anchor:Viewer[] link:#Viewer[->]Viewer:: - the display destination showing video frame and possibly some effect + The display destination showing video frame and possibly some effect overlays (masking etc.). When attached to a timeline, a viewer reflects the state of the timeline's associated PlayController, and it attaches to the timeline's global pipes (stream-type match or @@ -222,8 +221,3 @@ explanations, the long explanation is the topic of the document above..' mere control for sending video to a dedicated monitor (separate X display or firewire) - - - - - From 9b4b46afae6951420974c878bd74daad4f63afea Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 18:02:14 +0100 Subject: [PATCH 17/47] ProcessingGraph: text slightly expanded --- doc/user/intro/Glossary.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index ae51cdc21..e3aa86789 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -107,8 +107,8 @@ explanations, the long explanation is the topic of the document above..' media data needed for playback. anchor:ProcessingGraph[] link:#ProcessingGraph[->]Processing Graph:: - Rendering is expressed as detailed network of Nodes, each defining a - processing step. + Rendering is expressed as a detailed network of nodes. The edges can be + envisaged as data flow, while the nodes represent data processing. anchor:Project[] link:#Project[->]Project:: the top-level context in which all edit work is done over an extended From d83185d8d99307183da1fa701a364021c3db2d3a Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 18:08:39 +0100 Subject: [PATCH 18/47] Project: corrcted and text slightly modified --- doc/user/intro/Glossary.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index e3aa86789..f5782c4a3 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -111,10 +111,10 @@ explanations, the long explanation is the topic of the document above..' envisaged as data flow, while the nodes represent data processing. anchor:Project[] link:#Project[->]Project:: - the top-level context in which all edit work is done over an extended - period of time. The Project can be saved and re-opened. It is - comprised of the collection of all things the user is working on, it - contains all informations, assets, state and objects to be edited. + The top-level context in which all editing is done over an extended + period of time. A Project can be saved and re-opened. It consists of + various things a user is working on: user-information, assets, state and + objects to be edited. anchor:RenderTask[] link:#RenderTask[->]RenderTask:: basically a PlayController, but collecting output directly, without From 4ad651c5e0f987683f3a4183370163b2b91913f3 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 18:11:33 +0100 Subject: [PATCH 19/47] RenderTask: corrected --- doc/user/intro/Glossary.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index f5782c4a3..131585944 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -117,8 +117,8 @@ explanations, the long explanation is the topic of the document above..' objects to be edited. anchor:RenderTask[] link:#RenderTask[->]RenderTask:: - basically a PlayController, but collecting output directly, without - moving a PlayheadCursor (maybe a progress indicator) and not operating + This is basically a PlayController, but directlz collects output without + moving a PlayheadCursor (could be a progress indicator) and not operating in a timed fashion, but freewheeling or in background mode anchor:RulesSystem[] link:#RulesSystem[->]Rules System:: From f0d898a8323ac73279e868a58e3048fcb23ba241 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 29 Jul 2012 18:24:14 +0100 Subject: [PATCH 20/47] Viewer: corrected and somewhat modified --- doc/user/intro/Glossary.txt | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 131585944..a5348f1ee 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -117,7 +117,7 @@ explanations, the long explanation is the topic of the document above..' objects to be edited. anchor:RenderTask[] link:#RenderTask[->]RenderTask:: - This is basically a PlayController, but directlz collects output without + This is basically a PlayController, but directly collects output without moving a PlayheadCursor (could be a progress indicator) and not operating in a timed fashion, but freewheeling or in background mode @@ -214,10 +214,11 @@ explanations, the long explanation is the topic of the document above..' overlays (masking etc.). When attached to a timeline, a viewer reflects the state of the timeline's associated PlayController, and it attaches to the timeline's global pipes (stream-type match or - explicitly), showing video as monitor image and sending audio to the - system audio port. Possible extensions are for a viewer to be able to - attach to probe points within the render network, to show a second - stream as (partial) overlay for comparison, or to be collapsed to a - mere control for sending video to a dedicated monitor (separate X - display or firewire) - + explicitly), showing video as a monitor image and sending audio to the + system audio port. A number of supplimentary features are possible: the + viewer could support the ability to attach to view points within the + render network; the capability to display a second stream as an overlay + (partially) which would enable user comparison or it might even be + possible to allow the Viewer to be collapsed to a control, thus, + allowing a video to be sent to a dedicated monitor, e.g., to a separate + X/-display or to a firewire. From 2e785d7934910175ffd64d4a217cdf04e130d734 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Tue, 31 Jul 2012 23:16:41 +0100 Subject: [PATCH 21/47] Comments and Doxygen improved --- src/common/interface.h | 103 +++++++++++++++++++++++------------------ 1 file changed, 58 insertions(+), 45 deletions(-) diff --git a/src/common/interface.h b/src/common/interface.h index 3a8e2fb5c..82dabddf3 100644 --- a/src/common/interface.h +++ b/src/common/interface.h @@ -28,69 +28,82 @@ /* TODO better doxygen formating */ /** - * @file - * Lumiera interface macros and structures. + * @file interface.h + * @brief Lumiera interface macros and structures. * - * Instead just simple function/library bindings, Lumiera uses a system of - * versioned interfaces. This interfaces are C-binding compatible and thus - * can be used by any language which can bind to C. This interfaces are versioned - * to provide exceptional forward and backward compatibility for both, source and - * binary deployment of modules. This interfaces play a central role on the Lumiera - * architecture, other facilities, like serializing sessions and distributed computing + * Lumiera uses a system of versioned interfaces instead of just employing a + * simple library (containg the functions and data) and header file strategy. + * The interfaces defined here are C compatible and, thus, can be used by any + * language able to bind to C. The interfaces are versioned to provide forward + * and backward compatibility for both source and binary deployment of + * modules. The interfaces play a central role in the Lumiera architecture. + * Other facilities, such as serializing sessions and distributed computing * will use them extensively. * * Overview * - * Interfaces are used for two purposes in Lumiera: - * 1. The core uses them internally and exports its functionality though them. - * 2. Plugins (effects,...) extend Lumiera by providing interfaces + * Interfaces are used for 2 reasons in Lumiera: + * -# The Lumiera core system uses them internally and exports its functionality though them. + * -# Plugins (effects, ...) extend Lumiera by providing interfaces * - * We define some macros here which ease the declaration and definition of interfaces. + * To make an interface available to code so that the code can use the + * interface, the interface needs to be declared and then defined. We provide a + * number of macros here which ease this process. * - * Declaration of an interface happens in a header and has the form: - * LUMIERA_INTERFACE_DECLARE(name, version, - * LUMIERA_INTERFACE_SLOT(ret, name, params), - * ... - * ) - * Any code which want to use this interface must then include its declaration. - * - * Basic definition of an interface is done by mapping functions to slots or giving - * inline definitions for slot functions: - * LUMIERA_INTERFACE_INSTANCE(iname, version, name, descriptor, acquire, release, - * LUMIERA_INTERFACE_MAP (slot, luid, function), - * LUMIERA_INTERFACE_INLINE (slot, luid, ret, params, {body}), + * The interface is declared by placing the following macro in a + * header file: + * \code + * LUMIERA_INTERFACE_DECLARE(name, version, + * LUMIERA_INTERFACE_SLOT(ret, name, params), * ... * ) + * + * \endcode + * Any code that wants to use this interface must then include the header file. * - * There are 2 ways to define collections of interfaces: + * The interface is defined by mapping interface functions to slots, or + * providing inline definitions for slot functions. Defining the interface has + * the following form: + * \code + * LUMIERA_INTERFACE_INSTANCE(iname, version, name, descriptor, acquire, release, + * LUMIERA_INTERFACE_MAP (slot, luid, function), + * LUMIERA_INTERFACE_INLINE (slot, luid, ret, params, {body}), + * ... + * ) + * \endcode + * + * A collection of interfaces can be defined in 2 different ways depending on + * where whether the interface is exported by the core, or by a plugin: + * \code * LUMIERA_EXPORT(queryfunc, * LUMIERA_INTERFACE_DEFINE(...), * ... - * ) - * to export interfaces from the core. - * - * LUMIERA_PLUGIN(descriptor, acquire, release, luid, - * LUMIERA_INTERFACE_DEFINE(...), - * ... - * ) - * is used to export interfaces from a plugin. + * ) // Exporting from the core + * + * LUMIERA_PLUGIN(descriptor, acquire, release, luid, + * LUMIERA_INTERFACE_DEFINE(...), + * ... + * ) // Exporting from an interface + * \endcode * * Naming and Versioning + * * Interfaces have unique names and a major and minor version. The name and the major version - * is used to construct a C identifier for the interface, the minor version is implicit defined - * by the number of functions a interface. Interface instances are not versioned by the - * interface system, versioning these shall be defined somewhere else. + * is used to construct a C identifier for the interface, the minor version is implicitly defined + * by the number of functions in the interface. Interface instances are not versioned by the + * interface system, versioning these wii be defined somewhere else. * * Slot names are normal C identifiers, how these shall be versioned has to be defined somewhere - * else and is not subject of the interface system. Each function can has its own unique uuid. + * else and is not the subject of the interface system. Each function can have its own unique uuid. */ /* - Interface declaration macros + Macros to Declare an Interface */ /** + * * Construct a type identifier for an interface * @param name name of the interface * @param version major version of this interface @@ -107,7 +120,7 @@ #define LUMIERA_INTERFACE_DNAME(iname, version, dname) PPMPL_CAT (LUMIERA_INTERFACE_INAME (iname, version), _##dname) /** - * Construct a definition string r for an interface + * Construct a definition string for an interface * @param iname name of the interface * @param version major version of the interface * @param dname name for the instance @@ -145,14 +158,14 @@ /** * Declare an interface. * @param name name of the interface - * @param version major version of this interface declaration. 0 denotes a experimental interface, - * otherwise this shall be counting from 1 upwards for each new (incompatible) change of an interface. + * @param version major version of this interface declaration. 0 denotes an experimental interface, + * otherwise this will begin at 1 onwards for each new (incompatible) change to an interface. * The older interface declarations may still be maintained in parallel (backwards compatibility!). * @param ... Slot declarations for the functions provided by this interface @see LUMIERA_INTERFACE_SLOT * The number of Slots in an interface defines its 'minor' version. * New slots must be added at the end. The prototype and order of existing slots must not be changed. * Slots may be renamed, for example a slot 'foo' can be renamed to 'foo_old' when a new 'foo' slot is - * added. Binary modules will then still use the 'foo_old' slot which was the 'foo' slot at their + * added. Binary modules will then still use the 'foo_old' slot which was the 'foo' slot at the * compile time while compiling modules from source will use the new 'foo' slot. This may be * intentionally used to break compilation and force the update of modules to a new api. */ @@ -164,7 +177,7 @@ LUMIERA_INTERFACE_TYPE(name, version) \ } /** - * Declare function slot inside an interface. + * Declare a function slot inside an interface. * @param ret return type of the function * @param name name of this slot * @param params parentized list of parameters for the function @@ -175,11 +188,11 @@ LUMIERA_INTERFACE_TYPE(name, version) \ /* - Interface definition macros + Macros to Define an Interface */ /** - * Define a interface instance. + * Define an interface instance. * @param iname name of the interface to instance * @param version major version of the interface to instance * @param name name of the instance From fe6ff43de4c9af3c59690012bf874336b176b4ff Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sat, 25 Aug 2012 19:29:23 +0100 Subject: [PATCH 22/47] Fixed typo in AssetsView --- doc/user/intro/Glossary.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index a5348f1ee..bf4126e17 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -8,7 +8,7 @@ explanations, the long explanation is the topic of the document above..' anchor:AssetsView[] link:#AssetsView[->]Assets View:: Windows displaying and managing various things that can be edited, worked on, etc are collectively known as the Assets View. - Ingested footager, clips that have already been composed, available + Ingested footage, clips that have already been composed, available sub-projects, effects, transitions and internal artifacts are typical examples. From 306d11d091031dcc6f63a75d0be918c4e92ead50 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sat, 25 Aug 2012 19:47:46 +0100 Subject: [PATCH 23/47] AssetsView corrected. --- doc/user/intro/Glossary.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index bf4126e17..92ae5f49b 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -7,10 +7,9 @@ explanations, the long explanation is the topic of the document above..' anchor:AssetsView[] link:#AssetsView[->]Assets View:: Windows displaying and managing various things that can be edited, - worked on, etc are collectively known as the Assets View. - Ingested footage, clips that have already been composed, available - sub-projects, effects, transitions and internal artifacts are typical - examples. + worked on, etc are collectively known as the Assets View. + AssetsView consists of ingested footage, clips that have already been composed, available + sub-projects, effects, transitions and internal artifacts. anchor:Builder[] link:#Builder[->]Builder:: This is a kind of compiler that creates low-level, or processing, graphs From 799a418bbee482b173b1b70afb5e57619bfc35f7 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sat, 25 Aug 2012 19:52:18 +0100 Subject: [PATCH 24/47] InputDevice --- doc/user/intro/Glossary.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index 92ae5f49b..cd2ba0636 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -50,7 +50,9 @@ explanations, the long explanation is the topic of the document above..' anchor:InputDevice[] link:#InputDevice[->]Input Device:: Some hardware controler, like an extra keyboard, midi mixer, Jog, .. - TODO: decide on whether the main keyboard is in a special (global) state. + TODO: we still need to decide on whether we can treat the main keyboard + as special global state or whether we can handle the keyboard as a generic + input devide. anchor:LowLevelModel[] link:#LowLevelModel[->]Low Level Model:: The generated Processing Graph, to be ``performed'' within the engine From fdb78f10f60f417c05701cacb51bd9bc2ea85c5e Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Sun, 26 Aug 2012 16:49:58 +0100 Subject: [PATCH 25/47] Reworked at Froscon 2012 --- doc/user/intro/intro.txt | 180 +++++++++++++++++++++++---------------- 1 file changed, 106 insertions(+), 74 deletions(-) mode change 100644 => 100755 doc/user/intro/intro.txt diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt old mode 100644 new mode 100755 index 1e846a3f1..eaf61e796 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -2,32 +2,33 @@ Lumiera (as seen) from Outer Space ================================== :Author: Lumiera_Core_Developers :Date: Summer 2010 - + [abstract] ****************************************************************************** -The Lumiera Community creates a non linear video editing and compositing FOSS -application for Linux/Unix/Posix Operating Systems, suitable for professional -and quality oriented work, building on common open source video, sound and GUI -toolkits and libraries, providing flexibility and a high degree of -configurability and full control of all parameters, but at the same time a -smooth workflow which scales well to larger and more complicated editing -projects. This Document outlines the Design from some distance, -helping people to understand the Ideas behind Lumiera and understand the tools -they get to work with. It is aimed for workflow designers any anyone who wants -to know how the program works in general. +The Lumiera Community is in the process of making a non-linear video editing +and compositing FOSS application for Linux/Unix/Posix Operating Systems. The +application is geared towards professional, high-quality work; but +it is equally suitable for low-end users, due to its in-design scalability. +Lumiera builds on common open source video, sound and GUI toolkits and +libraries, being highly flexibile, configurable---user-control over a broad +spectrum of configurable parameters---and with smoth workflows that scale well +to larger more intricate projects as and more smaller projects. + +This document outlines the design from a more general perspective, +providing potential users with sufficient insight into the tools and technology +behind Lumiera to get started working with Lumiera quickly. ****************************************************************************** // all things starting with '//' are asciidoc comments and drafts/notes while // working on this document .About this Document -This document is meant to be read electronically, it contains a lot -hyper-links between explanations denoted by an arrow ->. Lumiera is still in -development, we describe here planned features without explicitly tagging them; -some things are not worked out in detail yet. Although this document is heavily -cross-linked we try to start with a broad overview and work out more detailed -things towards the end. +// It contains many hyper-links to explanations which are denoted by an arrow ->. +Lumiera is still under active development. Here we describe planned features +without explicitly tagging them; some points have still to be worked out in +detail. Although this document is heavily cross-linked, we try to start with a +broad overview and developing details towards the end. Vision @@ -35,41 +36,48 @@ Vision // objective and goals of the project -Lumiera claims to be a _professional non-linear video editor_. To start with, we should +Lumiera strives towards being a _professional non-linear video editor_. To start with, we should point out that ``professional'' does not necessarily mean ``commercial'' or ``industrial''. -It's more of an attitude or mindset -- doing work seriously, and to be subject to any -kind of wider goal, demand, or purpose. When it comes to editing film, this might be -artistry, a narration or meaning to convey, a political message or something to show -to your audience. Anyhow, for the tools, the editing software used to this end, -we can identify several properties and requirements, to be labeled ``professional'': +It's more of an attitude or frame of mind -- doing work seriously, and to be subject to any +kind of wider goal, demand, or purpose. + +The concept of professionality in film editing can mean something of an artistic +nature, a narrative or having a meaning to convey, a political message, or +portray something to an audience. + +Anyhow, for the tools, the editing software used to this end, we can identify +several properties and requirements, to be labeled ``professional'': + +With this perspective in mind, we can identify a number of key properties +of professional film production tools: Reliability:: - Whatever happens, your work must be safe, protected against software - glitches and incompatibilities. Ideally Lumiera should be very stable and - never crash, in practice even crashes or power outages should not - result in lost work. + Your work must be safe and protected at all costs against software + glitches and incompatibilities. Ideally, Lumiera should be reliable, + very stable and not crash. In practice, even crashes or power outages + should not result in data or work loss.. Quality:: - If you work with high quality, cinema grade digital video material you - want to be sure that you can deliver crisp quality without compromise, - throughout the whole workflow to your final product. All rendering - must be reproducible to the bit. - + The demands placed on high-quality, cinema grade digital video material + requires crisp-quality without any compromsise throught the entire work + flow in the final product. All rendering will have to be reproducable + down to the last digit. + Performance and Productivity:: - Professionals want to get things done, in time, but optionally with control - over every aspect. Balancing these goals should be the central concern for - workflow design and usability. + Professionals want to get things done, in time and content, but ideally + with control over all details. The fine balance of these goals is a + central goal of workflow design and usability. Scalability and Adaptability:: Projects and budgets differ, hardware advances, Lumiera must scale - in different dimensions and use the available resources as best as it + in different dimensions and use available resources as best it can. From small Laptops to multi core computers and Renderfarms. Durability:: Soft and Hardware advances at a fast pace. We must not lock into the - current state of technology but being flexible to extend the System - without breaking compatibility. Projects you create nowadays with - Lumiera should be usable in foreseeable future, at least there needs + current state of technology but must be flexible enough to extend the + system without breaking compatibility. Projects you create nowadays with + Lumiera should be usable in the foreseeable future, there at least needs to be a guaranteed upgrade path. @@ -137,24 +145,24 @@ final video. Pulling not Pushing ~~~~~~~~~~~~~~~~~~~ -On a first glance, it looks fairly natural to set up the graphs xref:graphs[->] +At a first glance, it looks fairly natural to set up the graphs xref:graphs[->] as described above and then push data into the system through the input nodes whereas the final result can then be seen soon on the output node. Several -multimedia frameworks use this approach. But it has a lot of shortcomings -which make it inappropriate for non-linear video editing. +multimedia frameworks use this approach. However this scheme exhibits a number +of shortcomings which make it inappropriate for non-linear video editing. -Lumiera instead pulls data though the pipe, that is a request starts at the -output node and makes it way up to the inputs. This has certain advantages -xref:pull[->], explained later. +Lumiera instead pulls data though the pipe, i.e., a request starts at the +output node and makes its way up to the inputs. This has certain advantages +xref:pull[->], which will be explained later. Don't waste work ~~~~~~~~~~~~~~~~ -Rendering A/V Data can be quite CPU intensive, to ensure that we do not waste -CPU power by rendering things twice, or the worse, have to throw results away -because they couldn't be rendered in time, we use sophisticated caching -xref:caching[->] and profiling xref:profiling[->]. +Rendering A/V Data can be quite CPU intensive. To ensure that we do not waste +any CPU power by rendering things twice, or worse still, having to throw away +results because it couldn't rendered in time, we use in Lumiera sophisticated +caching xref:caching[->] and profiling xref:profiling[->]. The visible Universe @@ -180,18 +188,14 @@ xref:screenconcept[->] to adapt to different workplaces and workflows. Viewer ~~~~~~ -[red]#to be written# - -// only one viewer type used for everything -// how is audio integrated in the viewer -// effects may add overlays (masking/rotoscoping, information for example) -// these may be manipulateable in the viewer, but not part of the rendered -// video. Maybe effects can add widgets to the viewer too (how, where?) -// one can open as many viewers he needs -// these can be attached everyhere in the processing graph (pre/post effect) -// have bus in front to adapt output format -// detachable window, fullscreen, external screen +The viewer is an area where material can be displayed, i.e., ``play-back'', +which also supports audio playback connections. As there are many sources that +can be displayed, a viewer is attached to a source via the viewer switch board. +Timelines, probepoints, wiretaps and individual clips are examlpes of sources +that can be atached to a viewer. Moreover, the number of viewers open at any one +time is only limited by the hardware, and each viewer can be collapsed, hooked +up to a beamer or monitor. Transport Controls @@ -222,13 +226,26 @@ no magic here. Timeline View ~~~~~~~~~~~~~ -hierarchical tracks, not just a list +A timeline is a container that provides a time axis and an output. The output +can de derived from various sources and have different configurations. An +output can have various configurations, for each output configuration, there +will be one timeline. A timeline does not temporally arrange material, this is +performed by a sequence, which can be snapped to a timeline. -Format Independent Timeline, one can put anything on the timeline. -the busses constrain what kind of data is pulled out and in turn the -builder creates a processing graph which does the necessary conversions and -stuff. +A typical film will define many sequences, but only a few timelines. A sequence +contains a number of tracks which are ordered in a hierarchy. Tracs do not have +any format associated with them and more or less anything can be put into a +track. Consequently, audio and video material can be equally assigned to a +track, there is no discrimination between audio and video in the Lumiera concept +of a track. +A timeline must be assigned to viewer if playback viewing is desired. + +//Format Independent Timeline, one can put anything on the timeline. +//the busses constrain what kind of data is pulled out and in turn the +//builder creates a processing graph which does the necessary conversions and +//stuff. +// // Q: how to handle interaction, for example when some conversion can only be // done in a lossy way and some conversion node may or may not be inserted // (i mean gui wise)? @@ -246,19 +263,30 @@ stuff. Busses ~~~~~~ + The GUI provides a separate _bus view_, showing the master busses (subgroups) -in a manner similar to an audio mixing desk. Any bus is just a means to collect -and sum up the output of a specific kind of media (video, audio, number of channels), -produced by various processing elements and other busses. Conceptionally, these global -busses are considered a part of the timeline +in a manner similar to an audio mixing desk. Any bus is just a means of collecting +and and adding (aka overlaying) together the output of various kinds of media +(video, audio, number of channels), produced by various processing elements and +from other busses. These global busses can be concieved as being part of the +timeline. Asset View ~~~~~~~~~~ +We can conceive the Asset View as the timeline's book keeper: it manages the various +constituent in the timeline. Moreover, in addition to managing timeline +constituents, raw material, clips, bins (folders) are managed by the Asset +View, i.e., typical management operations including, deleting, adding, +naming, tagging, groupping into bins, etc. all occur here. + +Plugins are also managed in the Asset View. + + Manages all assets available in one project. * source media/footage/soundfiles - * prepared clips, known subprojects + * all available effects and transitions * internal artefacts like sequences and automation data sets @@ -285,18 +313,20 @@ Manages all assets available in one project. Dark Matter ----------- -[red]#to be written# -coarse overview about things the user does not see but have some contact -with, details later... +The material in this section provides a cursory view of features not required by +a typical user, but of more importance to people loking under the hod, i.e., +programers, etc. -Now lets take a look under the hood. Session storage ~~~~~~~~~~~~~~~ [red]#to be written# + + +//databank with logging, no data loss. // not generateable data // its the timeline mostly @@ -406,6 +436,8 @@ and only provide limited functionality without any plug-ins. Lumiera will not reinvent the wheel. One major goal is to provide considerable functionality via well-designed, external code supplied to Lumiera by plug-ins. +How are Plugins Implemented? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From c28ff6a0ab71eed01b4b4fd3f38bb902ac1f673e Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Wed, 29 Aug 2012 16:54:05 +0100 Subject: [PATCH 26/47] Added some intro stuff --- doc/user/tutorials/contributing.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/user/tutorials/contributing.txt b/doc/user/tutorials/contributing.txt index df10c1a0d..6658706ae 100644 --- a/doc/user/tutorials/contributing.txt +++ b/doc/user/tutorials/contributing.txt @@ -1,6 +1,22 @@ Contributing to Lumiera ======================= +All files in the Lumiera project are managed by *Git*. Although *Git* was +primarily brought to life to manage source code, it plays a fundamental role in +Lumiera project communication and contributing to Lumiera. +If you'd like to contribute to Lumiera, you will have to acquire some +understanding of *Git* at some stage or other. Please note, this is not the only +way to contribute to Lumiera, you can always send direct contributions to the +mailing list. + + +a powerful tool +that not only + + + which is a distributed +source code management system. + The Lumiera project uses an infrastructure based on *Git*, the distibuted sourcecode management software. This deliberately places the barrier for contributing very low: No formal ``commit right'' is necessary; you can @@ -10,6 +26,8 @@ For starters, follow the http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[basic instructions] for using Git, notably the following parts: +http://gitref.org/ + ------------------------------------------------------------ $ git config --global user.name "Your Name Comes Here" $ git config --global user.email you@yourdomain.example.com From dbc8355a3fe97dae74e8e40e878501a92109d997 Mon Sep 17 00:00:00 2001 From: Benny Lyons Date: Wed, 29 Aug 2012 16:55:00 +0100 Subject: [PATCH 27/47] More corrections. Text for I/O --- doc/user/intro/intro.txt | 95 ++++++++++++++++++++++++++-------------- 1 file changed, 63 insertions(+), 32 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index eaf61e796..6e77f2523 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -7,17 +7,17 @@ Lumiera (as seen) from Outer Space [abstract] ****************************************************************************** The Lumiera Community is in the process of making a non-linear video editing -and compositing FOSS application for Linux/Unix/Posix Operating Systems. The +and compositing FOSS application for Linux/Unix/Posix operating systems. The application is geared towards professional, high-quality work; but it is equally suitable for low-end users, due to its in-design scalability. Lumiera builds on common open source video, sound and GUI toolkits and libraries, being highly flexibile, configurable---user-control over a broad -spectrum of configurable parameters---and with smoth workflows that scale well -to larger more intricate projects as and more smaller projects. +spectrum of configurable parameters---and with smooth workflows that scale well +to larger more intricate projects and smaller projects. This document outlines the design from a more general perspective, providing potential users with sufficient insight into the tools and technology -behind Lumiera to get started working with Lumiera quickly. +behind Lumiera to start working with Lumiera quickly. ****************************************************************************** // all things starting with '//' are asciidoc comments and drafts/notes while @@ -28,7 +28,7 @@ behind Lumiera to get started working with Lumiera quickly. Lumiera is still under active development. Here we describe planned features without explicitly tagging them; some points have still to be worked out in detail. Although this document is heavily cross-linked, we try to start with a -broad overview and developing details towards the end. +broad overview, then develop details towards the end. Vision @@ -39,7 +39,7 @@ Vision Lumiera strives towards being a _professional non-linear video editor_. To start with, we should point out that ``professional'' does not necessarily mean ``commercial'' or ``industrial''. It's more of an attitude or frame of mind -- doing work seriously, and to be subject to any -kind of wider goal, demand, or purpose. +kind of wider goal, requirement, or purpose. The concept of professionality in film editing can mean something of an artistic nature, a narrative or having a meaning to convey, a political message, or @@ -87,20 +87,21 @@ Fundamental Forces // the basic ideas which drive the Lumiera design The Lumiera design is guided by a small number of basic principles. Keeping -these in mind will help to understand how actually more interesting things can -be built up on that foundation. +these principles in mind will help you understand how more interesting things can +be built up from these fundamental principles. -Open ended combining of Building Blocks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Open Ended Combination of Building Blocks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Lumiera is not so much defined in terms of _features_ -- rather it allows to -combine basic _building blocks._ These basic modules, entities or objects each -have a distinct _type_ explicitly limiting the connections. Within these -limits, any conceivable combination shall be supported without further hidden -limitations. +Lumiera is not so much defined in terms of _features_. It is more like a +workshop, where individual _basic building-blocks_ can be combined together in +interesting ways to form more complex structures. These basic modules, entities +or objects each have a distinct _type_ explicitly limiting the +connections. Within these limits, any conceivable combination is supported +without further hidden limitations. -Lumiera is neither a set of Lego bricks, nor is it the business application +Lumiera is neither a set of Lego bricks, nor is it a business application driven by finite usage stories. @@ -112,13 +113,17 @@ user may, if desired, directly manipulate through the GUI clips, individual effects, masks, and even the placements xref:placement[->] used to stitch the objects together, which is comparatively low-level. On the other hand, these abstractions shield the user from the actual technical details like format -conversions and the accessing of individual channels. +conversions and accessing individual channels. To complement this approach, Lumiera does _not_ rely on hard wired, global conventions -- rather we allow to build up project specific conventions and rules xref:rules[->] to fit the given requirements and preferred working -style. To help getting started, Lumiera will ship with a fairly conventional -project template and default configuration. +style. + +To ease the user in getting started with Lumiera, it will be supplied with a +rather conventional template and a default configuration will be supplied that +is relative conventional. + [[graphs]] @@ -174,15 +179,17 @@ Now its time to take a look at the prelimary Lumiera GUI: image:{l}/images/lumiera_gui_small.png[Current Lumiera GUI Screenshot] -The GUI is a plugin by itself and only one way to work Lumiera, it will become -possible to create special-purpose GUIs or control Lumiera in different ways, -like a headless rendernode xref:rendernode[->] or frameserver -xref:frameserver[->]. Completely script driven interfaces for automated -processing are also planned. -The GUI screenshot you see above is faily default as when you start Lumiera up -for the first time (the plan is to add a 2nd Viewer to the default -configuration). While we support a much more sophisticated screen concept +Lumiera consists of three major parts: the GUI, proc and backend. The initial +GUI Lumiera will ship with is not the only GUI possible, indeed Lumiera can work +satisfactorily without a GUI, for example, for specail purposes. +headless rendernode xref:rendernode[->] or frameserver +xref:frameserver[->]. Later scripts will be written for automated +processing. Special purpose GUIs are also envisaged later. + +The GUI screenshot you above is more or less the default you see when when you +start Lumiera up for the first time. A 2nd viewer is planned for later to be +added to the default. We support a much more sophisticated screen concept xref:screenconcept[->] to adapt to different workplaces and workflows. @@ -314,10 +321,11 @@ Dark Matter ----------- The material in this section provides a cursory view of features not required by -a typical user, but of more importance to people loking under the hod, i.e., +a typical user, but of more importance to people loking under the hud, i.e., programers, etc. - +Most of the material in this section is to be found in the proc layer and in the +backend. Session storage @@ -365,9 +373,32 @@ rendering... rules system [red]#to be written# -I/O Subsystem -~~~~~~~~~~~~~ -[red]#to be written# +Input-Output Subsystem +~~~~~~~~~~~~~~~~~~~~~~~ + +Lumiera will process large quantities of data and it is of critical imnportance +to perform this efficiently. The input and output subsystem are all processed +in the backend, in fact, this is one very important function provided by the +back end. + +The typical Lumiera user will have many clips, in various configurations located +at various places. All this data will have to be stored by the backend, +moreover all this data will have to be rapidly retrieved from storage and +provided to the user. The demands on memory are high: huge chunks of data, +that can be quickly stored and equally quickly fetched, even if stored over +longer periods of time. Moreover, due to the scalability requirement of Lumiera, +this process will have to perform adequately on lower-end hardware, and perform +efficiently on higher-end hardware. + +Lumiera will break down processes that need to be processed into smaller units +called _tasks_. Typically, there will be many hundreds of tasks waiting for +processing at any one time. These tasks are qued for processing and the order in +which this is performed is managed by the _scheduler_. This is all done in the +back end. + +Apart from memory, the backend will be responsible for accessing and saving +files. It will be of the utmost to do this efficiently. This will be carried out +in the backend using low-level mechanisms. // file handling // vault, work, cache From 88cd5d67cd3aeff2bc3ad4c4a4f0ee0268fb549f Mon Sep 17 00:00:00 2001 From: Benny Date: Sun, 30 Dec 2012 20:23:01 +0100 Subject: [PATCH 28/47] Section Vision completely reworked wrt language. --- doc/user/intro/intro.txt | 57 +++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 6e77f2523..c09e9b995 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -36,50 +36,53 @@ Vision // objective and goals of the project -Lumiera strives towards being a _professional non-linear video editor_. To start with, we should -point out that ``professional'' does not necessarily mean ``commercial'' or ``industrial''. -It's more of an attitude or frame of mind -- doing work seriously, and to be subject to any -kind of wider goal, requirement, or purpose. - -The concept of professionality in film editing can mean something of an artistic -nature, a narrative or having a meaning to convey, a political message, or -portray something to an audience. +Lumiera strives towards being a _professional non-linear video editor_. It is +important to note that by ``professional'' we do not necessarily imply +``commercial'' or even ``industrial''. We do, however, wish to suggest an +attitude or frame of mind in how this work is approached, but not the goal, +requirement or purpose of this work. The concept of professionality in film +editing can indicate something of an artistic nature, suggest that there is a +narration, meaning or political messages revealed by the work; or, simply, that +the work attempts to convey something to an audience. Anyhow, for the tools, the editing software used to this end, we can identify several properties and requirements, to be labeled ``professional'': With this perspective in mind, we can identify a number of key properties -of professional film production tools: +film production tools should have and be professional: Reliability:: - Your work must be safe and protected at all costs against software - glitches and incompatibilities. Ideally, Lumiera should be reliable, - very stable and not crash. In practice, even crashes or power outages - should not result in data or work loss.. + All work must be secure and be safe against any software glitches, + incompatibility or instability. Ideally, Lumiera should be reliable, + very stable and not susceptible to software crashes, i.e., crashes or + power failure should ideally not result in data or work loss. Quality:: The demands placed on high-quality, cinema grade digital video material - requires crisp-quality without any compromsise throught the entire work - flow in the final product. All rendering will have to be reproducable - down to the last digit. + requires crisp-quality results with no concessions made throughout the + entire workflow that might compromise quality of the final work. + It will be necessary to be able to reconstruct all rendering down to a + single digit. Performance and Productivity:: - Professionals want to get things done, in time and content, but ideally - with control over all details. The fine balance of these goals is a + Professionals want to get things done in time and content, but, ideally, + with control over all detail. The fine balance of these goals is a central goal of workflow design and usability. Scalability and Adaptability:: - Projects and budgets differ, hardware advances, Lumiera must scale - in different dimensions and use available resources as best it - can. From small Laptops to multi core computers and Renderfarms. + Projects and budgets differ, hardware advances; and Lumiera must scale + in different dimensions and make optimum use of the resources that are + available. From small Laptops to multi-core computers up to render farms, + Lumiera must be adept in optimum use of the hardware at hand. Durability:: - Soft and Hardware advances at a fast pace. We must not lock into the - current state of technology but must be flexible enough to extend the - system without breaking compatibility. Projects you create nowadays with - Lumiera should be usable in the foreseeable future, there at least needs - to be a guaranteed upgrade path. - + The rapid pace at which software and hardware rampage forward is surely + a warning to new software projects and the dangers of locking into any + current technological ``fashion'' to achieve a ``cheap'' goal, feature + or performance boost. Once the fad fades, the software woes begin. + The software must be able to engage new technological developments + without any compromise to functionality or backward compatibility. + Fundamental Forces ------------------ From 2195fdad8427fab727bd411965679bfc63bdacfa Mon Sep 17 00:00:00 2001 From: Benny Date: Sun, 30 Dec 2012 21:20:24 +0100 Subject: [PATCH 29/47] DOC: Fundamental Forces, language corrected. Section Fundamental Forces corrected, all sub-sections corrected. Some sub-sections slightly expanded for clarification purposes. Some awkward expressrions removed, replaced or expanded. --- doc/user/intro/intro.txt | 87 ++++++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 40 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index c09e9b995..443b32093 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -97,80 +97,87 @@ be built up from these fundamental principles. Open Ended Combination of Building Blocks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Lumiera is not so much defined in terms of _features_. It is more like a -workshop, where individual _basic building-blocks_ can be combined together in -interesting ways to form more complex structures. These basic modules, entities -or objects each have a distinct _type_ explicitly limiting the -connections. Within these limits, any conceivable combination is supported -without further hidden limitations. +Lumiera is not so much defined in terms of _features_. Instead it can be better +envisaged as a workshop in which the emphasis is on individual +_basic building-blocks_ that can be combined together in interesting ways to +form more complex structures. These basic modules, entities +or objects each have a distinct _type_ which explicitly limits the +connections between the modules. Within these limits, any conceivable +combination is possible without additional hidden restrictions. -Lumiera is neither a set of Lego bricks, nor is it a business application +Lumiera is not a set of Lego bricks, nor is it a business application driven by finite usage stories. -Medium level Abstraction and Project specific Conventions +Medium Level Abstraction and Project Specific Conventions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These building blocks within Lumiera create a moderate level of abstraction; a -user may, if desired, directly manipulate through the GUI clips, individual -effects, masks, and even the placements xref:placement[->] used to stitch the -objects together, which is comparatively low-level. On the other hand, these -abstractions shield the user from the actual technical details like format -conversions and accessing individual channels. +user may, if desired, directly manipulate -- using, for example, GUI clips -- +individual effects, masks, and even the placements xref:placement[->] used to +stitch the objects together, which is comparatively low-level. Such abstraction +protects the user from technical details such as format conversion or access +to individual channels. -To complement this approach, Lumiera does _not_ rely on hard wired, global -conventions -- rather we allow to build up project specific conventions and -rules xref:rules[->] to fit the given requirements and preferred working -style. - -To ease the user in getting started with Lumiera, it will be supplied with a -rather conventional template and a default configuration will be supplied that -is relative conventional. +To complement this approach, Lumiera does _not_ rely on hard-wired, global +conventions -- rather we allow the building up of project specific conventions and +rules xref:rules[->] to fit a given requirement and preferred working style. +Lumiera will be supplied with a conventional template and a default +configuration to ease the learning curve #for new users. [[graphs]] Rendering is Graph Processing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Processing of Video (and audio) data can be generalized as graph processing -(more precisely ``directed acyclic graphs''). Data flows on the edges of these -graphs and is processed in the nodes. +Processing video (and audio) data can be conceived as a graph (more precisely +``directed acyclic graphs''). In this model of video processing, data flows +along the edges of the graph and is processed at the nodes. + +The following figure depicts manipulating video data as a graph. The nodes of +the root of the graph is where data input occurs. From there, the data moves on +to the next nodes: the direct syblings of the root. Here, the video data +pre-processing occurs. All other operations on the data can be represented by +nodes, and data flows from one operation to the next along the nodes of the +graph. + image:{imgd}/lumiera_big_graph.png[Example for a graph] When we look at this model we discover that we only need to build xref:builder[->] such graphs, the nodes themselves can be seen as black boxes and will be implemented by plugins xref:plugins[->]. Moreover one can -preconfigure subgraphs and handle them as single entity xref:pluginstack[->]. +pre-configure subgraphs and handle them as a single entity xref:pluginstack[->]. -In Lumiera everything will be translated into such a graph. Your footage will -be demultiplexed xref:demultiplexer[->] at a first node, down to the encoding -xref:encoder[->] and multiplexer xref:multiplexer[->] which assembles the -final video. +In Lumiera everything will be translated into such a graph. Footage will +be demultiplexed xref:demultiplexer[->] at the first node, thereafter to the +encoding stage xref:encoder[->] and on to the multiplexer xref:multiplexer[->] +which assembles the final video. Pulling not Pushing ~~~~~~~~~~~~~~~~~~~ At a first glance, it looks fairly natural to set up the graphs xref:graphs[->] -as described above and then push data into the system through the input nodes -whereas the final result can then be seen soon on the output node. Several -multimedia frameworks use this approach. However this scheme exhibits a number -of shortcomings which make it inappropriate for non-linear video editing. +as described above. Data can then be pushed into the system through the input +nodes and the final result can be seen at the output node. Several multimedia +frameworks use this approach. However this scheme exhibits a number of +shortcomings which make it inappropriate for non-linear video editing. -Lumiera instead pulls data though the pipe, i.e., a request starts at the -output node and makes its way up to the inputs. This has certain advantages -xref:pull[->], which will be explained later. +Lumiera takes a different approach. Data is pulled through a pipe, i.e., a +request starts at the output node and makes its way back up through the graph to +the inputs. This scheme offers a number of advantages over the naive scheme +xref:pull[->], beu we will defer the reasons until later. Don't waste work ~~~~~~~~~~~~~~~~ -Rendering A/V Data can be quite CPU intensive. To ensure that we do not waste -any CPU power by rendering things twice, or worse still, having to throw away -results because it couldn't rendered in time, we use in Lumiera sophisticated -caching xref:caching[->] and profiling xref:profiling[->]. +Rendering A/V data can be CPU intensive. To relieve the CPU workload by not +rendering material twice or avoiding having to throw away material because it +could not be rendered in time, Lumiera employs a sophisticated means of using +cache xref:caching[->] and profiling xref:profiling[->]. The visible Universe From 7e26d5718ebff08e2371c6773b684a882e505be2 Mon Sep 17 00:00:00 2001 From: Benny Date: Sun, 30 Dec 2012 21:28:21 +0100 Subject: [PATCH 30/47] DOC: Abstract, small typo correction to this section. --- doc/user/intro/intro.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 443b32093..cebe0ad9d 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -11,8 +11,8 @@ and compositing FOSS application for Linux/Unix/Posix operating systems. The application is geared towards professional, high-quality work; but it is equally suitable for low-end users, due to its in-design scalability. Lumiera builds on common open source video, sound and GUI toolkits and -libraries, being highly flexibile, configurable---user-control over a broad -spectrum of configurable parameters---and with smooth workflows that scale well +libraries, being highly flexibile, configurable -- user-control over a broad +spectrum of configurable parameters -- and with smooth workflows that scale well to larger more intricate projects and smaller projects. This document outlines the design from a more general perspective, From 6272fb80360990538677e64984f705c6aa9c7a28 Mon Sep 17 00:00:00 2001 From: Benny Date: Sun, 30 Dec 2012 22:34:53 +0100 Subject: [PATCH 31/47] DOC: The Visible Universe, language reworked. --- doc/user/intro/intro.txt | 94 +++++++++++++++++++++++----------------- 1 file changed, 55 insertions(+), 39 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index cebe0ad9d..4def71f6f 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -190,26 +190,41 @@ Now its time to take a look at the prelimary Lumiera GUI: image:{l}/images/lumiera_gui_small.png[Current Lumiera GUI Screenshot] -Lumiera consists of three major parts: the GUI, proc and backend. The initial -GUI Lumiera will ship with is not the only GUI possible, indeed Lumiera can work -satisfactorily without a GUI, for example, for specail purposes. -headless rendernode xref:rendernode[->] or frameserver -xref:frameserver[->]. Later scripts will be written for automated -processing. Special purpose GUIs are also envisaged later. +Lumiera consists of three major parts: +- Graphical User Interface (GUI) +- Proc layer +- Backend -The GUI screenshot you above is more or less the default you see when when you -start Lumiera up for the first time. A 2nd viewer is planned for later to be -added to the default. We support a much more sophisticated screen concept -xref:screenconcept[->] to adapt to different workplaces and workflows. +In this section, we discuss only the GUI. + +Lumiera will initially ship with a standard, default GUI. This, however, is not +the only GUI possible to operate Lumiera. Indeed, Lumiera can work +satisfactorily without a GUI, for example, for special purposes. +headless rendernode xref:rendernode[->] or frameserver +xref:frameserver[->]. At a later stage in the project, scripts will be written +to faciltate automated processing. GUIs geared towrads special purposes are +also envisaged later. + +The screenshot of the GUI presented above is more or less the standard GUI when +it is started for the first time without any user configuration etc. A second +viewer is planned for later to be added to the default. We support a much more +sophisticated screen concept xref:screenconcept[->] to adapt to different +workplaces and workflows. + +At a first glance, the GUI might seem somewhat overwhelming, something similar +to the cockpit of a jumbo jet. However, nearly all the bells and whistles can +be subdivided into groups according to their functionality. The following +sub-sections discusses the more prominent groupings. Viewer ~~~~~~ -The viewer is an area where material can be displayed, i.e., ``play-back'', -which also supports audio playback connections. As there are many sources that +The viewer is an area where material can be displayed, i.e., ``play-back''. +A viewer is a window where material can not only be played back or viewed, but +support for audio will also be provided. As there are many sources that can be displayed, a viewer is attached to a source via the viewer switch board. -Timelines, probepoints, wiretaps and individual clips are examlpes of sources +Timelines, probepoints, wiretaps and individual clips are examples of sources that can be atached to a viewer. Moreover, the number of viewers open at any one time is only limited by the hardware, and each viewer can be collapsed, hooked up to a beamer or monitor. @@ -218,21 +233,22 @@ up to a beamer or monitor. Transport Controls ~~~~~~~~~~~~~~~~~~ -The layout in current gui is rather preliminary -- it is not finally decided -where transport controls will be integrated; possibly as its own gui element +The preliminary layout in the current gui is rather provisional -- a final decision +has yet to be taken on where the transport controls will be located. In later +versions of the standard GUI, the transport controls will change. There is even +a possibility that the transport controls will be allocated their own GUI element. -This are devices either controlled by widgets or by some input device -(MIDI, control surface, etc) so their gui may look differently. -Either way they connect to a Play Controler xref.. in the core which -manages playing and cursor positioning. - -thus there will be some gui facility to attach Transport controls to Play -Controllers. Transport controls are ganged when they attach to the same -Play Controler. - -just playing some footage for preview creates a simple internal timeline, -no magic here. +Transport controls are devices that are controlled by widgets or by some input device +(MIDI, control surface, etc) so the look-and-feel of the transport control +widget may vary, depending on what the transport controls have been assigned +to. Irrespective of their look-and-feel, they are connected to a play +controller. +// TODO xref.. +A play controller coordinates playback, cueing and rewinding. Transport +controls are ganged when they attach to the same play controler. +// just playing some footage for preview creates a simple internal timeline, +// no magic here. // TODO: bit unrelated, think about how ganging controls in general should // work, also for faders, masks and so on // Note by Ichthyo: the connection to a fader is handled through the placements, @@ -244,17 +260,17 @@ Timeline View ~~~~~~~~~~~~~ A timeline is a container that provides a time axis and an output. The output -can de derived from various sources and have different configurations. An +can be derived from various sources, each with a different configuration. An output can have various configurations, for each output configuration, there will be one timeline. A timeline does not temporally arrange material, this is -performed by a sequence, which can be snapped to a timeline. +performed by a sequence, which can be connected (snapped) to a timeline. -A typical film will define many sequences, but only a few timelines. A sequence -contains a number of tracks which are ordered in a hierarchy. Tracs do not have -any format associated with them and more or less anything can be put into a -track. Consequently, audio and video material can be equally assigned to a -track, there is no discrimination between audio and video in the Lumiera concept -of a track. +A typical film will define many sequences, but will only have a few timelines. A +sequence contains a number of tracks which are ordered in a hierarchy. Tracs do +not have any format associated with them and more or less anything can be put +into a track. Consequently, audio and video material can equally be assigned to +a track, there is no discrimination between audio and video in the Lumiera +concept of a track. A timeline must be assigned to viewer if playback viewing is desired. @@ -280,10 +296,10 @@ A timeline must be assigned to viewer if playback viewing is desired. Busses ~~~~~~ - +// TODO: needs rewriting. The GUI provides a separate _bus view_, showing the master busses (subgroups) in a manner similar to an audio mixing desk. Any bus is just a means of collecting -and and adding (aka overlaying) together the output of various kinds of media +and and adding (aka overlaying) together output of various kinds of media (video, audio, number of channels), produced by various processing elements and from other busses. These global busses can be concieved as being part of the timeline. @@ -291,8 +307,8 @@ timeline. Asset View ~~~~~~~~~~ -We can conceive the Asset View as the timeline's book keeper: it manages the various -constituent in the timeline. Moreover, in addition to managing timeline +An Asset View can be conceived as the timeline's book keeper: it manages the +various constituents in the timeline. Moreover, in addition to managing timeline constituents, raw material, clips, bins (folders) are managed by the Asset View, i.e., typical management operations including, deleting, adding, naming, tagging, groupping into bins, etc. all occur here. @@ -302,8 +318,8 @@ Plugins are also managed in the Asset View. Manages all assets available in one project. - * source media/footage/soundfiles + * source media/footage/soundfiles * all available effects and transitions * internal artefacts like sequences and automation data sets From 9a6202aac22d8866fb744c513d612cd8c750d8fa Mon Sep 17 00:00:00 2001 From: Benny Date: Sun, 30 Dec 2012 23:09:19 +0100 Subject: [PATCH 32/47] DOC: Session Storage, very general introduction without tech. details. --- doc/user/intro/intro.txt | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 4def71f6f..3be4d7a45 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -354,10 +354,29 @@ Most of the material in this section is to be found in the proc layer and in the backend. -Session storage +Session Storage ~~~~~~~~~~~~~~~ -[red]#to be written# +[red]#Deatils to be written# +The current representation of a project resident in memory is internally known +as a session, whereas from a GUI user perspective, this is known as a project. +In this section, we will use the term ``session'' as we discussing the internals +of Lumiera here. +Everything is stored in a session. If a user saves a session, then there should +be no difference to the user whether they continue working or throw all their +work away and load the session that has just been saved. In other words +``everything is stored in a session!'' + +This ambitious goal has a number of advantages. If all steps are to be stored, +then all steps must be available as an object to be stored. We can perform +operations on these objects. For example unlimited ability to undo previous +steps, selective undo of previous steps or the possibility of merging various +steps might even be a possibility. For example, work on a project at the +office and work on the same project at home can be merged each morning and +evening. + +Session storage is envisaged to be performed as databank with logging, some +search facilities and a number of features associated with databanks. //databank with logging, no data loss. @@ -375,7 +394,7 @@ Placements ~~~~~~~~~~ Generic mechanism to stitch together media objects. Any placement may contain -a list of conditions how to locate the placed object, examples being +a list of conditions on how to locate the placed object, examples being time-absolute/relative, relative to another object, or relative to some specific source media frame. From d1aee6a066e09505b31445ff2252f55db89f94c1 Mon Sep 17 00:00:00 2001 From: Benny Date: Tue, 1 Jan 2013 16:04:27 +0100 Subject: [PATCH 33/47] DOC: errors corrected, new sections. Some obvious typos were corrected. Other material improved. The section on Git was considerably improved. An entirely new section on Git was added, but which contains some previous material on git. The reason for adding a new section on Git was I though it better to have one single place where someone new to Git and Lumiera could read a simple recipe-type explanation on how to retrieve source code, make changes and then push the changes. All information necessary including Git, links, etc should be on this page, no following liknks. In fact there is no real _new_ information here that isn't to be found somewhere else. The point being that _all_ information necessary to ge someone up and going is located on one page. For this reason, I added information on the mailing list and IRC; again, all essential information in how to contribute to Lumiera, the title ang goal of this page. There might be stuff missing here, so please add, but do not make this page too long. That tends to scare people, in fact, someone might just like to shorten my contributions here, that would be good! --- doc/user/tutorials/contributing.txt | 117 +++++++++++++++++++++++----- 1 file changed, 96 insertions(+), 21 deletions(-) diff --git a/doc/user/tutorials/contributing.txt b/doc/user/tutorials/contributing.txt index 6658706ae..aa73a496e 100644 --- a/doc/user/tutorials/contributing.txt +++ b/doc/user/tutorials/contributing.txt @@ -3,41 +3,91 @@ Contributing to Lumiera All files in the Lumiera project are managed by *Git*. Although *Git* was primarily brought to life to manage source code, it plays a fundamental role in -Lumiera project communication and contributing to Lumiera. -If you'd like to contribute to Lumiera, you will have to acquire some +the Lumiera project. It is central to communication and contribution in the +project. If you'd like to contribute to Lumiera, you will have to acquire some understanding of *Git* at some stage or other. Please note, this is not the only way to contribute to Lumiera, you can always send direct contributions to the mailing list. - -a powerful tool -that not only - - - which is a distributed -source code management system. - The Lumiera project uses an infrastructure based on *Git*, the distibuted sourcecode management software. This deliberately places the barrier for -contributing very low: No formal ``commit right'' is necessary; you can -start right away and present your first results in the _mob repository_. +contributing very low: No formal ``commit permission'' is necessary; you can +start right away and present your first results to the _mob repository_. -For starters, follow the + + +Git: Lumiera Essentials +----------------------- + +One very useful place to begin with using Git is the following: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[basic -instructions] for using Git, notably the following parts: +instructions]. In particular, the following parts: http://gitref.org/ +In the following, we assume you have set up Git on your system. If you are +experiencing problems with Git, just ask the Lumiera community. + + +Letting People Know Who You Are +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ------------------------------------------------------------ $ git config --global user.name "Your Name Comes Here" $ git config --global user.email you@yourdomain.example.com ------------------------------------------------------------ -If you followed the link:building.html[building-lumiera tutorial], you created -already a local clone of the Lumiera repository. So you are ready to go, -you can edit build and commit your changes to the lumiera code locally in -your cloned repository. Please commit frequently, do small commits which -fix/improve only one single thing and use meaningful commit messages. +Obtaining Lumiera Code +~~~~~~~~~~~~~~~~~~~~~~ + +------------------------------------------------------------ +$ git clone git://git.lumiera.org/LUMIERA +------------------------------------------------------------ + +If everything goes ok, you should have the Lumiera source code. However, you do +not have enough code to build as there are some external packages missing that +are required to build Lumiera. Please refer to the +link:building.html[building-lumiera tutorial] on how to obtain all packages to +build Lumiera. + + +Contributing +~~~~~~~~~~~~ + +So you are ready to go, you can edit and commit your changes to the +lumiera code locally in your cloned repository. Please commit frequently, do +small commits which fix or improve only one single thing and try to use +meaningful commit messages. + +Let's assume, as an example, you've made changes to this file: +_.../doc/users/tutorials/contributing.txt_. + +Here's how to add your changes to Git: + +------------------------------------------------------------ +$ cd .../doc/users/tutorials +$ git add contributing.txt +$ git commit contributing.txt -m "Corrected a grammatical error in section Git" +------------------------------------------------------------ + +You can, of course, add more detailed information to your commit message. To do +this, you'll have to set-up git to use your favourite editor. Here's how to get +Git to use emacs: + +------------------------------------------------------------ +$ git config --global core.editor emacs +------------------------------------------------------------ + +Then while commiting, do not use the _-m_ option. Your editor will appear +requiring you to enter your comments. Enter, as your first line, a one line +summary of less than 80 characters in length (some applications use this line +for various purposes and longer entries tend to cause difficulties). +The line following your one line summary should be blank. Then on the third +line, you can begin your exposition on your changes. + + +Publishing Your Contribution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Check that you didn't break anything, by running the testsuite. @@ -47,7 +97,32 @@ Finally you can push your changes to the lumiera server to the 'mob' repository: $ git push git://git.lumiera.org/lumiera/mob master:refs/heads/YOURNAME ------------------------------------------------------------ -This creates a new branch 'YOURNAME' on the mob repository. Then you notify the -other devs on the mailinglist and they may merge your code into the mainline. +This creates a new branch 'YOURNAME' on the mob repository. + +Check that indeed your changes are public by visiting +http://www.lumiera.org/gitweb [http://www.lumiera.org/gitweb]. The lumiera/mob +repository should indicate 'right now' as its _Last Change_ entry. + +Thereafter, notify the other developers on the mailinglist and they may merge +your code into the main project line. + + +Lumiera Communication Channels +------------------------------ + + +The Mailing List +~~~~~~~~~~~~~~~~ + +lumiera@lists.lumiera.org + + +IRC Meetings +~~~~~~~~~~~~ +The Lumiera community generally meets on the second Wednesday of each month at +20:00 uucp on: _freenode #Lumiera_. + +All are more than welcome to join and to contribute to the discussions there. + From 4dab7d8667e157ed83001d59c059cb6c56717557 Mon Sep 17 00:00:00 2001 From: Benny Date: Thu, 3 Jan 2013 02:59:22 +0100 Subject: [PATCH 34/47] DOC: corrected --- doc/user/tutorials/building.txt | 125 +++++++++++++++++++------------- 1 file changed, 73 insertions(+), 52 deletions(-) diff --git a/doc/user/tutorials/building.txt b/doc/user/tutorials/building.txt index 0092da1cc..4591637a9 100644 --- a/doc/user/tutorials/building.txt +++ b/doc/user/tutorials/building.txt @@ -1,13 +1,19 @@ Building Lumiera from source ============================ -Currently, after building the application, you can try out the Lumiera GUI -and you can run the test suite. This tutorial details the basic procedure -to compile Lumiera on a Linux (or comparable) system. We'll assume that -the reader has acquired basic _commandline survival skills_ and is able -to figure out the usage of the Git version management system from the -documentation (but we'll mention each actually required command -explicitly) +At the moment you can build Lumiera, start the standard Lumiera GUI and run the +Lumiera test suite. + +This tutorial outlines the fundamental steps required to compile Lumiera on +Linux (or a comparable) system. We'll assume that you have a certain familiarity +with _commandline survival skills_ on your system. Although Git is required if +you do not use the Debian package, we'll explicitly provide all giot commands. + +There are two distinct methods to build: + +- use the Debian source code package of Lumiera +- use Git to retrieve all source code + NOTE: just compiling Lumieara on a _Debian-based_ system (e.g. Ubuntu) is much simpler using the Debian source package. See the separate @@ -16,24 +22,30 @@ NOTE: just compiling Lumieara on a _Debian-based_ system (e.g. Ubuntu) The purpose of this tutorial here is to show you the elementary and generic steps to compile Lumiera from source. -For building Lumiera, besides the GNU C/C++ compiler (Version 4.X), you will need: + +Requirements +------------ + +To build Lumiera, you'll require GNU C/C++ compiler (Version 4.X) in addition to +the following: * link:http://git-scm.com/[Git VCS] * link:http://www.scons.org/[SCons build system] * link:http://www.boost.org/[Boost libraries] * link:http://gmerlin.sourceforge.net/[GAVL library] * *NoBug* (see below) + * Lumiera source code -The GUI depends on: +The GUI depends on the following: * http://www.gtkmm.org/en/[gtkmm] * http://cgit.freedesktop.org/xorg/lib/libXv[libXv] -TIP: Generally speaking, when you want to build software, you need the -_development_ version of the packages, containing the headers and pre-built -libraries to link against. Usually, these packages are named `-devel` or `-dev` +TIP: Generally speaking, when you want to build software, you'll need the +_development_ version of the packages that contain the headers and pre-built +libraries to link against. These packages are ususally named `-devel` or `-dev`. -For Debian based systems, e.g. Ubuntu, you can install these dependencies with: +For Debian based systems, e.g. Ubuntu, you can install these packages as follows: ------------------------------------------------------------------------------------- sudo apt-get install build-essential autoconf scons valgrind libtool git-core \ @@ -44,42 +56,47 @@ libgavl-dev libgdl-1-dev libgtkmm-2.4-dev librsvg2-dev libxv-dev Optionally, you may also want to install the *gtk2-engines* package. -Build directory +Build Directory --------------- -You need a directory for checking out the sources and running the build. This -could be a temp directory, or some "workspace" directory below your home -directory. We'll call it _workspace directory_ from now on. +You'll need to check out the source code in some directory or other. You'll also +have to use this directory to build Lumiera. This could be a temporary +directory, or some "workspace" directory below your home directory. We'll refer +to this directory as _workspace directory_ . -Lumiera specific libraries +Lumiera Specific Libraries -------------------------- -Now that you have your basic build system setup, Lumiera needs a few more -special support libraries. Currently you need to build those from source and -install them, so the Lumiera build process can pick them up. +Now that you have your basic build system setup, you'll next have obtain support +libraries required by Lumiera that are not directly part of the Lumiera project +itself. At the moment, you'll have to get the source code for the support +libraries at build them from source. We do not have them pre-packaged at the +moment, but this will hopefully change over time. However, it is not too +difficult to build the support libraries and the instructions following here +should not be too difficult. WARNING: Note that the following procedures will try to install files into your base system below `/usr/local`. -To do so, you'll need administrative permissions for the machine you're working +To do so, you'll need administrative permission for the machine you're working on. These additions might interfere with other libraries installed by your package manager (if you get into trouble updating your system later on, -sometimes you need to remove these manually built libraries). +you might have to manually remove these libraries). -Installing NoBug -~~~~~~~~~~~~~~~~ +NoBug: obtaining, building and installing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *NoBug* is an instrumentation and diagnostics library. + -Go into the mentioned _workspace direcory_ (maybe create a new -directory). First, let's get the NoBug source code: +Enter _workspace direcory_ as explained above. +Get the NoBug source code: ------------------------------------------------------------ git clone git://git.pipapo.org/nobug ------------------------------------------------------------ -This will create a (sub)directory called nobug with source code in your current -directory. + -Compile NoBug with the following commands +This will create a (sub)directory called nobug that contains source code. + +Compile and install NoBug with the following commands: (this will try to install +the NoBug library in /usr/lib, so you will require root privilages to do so!) ------------------------------------------------------------ cd nobug @@ -91,8 +108,8 @@ make sudo make install ------------------------------------------------------------ -Installing GDL -~~~~~~~~~~~~~~ +GDL: obtaining, building and installing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The *GNOME Docking library* is generally available through your package manager, but we contributed some improvements, which are only available in the very @@ -126,8 +143,8 @@ check library linkage The compile will warn you to add various directories to /etc/ld.so.conf and then run ldconfig. This will allow your dynamic liker to pick up the newly built libraries later when you try to start Lumiera. If you don't want to reconfigure -your system and add `/usr/local/lib` to the mentioned linker configuration, you -may alternatively just add the directories to your LD_LIBRARY_PATH environment +your system and add `/usr/local/lib` to the linker configuration, you may +alternatively just add the directories to your LD_LIBRARY_PATH environment variable. Either way, check that all libraries are accessible and OK: @@ -144,27 +161,30 @@ and you should get a list of the libraries, part of which should look like this: libgdl-lum.so.0 -> /usr/local/lib/libgdl-lum.so.0.0.0 ------------------------------------------------------------ -or similar. The same holds true for 'libgdl-lum.so.0' if you needed to build it -explicitly for your system. If any if these libraries are not listed, -investigate why before continuing. +or similar. The same applies to 'libgdl-lum.so.0' if you needed to build it +explicitly for your system. If any of these libraries are not listed, you'll +have to see why before you can continue. Building Lumiera ---------------- -Up to now, Lumiera has had two maintained (and equivalent) build systems: *scons* and -*autotools*. (Note 3/2011: Right now, the autotools build is broken. It is always a good -idea to check the current build stats from our *builddrone*, which automatically builds -the latest version from master repository. Please have a look at this +Up to now, Lumiera has had (and equivalent) build systems: *scons* and +*autotools*. (Note 3/2011: At the moment, the autotools build system is +broken; only the scons build mechanism is working. It is always a good idea to +check the current build stats from our *builddrone*, which automatically builds +the latest version from the master repository. Please have a look at this http://lumiera.org/builddrone/table.html[current build stats]-page.) -Next, after having built and installed the prerequisite libraries, go into the -_workspace directory_ to retrieve the Lumiera source code and build it. +Next, after having built and installed the external libraries, go into the +_workspace directory_ and retrieve the Lumiera source code. Thereafter, build +Lumiera. - * to retrieve the source code with git and then build with *scons*: + * Issue the following command to retireve the Lumiera source code and, + thereafter, build Lumiera using *scons*: + -(see available build options by issuing `scons -h` ) +(more options for building with scons can be found via:`scons -h` ) + ----------------- git clone git://git.lumiera.org/LUMIERA @@ -173,7 +193,8 @@ scons ----------------- + - * alternatively, if you prefer building with *autotools* _(not working currently 3/11)_: + * Alternatively, if you'd prefer to build using *autotools* _(not working + currently 3/11)_, issue the following commands: + ----------------- git clone git://git.lumiera.org/LUMIERA @@ -187,17 +208,17 @@ make maybe build and run the test suite by issuing `scons check` or `make check` -This will take some time. +The build process will take some time, so sit back and relax. -NOTE: you do not need to _install_ Lumiera. It will find its required files -relative to the generated directory structure, which is freely relocatable +NOTE: you do not need to _install_ Lumiera. It will find all files it requires +relative to the directory structure it generates, which is freely relocatable as a whole. Just invoke the +target/lumiera+ executable. The current -working directory is not relevant. +working directory is not particularly relevant. After the build has finished successfully, you should be able to start Lumiera. Currently, this will bring up the GUI, without any further functionality -You should see something like: +You should see something like this: image:{l}/images/lumiera_gui_small.png[Current Lumiera GUI Screenshot] @@ -205,7 +226,7 @@ image:{l}/images/lumiera_gui_small.png[Current Lumiera GUI Screenshot] What's next? ------------ If you're a coder, maybe you've found something to improve...? + -Contributing to Lumiera is made easy, thanks to *Git* +Contributing to Lumiera is easy, thanks to *Git* -> Tutorial link:contributing.html[Contributing to Lumiera coding] From 6856fb8846a58de2c6b950e22655eb223c061016 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Thu, 3 Jan 2013 09:05:15 +0100 Subject: [PATCH 35/47] DOC/Intro: expand on the global pipes (master bus section) --- doc/user/intro/intro.txt | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 1ab67a354..59e2fdcb4 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -285,15 +285,21 @@ footage for preview creates a simple internal timeline. -Busses -~~~~~~ +Global Pipes +~~~~~~~~~~~~ // TODO: needs rewriting. -The GUI provides a separate _bus view_, showing the master busses (subgroups) -in a manner similar to an audio mixing desk. Any bus is just a means of collecting -and and adding (aka overlaying) together output of various kinds of media -(video, audio, number of channels), produced by various processing elements and -from other busses. These global busses can be conceived as being part of the -timeline. +The GUI provides a separate _bus view_, showing the _global pipes_. These are the +master busses for each kind of output (image and sound) and collect the output of +the subgroups, in a manner similar to an audio mixing desk. Any _pipe_ is just a +means of collecting, mixing or overlaying output produced by other pipes. +A simple (linear) chain of effects can be applied within each pipe. + +Most of the pipes are managed automatically, e.g. the pipes corresponding to +individual clips, or the pipes collecting output from transitions, from nested +sequences and from groups of tracks. At some point, at the level of the +timeline, all of the processed data is collected within the aforementioned +global pipes to form the small number of output streams produced by rendering +and playback. Each timeline uses a separate set of global pipes. Asset View From 8946cb7b6aa9d721d473c86edaf3ac5cbd60d047 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Thu, 3 Jan 2013 09:06:11 +0100 Subject: [PATCH 36/47] DOC/Intro: more about assets --- doc/user/intro/Glossary.txt | 13 +++++++------ doc/user/intro/intro.txt | 31 +++++++++++-------------------- 2 files changed, 18 insertions(+), 26 deletions(-) diff --git a/doc/user/intro/Glossary.txt b/doc/user/intro/Glossary.txt index cd2ba0636..259ae059b 100644 --- a/doc/user/intro/Glossary.txt +++ b/doc/user/intro/Glossary.txt @@ -2,14 +2,15 @@ Glossary ======== -'NOTE Draft, please help rephrase/review and shorten -explanations, the long explanation is the topic of the document above..' +NOTE: Draft, please help rephrase/review and shorten explanations! anchor:AssetsView[] link:#AssetsView[->]Assets View:: - Windows displaying and managing various things that can be edited, - worked on, etc are collectively known as the Assets View. - AssetsView consists of ingested footage, clips that have already been composed, available - sub-projects, effects, transitions and internal artifacts. + The session contains various things that can be edited, worked on + and connected. These things are collectively known as the _assets_. + The _assets view_ is a ``bookkeeping view'' for displaying and managing + the assets of the current session. It provides a list of all ingested footage, + a list of all clips, effects, transitions, available timelines and sub-sequences, + automation data, time grids, tags, labels and similar internal artefacts. anchor:Builder[] link:#Builder[->]Builder:: This is a kind of compiler that creates low-level, or processing, graphs diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 59e2fdcb4..1ece14a34 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -306,33 +306,24 @@ Asset View ~~~~~~~~~~ An Asset View can be conceived as the timeline's book keeper: it manages the various constituents in the timeline. Moreover, in addition to managing timeline -constituents, raw material, clips, bins (folders) are managed by the Asset -View, i.e., typical management operations including, deleting, adding, +constituents, raw material, clips, bins (folders) and effects are managed by the +Asset View, i.e., typical management operations including, deleting, adding, naming, tagging, grouping into bins, etc. all occur here. -Plugins are also managed in the Asset View. - - - -Manages all assets available in one project. +There are various kinds of assets available in any project. * source media/footage/soundfiles * all available effects and transitions + * user defined ``effect stacks'' and effect collections ("effect palette") * internal artefacts like sequences and automation data sets + * markers, labels, tags and similar kinds of metadata -// (much) Later it is planed to make this a database driven interface, where -// the tabs showing things are basically just database queries. Then it -// becomes possible to create/extend this by customized queries and augment -// assets with all kinds of metadata which can be queried - -// The user may build custom effect collections ("effect palette") - -// Actually, the same underlying data structure is used to implement the -// asset view with folders, clip bins and effect palettes, and the timeline -// view with tracks, clips and attached effects. Technically, there is no -// difference between a track or a clip bin -- just the presentation varies. -// Timeline contents can be viewed like assets for bookkeeping purposes, and -// the contents of a clip bin can be played like a storyboard +Actually, the same underlying data structure is used to implement the +asset view with folders, clip bins and effect palettes, and the timeline +view with tracks, clips and attached effects. Technically, there is no +difference between a track or a clip bin -- just the presentation varies. +Timeline contents can be viewed like assets for bookkeeping purposes, and +the contents of a clip bin can be played like a storyboard From b5a1bb386c47733bc39d4b3e0b5c46e678f5fb42 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Thu, 3 Jan 2013 09:25:20 +0100 Subject: [PATCH 37/47] DOC/Intro: add some details regarding session storage --- doc/user/intro/intro.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 1ece14a34..a164ee8e9 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -367,15 +367,15 @@ steps might even be a possibility. For example, work on a project at the office and work on the same project at home can be merged each morning and evening. -Session storage is envisaged to be performed as database with logging, some -search facilities and a number of features associated with databases. +Session storage is envisaged to operate similar to a database or journalling +file system. Any operation will be logged prior to execution. This protects +the session contents against corruption and allows for automated recovery +in case of a crash. The actual storage is delegated to several back-ends. +One of these back-ends implements a _binary storage format_ for performance +reasons, while another one exposes all of the session contents in textual, +human readable form. The storage format is designed in a way to ensure +a certain degree of compatibility while the application evolves. -[red]#Details to be written# -//database with logging, no data loss. -// not generateable data - -// its the timeline mostly -// session storage [[placement]] From d12bb1f186757c4d71c864c111c88fe5ff1b6ea9 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Thu, 3 Jan 2013 11:05:16 +0100 Subject: [PATCH 38/47] DOC/Intro: about this document reword and expand the very first paragraph and add some cross links --- doc/user/intro/intro.txt | 40 +++++++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index a164ee8e9..d103f1755 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -25,10 +25,15 @@ behind Lumiera to start working with Lumiera quickly. // working on this document .About this Document -Lumiera is still under active development. Here we describe planned features -without explicitly tagging them; some points have still to be worked out in -detail. Although this document is heavily cross-linked, we try to start with a -broad overview, then develop details towards the end. +Lumiera is an innovative video editing software, still under active development +by an open source community. This document acts as introduction, we try to start +with a broad overview, then explain some core concepts towards the end. +We describe planned features here without explicitly tagging them and we'll omit +any technical details. +There is a link:Glossary.html[Glossary of common terms]; readers curious about +the inner workings might want to continue their path of exploration into +link:{ldoc}/technical/overview.html[The Inner Core] + @@ -517,15 +522,36 @@ Integration with external libraries, frameworks and applications ---------------------------------------------------------------- [red]#to be written# +____ + . + . + . +____ + +'''' - - +Further reading +--------------- Glossary --------- +~~~~~~~~ The above outline of the design uses a lot of special terms and common terms used with specific meaning within Lumiera. To ease the understanding, we've collected a link:Glossary.html[Glossary of common terms]. +Tutorials and User Manual +~~~~~~~~~~~~~~~~~~~~~~~~~ +For most users, the next step would be to skim the user manual and to install +the application. But we aren't this far, unfortunately. As of 1/2013, Lumiera +isn't usable in any way. Later, when we approach the alpha and beta development phase, +we'll care for a user manual and a tutorial section. + +The Inner Core +~~~~~~~~~~~~~~ +Developers and Readers curious about the inner workings of the application +might want to have a look into the overview document of our technical +documentation section. Learn more about +link:{ldoc}/technical/overview.html[The Inner Core]... + From ce3be0279cbb0fab94acbc728f9a6ed91ff02cfc Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Thu, 3 Jan 2013 11:06:00 +0100 Subject: [PATCH 39/47] DOC/Intro: proposal for the Vision section --- doc/user/intro/intro.txt | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index d103f1755..0a1d62ca3 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -46,20 +46,19 @@ link:{ldoc}/technical/overview.html[The Inner Core] Vision ------ -Lumiera strives towards being a _professional non-linear video editor_. It is +Lumiera strives towards being a *professional non-linear video editing system*. It is important to note that by ``professional'' we do not necessarily imply ``commercial'' or even ``industrial''. We do, however, wish to suggest an -attitude or frame of mind in how this work is approached, but not the goal, -requirement or purpose of this work. The concept of professionality in film -editing can indicate something of an artistic nature, suggest that there is a -narration, meaning or political messages revealed by the work; or, simply, that -the work attempts to convey something to an audience. +attitude or frame of mind in how this work is approached. -Anyhow, for the tools, the editing software used to this end, we can identify -several properties and requirements, to be labelled ``professional'': +Professionalism implies _to do work with sincerity, and to be subject to any +kind of wider goal, demand, or purpose._ When it comes to editing film, this +wider goal, demand, or purpose might be artistry, a narration or meaning to convey, +a political message or commercial revenue -- it might be something to reveal to +your audience, to let them see, feel and perceive. -With this perspective in mind, we can identify a number of key properties -film production tools should have and be professional: +With this perspective in mind, for the editing software used to this end, we can identify +a number of key properties film production tools should have to be labelled ``professional'': Reliability:: All work must be secure and be safe against any software glitches, From 54f303709852e0729052f4c750e835935f47cd00 Mon Sep 17 00:00:00 2001 From: Benny Date: Tue, 1 Jan 2013 16:04:27 +0100 Subject: [PATCH 40/47] DOC: "contributing"-tutorial, errors corrected, new sections. Some obvious typos were corrected. Other material improved. The section on Git was considerably improved. An entirely new section on Git was added, but which contains some previous material on git. The reason for adding a new section on Git was I though it better to have one single place where someone new to Git and Lumiera could read a simple recipe-type explanation on how to retrieve source code, make changes and then push the changes. All information necessary including Git, links, etc should be on this page, no following liknks. In fact there is no real _new_ information here that isn't to be found somewhere else. The point being that _all_ information necessary to ge someone up and going is located on one page. For this reason, I added information on the mailing list and IRC; again, all essential information in how to contribute to Lumiera, the title ang goal of this page. There might be stuff missing here, so please add, but do not make this page too long. That tends to scare people, in fact, someone might just like to shorten my contributions here, that would be good! --- doc/user/tutorials/contributing.txt | 117 +++++++++++++++++++++++----- 1 file changed, 96 insertions(+), 21 deletions(-) diff --git a/doc/user/tutorials/contributing.txt b/doc/user/tutorials/contributing.txt index 6658706ae..aa73a496e 100644 --- a/doc/user/tutorials/contributing.txt +++ b/doc/user/tutorials/contributing.txt @@ -3,41 +3,91 @@ Contributing to Lumiera All files in the Lumiera project are managed by *Git*. Although *Git* was primarily brought to life to manage source code, it plays a fundamental role in -Lumiera project communication and contributing to Lumiera. -If you'd like to contribute to Lumiera, you will have to acquire some +the Lumiera project. It is central to communication and contribution in the +project. If you'd like to contribute to Lumiera, you will have to acquire some understanding of *Git* at some stage or other. Please note, this is not the only way to contribute to Lumiera, you can always send direct contributions to the mailing list. - -a powerful tool -that not only - - - which is a distributed -source code management system. - The Lumiera project uses an infrastructure based on *Git*, the distibuted sourcecode management software. This deliberately places the barrier for -contributing very low: No formal ``commit right'' is necessary; you can -start right away and present your first results in the _mob repository_. +contributing very low: No formal ``commit permission'' is necessary; you can +start right away and present your first results to the _mob repository_. -For starters, follow the + + +Git: Lumiera Essentials +----------------------- + +One very useful place to begin with using Git is the following: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[basic -instructions] for using Git, notably the following parts: +instructions]. In particular, the following parts: http://gitref.org/ +In the following, we assume you have set up Git on your system. If you are +experiencing problems with Git, just ask the Lumiera community. + + +Letting People Know Who You Are +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ------------------------------------------------------------ $ git config --global user.name "Your Name Comes Here" $ git config --global user.email you@yourdomain.example.com ------------------------------------------------------------ -If you followed the link:building.html[building-lumiera tutorial], you created -already a local clone of the Lumiera repository. So you are ready to go, -you can edit build and commit your changes to the lumiera code locally in -your cloned repository. Please commit frequently, do small commits which -fix/improve only one single thing and use meaningful commit messages. +Obtaining Lumiera Code +~~~~~~~~~~~~~~~~~~~~~~ + +------------------------------------------------------------ +$ git clone git://git.lumiera.org/LUMIERA +------------------------------------------------------------ + +If everything goes ok, you should have the Lumiera source code. However, you do +not have enough code to build as there are some external packages missing that +are required to build Lumiera. Please refer to the +link:building.html[building-lumiera tutorial] on how to obtain all packages to +build Lumiera. + + +Contributing +~~~~~~~~~~~~ + +So you are ready to go, you can edit and commit your changes to the +lumiera code locally in your cloned repository. Please commit frequently, do +small commits which fix or improve only one single thing and try to use +meaningful commit messages. + +Let's assume, as an example, you've made changes to this file: +_.../doc/users/tutorials/contributing.txt_. + +Here's how to add your changes to Git: + +------------------------------------------------------------ +$ cd .../doc/users/tutorials +$ git add contributing.txt +$ git commit contributing.txt -m "Corrected a grammatical error in section Git" +------------------------------------------------------------ + +You can, of course, add more detailed information to your commit message. To do +this, you'll have to set-up git to use your favourite editor. Here's how to get +Git to use emacs: + +------------------------------------------------------------ +$ git config --global core.editor emacs +------------------------------------------------------------ + +Then while commiting, do not use the _-m_ option. Your editor will appear +requiring you to enter your comments. Enter, as your first line, a one line +summary of less than 80 characters in length (some applications use this line +for various purposes and longer entries tend to cause difficulties). +The line following your one line summary should be blank. Then on the third +line, you can begin your exposition on your changes. + + +Publishing Your Contribution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Check that you didn't break anything, by running the testsuite. @@ -47,7 +97,32 @@ Finally you can push your changes to the lumiera server to the 'mob' repository: $ git push git://git.lumiera.org/lumiera/mob master:refs/heads/YOURNAME ------------------------------------------------------------ -This creates a new branch 'YOURNAME' on the mob repository. Then you notify the -other devs on the mailinglist and they may merge your code into the mainline. +This creates a new branch 'YOURNAME' on the mob repository. + +Check that indeed your changes are public by visiting +http://www.lumiera.org/gitweb [http://www.lumiera.org/gitweb]. The lumiera/mob +repository should indicate 'right now' as its _Last Change_ entry. + +Thereafter, notify the other developers on the mailinglist and they may merge +your code into the main project line. + + +Lumiera Communication Channels +------------------------------ + + +The Mailing List +~~~~~~~~~~~~~~~~ + +lumiera@lists.lumiera.org + + +IRC Meetings +~~~~~~~~~~~~ +The Lumiera community generally meets on the second Wednesday of each month at +20:00 uucp on: _freenode #Lumiera_. + +All are more than welcome to join and to contribute to the discussions there. + From c876bcffc32bb1b80e09afbc3581378122e4e311 Mon Sep 17 00:00:00 2001 From: Hendrik Boom Date: Thu, 3 Jan 2013 14:10:00 -0500 Subject: [PATCH 41/47] vision section, small wording improvement --- doc/user/intro/intro.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 0a1d62ca3..8e49b43e1 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -51,7 +51,7 @@ important to note that by ``professional'' we do not necessarily imply ``commercial'' or even ``industrial''. We do, however, wish to suggest an attitude or frame of mind in how this work is approached. -Professionalism implies _to do work with sincerity, and to be subject to any +Professionalism implies _doing work with sincerity and being subject to any kind of wider goal, demand, or purpose._ When it comes to editing film, this wider goal, demand, or purpose might be artistry, a narration or meaning to convey, a political message or commercial revenue -- it might be something to reveal to From 501f92bc878d29d873be709068fdf041e49e09c5 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Fri, 4 Jan 2013 01:45:47 +0100 Subject: [PATCH 42/47] improved and slightly extended the design index page this is the entry point into the section holding the various design documents -- we try to separatte conceptual/design from the actual technical documentation --- doc/design/architecture/playRender.txt | 4 +- doc/design/index.txt | 79 ++++++++++++++++++-------- 2 files changed, 57 insertions(+), 26 deletions(-) diff --git a/doc/design/architecture/playRender.txt b/doc/design/architecture/playRender.txt index 2d76f716e..5b7caf0c5 100644 --- a/doc/design/architecture/playRender.txt +++ b/doc/design/architecture/playRender.txt @@ -149,7 +149,7 @@ reconfigure the backend services. Frame quantisation ^^^^^^^^^^^^^^^^^^ -Quantisation is a kind of rounding; like any kind of rounding, quantisation is +link:../TimeQuant.html[Quantisation] is a kind of rounding; like any kind of rounding, quantisation is a dangerous operation because it kills information content. Thus there are three fundamental guidelines when it comes to rounding @@ -183,7 +183,7 @@ application the subsystem most remote and unaware of output requirements. Which leaves us with the player and the session. Both positions could arguably be supported. Here, a more careful consideration shows, that the ``act of frame rounding'' can be decomposed: into the _act of quantisation_ -and the _frame grid:. Basically its the session which has the ability +and the _frame grid_. Basically it's the session which has the ability to form the *frame grid*, but it is lacking crucial information about the output. Only when connecting both -- which is the essence of the player -- frame quantisation can actually be performed. Thus, the diff --git a/doc/design/index.txt b/doc/design/index.txt index 1b8114d54..8c3e21562 100644 --- a/doc/design/index.txt +++ b/doc/design/index.txt @@ -16,15 +16,21 @@ for the core of a Non-Linear Editing software. One of the key aspect of Lumiera is the strong separation between the user interface and the processing core. Lumiera as a software will come along with a GTK GUI but that does not make this exclusive, any other GUI could be written as well as scripts to drive the core. -This is made possible by the above-mentioned quality of Lumiera being built against -clearly defined interfaces, strictly separating model and presentation. Lumiera +This is made 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 do anything possibly conceivable, therefore it may be used to do any task on video (and audio?), even unrelated to video editing. .Workflow -**** -The word Workflow is used to name the way tasks can be achieved in an application. Any operation in Lumiera must be possible in the most suitable and stringent fashion. The Workflow is closely related to how flexible the GUI is but also the concern of deeper and more technical parts of the application. -**** +***************** +The word Workflow is used to name the way tasks can be achieved in an +application. Any operation in Lumiera must be possible in the most suitable and +stringent fashion. The Workflow is closely related to how flexible the GUI is +but also the concern of deeper and more technical parts of the application. +***************** + Overview -------- @@ -32,45 +38,70 @@ Overview The internal structure of Lumiera is divided in numerous subsystems. This overview will try to go through the elements from the highest to the lowest piece of the structure. They can be categorized into three main categories plus -extra components : +extra components: -link:gui/index.html[Graphical User Interface] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -User interfaces are basically handled like plugins, consequently it is possible +Graphical User Interface +~~~~~~~~~~~~~~~~~~~~~~~~ + +User interfaces are basically included as a plugin, consequently it is possible to interface with Lumiera through scripts. It is also possible to create specialised GUIs. The interface is the closest component to the user, it is purely visual. There 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. +are contained within a structure called the Session. + +-> link:gui/index.html[GUI design documents] + The Processing Layer ~~~~~~~~~~~~~~~~~~~~ -The Processing layer (or proc) is where the elements from the Session are -assembled to form a network of nodes, to be sent to the backend. The lowest data -structure is called the Low-level model. + +The processing layer (``Proc-layer'' or ``proc'') covers several closely related aspects. +While 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 here. 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. +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 +generate individual _frame render jobs,_ ready to be handed over to the backend +for the actual rendering calculations. + +-> more about the link:model/index.html[Model] + +-> design of the link:engine/index.html[Engine] subsystem - * link:model/index.html[Model] + - * link:engine/index.html[Engine] -link:backend/index.html[The Backend] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The backend uses the Low-level model. It allows the rendering and makes a heavy -use of the Input/Output System to the screen or to external monitors. +The Backend +~~~~~~~~~~~ + +The backend uses the Low-level model and the _render jobs_ generated by Proc. +It actually performs the the rendering operations and makes a heavy use of the +Input/Output System for accessing media content and sending generated data to +the screen or external output. + +-> link:backend/index.html[Backend design level documents] + +-> link:{ldoc}/technical/backend/index.html[technical documentation] + + Extra components ---------------- -link:application/index.html[The Application] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The Application +~~~~~~~~~~~~~~~ The application controls the initialization and shutdown procedures as well as -loading external elements like plugins that are widely used. +loading external elements like plugins that are widely used. It acts as a framework +to support the operation of the core components. This framework is complemented by +a library of commonly used components, algorithms and data structures. + +-> link:application/index.html[Application framework] + link:plugins/index.html[Plugins] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Plugins are key elements in Lumiera since the application relies heavily on this -concept of modules. For example, the GUI of Lumiera is a plugin. +Plugins play an important role within Lumiera since the application relies heavily +existing implementations and external libraries. Moreover, the application is envisioned +to be configurable and can be extended in various ways; whenever some extension isn't permanent +or will be used only on demand, it is packaged as separate module into a plug-in. For example, +the GUI of Lumiera is a plugin. + +-> design doruments regarding the link:plugins/index.html[Plugins] + From 8f479809b6843afdaca6d7511cd76d72a2670021 Mon Sep 17 00:00:00 2001 From: Benny Date: Sun, 6 Jan 2013 16:16:58 +0100 Subject: [PATCH 43/47] DOC: Language corrected. No rewrite of sections, only the language was corrected. Only very little rewriting, although some sections might be rewritten and improved later. A slight note on style: after a colon (i.e., ':') upper case or lower case can follow. Both are corrected. To be consistent, I changed all to be the same, i.e., lower case. --- doc/design/architecture/playRender.txt | 129 +++++++++++++------------ 1 file changed, 67 insertions(+), 62 deletions(-) diff --git a/doc/design/architecture/playRender.txt b/doc/design/architecture/playRender.txt index 5b7caf0c5..f0dd1e510 100644 --- a/doc/design/architecture/playRender.txt +++ b/doc/design/architecture/playRender.txt @@ -9,19 +9,19 @@ Design: Playback and Render Control This part of the architecture is concened with how to initiate, coordinate and control the calculation processes necessary to generate visible / audible data from our source media. This design is _not so much_ concerned with the actual calculations; indeed it -takes on an ``bird eye's view'', treating the actual render engine mostly just as an +takes a ``birds eye view'', treating the actual render engine mostly just like an opaque entity providing some service. ************************************************************************************** Collecting initial drafts ------------------------- -At start of 2011, several design sketches emerged already, as an offspring of other -discussions and brainstorming. +At the start of 2011, several design sketches emerged as an offspring of other +discussions and brainstorming sessions. * the link:/documentation/devel/rfc_pending/EngineInterfaceOverview.html[Engine Interface draft] contains some fundamental terms and definitions. - * discussions regarding time values and timecode handling shed some light onto the requirements + * discussions regarding time values and timecode handling shed some light on the requirements to be fulfilled by a player subsystem - link:http://article.gmane.org/gmane.comp.video.lumiera.general/2116[Timecode Widget and Framerates] @@ -30,38 +30,38 @@ discussions and brainstorming. from the implementation notes in the TiddlyWiki -Reasoning about the Player Subsystem's structure +Reasoning Behind the Player Subsystem's Structure ------------------------------------------------ -At first sight, the name ``Player'' might be surprising. +The name ``Player'' might seem surprising at first. The full, complete and precise name would be something along the lines of ``_render- and playback-process coordination subsystem_''. -Now, we need to shorten that into a single word. The more obvious -abbreviation (just by the importance) would be _Render_, but that -would be strikingly misleading, because everyone would take that -to be the render engine. Which leaves us with _Player_. A second -consideration highlights similarities with the structure of a -typical software player -- the chosen term turns out to be well -aligned with the actual nature of that subsystem. +However we need to shorten that into a single word. The more obvious +abbreviation (assuming importance of words to be the selection criteria) would be +_Render_, but that would be strikingly misleading, because everyone would take +that to refer to the render engine. Thus, we are left with _Player_. A second +consideration highlights similarities to the structure of a +typical software player -- the term we selected turns out to be suitably +aligned to the actual nature of that subsystem. Influences and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ In accordance with the spirit of modern software development, the analysis -starts by determining which would be the _Service_ to be provided by such -a player. Consideration of the use cases determines the fundamental forces +starts by determining the _Service_ that is provided by such a +player. Examination of the Use Cases determines the fundamental forces to be _multiplicity_, combined with _differentiation in detail_, all under the government of _time-bound delivery_, combined with _live reconfiguration_. -The basic service turns out to be the *performing of a preconfigured object model*. +The basic service turns out to be *performing of a preconfigured object model*. This performance is *time based*. Multiple usage instances of this service can be expected to coexist, each of which can be broken down into a set of *elementary streams to be delivered in sync*. The parameters of delivery can be *reconfigured on-the-fly*. -Modes of operation +Modes of Operation ^^^^^^^^^^^^^^^^^^ -Delivery can be either _free-wheeling_, so to cover a predefined time interval +Delivery can be either _free-wheeling_, so as to cover a predefined time interval with fixed quality calculations (final render), and it can be _throttled_ for using excess computation power (background rendering). Or -- alternatively -- delivery can be _time-bound_ (for classical playback), following the projection of wall clock time @@ -71,78 +71,82 @@ proceeding along a timeline). Reconfiguration ^^^^^^^^^^^^^^^ Some of these operation modes need to be prepared to encounter an unpredictable live -reconfiguration, driven by user interactions: +reconfiguration driven by user interactions: - any part of background rendering can be invalidated and restarted, while other parts - should be re-integrated, possibly with adjusted position -- the linearly proceeding playback can at any time be + should be re-integrated, possibly with a re-adjusted position +- playback, which evolves in a linear manner, can be in one of any of these + states at any particular time : * paused * reversed in direction - * playback speed adjusted + * playback speed re-adjusted -- the playback can be looped, with _unlimited_ adjustments of the loop boundaries any time. +- playback can be looped, with _unlimited_ adjustments of the loop boundaries at + any time. Conclusions for the Design ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Based on these observations, the following design looks pretty much obvious: +Based on these observations, the following design would appear to be pretty much +obvious: -Overall, the player subsystem can be described as ``play/render-this''-service. -Given an suitable (high-level) object, the Player has the ability to ``perform'' -(play or render) it. +The overall player subsystem can be described as ``play/render-this''-service. +Given a suitable (high-level) object, the player has the ability to ``perform'' +(play or render) the object. -- the standard case is _playing a timeline_. -- it's conceivable to allow playing a selection of other objects, - like e.g. directly playing a clip or even media asset. In these cases, - its the player's job to prepare the necessary scaffolding on the fly. +- the standard operation is _playing a timeline_. +- it is conceivable that playing a selection of other objects would be + permitted, for example, directly playing a clip or even a media asset. In + these cases, it is the player's job to prepare the scaffolding that + is required on the fly. Yet each such performance of an object is a _stateful instance_, a player application: -On application of the player service, the client gets a front-end handle, a *play-controller*, -which is a _state machine_. It provides states and transitions of the kind 'play', 'pause', 'ffwd', -'rew', 'goto', 'step', 'scrub' and similar. Moreover it maintains (or connects to) a distinct -playback location, and it can be hooked up with a play-control GUI widget -(or something simpler in case of a render process, which is free wheeling). +on application of the player service, the client obtains a front-end handle, a *play-controller*, +which is a _state machine_. This provides states and transitions such as 'play', 'pause', 'ffwd', +'rew', 'goto', 'step', 'scrub' and similar. Moreover, it maintains (or connects to) a distinct +playback location, and it can be hooked up to a play-control GUI widget +(or something simpler in the case of a render process, which is free wheeling). -Each play-controller in turn gets associated with several *play/render-processes*, +Each play-controller, in turn, is then associated with several *play/render-processes*, one for each independent media stream (channel) to be produced. Of course this isn't an operating system process; rather, each such process is a compound of entries -in a registration table, which serve the purpose of tying several other services together, +in a registration table, which serves the purpose of tying several other services together, which we initiate and use in order to make that render process happen. -Most notably, we'll use the services of the actual engine, which provides us with kind of -a *calculation stream service*: the ability to deliver a sequence of calculated -data frames in a timely fashion. +Most notably, we'll use the services of the actual engine which provides us with +a kind of a *calculation stream service*: the ability to deliver a sequence of +calculated data frames in a timely fashion. When a client requests such an instance of the player service, we build up these parts providing that service, which cascades down to the individual elements. -At that point, we need to pull and combine two kinds of informations: +At that point, we need to pull and combine two kinds of information: - the ``what'' to render: this information stems from the session/model. - the ``how'' to render: this information is guided by the derived output configuration. -Viewer and Output connection +Viewer and Output Connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Creating a player instance binds together three partners: a _timeline_, a _viewer_ -and _the engine_. While the timeline provides the content to play, the _viewer connection_ -is crucial for working out the actual output sink(s) and thus the output format to use. -Thus, a viewer connection is prerequisite for creating a player instance. +Creating a player instance binds three partners together: a _timeline_, a _viewer_ +and _the engine_. While the timeline provides the contents to play, the _viewer connection_ +is crucial for working out the actual output sink(s) and, hence, the output format to use. +Thus, a viewer connection is a prerequisite in order to create a player instance. -Viewer connections exist as associations in the session/model -- as entities separate +Viewer connections exist as associations in the session/model -- which are entities separate from the player. Usually, a timeline has (at least) one viewer connection. But in case such a connection is (still) missing, building a player instance recurs to the session to get a suitable viewer _allocated_. The viewer connection can't be broken during the lifetime of that player instance (or putting it the other way: breaking that viewer connection, e.g. by forcing a different connection or by shutting down the viewer, -immediately terminates the player. This detaching works synchronously, i.e. it -blocks until all the allocated _output slots_ could be released. +immediately terminates the player.) This detaching works synchronously, i.e. it +blocks until all the allocated _output slots_ can be released. Live switching ^^^^^^^^^^^^^^ While the viewer connection can be treated as fixed during the lifespan of a player -instance, several life switching and reconfiguration operations might happen any time: -The _model port_ (place where data is retrieved from calculation), the output characteristics +instance, several life switching and reconfiguration operations might happen at any time: +the _model port_ (the place where data is retrieved from calculation), the output characteristics (framerate, direction) and the delivery goals (playback position, loop playing, scrubbing) all may be changed during playback -- we need a way for the player to ``cancel'' and reconfigure the backend services. @@ -152,7 +156,7 @@ Frame quantisation link:../TimeQuant.html[Quantisation] is a kind of rounding; like any kind of rounding, quantisation is a dangerous operation because it kills information content. -Thus there are three fundamental guidelines when it comes to rounding +Thus, there are three fundamental guidelines when it comes to rounding: . don't do it . do it at most once @@ -161,29 +165,30 @@ Thus there are three fundamental guidelines when it comes to rounding These may guide the process of finding the right place for the Quantiser(s) to apply. We need some information flows to be joined in order to be able to do the quantisation, which leaves us with just a few possible junction points -where to place quantisation: The backend, the GUI, the player, the session. +where to place quantisation: the backend, the GUI, the player and the session. - putting it into the backend seems to be the most reasonable at first sight: - We can ``do away'' with nasty things soon, especially if they are technicalities, + we can ``do away'' with nasty things soon, especially if they are technicalities, ``get a clean state soon'' -- and hasn't frame quantisation something to do with media data, which is handled in the backend? + Well, actually, all of those are pitfalls to trap the unwary. About -cleanliness, well (sigh). Doing rounding soon will leave us with a huge -amount of degraded information flows throughout the whole system; thus the -general rule to do it as late as possible. Uncrippled information is -enablement. And last but not least: the frame quantisation is connected +cleanliness, well, sigh! Doing rounding soon will leave us with a huge +amount of degraded information flows throughout the whole system; as a +consequence, the general rule is to do it as late as possible. Uncrippled +information is an enablement. And last but not least: the frame quantisation is connected to the _output_ format -- and the backend is likely within the whole application the subsystem most remote and unaware of output requirements. - rounding/quantising in the GUI is extremely common within media applications; - unfortunately there seems to be not a single rational argument supporting that habit. - Most of all, it violates the subsidiarity principle. + unfortunately there does not appear to be a single rational argument in + support of this habit. Most of all, it is a violation of the subsidiarity + principle. Which leaves us with the player and the session. Both positions could arguably be supported. Here, a more careful consideration shows, that the ``act of frame rounding'' can be decomposed: into the _act of quantisation_ -and the _frame grid_. Basically it's the session which has the ability +and the _frame grid_. Basically it is the session which has the ability to form the *frame grid*, but it is lacking crucial information about the output. Only when connecting both -- which is the essence of the player -- frame quantisation can actually be performed. Thus, the From 01bb1cf18480ffb9f0f5954d22ab992fe7da0f75 Mon Sep 17 00:00:00 2001 From: Benny Date: Sun, 6 Jan 2013 16:47:22 +0100 Subject: [PATCH 44/47] DOC: Mostly language corrected, but a few rewrites. Only just language corrections. Reviewer might like to examine the following sections: Overview and GUI. TODO: Backend, needs just a little more, not much, e.g.: Area where low-level memory, hardware i/o, etc occur => here is where real gain in efficiency through modern algorithms can occur, thus, achieving another goal of Lumiera: efficient & runs on all kinds of hardware! --- doc/design/index.txt | 57 ++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/doc/design/index.txt b/doc/design/index.txt index 8c3e21562..538b7c7b6 100644 --- a/doc/design/index.txt +++ b/doc/design/index.txt @@ -25,31 +25,31 @@ may be used to do any task on video (and audio?), even unrelated to video editin .Workflow ***************** -The word Workflow is used to name the way tasks can be achieved in an +The word 'workflow' is used to name the way tasks can be achieved in an application. Any operation in Lumiera must be possible in the most suitable and -stringent fashion. The Workflow is closely related to how flexible the GUI is -but also the concern of deeper and more technical parts of the application. +stringent fashion. The workflow is closely related to how flexible the GUI is +but is also the concern of deeper and more technical parts of the application. ***************** Overview -------- -The internal structure of Lumiera is divided in numerous subsystems. This -overview will try to go through the elements from the highest to the lowest -piece of the structure. They can be categorized into three main categories plus -extra components: - +The internal structure of Lumiera is divided into numerous subsystems. This +overview will provide a general description of the major areas that make up +Lumiera from the highest down to the lowest level. Lumiera can be considered to +be composed of three main areas with an additional extra components. We discuss +theses areas below. Graphical User Interface ~~~~~~~~~~~~~~~~~~~~~~~~ -User interfaces are basically included as a plugin, consequently it is possible -to interface with Lumiera through scripts. It is also possible to create -specialised GUIs. The interface is the closest component to the user, it is -purely visual. There 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. + +User interfaces are basically implemented as a plugin. As a consequence, it is +possible to interface with Lumiera through scripts. It is also possible to create +specialised GUIs. The interface is the closest component to the user. It is +a purely visual interaction with the user. There 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] @@ -64,8 +64,8 @@ a component known as _the Builder_ assembles the contents of this model and tran them to form a network of nodes, which can be _performed_ efficiently 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 -generate individual _frame render jobs,_ ready to be handed over to the backend -for the actual rendering calculations. + +generate individual _frame render jobs,_ ready to be handed over to the backend, which +performs the actual rendering calculations. + -> more about the link:model/index.html[Model] + -> design of the link:engine/index.html[Engine] subsystem @@ -74,34 +74,35 @@ for the actual rendering calculations. + The Backend ~~~~~~~~~~~ -The backend uses the Low-level model and the _render jobs_ generated by Proc. -It actually performs the the rendering operations and makes a heavy use of the +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 Input/Output System for accessing media content and sending generated data to -the screen or external output. + +the screen or to external output. + -> link:backend/index.html[Backend design level documents] + -> link:{ldoc}/technical/backend/index.html[technical documentation] + -Extra components +Extra Components ---------------- The Application ~~~~~~~~~~~~~~~ The application controls the initialization and shutdown procedures as well as -loading external elements like plugins that are widely used. It acts as a framework -to support the operation of the core components. This framework is complemented by -a library of commonly used components, algorithms and data structures. + +loading external elements such as plugins, which are widely used throughout +Lumiera. It acts as the framework which supports core component operations. This +framework is complemented by a library of commonly used components, algorithms and data structures. + -> link:application/index.html[Application framework] link:plugins/index.html[Plugins] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Plugins play an important role within Lumiera since the application relies heavily -existing implementations and external libraries. Moreover, the application is envisioned -to be configurable and can be extended in various ways; whenever some extension isn't permanent -or will be used only on demand, it is packaged as separate module into a plug-in. For example, -the GUI of Lumiera is a plugin. + +Plugins play an important role within Lumiera since the application relies +heavily on current FLOSS implementations and external libraries. Moreover, the +application is envisioned to be configurable and can be extended in various +ways; whenever some extension isn't permanent or will be used only on demand, it +is packaged as a separate module into a plug-in. For example, the GUI of Lumiera +is a plugin. + -> design doruments regarding the link:plugins/index.html[Plugins] From ea0be312e5baddc828a88563f28c401fee773e60 Mon Sep 17 00:00:00 2001 From: Benny Date: Sun, 6 Jan 2013 17:22:55 +0100 Subject: [PATCH 45/47] DOC: language corrected --- doc/user/intro/intro.txt | 50 ++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 8e49b43e1..9ed946a4a 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -45,7 +45,6 @@ link:{ldoc}/technical/overview.html[The Inner Core] Vision ------ - Lumiera strives towards being a *professional non-linear video editing system*. It is important to note that by ``professional'' we do not necessarily imply ``commercial'' or even ``industrial''. We do, however, wish to suggest an @@ -294,16 +293,16 @@ Global Pipes // TODO: needs rewriting. The GUI provides a separate _bus view_, showing the _global pipes_. These are the master busses for each kind of output (image and sound) and collect the output of -the subgroups, in a manner similar to an audio mixing desk. Any _pipe_ is just a +subgroups together in a manner similar to an audio mixing desk. Any _pipe_ is just a means of collecting, mixing or overlaying output produced by other pipes. A simple (linear) chain of effects can be applied within each pipe. -Most of the pipes are managed automatically, e.g. the pipes corresponding to +Most pipes are managed automatically, e.g. the pipes corresponding to individual clips, or the pipes collecting output from transitions, from nested -sequences and from groups of tracks. At some point, at the level of the -timeline, all of the processed data is collected within the aforementioned -global pipes to form the small number of output streams produced by rendering -and playback. Each timeline uses a separate set of global pipes. +sequences and from groups of tracks. At some point, at the timeline level, all +processed data is collected within the aforementioned global pipes to form the +small number of output streams produced by rendering and playback. Each timeline +uses a separate set of global pipes. Asset View @@ -314,7 +313,7 @@ constituents, raw material, clips, bins (folders) and effects are managed by the Asset View, i.e., typical management operations including, deleting, adding, naming, tagging, grouping into bins, etc. all occur here. -There are various kinds of assets available in any project. +There are various kinds of assets available in any project: * source media/footage/soundfiles * all available effects and transitions @@ -325,9 +324,9 @@ There are various kinds of assets available in any project. Actually, the same underlying data structure is used to implement the asset view with folders, clip bins and effect palettes, and the timeline view with tracks, clips and attached effects. Technically, there is no -difference between a track or a clip bin -- just the presentation varies. -Timeline contents can be viewed like assets for bookkeeping purposes, and -the contents of a clip bin can be played like a storyboard +difference between a track or a clip bin -- just the presentation appears +different. Timeline contents can be viewed, just like assets, for bookkeeping +purposes, and the contents of a clip bin can be played like a storyboard. @@ -355,7 +354,7 @@ Session Storage The current representation of a project resident in memory is internally known as a session, whereas from a GUI user perspective, this is known as a project. -In this section, we will use the term ``session'' as we discussing the internals +In this section, we will use the term ``session'' as we are discussing the internals of Lumiera here. Everything is stored in a session. If a user saves a session, then there should @@ -365,18 +364,18 @@ work away and load the session that has just been saved. In other words This ambitious goal has a number of advantages. If all steps are to be stored, then all steps must be available as an object to be stored. We can perform -operations on these objects. For example unlimited ability to undo previous +operations on these objects. For example, unlimited ability to undo previous steps, selective undo of previous steps or the possibility of merging various -steps might even be a possibility. For example, work on a project at the -office and work on the same project at home can be merged each morning and +steps might even be a possibility. On a practical note, work on a project at +the office and work on the same project at home can be merged each morning and evening. Session storage is envisaged to operate similar to a database or journalling file system. Any operation will be logged prior to execution. This protects the session contents against corruption and allows for automated recovery -in case of a crash. The actual storage is delegated to several back-ends. -One of these back-ends implements a _binary storage format_ for performance -reasons, while another one exposes all of the session contents in textual, +in case a crash occurs. The actual storage itself is delegated to several backends. +One of these backends implements a _binary storage format_ for performance +reasons, while another exposes all session contents in textual, human readable form. The storage format is designed in a way to ensure a certain degree of compatibility while the application evolves. @@ -437,7 +436,7 @@ Lumiera will break down processes that need to be processed into smaller units called _frame job_. Typically, there will be many hundreds of jobs waiting for processing at any one time. These jobs are queued for processing and the order in which this is performed is managed by the _scheduler_. -This is all done in the back-end. +This is all done in the backend. Apart from memory, the backend will be responsible for accessing and saving files. It will be of the utmost to do this efficiently. This will be carried out @@ -537,15 +536,16 @@ Glossary ~~~~~~~~ The above outline of the design uses a lot of special terms and common terms -used with specific meaning within Lumiera. To ease the understanding, we've -collected a link:Glossary.html[Glossary of common terms]. +used with specific meaning within Lumiera. To ease understanding, we've +collected together a link:Glossary.html[glossary of common terms]. Tutorials and User Manual ~~~~~~~~~~~~~~~~~~~~~~~~~ -For most users, the next step would be to skim the user manual and to install -the application. But we aren't this far, unfortunately. As of 1/2013, Lumiera -isn't usable in any way. Later, when we approach the alpha and beta development phase, -we'll care for a user manual and a tutorial section. +For most users, the next step would be to skim through the user manual and to +install the application. But we are not this far yet, unfortunately. As of +1/2013, Lumiera isn't usable in any way. Later, when we approach the alpha and +beta development phase, we'll devote some attention to a user manual and provide +a sections on tutorials. The Inner Core ~~~~~~~~~~~~~~ From 98b9f03539d2c32f9fe8f161693a1c320c8c6c55 Mon Sep 17 00:00:00 2001 From: Benny Date: Sun, 6 Jan 2013 17:33:54 +0100 Subject: [PATCH 46/47] DOC & WIP: section vision -->careful review required. No problem if changes/questions are done to this section. As this section is so important, the reviewer may correct, add or even reject the corrections here. We'll get there, iteratively. --- doc/user/intro/intro.txt | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 9ed946a4a..48784c284 100755 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -45,18 +45,36 @@ link:{ldoc}/technical/overview.html[The Inner Core] Vision ------ -Lumiera strives towards being a *professional non-linear video editing system*. It is + + Lumiera strives towards being a _professional non-linear video editor_. It + is important to note that by ``professional'' we do not necessarily imply + ``commercial'' or even ``industrial''. We do, however, wish to suggest an + attitude or frame of mind in how this work is approached, but not the goal, + requirement or purpose of this work. The concept of professionality in film + editing can indicate something of an artistic nature, suggest that there is + a narration, meaning or political messages revealed by the work; or, simply, + that the work attempts to convey something to an audience. + + Anyhow, for the tools, the editing software used to this end, we can identify + several properties and requirements, to be labelled ``professional'': + + With this perspective in mind, we can identify a number of key properties + film production tools should have and be professional + + + +Lumiera strives to be a *professional non-linear video editing system*. It is important to note that by ``professional'' we do not necessarily imply ``commercial'' or even ``industrial''. We do, however, wish to suggest an -attitude or frame of mind in how this work is approached. +attitude or frame of mind in how an approach to such work is made. -Professionalism implies _doing work with sincerity and being subject to any +Professionalism implies _doing work with sincerity and not being subject to any kind of wider goal, demand, or purpose._ When it comes to editing film, this -wider goal, demand, or purpose might be artistry, a narration or meaning to convey, +wider goal, demand, or purpose might be artistry, a narration or have meaning to convey, a political message or commercial revenue -- it might be something to reveal to your audience, to let them see, feel and perceive. -With this perspective in mind, for the editing software used to this end, we can identify +With this perspective in mind and for the editing software used to this end, we can identify a number of key properties film production tools should have to be labelled ``professional'': Reliability:: From 845a6180f558380f7949fa9ae0b4866d482d967b Mon Sep 17 00:00:00 2001 From: Benny Date: Tue, 8 Jan 2013 01:15:23 +0100 Subject: [PATCH 47/47] Initial draft of IRC meeting in October, 2012 --- doc/devel/meeting_summary/2012-10-11.txt | 35 ++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 doc/devel/meeting_summary/2012-10-11.txt diff --git a/doc/devel/meeting_summary/2012-10-11.txt b/doc/devel/meeting_summary/2012-10-11.txt new file mode 100644 index 000000000..f12773e6f --- /dev/null +++ b/doc/devel/meeting_summary/2012-10-11.txt @@ -0,0 +1,35 @@ +2012-10-11 Lumiera Developers Meeting +===================================== +:Author: benn +:Date: 2012-10-11 + +Oct 11, 2012 on #lumiera 20:00 - 01:30 + +__Participants__ + + * cehteh + * ichthyo + * benn + * mfisher31_ + * skangas + +Summary of The Meeting +---------------------- + +. _cehteh_ now Debian package maintainer for NoBug as is _ichthyo_. +. Discussed the naming convention for the Debian package of the Gnome Docking + Library, (Lumiera have added some features to this library): libgdlmm-lum + and libgdlmm-#-dev; where '#' is a number that changes with each change in + the ABI to ensure compatibility. +. _cehteh_ reports that progress on the builddrone progressing nicely. +. Discussed improving the Asciidoc documentation in particular the many broken + links to other documents and how cumbersome it is to get references to other + documents correct while trying to concentrate on content. + Moreover, we discussed at Froscon the desire of having some + automatic means of generating a glossary of terms, i.e., automatically + generating the glossary.txt files, we decided to do all these things together. + _benn_ agreed to write a script that would do the above. The script will be + called directly by build_website.sh. +. git://www.lumiera.org/website-staging is for experiments and contained the + new Lumiera site (http://staging.lumiera.org/). This was changed to contain + the contents of the current Lumiera web site.