Update source-tree layout description

1 files changed, 72 insertions, 56 deletions

diff --git a/doc/source_tree_layout.txt b/doc/source_tree_layout.txt
index e75675e6f0..e4b8f58999 100644
--- a/doc/source_tree_layout.txt
+++ b/doc/source_tree_layout.txt
@@ -1,4 +1,22 @@
-Ardour Source-Tree layout (July 2017)
+Ardour Source-Tree layout (April 2020)
+
+===== Front Ends =====
+
+gtk2_ardour/
+ The main Ardour GUI -- This is where most of the complexity is :)
+ It is cleanly separated from the backend and processing engine.
+
+headless/
+ hardour -- headless Ardour, mostly demo-code how to use Ardour without a GUI.
+
+session_utils/
+ command-line tools using libardour (e.g. export)
+
+luasession/
+ arlua -- commandline interface to libardour
+
+vst
+ wine application top-level (WindowsVST on Linux)
 
 ===== LIBRARIES =====
  A collection of libraries and utility functions. While most are shared
@@ -8,10 +26,6 @@ libs/
 
  **** Independent libs ****
 
- - fluidsynth
-   Stripped down (library only) and slightly customized version of fluidsynth
-   use  tools/update_fluidsynth.sh to update from upstream
-
  - appleutility
    Utility Classes, abstraction for CoreAudio and AudioUnits (OSX, macOS)
 
@@ -20,6 +34,13 @@ libs/
    Device-reservation comandline tool (linked against libdbus), which is
    also available from https://github.com/x42/alsa_request_device
 
+ - clearlooks-newer
+   GTK theme engine (used by gtk2_ardour)
+
+ - fluidsynth
+   Stripped down (library only) and slightly customized version of fluidsynth
+   use  tools/update_fluidsynth.sh to update from upstream
+
  - hidapi
    Unmodified https://github.com/signal11/hidapi for interaction with some
    control surfaces (Push2, NI Maschine)
@@ -27,11 +48,22 @@ libs/
  - libltc
    Unmodified https://github.com/x42/libltc/ for Linear Timecode en/decoding
 
+ - lua
+   Lua Script interpreter and C++ class abstraction
+   - libs/lua/lua-5.3.5 is unmodified upstream Lua-5.3.5
+   - libs/lua/LuaBridge is a highly customized version of
+     https://github.com/vinniefalco/LuaBridge (C++ bindings)
+
+ - midi++2
+   (uses libpdb, libevoral)
+   Standard MIDI Files I/O
+
  - ptformat
    Unmodified https://github.com/zamaudio/ptformat for loading ProTools sessions
 
- - vfork
-   A exec-wrapper which redirects file-descriptors to be used with vfork(2)
+ - temporal
+   various utility code for dealing with different kinds of time,
+   including Timecode (FPS) and musical time conversions
 
  - qm-dsp
    Stripped down version of https://github.com/c4dm/qm-dsp
@@ -40,28 +72,30 @@ libs/
  - vamp-plugins
    VAMP plugins for audio analysis and offline processing (uses qm-dsp)
 
- - temporal
-   various utility code for dealing with different kinds of time,
-   including Timecode (FPS) and musical time conversions
+ - vamp-pyin
+   VAMP plugins for pitch and note-tracking (uses qm-dsp), offline analyis
 
- - lua
-   Lua Script interpreter and C++ class abstraction
-   - libs/lua/lua-5.3.3 is unmodified upstream Lua-5.3.3
-   - libs/lua/LuaBridge is a highly customized version of
-     https://github.com/vinniefalco/LuaBridge (C++ bindings)
+ - vfork
+   A exec-wrapper which redirects file-descriptors to be used with vfork(2)
 
  - plugins
    LV2 Plugins included with Ardour. These are currently mostly
-   independent (a-fluidsynth uses libfluidsynth)
+   independent (a-fluidsynth uses libfluidsynth).
+   Most of them are custom version of existing plugins (zamaudio, x42),
+   that have been customized to be bundled with Ardour on all platforms
+   tha ardour runs on.
 
