Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

180 lines
7.4KB

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