OpenShot Library | OpenShotAudio  0.2.1
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 
27 namespace juce
28 {
29 
30 //==============================================================================
31 /**
32  Used by AudioSource::getNextAudioBlock().
33 
34  @tags{Audio}
35 */
37 {
38  /** Creates an uninitialised AudioSourceChannelInfo. */
39  AudioSourceChannelInfo() = default;
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 {
115 protected:
116  //==============================================================================
117  /** Creates an AudioSource. */
118  AudioSource() = default;
119 
120 public:
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 clearActiveBufferRegion() const
Convenient method to clear the buffer if the source is not producing any data.
#define JUCE_API
This macro is added to all JUCE public class declarations.
int numSamples
The number of samples in the buffer which the callback is expected to fill with data.
AudioSourceChannelInfo(AudioBuffer< float > &bufferToUse) noexcept
Creates an AudioSourceChannelInfo that uses the whole of a buffer.
Base class for objects that can produce a continuous stream of audio.
int startSample
The first sample in the buffer from which the callback is expected to write data. ...
AudioBuffer< float > * buffer
The destination buffer to fill with audio data.
AudioSourceChannelInfo(AudioBuffer< float > *bufferToUse, int startSampleOffset, int numSamplesToUse) noexcept
Creates an AudioSourceChannelInfo.
Used by AudioSource::getNextAudioBlock().
void clear() noexcept
Clears all the samples in all channels.