- - clearlooks-newer
-   GTK theme engine (used by gtk2_ardour)
+ - zita-convolver
+   convolution kernel, so far only avialable to Lua scripts.
 
+ - zita-resampler
+   Efficient resampler with variable rate, useful for adaptive resampling.
+   Mainly used for vari-speed playback.
 
  **** PBD dependent libs ****
 
  - pbd
-   Paul B-D's utility classes. This is the basis for all Ardour specifics.
+   Paul B. Davis' utility classes. This is the basis for all Ardour specifics.
    It provides basic concepts and OS abstractions.
 
  - evoral
@@ -69,18 +103,15 @@ libs/
    Control events, control lists, automation evaluation,
    parameter descriptions, incl MIDI event abstraction
 
- - midi++2
-   (uses libpdb, libevoral)
-   Standard MIDI Files I/O
-
  - backends
    (uses libpdb, ardouralsautil | appleutility, implements libardour interface)
    Interaction with Operating System's Audio/MIDI API:
-   ALSA, CoreAudio, JACK, PortAudio/ASIO
+   ALSA, CoreAudio, JACK, PortAudio/ASIO, Pulseaudio
 
  - surfaces
    (uses libpbd, libevoral, libtimecode, libardour ;; libgtkmm2ext, libcanvas)
-   Control Surfaces, dynamically loaded by libardour on runtime.
+   Control Surfaces, dynamically loaded by libardour on runtime,
+   to remote-control ardour (midi bindings, network etc).
 
  - panners
    (uses libpdb, implements libardour interface)
@@ -93,11 +124,12 @@ libs/
  - fst
    (uses libpbd, implements external methods for libardour and gtk2ardour)
    VST scanner tool and abstraction for Windows-VSTs to be used with
-   wine or actual windows.
+   wine or MS windows.
 
  - ardour
    (uses pretty much all the libs above)
-   This is it. libardour runs Ardour sessions.
+   This is it. libardour runs Ardour sessions
+   All realtime processing happens here, plugins are managed etc.
 
  **** UI related libs ****
 
@@ -105,43 +137,46 @@ libs/
    (uses libpbd)
    Utility Library to extend GDK, GTK, and basic abstraction for UIs
    and event-loops. This library is not limited to the GUI, but also
-   used for other graphical interfaces (e.g. Push2, NI Maschine)
+   used for other graphical interfaces (e.g. Push2, NI Maschine control
+   surfaces).
 
  - canvas
    (uses libpbd, libgtkmm2ext)
    Cairo Canvas, provides a slate for scalable drawing and basic layout/packing
+  This is used by gtk2ardour's main editor.
 
  - widgets
    (uses libpbd, libgtkmm2ext ;; libcanvas utils/colors)
-   Custom GUI widgets
+   Ardour GUI widgets (buttons, fader, knobs, etc)
 
  - waveview
    (uses libpbd, libgtkmm2ext, canvas,  libardour)
-  Threaded waveform rendering
+   Threaded waveform rendering and waveform image cache
 
 
 ===== RESOURCE FILES =====
 These are bundled as-is.
 
-export/
+share/export/
  Export Presets
 
-mcp/
+share/mcp/
  Mackie control surface device files
 
-midi_maps/
+share/midi_maps/
  Generic MIDI control surface presets
 
-osc/
+share/osc/
  Configuration presets for the OSC control surface
 
-patchfiles/
+share/patchfiles/
  MIDNAM files, MIDI synth descriptions (note-names, CC, PGM names)
 
-scripts/
+share/scripts/
  Lua scripts (files with a leading underscore are not bundled)
+ see also share/scripts/README
 
-templates/
+share/templates/
  Session templates (currently none)
 
 
@@ -154,22 +189,3 @@ patches/
 
 tools/
  Various developer tools, most notably packaging scripts
-
-
-===== Front Ends =====
-
-gtk2_ardour/
- The main Ardour GUI
-
-headless/
- hardour -- headless Ardour, mostly demo-code how to use
- Ardour without a GUI.
-
-session_utils/
- command-line tools using libardour (e.g. export)
-
-luasession/
- arlua -- commandline interface to libardour
-
-vst
- wine application top-level (WindowsVST on Linux)