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.

314 lines
14KB

  1. /*
  2. ==============================================================================
  3. This file is part of the JUCE library.
  4. Copyright (c) 2015 - ROLI Ltd.
  5. Permission is granted to use this software under the terms of either:
  6. a) the GPL v2 (or any later version)
  7. b) the Affero GPL v3
  8. Details of these licenses can be found at: www.gnu.org/licenses
  9. JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  10. WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  11. A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  12. ------------------------------------------------------------------------------
  13. To release a closed-source product which uses JUCE, commercial licenses are
  14. available: visit www.juce.com for more information.
  15. ==============================================================================
  16. */
  17. #ifndef JUCE_MPESynthesiser_H_INCLUDED
  18. #define JUCE_MPESynthesiser_H_INCLUDED
  19. //==============================================================================
  20. /**
  21. Base class for an MPE-compatible musical device that can play sounds.
  22. This class extends MPESynthesiserBase by adding the concept of voices,
  23. each of which can play a sound triggered by a MPENote that can be modulated
  24. by MPE dimensions like pressure, pitchbend, and timbre, while the note is
  25. sounding.
  26. To create a synthesiser, you'll need to create a subclass of MPESynthesiserVoice
  27. which can play back one of these sounds at a time.
  28. Then you can use the addVoice() methods to give the synthesiser a set of voices
  29. it can use to play notes. If you only give it one voice it will be monophonic -
  30. the more voices it has, the more polyphony it'll have available.
  31. Then repeatedly call the renderNextBlock() method to produce the audio (inherited
  32. from MPESynthesiserBase). The voices will be started, stopped, and modulated
  33. automatically, based on the MPE/MIDI messages that the synthesiser receives.
  34. Before rendering, be sure to call the setCurrentPlaybackSampleRate() to tell it
  35. what the target playback rate is. This value is passed on to the voices so that
  36. they can pitch their output correctly.
  37. @see MPESynthesiserBase, MPESythesiserVoice, MPENote, MPEInstrument
  38. */
  39. class JUCE_API MPESynthesiser : public MPESynthesiserBase
  40. {
  41. public:
  42. //==============================================================================
  43. /** Constructor.
  44. You'll need to add some voices before it'll make any sound.
  45. @see addVoice
  46. */
  47. MPESynthesiser();
  48. /** Constructor to pass to the synthesiser a custom MPEInstrument object
  49. to handle the MPE note state, MIDI channel assignment etc.
  50. (in case you need custom logic for this that goes beyond MIDI and MPE).
  51. The synthesiser will take ownership of this object.
  52. @see MPESynthesiserBase, MPEInstrument
  53. */
  54. MPESynthesiser (MPEInstrument* instrument);
  55. /** Destructor. */
  56. ~MPESynthesiser();
  57. //==============================================================================
  58. /** Deletes all voices. */
  59. void clearVoices();
  60. /** Returns the number of voices that have been added. */
  61. int getNumVoices() const noexcept { return voices.size(); }
  62. /** Returns one of the voices that have been added. */
  63. MPESynthesiserVoice* getVoice (int index) const;
  64. /** Adds a new voice to the synth.
  65. All the voices should be the same class of object and are treated equally.
  66. The object passed in will be managed by the synthesiser, which will delete
  67. it later on when no longer needed. The caller should not retain a pointer to the
  68. voice.
  69. */
  70. void addVoice (MPESynthesiserVoice* newVoice);
  71. /** Deletes one of the voices. */
  72. void removeVoice (int index);
  73. /** Reduces the number of voices to newNumVoices.
  74. This will repeatedly call findVoiceToSteal() and remove that voice, until
  75. the total number of voices equals newNumVoices. If newNumVoices is greater than
  76. or equal to the current number of voices, this method does nothing.
  77. */
  78. void reduceNumVoices (int newNumVoices);
  79. /** Release all MPE notes and turn off all voices.
  80. If allowTailOff is true, the voices will be allowed to fade out the notes gracefully
  81. (if they can do). If this is false, the notes will all be cut off immediately.
  82. This method is meant to be called by the user, for example to implement
  83. a MIDI panic button in a synth.
  84. */
  85. virtual void turnOffAllVoices (bool allowTailOff);
  86. //==============================================================================
  87. /** If set to true, then the synth will try to take over an existing voice if
  88. it runs out and needs to play another note.
  89. The value of this boolean is passed into findFreeVoice(), so the result will
  90. depend on the implementation of this method.
  91. */
  92. void setVoiceStealingEnabled (bool shouldSteal) noexcept { shouldStealVoices = shouldSteal; }
  93. /** Returns true if note-stealing is enabled. */
  94. bool isVoiceStealingEnabled() const noexcept { return shouldStealVoices; }
  95. //==============================================================================
  96. /** Tells the synthesiser what the sample rate is for the audio it's being used to render.
  97. This overrides the implementation in MPESynthesiserBase, to additionally
  98. propagate the new value to the voices so that they can use it to render the correct
  99. pitches.
  100. */
  101. void setCurrentPlaybackSampleRate (double newRate) override;
  102. //==============================================================================
  103. /** Handle incoming MIDI events.
  104. This method will be called automatically according to the MIDI data passed
  105. into renderNextBlock(), but you can also call it yourself to manually
  106. inject MIDI events.
  107. This implementation forwards program change messages and non-MPE-related
  108. controller messages to handleProgramChange and handleController, respectively,
  109. and then simply calls through to MPESynthesiserBase::handleMidiEvent to deal
  110. with MPE-related MIDI messages used for MPE notes, zones etc.
  111. This method can be overridden further if you need to do custom MIDI
  112. handling on top of what is provided here.
  113. */
  114. void handleMidiEvent (const MidiMessage&) override;
  115. /** Callback for MIDI controller messages. The default implementation
  116. provided here does nothing; override this method if you need custom
  117. MIDI controller handling on top of MPE.
  118. This method will be called automatically according to the midi data passed into
  119. renderNextBlock().
  120. */
  121. virtual void handleController (int /*midiChannel*/,
  122. int /*controllerNumber*/,
  123. int /*controllerValue*/) {}
  124. /** Callback for MIDI program change messages. The default implementation
  125. provided here does nothing; override this method if you need to handle
  126. those messages.
  127. This method will be called automatically according to the midi data passed into
  128. renderNextBlock().
  129. */
  130. virtual void handleProgramChange (int /*midiChannel*/,
  131. int /*programNumber*/) {}
  132. protected:
  133. //==============================================================================
  134. /** Attempts to start playing a new note.
  135. The default method here will find a free voice that is appropriate for
  136. playing the given MPENote, and use that voice to start playing the sound.
  137. If isNoteStealingEnabled returns true (set this by calling setNoteStealingEnabled),
  138. the synthesiser will use the voice stealing algorithm to find a free voice for
  139. the note (if no voices are free otherwise).
  140. This method will be called automatically according to the midi data passed into
  141. renderNextBlock(). Do not call it yourself, otherwise the internal MPE note state
  142. will become inconsistent.
  143. */
  144. virtual void noteAdded (MPENote newNote) override;
  145. /** Stops playing a note.
  146. This will be called whenever an MPE note is released (either by a note-off message,
  147. or by a sustain/sostenuto pedal release for a note that already received a note-off),
  148. and should therefore stop playing.
  149. This will find any voice that is currently playing finishedNote,
  150. turn its currently playing note off, and call its noteStopped callback.
  151. This method will be called automatically according to the midi data passed into
  152. renderNextBlock(). Do not call it yourself, otherwise the internal MPE note state
  153. will become inconsistent.
  154. */
  155. virtual void noteReleased (MPENote finishedNote) override;
  156. /** Will find any voice that is currently playing changedNote, update its
  157. currently playing note, and call its notePressureChanged method.
  158. This method will be called automatically according to the midi data passed into
  159. renderNextBlock(). Do not call it yourself.
  160. */
  161. virtual void notePressureChanged (MPENote changedNote) override;
  162. /** Will find any voice that is currently playing changedNote, update its
  163. currently playing note, and call its notePitchbendChanged method.
  164. This method will be called automatically according to the midi data passed into
  165. renderNextBlock(). Do not call it yourself.
  166. */
  167. virtual void notePitchbendChanged (MPENote changedNote) override;
  168. /** Will find any voice that is currently playing changedNote, update its
  169. currently playing note, and call its noteTimbreChanged method.
  170. This method will be called automatically according to the midi data passed into
  171. renderNextBlock(). Do not call it yourself.
  172. */
  173. virtual void noteTimbreChanged (MPENote changedNote) override;
  174. /** Will find any voice that is currently playing changedNote, update its
  175. currently playing note, and call its noteKeyStateChanged method.
  176. This method will be called automatically according to the midi data passed into
  177. renderNextBlock(). Do not call it yourself.
  178. */
  179. virtual void noteKeyStateChanged (MPENote changedNote) override;
  180. //==============================================================================
  181. /** This will simply call renderNextBlock for each currently active
  182. voice and fill the buffer with the sum.
  183. Override this method if you need to do more work to render your audio.
  184. */
  185. virtual void renderNextSubBlock (AudioBuffer<float>& outputAudio,
  186. int startSample,
  187. int numSamples) override;
  188. /** This will simply call renderNextBlock for each currently active
  189. voice and fill the buffer with the sum. (souble-precision version)
  190. Override this method if you need to do more work to render your audio.
  191. */
  192. virtual void renderNextSubBlock (AudioBuffer<double>& outputAudio,
  193. int startSample,
  194. int numSamples) override;
  195. //==============================================================================
  196. /** Searches through the voices to find one that's not currently playing, and
  197. which can play the given MPE note.
  198. If all voices are active and stealIfNoneAvailable is false, this returns
  199. a nullptr. If all voices are active and stealIfNoneAvailable is true,
  200. this will call findVoiceToSteal() to find a voice.
  201. If you need to find a free voice for something else than playing a note
  202. (e.g. for deleting it), you can pass an invalid (default-constructed) MPENote.
  203. */
  204. virtual MPESynthesiserVoice* findFreeVoice (MPENote noteToFindVoiceFor,
  205. bool stealIfNoneAvailable) const;
  206. /** Chooses a voice that is most suitable for being re-used to play a new
  207. note, or for being deleted by reduceNumVoices.
  208. The default method will attempt to find the oldest voice that isn't the
  209. bottom or top note being played. If that's not suitable for your synth,
  210. you can override this method and do something more cunning instead.
  211. If you pass a valid MPENote for the optional argument, then the note number
  212. of that note will be taken into account for finding the ideal voice to steal.
  213. If you pass an invalid (default-constructed) MPENote instead, this part of
  214. the algorithm will be ignored.
  215. */
  216. virtual MPESynthesiserVoice* findVoiceToSteal (MPENote noteToStealVoiceFor = MPENote()) const;
  217. /** Starts a specified voice and tells it to play a particular MPENote.
  218. You should never need to call this, it's called internally by
  219. MPESynthesiserBase::instrument via the noteStarted callback,
  220. but is protected in case it's useful for some custom subclasses.
  221. */
  222. void startVoice (MPESynthesiserVoice* voice, MPENote noteToStart);
  223. /** Stops a given voice and tells it to stop playing a particular MPENote
  224. (which should be the same note it is actually playing).
  225. You should never need to call this, it's called internally by
  226. MPESynthesiserBase::instrument via the noteReleased callback,
  227. but is protected in case it's useful for some custom subclasses.
  228. */
  229. void stopVoice (MPESynthesiserVoice* voice, MPENote noteToStop, bool allowTailOff);
  230. //==============================================================================
  231. OwnedArray<MPESynthesiserVoice> voices;
  232. private:
  233. //==============================================================================
  234. bool shouldStealVoices;
  235. CriticalSection voicesLock;
  236. JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (MPESynthesiser)
  237. };
  238. #endif // JUCE_MPESynthesiser_H_INCLUDED