Debian Codegraph @

BambooTracker/chip/blip_buf/blip_buf.txt

raw
1 blip_buf 1.1.0
2 --------------
3 Author : Shay Green <[email protected]>
4 Website : http://www.slack.net/~ant/
5 License : GNU Lesser General Public License (LGPL)
6
7
8 Contents
9 --------
10 * Overview
11 * Buffer creation
12 * Waveform generation
13 * Time frames
14 * Complex waveforms
15 * Sample buffering
16 * Thanks
17
18
19 Overview
20 --------
21 This library resamples audio waveforms from input clock rate to output
22 sample rate. Usage follows this general pattern:
23
24 * Create buffer with blip_new().
25 * Set clock rate and sample rate with blip_set_rates().
26 * Waveform generation loop:
27 - Generate several clocks of waveform with blip_add_delta().
28 - End time frame with blip_end_frame().
29 - Read samples from buffer with blip_read_samples().
30 * Free buffer with blip_delete().
31
32
33 Buffer creation
34 ---------------
35 Before synthesis, a buffer must be created with blip_new(). Its size is
36 the maximum number of unread samples it can hold. For most uses, this
37 can be 1/10 the sample rate or less, since samples will usually be read
38 out immediately after being generated.
39
40 After the buffer is created, the input clock rate and output sample rate
41 must be set with blip_set_rates(). This determines how many input clocks
42 there are per second, and how many output samples are generated per
43 second.
44
45 If the compiler supports a 64-bit integer type, then the input-output
46 ratio is stored very accurately. If the compiler only supports a 32-bit
47 integer type, then the ratio is stored with only 20 fraction bits, so
48 some ratios cannot be represented exactly (for example, sample
49 rate=48000 and clock rate=48001). The ratio is internally rounded up, so
50 there will never be fewer than 'sample rate' samples per second. Having
51 too many per second is generally better than having too few.
52
53
54 Waveform generation
55 -------------------
56 Waveforms are generated at the input clock rate. Consider a simple
57 square wave with 8 clocks per cycle (4 clocks high, 4 clocks low):
58
59 |<-- 8 clocks ->|
60 +5| ._._._._ ._._._._ ._._._._ ._._
61 | | | | | | | |
62 Amp 0|._._._._ | | | | | |
63 | | | | | | |
64 -5| ._._._._ ._._._._ ._._._._
65 * . . . * . . . * . . . * . . . * . . . * . . . * . . . * .
66 Time 0 4 8 12 16 20 24 28
67
68 The wave changes amplitude at time points 0, 4, 8, 12, 16, etc.
69
70 The following generates the amplitude at every clock of above waveform
71 at the input clock rate:
72
73 int wave [30];
74
75 for ( int i = 4; i < 30; ++i )
76 {
77 if ( i % 8 < 4 )
78 wave [i] = -5;
79 else
80 wave [i] = +5;
81 }
82
83 Without this library, the wave array would then need to be resampled
84 from the input clock rate to the output sample rate. This library does
85 this resampling internally, so it won't be discussed further; waveform
86 generation code can focus entirely on the input clocks.
87
88 Rather than specify the amplitude at every clock, this library merely
89 needs to know the points where the amplitude CHANGES, referred to as a
90 delta. The time of a delta is specified with a clock count. The deltas
91 for this square wave are shown below the time points they occur at:
92
93 +5| ._._._._ ._._._._ ._._._._ ._._
94 | | | | | | | |
95 Amp 0|._._._._ | | | | | |
96 | | | | | | |
97 -5| ._._._._ ._._._._ ._._._._
98 * . . . * . . . * . . . * . . . * . . . * . . . * . . . * .
99 Time 0 4 8 12 16 20 24 28
100 Delta +5 -10 +10 -10 +10 -10 +10
101
102 The following calls generate the above waveform:
103
104 blip_add_delta( blip, 4, +5 );
105 blip_add_delta( blip, 8, -10 );
106 blip_add_delta( blip, 12, +10 );
107 blip_add_delta( blip, 16, -10 );
108 blip_add_delta( blip, 20, +10 );
109 blip_add_delta( blip, 24, -10 );
110 blip_add_delta( blip, 28, +10 );
111
112 In the examples above, the amplitudes are small for clarity. The 16-bit
113 sample range is -32768 to +32767, so actual waveform amplitudes would
114 need to be in the thousands to be audible (for example, -5000 to +5000).
115
116 This library allows waveform generation code to pay NO attention to the
117 output sample rate. It can focus ENTIRELY on the essence of the
118 waveform: the points where its amplitude changes. Since these points can
119 be efficiently generated in a loop, synthesis is efficient. Sound chip
120 emulation code can be structured to allow full accuracy down to a single
121 clock, with the emulated CPU being able to simply tell the sound chip to
122 "emulate from wherever you left off, up to clock time T within the
123 current time frame".
124
125
126 Time frames
127 -----------
128 Since time keeps increasing, if left unchecked, at some point it would
129 overflow the range of an integer. This library's solution to the problem
130 is to break waveform generation into time frames of moderate length.
131 Clock counts within a time frame are thus relative to the beginning of
132 the frame, where 0 is the beginning of the frame. When a time frame of
133 length T is ended, what was at time T in the old time frame is now at
134 time 0 in the new time frame. Breaking the above waveform into time
135 frames of 10 clocks each looks like this:
136
137 +5| ._._._._ ._._._._ ._._._._ ._._
138 | | | | | | | |
139 Amp 0|._._._._ | | | | | |
140 | | | | | | |
141 -5| ._._._._ ._._._._ ._._._._
142 * . . . * . . . * . . . * . . . * . . . * . . . * . . . * .
143 Time |0 4 8 | 2 6 |0 4 8 |
144 | first time frame | second time frame | third time frame |
145 |<--- 10 clocks --->|<--- 10 clocks --->|<--- 10 clocks --->|
146
147 The following calls generate the above waveform. After they execute, the
148 first 30 clocks of the waveform will have been resampled and be
149 available as output samples for reading with blip_read_samples().
150
151 blip_add_delta( blip, 4, +5 );
152 blip_add_delta( blip, 8, -10 );
153 blip_end_frame( blip, 10 );
154
155 blip_add_delta( blip, 2, +10 );
156 blip_add_delta( blip, 6, -10 );
157 blip_end_frame( blip, 10 );
158
159 blip_add_delta( blip, 0, +10 );
160 blip_add_delta( blip, 4, -10 );
161 blip_add_delta( blip, 8, +10 );
162 blip_end_frame( blip, 10 );
163 ...
164
165 Time frames can be a convenient length, and the length can vary from one
166 frame to the next. Once a time frame is ended, the resulting output
167 samples become available for reading immediately, and no more deltas can
168 be added to it.
169
170 There is a limit of about 4000 output samples per time frame. The number
171 of clocks depends on the clock rate. At common sample rates, this allows
172 time frames of at least 1/15 second, plenty for most uses. This limit
173 allows increased resampling ratio accuracy.
174
175 In an emulator, it is usually convenient to have audio time frames
176 correspond to video frames, where the CPU's clock counter is reset at
177 the beginning of each video frame and thus can be used directly as the
178 relative clock counts for audio time frames.
179
180
181 Complex waveforms
182 -----------------
183 Any sort of waveform can be generated, not just a square wave. For
184 example, a saw-like wave:
185
186 +5| ._._._._ ._._._._ ._._
187 | | | | | |
188 Amp 0|._._._._ | ._._._._ | ._._._._
189 | | | | |
190 -5| ._._._._ ._._._._
191 * . . . * . . . * . . . * . . . * . . . * . . . * . . . * .
192 Time 0 4 8 12 16 20 24 28
193 Delta +5 -10 +5 +5 -10 +5 +5
194
195 Code to generate above waveform:
196
197 blip_add_delta( blip, 4, +5 );
198 blip_add_delta( blip, 8, -10 );
199 blip_add_delta( blip, 12, +5 );
200 blip_add_delta( blip, 16, +5 );
201 blip_add_delta( blip, 20, +10 );
202 blip_add_delta( blip, 24, +5 );
203 blip_add_delta( blip, 28, +5 );
204
205 Similarly, multiple waveforms can be added within a time frame without
206 problem. It doesn't matter what order they're added, because all the
207 library needs are the deltas. The synthesis code doesn't need to know
208 all the waveforms at once either; it can calculate and add the deltas
209 for each waveform individually. Deltas don't need to be added in
210 chronological order either.
211
212
213 Sample buffering
214 ----------------
215 Sample buffering is very flexible. Once a time frame is ended, the
216 resampled waveforms become output samples that are immediately made
217 available for reading with blip_read_samples(). They don't have to be
218 read immediately; they can be allowed to accumulate in the buffer, with
219 each time frame appending more samples to the buffer. When reading, some
220 or all of the samples in can be read out, with the remaining unread
221 samples staying in the buffer for later. Usually a program will
222 immediately read all available samples after ending a time frame and
223 play them immediately. In some systems, a program needs samples in
224 fixed-length blocks; in that case, it would keep generating time frames
225 until some number of samples are available, then read only that many,
226 even if slightly more were available in the buffer.
227
228 In some systems, one wants to run waveform generation for exactly the
229 number of clocks necessary to generate some desired number of output
230 samples, and no more. In that case, use blip_clocks_needed( blip, N ) to
231 find out how many clocks are needed to generate N additional samples.
232 Ending a time frame with this value will result in exactly N more
233 samples becoming available for reading.
234
235
236 Thanks
237 ------
238 Thanks to Jsr (FamiTracker author), the Mednafen team (multi-system
239 emulator), ShizZie (Nhes GMB author), Marcel van Tongeren, Luke Molnar
240 (UberNES author), Fredrick Meunier (Fuse contributor) for using and
241 giving feedback for another similar library. Thanks to Disch for his
242 interest and discussions about the synthesis algorithm itself, and for
243 writing his own implementation of it (Schpune) rather than just using
244 mine. Thanks to Xodnizel for Festalon, whose sound quality got me
245 interested in video game sound emulation in the first place, and where I
246 first came up with the algorithm while optimizing its brute-force
247 filter.
248
249 --
250 Shay Green <[email protected]>