diff --git a/admin/scons/LumieraEnvironment.py b/admin/scons/LumieraEnvironment.py index d50b4db04..11dc15b5a 100644 --- a/admin/scons/LumieraEnvironment.py +++ b/admin/scons/LumieraEnvironment.py @@ -62,7 +62,7 @@ class LumieraEnvironment(Environment): self.mergeConf(self.libInfo[other]) else: self.Append (LIBS = other.get ('LIBS',[])) - self.Append (LIBPATH = other.get ('LIBPATH', [])) + self.Append (LIBPATH = other.get('LIBPATH', [])) self.Append (CPPPATH = other.get('CPPPATH', [])) self.Append (LINKFLAGS = other.get('LINKFLAGS', [])) @@ -165,9 +165,11 @@ def register_LumieraResourceBuilder(env): def ConfigData(env, prefix, source, targetDir=None): """ install (copy) configuration- and metadata. - target dir is either the install location configured (in SConstruct), - or an explicitly given absolute or relative path segment, which might refer - to the location of the executable through the $ORIGIN token + @param targetDir: when None, then use he install location configured (in SConstruct), + otherwise an explicitly given absolute or relative path segment, + which might refer to the location of the executable through the $ORIGIN token + @param prefix: a prefix relative to the current path (location of SConscript), + i.e. typically a subdirectory where to find the source config file """ source = path.join(prefix,str(source)) subdir = getDirname(source, prefix) # removes source location path prefix @@ -188,6 +190,26 @@ def register_LumieraResourceBuilder(env): env.Install (toInstall, source) return env.Install(toBuild, source) + def DocFile(env, prefix, source, target=None): + """ install (copy) files for documentation. + Always places the documentation below the standard location 'installDoc' configured in Setup.py + @param prefix: relative to current path (SConscript), will be stripped at destination + @param target: when given, the target will be named explicitly, or (when only a directory) + placed into a specific subdir, otherwise (when None) the source spec will be placed + into the corresponding subdir after stripping the prefix + """ + source = path.join(prefix,str(source)) + subdir = getDirname(source, prefix) # removes source location path prefix + if not target: + target = subdir+'/' + elif target.endswith('/'): + target = target+subdir+'/' + toInstall = path.join(env.path.installDoc, target) + if toInstall.endswith('/'): + return env.Install(toInstall, source) + else: + return env.InstallAs(toInstall, source) # this renames at target + buildIcon = env.Builder( action = Action(invokeRenderer, "rendering Icon: $SOURCE --> $TARGETS") , single_source = True @@ -197,6 +219,7 @@ def register_LumieraResourceBuilder(env): env.AddMethod(IconResource) env.AddMethod(GuiResource) env.AddMethod(ConfigData) + env.AddMethod(DocFile) diff --git a/admin/scons/Setup.py b/admin/scons/Setup.py index 84ef3fd71..af2cfae53 100644 --- a/admin/scons/Setup.py +++ b/admin/scons/Setup.py @@ -40,6 +40,7 @@ installPlug = '#$DESTDIR/lib/lumiera/modules' installIcon = '#$DESTDIR/share/lumiera/icons' installUIRes = '#$DESTDIR/share/lumiera/' installConf = '#$DESTDIR/lib/lumiera/config' +installDoc = '#$DESTDIR/share/doc/lumiera/' #-------------------------------------------------------Configuration diff --git a/doc/SConscript b/doc/SConscript index 537b9b137..e0abc0ebb 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -8,9 +8,10 @@ Import('env') doxydoc = env.Doxygen('devel/Doxyfile') +env.Clean(doxydoc, doxydoc + ['devel/,doxylog','devel/doxygen-warnings.txt']) -# env.Install(dir = '$DESTDIR/share/doc/lumiera$VERSION/devel', source=documentation) -env.Clean (doxydoc, doxydoc + ['devel/,doxylog','devel/doxygen-warnings.txt']) +# HTML-documentation: this is a *placeholder* (eventually we'll build a user manual via Asciidoc) +env.DocFile('devel', 'LumieraHelpLandingPage.html', 'manual-html/index.html') Export('doxydoc') diff --git a/doc/devel/LumieraHelpLandingPage.NOTICE b/doc/devel/LumieraHelpLandingPage.NOTICE new file mode 100644 index 000000000..6a4525d7b --- /dev/null +++ b/doc/devel/LumieraHelpLandingPage.NOTICE @@ -0,0 +1,16 @@ +NOTE: this is a placeholder -- the intention is to build a user Manual via Asciidoc + +As of 2025, Lumiera is not usable, and thus only a placeholder HTML page is provided +for the DEB-Package. The content on this page is identical to the "User-Manual" page: +https://Lumiera.org/documentation/user/manual.html + +For the delivery +- this page has been rendered with Asciidoc +- the resulting HTML has been processed with the "Print Edit WE" plugin of Firefox, + which inlines any resources (CSS, images) + +This page will be installed by the Lumiera SCons build into $prefix/share/doc/lumiera +(see doc/SConsscript) + +Hint: for updates, re-render the Asciidoc and then use git/diff to combine the + new or changed content with the embedded inline images (base64 data) diff --git a/doc/devel/LumieraHelpLandingPage.html b/doc/devel/LumieraHelpLandingPage.html new file mode 100644 index 000000000..fa19103df --- /dev/null +++ b/doc/devel/LumieraHelpLandingPage.html @@ -0,0 +1,699 @@ + + + + + + + + + + + + + +Lumiera User Manual + + +
+
Lumiera
+
The new emerging NLE for GNU/Linux
+
+
+
+ +
+ + + +
+
+
+
There is no »User Manual« — yet

