File: hacking.html

package info (click to toggle)
soundtracker 0.6.7-5
links: PTS
area: main
in suites: sarge
size: 3,892 kB
ctags: 3,494
sloc: ansic: 32,988; sh: 3,746; asm: 476; makefile: 453; yacc: 318
file content (657 lines) | stat: -rw-r--r-- 25,533 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<!-- Created on May, 17  2003 by texi2html 1.65 -->
<!-- 
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
            Karl Berry  <karl@freefriends.org>
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
            and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
 
-->
<HEAD>
<TITLE>SoundTracker internals: </TITLE>

<META NAME="description" CONTENT="SoundTracker internals: ">
<META NAME="keywords" CONTENT="SoundTracker internals: ">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.65">

</HEAD>

<BODY LANG="en" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">

<A NAME="SEC_Top"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1>SoundTracker internals</H1></P><P>

<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0> 
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="hacking.html#SEC1">1. General Architecture</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="hacking.html#SEC2">2. Synchronization of Audio and GUI</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="hacking.html#SEC3">3. How the audio subsystem works</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="hacking.html#SEC4">4. Driver API</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="hacking.html#SEC8">5. Mixer API</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="hacking.html#SEC9">6. Contributing Code</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
</TABLE></BLOCKQUOTE>
<P>

<HR SIZE=1>
<A NAME="SEC1"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC2"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC2"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<A NAME="General Architecture"></A>
<H1> 1. General Architecture </H1>
<!--docid::SEC1::-->
<P>

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.
</P><P>

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.
</P><P>

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.
</P><P>

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.
</P><P>

<A NAME="Synchronization of Audio and GUI"></A>
<HR SIZE="6">
<A NAME="SEC2"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC1"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC3"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC1"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC3"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 2. Synchronization of Audio and GUI </H1>
<!--docid::SEC2::-->
<P>

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.
</P><P>

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].
</P><P>

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.
</P><P>

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

<A NAME="How the audio subsystem works"></A>
<HR SIZE="6">
<A NAME="SEC3"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC2"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC4"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC2"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC4"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 3. How the audio subsystem works </H1>
<!--docid::SEC3::-->
<P>

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.
</P><P>

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).
</P><P>

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.
</P><P>

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.
</P><P>

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.
</P><P>

<A NAME="Driver API"></A>
<HR SIZE="6">
<A NAME="SEC4"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC3"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC5"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC3"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC8"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 4. Driver API </H1>
<!--docid::SEC4::-->
<P>

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.
</P><P>

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.
</P><P>

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!
</P><P>

<HR SIZE="6">
<A NAME="SEC5"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC4"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC6"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC6"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.1 Adding drivers to the source tree </H2>
<!--docid::SEC5::-->
<P>

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.
</P><P>

<HR SIZE="6">
<A NAME="SEC6"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC5"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC7"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC7"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC7"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.2 Output drivers </H2>
<!--docid::SEC6::-->
<P>

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.
</P><P>

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.
</P><P>

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.
</P><P>

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.
</P><P>

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.
</P><P>

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

<HR SIZE="6">
<A NAME="SEC7"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC6"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC8"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.3 Input drivers </H2>
<!--docid::SEC7::-->
<P>

<A NAME="Mixer API"></A>
<HR SIZE="6">
<A NAME="SEC8"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC7"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC9"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC4"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC9"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 5. Mixer API </H1>
<!--docid::SEC8::-->
<P>

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.
</P><P>

<A NAME="Contributing Code"></A>
<HR SIZE="6">
<A NAME="SEC9"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC8"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC8"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 6. Contributing Code </H1>
<!--docid::SEC9::-->
<P>

Please follow these rules if you want to donate code to the
SoundTracker project:
</P><P>

<UL>
<LI>Coding Style. I prefer 4-space tabulators, and an indentation style
like this:
<P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>	if(something) {
	    work();
	}
</pre></td></tr></table></P><P>

instead of:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>	if (something)
	  {
	    work ();
	  }
</pre></td></tr></table></P><P>

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

<LI>Add yourself to the AUTHORS file.
<P>

<LI>Add a ChangeLog entry.
<P>

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

<LI>Generate a patch. Unpack the previously generated archive and the
original archive (into some other directory), and use
<P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>	diff -urN {original-directory} {your-directory} &#62; patch
</pre></td></tr></table></P><P>

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

<LI>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.
<P>

<LI>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.
<P>

</UL>
<P>

