Documentation for Guitarix Developers

1. Measurement of DSP processing times
2. Formatting of source code
3. Thread architecture
4. Parameters (for DSP algorithms etc.)
5. Integration of faust code
6. LADSPA

1. Measurement of DSP processing times
----------------------------------------------------------------

Guitarix must be compiled with --debug (specifically NDEBUG not
defined). Time measurement is switched on by defining the environment
variable GUITARIX_MEASURE. When setting its value to 1 results are
more verbose. Results are printed each second on stdout.

For better controlled measurements you can disable frequency scaling
and set cpu affinity:

$ sudo cpufreq-set -d 800MHz -u 800MHz # or whatever your cpu supports
$ GUITARIX_MEASURE=1 taskset -c 1 guitarix


2. Formatting of source code
----------------------------------------------------------------

We use emacs c++ style "linux" (other formatters like astyle have
similar styles under this name) with following modifications:

 - namespaces do not increase indentation
   in .emacs: (setq c-offsets-alist '((innamespace . 0)))

 - tabs at the beginning of lines, but not for aligning indentation
   ("smart tabs", http://www.emacswiki.org/emacs/SmartTabs). Should
   look correct with any tab width (though for tab width 8 you need
   a wide screen..).


3. Thread architecture
----------------------------------------------------------------

Basically there are 2 threads:

 - the main thread for all work (especially all user interface)
   except audio processing

 - the jack rt thread for audio processing in the process() callback
   in hard real time (as "hard" as available..). The jack notification
   callbacks have more relaxed time constraints and may be executed in
   another thread created by libjack (depends on if you are using
   jack1 or jack2).

All other threads are just waiting for some semaphore or process
signal and delegate their work to the main thread via g_idle_add (this
is safe because the glib main loop data structures are protected by a
mutex).

An exception is the library for the zita convolver, which creates rt
threads to spread the work for convolution processing. But this is
internal to the library.

At some places in the program g_idle and g_timeout callbacks are
called threads, but these are running synchronous in the main loop and
are not meant here (on MP systems the main thread can even run
simultaneously with the rt thread).


4. Parameters (for DSP algorithms etc.)
----------------------------------------------------------------

All parameters have a unique string id. Its a path notation of group,
subgroup(s) and name separated by ".".

There is a base type (Parameter) and a central registry
(ParamMap) for all parameters. Parameters have a user-visible
group and name (e.g. when you set the midi controller for a
parameter) and a description, and can be defined in faust dsp code.

Registered parameters are saved into the application settings file and
possibly into preset files (depending on a flag in the parameter
definition).


5. Integration of faust code
----------------------------------------------------------------

Since faust code (http://faust.grame.fr ) is quite legible, but not so
the generated c++ code, its a good idea to work with the faust code
directly. This could be done by using the faust generated c++ objects
(and quite some runtime shuffling), but we are using the python script
tools/dsp2cc to post-process the faust output (giving some more
control at the expense of being a bit more faust version dependent).

Faust dsp files are in src/faust, the generated files get copied to
src/faust-cc for distribution so the program can be build later even
if faust is not installed (or no compatible version).

6. LADSPA
----------------------------------------------------------------

Guitarix has been allocated the range 4061 - 4099 for LADSPA UniqueID's.