| 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]> |