← Back to branch summary

~registry/dolphin-emu/triforce

« back to all changes in this revision

Viewing changes to Externals/soundtouch/SoundTouch.h

  • Committer: Sérgio Benjamim
  • Date: 2015-02-13 05:54:40 UTC
  • Revision ID: sergio_br2@yahoo.com.br-20150213055440-ey2rt3sjpy27km78
Dolphin Triforce branch from code.google, commit b957980 (4.0-315).

Show diffs side-by-side

added added

removed removed

Lines of Context:
Externals/soundtouch/SoundTouch.h
 
1
//////////////////////////////////////////////////////////////////////////////
 
2
///
 
3
/// SoundTouch - main class for tempo/pitch/rate adjusting routines. 
 
4
///
 
5
/// Notes:
 
6
/// - Initialize the SoundTouch object instance by setting up the sound stream 
 
7
///   parameters with functions 'setSampleRate' and 'setChannels', then set 
 
8
///   desired tempo/pitch/rate settings with the corresponding functions.
 
9
///
 
10
/// - The SoundTouch class behaves like a first-in-first-out pipeline: The 
 
11
///   samples that are to be processed are fed into one of the pipe by calling
 
12
///   function 'putSamples', while the ready processed samples can be read 
 
13
///   from the other end of the pipeline with function 'receiveSamples'.
 
14
/// 
 
15
/// - The SoundTouch processing classes require certain sized 'batches' of 
 
16
///   samples in order to process the sound. For this reason the classes buffer 
 
17
///   incoming samples until there are enough of samples available for 
 
18
///   processing, then they carry out the processing step and consequently
 
19
///   make the processed samples available for outputting.
 
20
/// 
 
21
/// - For the above reason, the processing routines introduce a certain 
 
22
///   'latency' between the input and output, so that the samples input to
 
23
///   SoundTouch may not be immediately available in the output, and neither 
 
24
///   the amount of outputtable samples may not immediately be in direct 
 
25
///   relationship with the amount of previously input samples.
 
26
///
 
27
/// - The tempo/pitch/rate control parameters can be altered during processing.
 
28
///   Please notice though that they aren't currently protected by semaphores,
 
29
///   so in multi-thread application external semaphore protection may be
 
30
///   required.
 
31
///
 
32
/// - This class utilizes classes 'TDStretch' for tempo change (without modifying
 
33
///   pitch) and 'RateTransposer' for changing the playback rate (that is, both 
 
34
///   tempo and pitch in the same ratio) of the sound. The third available control 
 
35
///   'pitch' (change pitch but maintain tempo) is produced by a combination of
 
36
///   combining the two other controls.
 
37
///
 
38
/// Author        : Copyright (c) Olli Parviainen
 
39
/// Author e-mail : oparviai 'at' iki.fi
 
40
/// SoundTouch WWW: http://www.surina.net/soundtouch
 
41
///
 
42
////////////////////////////////////////////////////////////////////////////////
 
43
//
 
44
// Last changed  : $Date: 2013-06-12 15:24:44 +0000 (Wed, 12 Jun 2013) $
 
45
// File revision : $Revision: 4 $
 
46
//
 
47
// $Id: SoundTouch.h 171 2013-06-12 15:24:44Z oparviai $
 
48
//
 
49
////////////////////////////////////////////////////////////////////////////////
 
50
//
 
51
// License :
 
52
//
 
53
//  SoundTouch audio processing library
 
54
//  Copyright (c) Olli Parviainen
 
55
//
 
56
//  This library is free software; you can redistribute it and/or
 
57
//  modify it under the terms of the GNU Lesser General Public
 
58
//  License as published by the Free Software Foundation; either
 
59
//  version 2.1 of the License, or (at your option) any later version.
 
60
//
 
61
//  This library is distributed in the hope that it will be useful,
 
62
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
 
63
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 
64
//  Lesser General Public License for more details.
 
65
//
 
66
//  You should have received a copy of the GNU Lesser General Public
 
67
//  License along with this library; if not, write to the Free Software
 
68
//  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
69
//
 
70
////////////////////////////////////////////////////////////////////////////////
 
71
 
 
72
#ifndef SoundTouch_H
 
73
#define SoundTouch_H
 
74
 
 
75
#include "FIFOSamplePipe.h"
 
76
#include "STTypes.h"
 
77
 
 
78
namespace soundtouch
 
