SoundTracker internals
**********************

1 General Architecture
**********************

SoundTracker (short: ST) consists of two threads: the GUI (or main)
thread, and the audio (or mixer / player) thread. The reason for not
handling both jobs in one process via select() is obvious: the GUI can
sometimes block the process for quite a long time. For example when the
window is resized, widgets have to be redrawn, which can take a while.
To provide continous sound output, we're using a separate thread.

   Communication between the threads is accomplished using two pipes.
The communication codes for this pipe are defined in audio.h. When
messages are received, they are handled in gui.c::read_mixer_pipe() and
audio.c::audio_thread(), respectively.

   In its current form, the code is limited to dealing with one module
at the same time, with one editing window. Some of the GUI code has
already been modularized, since some of the editing facilities have been
encapsulated in custom GTK+ widgets, for example sample-display.c,
clavier.c, envelope-box.c, playlist.c and tracker.c. Noteworthy
exceptions and containers of generous amounts of global variables are
gui.c, sample-editor.c, instrument-editor.c and xm-player.c.

   For ST to be made fully multi-module capable ("object-oriented"),
large parts of the GUI will have to be changed. Unfortunately,
references to the global "tracker" and "xm" variables can be found
virtually everywhere in the source code.

2 Synchronization of Audio and GUI
**********************************

Since mixing buffer sizes can't be turned down as low as under primitive
operating systems such as DOS, special care must been taken to take the
audio latency into account.

   The audio thread thus keeps a list of recently reached pattern
positions and their occurence in the mixed audio output stream. The GUI
thread then checks periodically (track-editor.c::tracker_timeout(),
scope-group.c::scope_group_timeout()) for the current position of the
soundcard in the output stream and calculates which pattern position
corresponds to that time. The get_play_time() method in output drivers
is the key for this to work correctly. The lists are handled through the
time buffer interface, see time-buffer.[ch].

   The oscilloscope monitors are handled in a similar way through some
ring buffers. This is documented in audio.h, for example. time-buffer
can't be used here because scope data is continuous and is accessed
from the GUI thread in more than one location.

   Certain other events are handled through the event waiter interface
(see event-waiter.h for an overview).

3 How the audio subsystem works
*******************************

Module playing is initialized by the GUI thread sending a message
AUDIO_CTLPIPE_PLAY_SONG, for example. The audio thread then opens the
driver module, which in turn installs a callback method, which will be
called as soon as the sound card is accepting new data. The OSS driver,
for example, instructs the audio subsystem, through
audio.c::audio_poll_add(), to call
oss-output.c::oss_poll_ready_playing() once OSS accepts new data from
ST.

   After opening the output driver, various other things are
initialized in audio.c::audio_prepare_for_playing(). After that, an
acknowledgement message is sent back to the GUI thread, which is in
playing mode from then on (indicated by the global variable
gui.c::gui_playing_mode).

   After that, the audio thread goes back into its main poll() loop,
which also waits for the driver callback action now. Once this callback
is triggered, it calls audio.c::audio_mix() (defined in driver-out.h) to
request a new part of the sample output stream in any format and bitrate
it desires, which is then output.

   Calling the XM player at the right moment and handling the pitch
bending feature is all done in audio_mix() which should be rather
straight-forward to read.

   Interesting is also the interaction between xm-player.c and the rest
of the audio subsystem. There are some routines in audio.c starting with
driver_*, like driver_startnote, driver_setfreq. xm-player.c calls these
instead of the corresponding routines in the mixer because this way, a
modularized mixer system could be installed lateron. You can find more
about the Mixer API later in this document.

4 Driver API
************

The driver API is separated into two branches: output and input
(sampling) drivers. Input drivers are usually simpler, because they
don't have to include the mechanisms necessary for synchronization of
the audio output stream with the GUI. Also, currently only 16bit mono
sampling is supported (though changing this would require only some
changes to sample-editor.c), so a good amount of the settings widgets
are missing in input drivers.

   Note that the current API doesn't make any provisions for MIDI input
/ output. First and foremost, it must be thought about the
synchronization of MIDI output with mixed (DSP) output as the most
important aspect; the central audio code in audio.c hasn't been
designed with this in mind either.

   Also not accounted for, but related to the MIDI issue, are wavetable
devices like the GUS which can play multiple samples on their own. But
since hardware like this is more and more becoming extinct and CPU power
rises, I don't think that supporting this is important any longer,
especially once ST will be extended to support effect plug-ins which
can't be rendered by the audio hardware but must be calculated using the
CPU!

4.1 Adding drivers to the source tree
=====================================

You must add checks for any libs and includes in configure.in, add a
corresponding driver define to acconfig.h, add the driver to the drivers
list in main.c, and finally add all the files belonging to your driver
(should be only one) to drivers/Makefile.am. Now you still have to write
the code, that's what the two next sections are about.

4.2 Output drivers
==================

The st_out_driver structure, defined driver-out.h must be globally
defined in your source file. It must contain valid pointers to all the
functions and a unique entry in the name field. The rest of the
variables and functions in your source file should be defined static so
as to hide them from the rest of the program.

   You can keep the *settings functions empty at first, adding the right
code here shouldn't be a problem when you compare with oss-output.c.

   The first function you should write is new(), which allocates a new
object and initializes it with default settings. getwidget() can stay
empty for as long as you don't want the user to change settings.

   The next function you write should be open(), which opens the device
according to the settings in the object structure. release() does the
opposite. open() should install the callback mentioned earlier, which is
the function you're going to write now. That's it, you should have a
working minimal driver now.

   The next important function is getplaytime() which is necessary for
the GUI to synchronize with the audio output. This might require some
experimentation to get right.

   Now you can start adding the settings widget and add code to the
load / save settings functions.

4.3 Input drivers
=================

5 Mixer API
***********

To be written. Two mixers are already available; shouldn't be hard to
understand how it works. Basically it's really independent of the rest
of the tracker.

6 Contributing Code
*******************

Please follow these rules if you want to donate code to the
SoundTracker project:

   * Coding Style. I prefer 4-space tabulators, and an indentation style
     like this:

          	if(something) {
          	    work();
          	}

     instead of:

          	if (something)
          	  {
          	    work ();
          	  }

     If you're using Emacs, you can simply use "M-x c-set-style cc-mode"

   * Add yourself to the AUTHORS file.

   * Add a ChangeLog entry.

   * Do a "make dist" in the main directory. This generates a new
     archive containing your changes. Do NOT send me the whole archive,
     instead:

   * Generate a patch. Unpack the previously generated archive and the
     original archive (into some other directory), and use

          	diff -urN {original-directory} {your-directory} > patch

     to generate a file containing only your changes, and no
     auto-generated files.

   * Remove the `po' directory patches and patches to all auto-generated
     files (Makefile, Makefile.in, configure.log etc.) from the diff
     (that's what usually makes the patch unnecessarily large). Or just
     remove the po directories before generating the diff.

   * Send the patch to the `soundtracker-discuss' mailing-list, if you
     want feedback from other users. If you're not subscribed, then
     subscribe first (see README file). Mail it directly to the
     maintainer (`m.krause@tu-harburg.de') instead of to the list if
     it's large. Please explain what the patch changes.


