From 8462f587d65c1847551ca4e2b8af0104814bc7ab Mon Sep 17 00:00:00 2001 From: Benny Date: Thu, 31 Mar 2011 18:57:25 +0200 Subject: [PATCH 01/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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]