From 1d0ef6337f95ec456bde7b997d0e34e2a32aee83 Mon Sep 17 00:00:00 2001 From: Robin Gareus Date: Mon, 27 May 2024 19:14:06 +0200 Subject: [PATCH] Overhaul doxygen main page --- doc/Doxyfile | 6 +- doc/mainpage.md | 300 +++++++++++++++++++++++++++++++++++++ doc/mainpage.txt | 13 -- doc/source_tree_layout.txt | 203 ------------------------- 4 files changed, 303 insertions(+), 219 deletions(-) create mode 100755 doc/mainpage.md delete mode 100755 doc/mainpage.txt delete mode 100644 doc/source_tree_layout.txt diff --git a/doc/Doxyfile b/doc/Doxyfile index dad5be17f7..b744c4cda3 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -854,7 +854,8 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../gtk2_ardour \ +INPUT = mainpage.md \ + ../gtk2_ardour \ ../libs/ardour \ ../libs/ardouralsautil \ ../libs/audiographer \ @@ -882,7 +883,6 @@ INPUT = ../gtk2_ardour \ ../libs/widgets \ ../libs/zita-convolver \ ../libs/zita-resampler \ - mainpage.txt ## ytk internal use only # ../libs/tk/ydk-pixbuf/ydk-pixbuf/gdk-pixbuf \ ## tools w/binaries (maybe add those) @@ -1057,7 +1057,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = mainpage.md #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/doc/mainpage.md b/doc/mainpage.md new file mode 100755 index 0000000000..c730ffc9ea --- /dev/null +++ b/doc/mainpage.md @@ -0,0 +1,300 @@ +# Ardour - the open source Digital Audio Workstation + +Welcome to the in-code documentation for Ardour. + +The main components of Ardour are as follows: + +- A GTK2 front-end, in `gtk2_ardour`. +- libardour, the audio-processing back-end, in `libs/ardour`. + + + +The source tree is laid out as follows: + +## 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 + +## Libraries + +A collection of libraries and utility functions. Most are shared +libraries, and almost all are exclusive to Ardour. + +A few specific libraries are compiled statically (e.g. fluidsynth for use in plugins). + +### Ardour specific libs + +* `libs/pbd/` + + Generic utility classes. This is used the basis for all Ardour specific libraries. + It provides basic concepts and OS abstractions. + + *The name comes from "Paul Barton-Davis", Paul's full name at the time he started working on working on audio software.* + +* `libs/evoral/` + + Control events, control lists, automation evaluation, + parameter descriptions, incl. MIDI event abstraction + + - `libs/evoral/libsmf/` (contains several non-upstreamed fixes) + + Handling Standard MIDI File format. Abstracted to C++ in SMF.{cc,h} + (used inside evoral) + +* libs/backends/ + + Interaction with Operating System's Audio/MIDI API: + ALSA, CoreAudio, JACK, PortAudio/ASIO, PulseAudio + +* `libs/surfaces/` + + Control Surfaces, dynamically loaded by libardour on runtime, + to remote-control ardour (midi bindings, network etc). + +* `libs/midi++2/` + + MIDI parsing, MIDNAM handling, Port abstraction for I/O + +* `libs/temporal` + + Various utility code for dealing with different kinds of time, + including Timecode (FPS) and musical time conversions. + + This library also provides the fundamental time types, and the *TempoMap*. + See for more information. + +* `libs/panners/` + + Pan plugins (stereo-balance, VBAP, etc) are dynamically loaded at runtime. + +* `libs/audiographer/` + + Mini Ardour inside Ardour to export audio-files from sessions. + +* `libs/ardour/` + + This is it. libardour runs Ardour sessions. + + All realtime processing happens here, plugins are managed etc. + +### UI related libs + +* libs/gtkmm2ext/ + + 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 control + surfaces). + +* `libs/canvas/` + + Cairo Canvas, provides a slate for scalable drawing and basic layout/packing + This is used by `gtk2ardour`'s main editor. + +* `libs/widgets/` + + Ardour GUI widgets (buttons, fader, knobs, etc) + +* `libs/waveview/` + + Threaded waveform rendering and waveform image cache. + +* libs/tk/ + + A localized version of GTK+2, renamed as YTK: + + - `libs/tk/ydk` `libs/tk/ytk` + + gdk, gtk based on upstream gtk+ 2.24.23 + + - `libs/tk/ydk-pixbuf` + + stripped down version of gdk-pixbuf 2.31.1 + + - `libs/tk/ydkmm` , `libs/tk/ytkmm` + + gdkmm, gtkmm based on upstream gtkmm 2.45.3 + + - `libs/tk/ztk` + + atk 2.14.0 + + - `libs/tk/ztkmm` + + atkmm 2.22.7 + + - `libs/tk/suil` + + A local copy of (based on 0.10.8). + Since GTK2 is in our source tree, we also need to provide various plugin UI wrappers + (`x11_in_gtk2`, `win_in_gtk2`, `suil_cocoa_in_gtk2`). + +### Plugin Scan Tools + +By default plugins are scanned by a dedictaed external process. If that crashes the +main application is not affected, and the plugin that causes the scanner to crash can be +blacklisted. + +For practical and historical reasons the actual scanner code lives inside libardour. + +* `libs/auscan/` + + Apple Audio Unit Plugin Scan commandline tool. + +* `libs/fst/` + + VST2/3 plugin scan commandline tools + +* `libs/vfork/` + + A exec-wrapper which redirects file-descriptors to be used with vfork(2) + + +### Ardour Community Effect (ACE) Plugins + +* `libs/plugins/` + + A *bread and butter* set of LV2 Plugins included with Ardour. + + Many of them are custom version of existing plugins (zamaudio, x42), + that have been customized to be bundled with Ardour on all platforms + that ardour runs on. + + +### Independent, standalone libs + +* `libs/aaf/` + + Unmodified for importing AAF sessions. + use `tools/update_libaaf.sh` to update from upstream. + +* `libs/appleutility/` + + Utility Classes, abstraction for CoreAudio and AudioUnits (OSX, macOS) + +* `libs/ardouralsautil/` + + Utility Class for device-listing (used by the jack and ALSA backends). + Device-reservation commandline tool (linked against libdbus), which is + also available from + +* `libs/clearlooks-newer/` + + GTK theme engine (used by `gtk2_ardour`) + +* `libs/fluidsynth/` + + Stripped down (library only) and slightly customized version of fluidsynth. + Use `tools/update_fluidsynth.sh` to update from upstream. + +* `libs/hidapi/` + + Unmodified for interaction with some + control surfaces (Push2, NI Maschine) + +* `libs/libltc/` + + Unmodified for Linear Timecode en/decoding + +* `libs/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 + (C++ bindings) + +* `libs/ptformat/` + + Unmodified for loading ProTools sessions + +* `libs/qm-dsp/` + + Stripped down version of + The Queen Mary DSP library is used by VAMP Plugins. + +* `vamp-plugins` + + VAMP plugins for audio analysis and offline processing (uses qm-dsp) + +* `libs/vamp-pyin/` + + VAMP plugins for pitch and note-tracking (uses qm-dsp), offline analysis + +* `libs/vst3/` + + Stripped down version of Steinberg's VST3 SDK + + use `tools/update_vst3.sh` to update from upstream + +* `libs/zita-convolver/` + + convolution kernel, so far only available to Lua scripts. + +* `libs/zita-resampler/` + + Efficient resampler with variable rate, useful for adaptive resampling. + Mainly used for vari-speed playback. This has been customized for multiple mono + channel processing, and optimized to skip processing for a ratio of 1:1. + + +## RESOURCE FILES + +These are bundled as-is. + +* `share/export/` + + Export Presets + +* `share/mcp/` + + Mackie control surface device files + +* `share/midi_maps/` + + Generic MIDI control surface presets + +* `share/osc/` + + Configuration presets for the OSC control surface + +* `share/patchfiles/` + + MIDNAM files, MIDI synth descriptions (note-names, CC, PGM names) + +* `share/scripts/` + + Lua scripts (files with a leading underscore are not bundled). + see `share/scripts/README` for file name convention. + +* `share/templates/` + + Session templates (currently none) + +## MISC + +* `doc/` + + Misc developer oriented documentation files and Doxygen + +* `patches/` + + Some .diff files for the build-stack. + +* `tools/` + + Various developer tools, most notably packaging scripts diff --git a/doc/mainpage.txt b/doc/mainpage.txt deleted file mode 100755 index 5834a9f63a..0000000000 --- a/doc/mainpage.txt +++ /dev/null @@ -1,13 +0,0 @@ -/** \mainpage Ardour - * - * Welcome to the in-code documentation for Ardour. - * - * The main components of Ardour are as follows: - * - A GTK2 front-end, in \c gtk2_ardour. - * - libardour, the audio-processing back-end, in \c libs/ardour. - * - libpbd, a utility library, in \c libs/pbd. - * - * There are other assorted component libraries: - * - gtkmm2ext, an library of extensions to gtkmm2, in \c libs/gtkmm2ext. - * - and others... - */ diff --git a/doc/source_tree_layout.txt b/doc/source_tree_layout.txt deleted file mode 100644 index 8d6b3ece5e..0000000000 --- a/doc/source_tree_layout.txt +++ /dev/null @@ -1,203 +0,0 @@ -Ardour Source-Tree layout (Feb 2022) - -===== 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 - -===== LIBRARIES ===== - A collection of libraries and utility functions. While most are shared - libraries, and almost all are exclusive to Ardour. - -libs/ - - **** Independent, standalone libs **** - - - libs/appleutility/ - Utility Classes, abstraction for CoreAudio and AudioUnits (OSX, macOS) - - - libs/ardouralsautil/ - Utility Class for device-listing (used by the jack and ALSA backends). - Device-reservation commandline tool (linked against libdbus), which is - also available from https://github.com/x42/alsa_request_device - - - libs/clearlooks-newer/ - GTK theme engine (used by gtk2_ardour) - - - libs/fluidsynth/ - Stripped down (library only) and slightly customized version of fluidsynth - use tools/update_fluidsynth.sh to update from upstream - - - libs/hidapi/ - Unmodified https://github.com/signal11/hidapi for interaction with some - control surfaces (Push2, NI Maschine) - - - libs/libltc/ - Unmodified https://github.com/x42/libltc/ for Linear Timecode en/decoding - - - libs/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) - - - libs/midi++2/ - (uses libpdb) - MIDI parsing, MIDNAM handling, Port abstraction for I/O - - - libs/ptformat/ - Unmodified https://github.com/zamaudio/ptformat for loading ProTools sessions - - - libs/temporal - various utility code for dealing with different kinds of time, - including Timecode (FPS) and musical time conversions - - - libs/qm-dsp/ - Stripped down version of https://github.com/c4dm/qm-dsp - The Queen Mary DSP library is used by VAMP Plugins - - - vamp-plugins - VAMP plugins for audio analysis and offline processing (uses qm-dsp) - - - libs/vamp-pyin/ - VAMP plugins for pitch and note-tracking (uses qm-dsp), offline analysis - - - libs/vfork/ - A exec-wrapper which redirects file-descriptors to be used with vfork(2) - - - libs/vst3/ - Stripped down version of Steinberg's VST3 SDK - https://github.com/steinbergmedia/vst3sdk/ - see also tools/update_vst3.sh - - - libs/plugins/ - LV2 Plugins included with Ardour. These are currently mostly - 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 - that ardour runs on. - - - libs/zita-convolver/ - convolution kernel, so far only available to Lua scripts. - - - libs/zita-resampler/ - Efficient resampler with variable rate, useful for adaptive resampling. - Mainly used for vari-speed playback. - - **** PBD dependent libs **** - - - libs/pbd/ - Generic non-Ardour-specific utility classes. This is the basis for all Ardour specifics. - It provides basic concepts and OS abstractions. The name comes from "Paul - Barton-Davis", Paul's full name at the time he started working on working on - audio software. - - - libs/evoral/ - (uses libpbd) - Control events, control lists, automation evaluation, - parameter descriptions, incl MIDI event abstraction - - - libs/evoral/libsmf/ (contains several non-upstreamed fixes) - (used inside evoral) - Handling Standard MIDI File format. Abstracted to C++ in SMF.{cc,h} - - - libs/backends/ - (uses libpdb, ardouralsautil | appleutility, implements libardour interface) - Interaction with Operating System's Audio/MIDI API: - ALSA, CoreAudio, JACK, PortAudio/ASIO, PulseAudio - - - libs/surfaces/ - (uses libpbd, libevoral, libtimecode, libardour ;; libgtkmm2ext, libcanvas) - Control Surfaces, dynamically loaded by libardour on runtime, - to remote-control ardour (midi bindings, network etc). - - - libs/panners/ - (uses libpdb, implements libardour interface) - Pan plugins (stereo-balance, VBAP, etc) are dynamically loaded at runtime. - - - libs/audiographer/ - (uses libpdb) - Mini Ardour inside Ardour to export audio-files from sessions. - - - libs/ardour/ - (uses pretty much all the libs above) - This is it. libardour runs Ardour sessions - All realtime processing happens here, plugins are managed etc. - - **** Plugin Scan Tools **** - - - libs/auscan/ - Apple Audio Unit Plugin Scan commandline tool. - - - libs/fst/ - VST2/3 plugin scan commandline tool. - - - **** UI related libs **** - - - libs/gtkmm2ext/ - (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 control - surfaces). - - - libs/canvas/ - (uses libpbd, libgtkmm2ext) - Cairo Canvas, provides a slate for scalable drawing and basic layout/packing - This is used by gtk2ardour's main editor. - - - libs/widgets/ - (uses libpbd, libgtkmm2ext ;; libcanvas utils/colors) - Ardour GUI widgets (buttons, fader, knobs, etc) - - - libs/waveview/ - (uses libpbd, libgtkmm2ext, canvas, libardour) - Threaded waveform rendering and waveform image cache - - -===== RESOURCE FILES ===== -These are bundled as-is. - -share/export/ - Export Presets - -share/mcp/ - Mackie control surface device files - -share/midi_maps/ - Generic MIDI control surface presets - -share/osc/ - Configuration presets for the OSC control surface - -share/patchfiles/ - MIDNAM files, MIDI synth descriptions (note-names, CC, PGM names) - -share/scripts/ - Lua scripts (files with a leading underscore are not bundled) - see also share/scripts/README - -share/templates/ - Session templates (currently none) - - -===== MISC ===== -doc/ - Misc developer oriented documentation files and Doxygen - -patches/ - Some .diff files for the build-stack. - -tools/ - Various developer tools, most notably packaging scripts