1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<HTML>
<HEAD>
<!-- Created by texi2html 1.56k from hacking.texi on 26 December 1999 -->
<TITLE>SoundTracker internals</TITLE>
</HEAD>
<BODY>
<H1>SoundTracker internals</H1>
<P>
<P><HR><P>
<H1>Table of Contents</H1>
<UL>
<LI><A NAME="TOC1" HREF="hacking.html#SEC1">General Architecture</A>
<LI><A NAME="TOC2" HREF="hacking.html#SEC2">Synchronization of Audio and GUI</A>
<LI><A NAME="TOC3" HREF="hacking.html#SEC3">How the audio subsystem works</A>
<LI><A NAME="TOC4" HREF="hacking.html#SEC4">Driver API</A>
<UL>
<LI><A NAME="TOC5" HREF="hacking.html#SEC5">Adding drivers to the source tree</A>
<LI><A NAME="TOC6" HREF="hacking.html#SEC6">Output drivers</A>
<LI><A NAME="TOC7" HREF="hacking.html#SEC7">Input drivers</A>
</UL>
<LI><A NAME="TOC8" HREF="hacking.html#SEC8">Mixer API</A>
<LI><A NAME="TOC9" HREF="hacking.html#SEC9">Contributing Code</A>
</UL>
<P><HR><P>
<H1><A NAME="SEC1" HREF="hacking.html#TOC1">General Architecture</A></H1>
<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>
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>
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 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>
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.
<H1><A NAME="SEC2" HREF="hacking.html#TOC2">Synchronization of Audio and GUI</A></H1>
<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>
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>
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.
<H1><A NAME="SEC3" HREF="hacking.html#TOC3">How the audio subsystem works</A></H1>
<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>
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>
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>
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>
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.
<H1><A NAME="SEC4" HREF="hacking.html#TOC4">Driver API</A></H1>
<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>
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>
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!
<H2><A NAME="SEC5" HREF="hacking.html#TOC5">Adding drivers to the source tree</A></H2>
<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.
<H2><A NAME="SEC6" HREF="hacking.html#TOC6">Output drivers</A></H2>
<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>
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>
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>
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>
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>
Now you can start adding the settings widget and add code to the load /
save settings functions.
<H2><A NAME="SEC7" HREF="hacking.html#TOC7">Input drivers</A></H2>
<H1><A NAME="SEC8" HREF="hacking.html#TOC8">Mixer API</A></H1>
<H1><A NAME="SEC9" HREF="hacking.html#TOC9">Contributing Code</A></H1>
<P>
Please follow these rules if you want to donate code to the
SoundTracker project:
<UL>
<LI>Coding Style. I prefer 4-space tabulators, and an indentation style
like this:
<PRE>
if(something) {
work();
}
</PRE>
instead of:
<PRE>
if (something)
{
work ();
}
</PRE>
If you're using Emacs, you can simply use "M-x c-set-style cc-mode"
<LI>Add yourself to the AUTHORS file.
<LI>Add a ChangeLog entry.
<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:
<LI>Generate a patch. Unpack the previously generated archive and the
original archive (into some other directory), and use
<PRE>
diff -urN {original-directory} {your-directory} > patch
</PRE>
to generate a file containing only your changes, and no auto-generated
files.
<LI>Send the patch to the `soundtracker-discuss' mailing-list. If you're
not subscribed, then subscribe first (see README file).
</UL>
<P><HR><P>
This document was generated on 26 December 1999 using
<A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A> 1.56k.
</BODY>
</HTML>
|