<HR SIZE="6">
<A NAME="SEC_Contents"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1>Table of Contents</H1>
<BLOCKQUOTE>
<A NAME="TOC1" HREF="hacking.html#SEC1">1. General Architecture</A>
<BR>
<A NAME="TOC2" HREF="hacking.html#SEC2">2. Synchronization of Audio and GUI</A>
<BR>
<A NAME="TOC3" HREF="hacking.html#SEC3">3. How the audio subsystem works</A>
<BR>
<A NAME="TOC4" HREF="hacking.html#SEC4">4. Driver API</A>
<BR>
<BLOCKQUOTE>
<A NAME="TOC5" HREF="hacking.html#SEC5">4.1 Adding drivers to the source tree</A>
<BR>
<A NAME="TOC6" HREF="hacking.html#SEC6">4.2 Output drivers</A>
<BR>
<A NAME="TOC7" HREF="hacking.html#SEC7">4.3 Input drivers</A>
<BR>
</BLOCKQUOTE>
<A NAME="TOC8" HREF="hacking.html#SEC8">5. Mixer API</A>
<BR>
<A NAME="TOC9" HREF="hacking.html#SEC9">6. Contributing Code</A>
<BR>
</BLOCKQUOTE>
<HR SIZE=1>
<A NAME="SEC_OVERVIEW"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1>Short Table of Contents</H1>
<BLOCKQUOTE>
<A NAME="TOC1" HREF="hacking.html#SEC1">1. General Architecture</A>
<BR>
<A NAME="TOC2" HREF="hacking.html#SEC2">2. Synchronization of Audio and GUI</A>
<BR>
<A NAME="TOC3" HREF="hacking.html#SEC3">3. How the audio subsystem works</A>
<BR>
<A NAME="TOC4" HREF="hacking.html#SEC4">4. Driver API</A>
<BR>
<A NAME="TOC8" HREF="hacking.html#SEC8">5. Mixer API</A>
<BR>
<A NAME="TOC9" HREF="hacking.html#SEC9">6. Contributing Code</A>
<BR>

</BLOCKQUOTE>
<HR SIZE=1>
<A NAME="SEC_About"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="hacking.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1>About this document</H1>
This document was generated 
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
<P></P>  
The buttons in the navigation panels have the following meaning:
<P></P>
<table border = "1">
<TR>
<TH> Button </TH>
<TH> Name </TH>
<TH> Go to </TH>
<TH> From 1.2.3 go to</TH>
</TR>
<TR>
<TD ALIGN="CENTER">
 [ &lt; ] </TD>
<TD ALIGN="CENTER">
Back
</TD>
<TD>
previous section in reading order
</TD>
<TD>
1.2.2
</TD>
</TR>
<TR>
<TD ALIGN="CENTER">
 [ &gt; ] </TD>
<TD ALIGN="CENTER">
Forward
</TD>
<TD>
next section in reading order
</TD>
<TD>
1.2.4
</TD>
</TR>
<TR>
<TD ALIGN="CENTER">
 [ &lt;&lt; ] </TD>
<TD ALIGN="CENTER">
FastBack
</TD>
<TD>
previous or up-and-previous section 
</TD>
<TD>
1.1
</TD>
</TR>
<TR>
<TD ALIGN="CENTER">
 [ Up ] </TD>
<TD ALIGN="CENTER">
Up
</TD>
<TD>
up section
</TD>
<TD>
1.2
</TD>
</TR>
<TR>
<TD ALIGN="CENTER">
 [ &gt;&gt; ] </TD>
<TD ALIGN="CENTER">
FastForward
</TD>
<TD>
next or up-and-next section
</TD>
<TD>
1.3
</TD>
</TR>
<TR>
<TD ALIGN="CENTER">
 [Top] </TD>
<TD ALIGN="CENTER">
Top
</TD>
<TD>
cover (top) of document
</TD>
<TD>
 &nbsp; 
</TD>
</TR>
<TR>
<TD ALIGN="CENTER">
 [Contents] </TD>
<TD ALIGN="CENTER">
Contents
</TD>
<TD>
table of contents
</TD>
<TD>
 &nbsp; 
</TD>
</TR>
<TR>
<TD ALIGN="CENTER">
 [Index] </TD>
<TD ALIGN="CENTER">
Index
</TD>
<TD>
concept index
</TD>
<TD>
 &nbsp; 
</TD>
</TR>
<TR>
<TD ALIGN="CENTER">
 [ ? ] </TD>
<TD ALIGN="CENTER">
About
</TD>
<TD>
this page
</TD>
<TD>
 &nbsp; 
</TD>
</TR>
</TABLE>
<P></P>
where the <STRONG> Example </STRONG> assumes that the current position 
is at <STRONG> Subsubsection One-Two-Three </STRONG> of a document of 
the following structure:
<UL>
<LI> 1. Section One  </LI>
<UL>
<LI>1.1 Subsection One-One</LI>
<UL>
<LI> ... </LI>
</UL>
<LI>1.2 Subsection One-Two</LI>
<UL>
<LI>1.2.1 Subsubsection One-Two-One
</LI><LI>1.2.2 Subsubsection One-Two-Two
</LI><LI>1.2.3 Subsubsection One-Two-Three &nbsp; &nbsp; <STRONG>
&lt;== Current Position </STRONG>
</LI><LI>1.2.4 Subsubsection One-Two-Four
</LI></UL>
<LI>1.3 Subsection One-Three</LI>
<UL>
<LI> ... </LI>
</UL>
<LI>1.4 Subsection One-Four</LI>
</UL>
</UL>

<HR SIZE=1>
<BR>  
<FONT SIZE="-1">
This document was generated
by <I>Michael Krause</I> on <I>May, 17  2003</I>
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</FONT>

</BODY>
</HTML>