OpenShot Library | OpenShotAudio 0.2.2
juce_AudioSource.h
1
2/** @weakgroup juce_audio_basics-sources
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30//==============================================================================
31/**
32 Used by AudioSource::getNextAudioBlock().
33
34 @tags{Audio}
35*/
37{
38 /** Creates an uninitialised AudioSourceChannelInfo. */
40
41 /** Creates an AudioSourceChannelInfo. */
43 int startSampleOffset, int numSamplesToUse) noexcept
44 : buffer (bufferToUse),
45 startSample (startSampleOffset),
46 numSamples (numSamplesToUse)
47 {
48 }
49
50 /** Creates an AudioSourceChannelInfo that uses the whole of a buffer.
51 Note that the buffer provided must not be deleted while the
52 AudioSourceChannelInfo is still using it.
53 */
54 explicit AudioSourceChannelInfo (AudioBuffer<float>& bufferToUse) noexcept
55 : buffer (&bufferToUse),
56 startSample (0),
57 numSamples (bufferToUse.getNumSamples())
58 {
59 }
60
61 /** The destination buffer to fill with audio data.
62
63 When the AudioSource::getNextAudioBlock() method is called, the active section
64 of this buffer should be filled with whatever output the source produces.
65
66 Only the samples specified by the startSample and numSamples members of this structure
67 should be affected by the call.
68
69 The contents of the buffer when it is passed to the AudioSource::getNextAudioBlock()
70 method can be treated as the input if the source is performing some kind of filter operation,
71 but should be cleared if this is not the case - the clearActiveBufferRegion() is
72 a handy way of doing this.
73
74 The number of channels in the buffer could be anything, so the AudioSource
75 must cope with this in whatever way is appropriate for its function.
76 */
78
79 /** The first sample in the buffer from which the callback is expected
80 to write data. */
82
83 /** The number of samples in the buffer which the callback is expected to
84 fill with data. */
86
87 /** Convenient method to clear the buffer if the source is not producing any data. */
89 {
90 if (buffer != nullptr)
91 buffer->clear (startSample, numSamples);
92 }
93};
94
95
96//==============================================================================
97/**
98 Base class for objects that can produce a continuous stream of audio.
99
100 An AudioSource has two states: 'prepared' and 'unprepared'.
101
102 When a source needs to be played, it is first put into a 'prepared' state by a call to
103 prepareToPlay(), and then repeated calls will be made to its getNextAudioBlock() method to
104 process the audio data.
105
106 Once playback has finished, the releaseResources() method is called to put the stream
107 back into an 'unprepared' state.
108
109 @see AudioFormatReaderSource, ResamplingAudioSource
110
111 @tags{Audio}
112*/
114{
115protected:
116 //==============================================================================
117 /** Creates an AudioSource. */
118 AudioSource() = default;
119
120public:
121 /** Destructor. */
122 virtual ~AudioSource() = default;
123
124 //==============================================================================
125 /** Tells the source to prepare for playing.
126
127 An AudioSource has two states: prepared and unprepared.
128
129 The prepareToPlay() method is guaranteed to be called at least once on an 'unprepared'
130 source to put it into a 'prepared' state before any calls will be made to getNextAudioBlock().
131 This callback allows the source to initialise any resources it might need when playing.
132
133 Once playback has finished, the releaseResources() method is called to put the stream
134 back into an 'unprepared' state.
135
136 Note that this method could be called more than once in succession without
137 a matching call to releaseResources(), so make sure your code is robust and
138 can handle that kind of situation.
139
140 @param samplesPerBlockExpected the number of samples that the source
141 will be expected to supply each time its
142 getNextAudioBlock() method is called. This
143 number may vary slightly, because it will be dependent
144 on audio hardware callbacks, and these aren't
145 guaranteed to always use a constant block size, so
146 the source should be able to cope with small variations.
147 @param sampleRate the sample rate that the output will be used at - this
148 is needed by sources such as tone generators.
149 @see releaseResources, getNextAudioBlock
150 */
151 virtual void prepareToPlay (int samplesPerBlockExpected,
152 double sampleRate) = 0;
153
154 /** Allows the source to release anything it no longer needs after playback has stopped.
155
156 This will be called when the source is no longer going to have its getNextAudioBlock()
157 method called, so it should release any spare memory, etc. that it might have
158 allocated during the prepareToPlay() call.
159
160 Note that there's no guarantee that prepareToPlay() will actually have been called before
161 releaseResources(), and it may be called more than once in succession, so make sure your
162 code is robust and doesn't make any assumptions about when it will be called.
163
164 @see prepareToPlay, getNextAudioBlock
165 */
166 virtual void releaseResources() = 0;
167
168 /** Called repeatedly to fetch subsequent blocks of audio data.
169
170 After calling the prepareToPlay() method, this callback will be made each
171 time the audio playback hardware (or whatever other destination the audio
172 data is going to) needs another block of data.
173
174 It will generally be called on a high-priority system thread, or possibly even
175 an interrupt, so be careful not to do too much work here, as that will cause
176 audio glitches!
177
178 @see AudioSourceChannelInfo, prepareToPlay, releaseResources
179 */
180 virtual void getNextAudioBlock (const AudioSourceChannelInfo& bufferToFill) = 0;
181};
182
183} // namespace juce
184
185/** @}*/
void clear() noexcept
Clears all the samples in all channels.
Base class for objects that can produce a continuous stream of audio.
virtual void releaseResources()=0
Allows the source to release anything it no longer needs after playback has stopped.
AudioSource()=default
Creates an AudioSource.
virtual void prepareToPlay(int samplesPerBlockExpected, double sampleRate)=0
Tells the source to prepare for playing.
virtual ~AudioSource()=default
Destructor.
virtual void getNextAudioBlock(const AudioSourceChannelInfo &bufferToFill)=0
Called repeatedly to fetch subsequent blocks of audio data.
#define JUCE_API
This macro is added to all JUCE public class declarations.
Used by AudioSource::getNextAudioBlock().
AudioSourceChannelInfo(AudioBuffer< float > *bufferToUse, int startSampleOffset, int numSamplesToUse) noexcept
Creates an AudioSourceChannelInfo.
int numSamples
The number of samples in the buffer which the callback is expected to fill with data.
void clearActiveBufferRegion() const
Convenient method to clear the buffer if the source is not producing any data.
AudioBuffer< float > * buffer
The destination buffer to fill with audio data.
AudioSourceChannelInfo(AudioBuffer< float > &bufferToUse) noexcept
Creates an AudioSourceChannelInfo that uses the whole of a buffer.
AudioSourceChannelInfo()=default
Creates an uninitialised AudioSourceChannelInfo.
int startSample
The first sample in the buffer from which the callback is expected to write data.