The plan is to create the manual and tutorials later in a collaborative way.
+This work is postponed until the software is actually usable.

+
What is »Lumiera«?

Lumiera is a Free/Open Source project to build a Non-Linear Video Editing (NLE) +and compositing application for GNU/Linux. +Its primary focus is professional editing, quality, usability and flexibility. +On the one hand, it must meet the rigours of a professional +film and video production environment; on the other hand, it must +be flexible enough to satisfy the needs of more modest single-user +equipment.

+

These ambitious goals have led us to a complex and flexible internal structure, +over the course of the last years. Many elements still need to be connected and +integrated, so that the functionality becomes visible and can be explored by users. +And we are a small team. Nevertheless, please be assured that work on the project is ongoing.

+
+
+
+
+

UI Experiments

+
+

While most of the work is focused at the inner workings of the Render Engine +(as of Nov.2025), the User Interface has been upgraded to GTK-3 and outfitted with +some experimental connection channels, to test interplay with the application core.

+

After launching the lumiera application, a main window will be displayed.

+

+ + + +

+
+

Video Output

+

The play / pause / stop buttons will activate some video output demo code, +which is actually quite old — it was extracted 2009 from the Kino +video editing software and used for various experiments since then. In its current shape, +this dummy playback ensures that Lumiera is properly built and linked to use the +XVideo standard with the help of the X11 XServer. +This archaic standard from 1991 presumably was the first widely available and vendor-neutral interface +for passing raw video frames to the GPU, which then scales and integrates them into the desktop display.

+

The video frames for this demo are not generated by the Lumiera Render Engine — and +thus this code is largely obsolete; maybe it will continue to live somewhere as a fallback +for systems without proper support of OpenGL?

+
+
+

The UI-Bus

+

Instead of accessing a shared data model, the Lumiera UI is connected to the core +through an asynchronous messaging channel, to dispatch command instructions into the +session and to push responses up into the UI. There is a demo to verify this setup +by pushing info and error messages into the »Info Box«

+
    +
  • +

    +In the “Help” menu, there is the entry ‘Help > Self Tests’ +

    +
  • +
  • +

    +The tab #1099 in this non-modal dialog box + allows to push notification messages into the UI-Bus… +

    +
      +
    • +

      +enter some text into the input widget at the top +

      +
    • +
    • +

      +send a display message with this text at Info / Warn / or Error level +

      +
    • +
    • +

      +or push the “mark” button to send a mark message, selected from the + drop-down +

      +
    • +
    +
  • +
+
+
+

Timeline Display

+

The second tab in this “Test and Diagnostics” dialog box (‘Help > Self Tests’) +allows to Populate the Timeline Display with a structure corresponding to session content. +This structure is sent over the UI-Bus as a “Diff Message” — basically the core can notify +the UI about changes in structured content elements, which both sides know, without ever sharing +a common data representation.

+

This demo engages this mechanism to populate an previously empty Timeline with structured content; +the actual content is hard-wired for this test, offering two flavours (“Sequence 1” and “Sequence 2”).

+
+
+Sequence 1 +
+
+

+ A single Track, with two Clips, which can be clicked and dragged; they have a fixed given length, + but no further content. +

+
+
+Sequence 2 +
+
+

+ A complex arrangement of nested tracks, some of which are expanded, and some have overview rulers. + Note that it is possible to scroll vertically, while the top-level overview rulers remain always + visible and pinned on top. Note furthermore that the Track-Head display in the left pane scrolles + alongside, and remains in sync with the main content pane. Tracks can not yet be expanded / collapsed +

+
+
+

The Button “move elements” is part of an ongoing experiment and currently disabled.

+
+ + + +
+Note +the panes can be undocked and re-arranged, but retain their identity, so that + they can be addressed via UI-Bus without knowing where they are actually located + in the UI. And there are various known problems related to those docks…
+
+
+
+
+
+

