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.
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).
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.
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!
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.
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.
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.
Please follow these rules if you want to donate code to the SoundTracker project:
if(something) {
work();
}
instead of:
if (something)
{
work ();
}
If you're using Emacs, you can simply use "M-x c-set-style cc-mode"
diff -urN {original-directory} {your-directory} > patch
to generate a file containing only your changes, and no auto-generated
files.
This document was generated on 12 August 2001 using the texi2html translator version 1.51.