79
{
 
80
 
 
81
/// Soundtouch library version string
 
82
#define SOUNDTOUCH_VERSION          "1.7.2 (dev)"
 
83
 
 
84
/// SoundTouch library version id
 
85
#define SOUNDTOUCH_VERSION_ID       (10702)
 
86
 
 
87
//
 
88
// Available setting IDs for the 'setSetting' & 'get_setting' functions:
 
89
 
 
90
/// Enable/disable anti-alias filter in pitch transposer (0 = disable)
 
91
#define SETTING_USE_AA_FILTER       0
 
92
 
 
93
/// Pitch transposer anti-alias filter length (8 .. 128 taps, default = 32)
 
94
#define SETTING_AA_FILTER_LENGTH    1
 
95
 
 
96
/// Enable/disable quick seeking algorithm in tempo changer routine
 
97
/// (enabling quick seeking lowers CPU utilization but causes a minor sound
 
98
///  quality compromising)
 
99
#define SETTING_USE_QUICKSEEK       2
 
100
 
 
101
/// Time-stretch algorithm single processing sequence length in milliseconds. This determines 
 
102
/// to how long sequences the original sound is chopped in the time-stretch algorithm. 
 
103
/// See "STTypes.h" or README for more information.
 
104
#define SETTING_SEQUENCE_MS         3
 
105
 
 
106
/// Time-stretch algorithm seeking window length in milliseconds for algorithm that finds the 
 
107
/// best possible overlapping location. This determines from how wide window the algorithm 
 
108
/// may look for an optimal joining location when mixing the sound sequences back together. 
 
109
/// See "STTypes.h" or README for more information.
 
110
#define SETTING_SEEKWINDOW_MS       4
 
111
 
 
112
/// Time-stretch algorithm overlap length in milliseconds. When the chopped sound sequences 
 
113
/// are mixed back together, to form a continuous sound stream, this parameter defines over 
 
114
/// how long period the two consecutive sequences are let to overlap each other. 
 
115
/// See "STTypes.h" or README for more information.
 
116
#define SETTING_OVERLAP_MS          5
 
117
 
 
118
 
 
119
/// Call "getSetting" with this ID to query nominal average processing sequence
 
120
/// size in samples. This value tells approcimate value how many input samples 
 
121
/// SoundTouch needs to gather before it does DSP processing run for the sample batch.
 
122
///
 
123
/// Notices: 
 
124
/// - This is read-only parameter, i.e. setSetting ignores this parameter
 
125
/// - Returned value is approximate average value, exact processing batch
 
126
///   size may wary from time to time
 
127
/// - This parameter value is not constant but may change depending on 
 
128
///   tempo/pitch/rate/samplerate settings.
 
129
#define SETTING_NOMINAL_INPUT_SEQUENCE          6
 
130
 
 
131
 
 
132
/// Call "getSetting" with this ID to query nominal average processing output 
 
133
/// size in samples. This value tells approcimate value how many output samples 
 
134
/// SoundTouch outputs once it does DSP processing run for a batch of input samples.
 
135
///     
 
136
/// Notices: 
 
137
/// - This is read-only parameter, i.e. setSetting ignores this parameter
 
138
/// - Returned value is approximate average value, exact processing batch
 
139
///   size may wary from time to time
 
140
/// - This parameter value is not constant but may change depending on 
 
141
///   tempo/pitch/rate/samplerate settings.
 
142
#define SETTING_NOMINAL_OUTPUT_SEQUENCE         7
 
143
 
 
144
class SoundTouch : public FIFOProcessor
 
145
{
 
146
private:
 
147
    /// Rate transposer class instance
 
148
    class RateTransposer *pRateTransposer;
 
149
 
 
150
    /// Time-stretch class instance
 
151
    class TDStretch *pTDStretch;
 
152
 
 
153
    /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
 
154
    float virtualRate;
 
155
 
 
156
    /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
 
157
    float virtualTempo;
 
158
 
 
159
    /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
 
160
    float virtualPitch;
 
161
 
 
162
    /// Flag: Has sample rate been set?
 
163
    BOOL  bSrateSet;
 
164
 
 
165
    /// Calculates effective rate & tempo valuescfrom 'virtualRate', 'virtualTempo' and 
 
166
    /// 'virtualPitch' parameters.
 
167
    void calcEffectiveRateAndTempo();
 
168
 
 
169
protected :
 
170
    /// Number of channels
 
171
    uint  channels;
 
172
 
 
173
    /// Effective 'rate' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
 
174
    float rate;
 
175
 
 
176
    /// Effective 'tempo' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
 
177
    float tempo;
 
178
 
 
179
public:
 
180
    SoundTouch();
 
181
    virtual ~SoundTouch();
 
182
 
 
183
    /// Get SoundTouch library version string
 
184
    static const char *getVersionString();
 
185
 
 
186
    /// Get SoundTouch library version Id
 
187
    static uint getVersionId();
 
188
 
 
189
    /// Sets new rate control value. Normal rate = 1.0, smaller values
 
190
    /// represent slower rate, larger faster rates.
 
191
    void setRate(float newRate);
 
192
 
 
193
    /// Sets new tempo control value. Normal tempo = 1.0, smaller values
 
194
    /// represent slower tempo, larger faster tempo.
 
195
    void setTempo(float newTempo);
 
196
 
 
197
    /// Sets new rate control value as a difference in percents compared
 
198
    /// to the original rate (-50 .. +100 %)
 
199
    void setRateChange(float newRate);
 
200
 
 
201
    /// Sets new tempo control value as a difference in percents compared
 
202
    /// to the original tempo (-50 .. +100 %)
 
203
    void setTempoChange(float newTempo);
 
204
 
 
205
    /// Sets new pitch control value. Original pitch = 1.0, smaller values
 
206
    /// represent lower pitches, larger values higher pitch.
 
207
    void setPitch(float newPitch);
 
208
 
 
209
    /// Sets pitch change in octaves compared to the original pitch  
 
210
    /// (-1.00 .. +1.00)
 
211
    void setPitchOctaves(float newPitch);
 
212
 
 
213
    /// Sets pitch change in semi-tones compared to the original pitch
 
214
    /// (-12 .. +12)
 
215
    void setPitchSemiTones(int newPitch);
 
216
    void setPitchSemiTones(float newPitch);
 
217
 
 
218
    /// Sets the number of channels, 1 = mono, 2 = stereo
 
219
    void setChannels(uint numChannels);
 
220
 
 
221
    /// Sets sample rate.
 
222
    void setSampleRate(uint srate);
 
223
 
 
224
    /// Flushes the last samples from the processing pipeline to the output.
 
225
    /// Clears also the internal processing buffers.
 
226
    //
 
227
    /// Note: This function is meant for extracting the last samples of a sound
 
228
    /// stream. This function may introduce additional blank samples in the end
 
229
    /// of the sound stream, and thus it's not recommended to call this function
 
230
    /// in the middle of a sound stream.
 
231
    void flush();
 
232
 
 
233
    /// Adds 'numSamples' pcs of samples from the 'samples' memory position into
 
234
    /// the input of the object. Notice that sample rate _has_to_ be set before
 
235
    /// calling this function, otherwise throws a runtime_error exception.
 
236
    virtual void putSamples(
 
237
            const SAMPLETYPE *samples,  ///< Pointer to sample buffer.
 
238
            uint numSamples                         ///< Number of samples in buffer. Notice
 
239
                                                    ///< that in case of stereo-sound a single sample
 
240
                                                    ///< contains data for both channels.
 
241
            );
 
242
 
 
243
    /// Clears all the samples in the object's output and internal processing
 
244
    /// buffers.
 
245
    virtual void clear();
 
246
 
 
247
    /// Changes a setting controlling the processing system behaviour. See the
 
248
    /// 'SETTING_...' defines for available setting ID's.
 
249
    /// 
 
250
    /// \return 'TRUE' if the setting was succesfully changed
 
251
    BOOL setSetting(int settingId,   ///< Setting ID number. see SETTING_... defines.
 
252
                    int value        ///< New setting value.
 
253
                    );
 
254
 
 
255
    /// Reads a setting controlling the processing system behaviour. See the
 
256
    /// 'SETTING_...' defines for available setting ID's.
 
257
    ///
 
258
    /// \return the setting value.
 
259
    int getSetting(int settingId    ///< Setting ID number, see SETTING_... defines.
 
260
                   ) const;
 
261
 
 
262
    /// Returns number of samples currently unprocessed.
 
263
    virtual uint numUnprocessedSamples() const;
 
264
 
 
265
 
 
266
    /// Other handy functions that are implemented in the ancestor classes (see
 
267
    /// classes 'FIFOProcessor' and 'FIFOSamplePipe')
 
268
    ///
 
269
    /// - receiveSamples() : Use this function to receive 'ready' processed samples from SoundTouch.
 
270
    /// - numSamples()     : Get number of 'ready' samples that can be received with 
 
271
    ///                      function 'receiveSamples()'
 
272
    /// - isEmpty()        : Returns nonzero if there aren't any 'ready' samples.
 
273
    /// - clear()          : Clears all samples from ready/processing buffers.
 
274
};
 
275
 
 
276
}
 
277
#endif