+
+
+ + + diff --git a/doc/user/manual.txt b/doc/user/manual.txt index d5952352a..ef02b532f 100644 --- a/doc/user/manual.txt +++ b/doc/user/manual.txt @@ -1,8 +1,93 @@ Lumiera User Manual =================== -The plan is to create the users manual later in a collaborative -fashion, which was effective for Cinelerra. +.There is no »User Manual« -- yet +The plan is to create the manual and tutorials later in a collaborative way. + +This work is postponed until the software is actually usable. -This work is postponed until the software is actually working. +.What is »Lumiera«? +Lumiera is a Free/Open Source project to build a Non-Linear Video Editing (NLE) +and compositing application for GNU/Linux. +Its primary focus is professional editing, quality, usability and flexibility. +On the one hand, it must meet the rigours of a professional +film and video production environment; on the other hand, it must +be flexible enough to satisfy the needs of more modest single-user +equipment. +These ambitious goals have led us to a complex and flexible internal structure, +over the course of the last years. Many elements still need to be connected and +integrated, so that the functionality becomes visible and can be explored by users. +And we are a small team. Nevertheless, please be assured that work on the project is ongoing. + +- Look at the https://git.lumiera.org/[Git repositories] to see current activity +- Visit the http://Lumiera.org/documentation/user/intro/intro.html[»Lumiera from Outer Space«] + page at the https://Lumiera.org[Lumiera.org] website to read more about the Design and Vision. + + +UI Experiments +-------------- +While most of the work is focused at the inner workings of the Render Engine +(as of Nov.2025), the User Interface has been upgraded to GTK-3 and outfitted with +some experimental connection channels, to test interplay with the application core. + +After launching the `lumiera` application, a main window will be displayed. + +image:{imgg}/lumiera20250823.png["Lumiera GTK UI / Screenshot 2025-08",width=650, link="{imgg}/lumiera20250823.png"] + + +Video Output +~~~~~~~~~~~~ +The [green]#▶#_play_ / [blue]#⏸#_pause_ / [red]#⏹#_stop_ buttons will activate some video output demo code, +which is actually quite old -- it was extracted 2009 from the https://en.wikipedia.org/wiki/Kino_(software)[Kino] +video editing software and used for various experiments since then. In its current shape, +this dummy playback ensures that Lumiera is properly built and linked to use the +https://en.wikipedia.org/wiki/X_video_extension[XVideo] standard with the help of the X11 XServer. +This _archaic_ standard from 1991 presumably was the first widely available and vendor-neutral interface +for passing raw video frames to the GPU, which then scales and integrates them into the desktop display. + +The video frames for this demo _are not generated by the Lumiera Render Engine_ -- and +thus this code is largely obsolete; maybe it will continue to live somewhere as a fallback +for systems without proper support of OpenGL? + +The UI-Bus +~~~~~~~~~~ +Instead of accessing a shared data model, the Lumiera UI is connected to the core +through an _asynchronous messaging channel,_ to dispatch command instructions into the +session and to push responses up into the UI. There is a demo to verify this setup +by pushing info and error messages into the »Info Box« + +- In the ``Help'' menu, there is the entry `Help > Self Tests' +- The tab https://issues.lumiera.org/ticket/1099[#1099] in this non-modal dialog box + allows to push notification messages into the UI-Bus... + + * enter some text into the input widget at the top + * send a display message with this text at Info / Warn / or Error level + * or push the ``mark'' button to send a `mark` message, selected from the + drop-down + +Timeline Display +~~~~~~~~~~~~~~~~ +The second tab in this ``Test and Diagnostics'' dialog box (`Help > Self Tests') +allows to _Populate the Timeline Display_ with a structure corresponding to session content. +This structure is sent over the UI-Bus as a ``Diff Message'' -- basically the core can notify +the UI about changes in structured content elements, which both sides know, without ever sharing +a common data representation. + +This demo engages this mechanism to _populate_ an previously empty Timeline with structured content; +the actual content is hard-wired for this test, offering two flavours (``Sequence 1'' and ``Sequence 2''). + +Sequence 1:: + A single Track, with two Clips, which can be clicked and dragged; they have a fixed given length, + but no further content. + +Sequence 2:: + A complex arrangement of nested tracks, some of which are expanded, and some have overview rulers. + Note that it is possible to scroll vertically, while the top-level overview rulers remain always + visible and pinned on top. Note furthermore that the _Track-Head display_ in the left pane scrolles + alongside, and remains in sync with the main content pane. Tracks can not yet be expanded / collapsed + +The Button ``move elements'' is part of an ongoing experiment and currently disabled. + +NOTE: the panes can be undocked and re-arranged, but retain their identity, so that + they can be addressed via UI-Bus without knowing where they are actually located + in the UI. [red]#And there are various known problems related to those docks...#