OpenShot Library | libopenshot-audio  0.2.0
juce_MPESynthesiserVoice.h
1 
2 /** @weakgroup juce_audio_basics-mpe
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  Represents an MPE voice that an MPESynthesiser can use to play a sound.
33 
34  A voice plays a single sound at a time, and a synthesiser holds an array of
35  voices so that it can play polyphonically.
36 
37  @see MPESynthesiser, MPENote
38 
39  @tags{Audio}
40 */
42 {
43 public:
44  //==============================================================================
45  /** Constructor. */
47 
48  /** Destructor. */
49  virtual ~MPESynthesiserVoice();
50 
51  /** Returns the MPENote that this voice is currently playing.
52  Returns an invalid MPENote if no note is playing
53  (you can check this using MPENote::isValid() or MPEVoice::isActive()).
54  */
55  MPENote getCurrentlyPlayingNote() const noexcept { return currentlyPlayingNote; }
56 
57  /** Returns true if the voice is currently playing the given MPENote
58  (as identified by the note's initial note number and MIDI channel).
59  */
60  bool isCurrentlyPlayingNote (MPENote note) const noexcept;
61 
62  /** Returns true if this voice is currently busy playing a sound.
63  By default this just checks whether getCurrentlyPlayingNote()
64  returns a valid MPE note, but can be overridden for more advanced checking.
65  */
66  virtual bool isActive() const { return currentlyPlayingNote.isValid(); }
67 
68  /** Returns true if a voice is sounding in its release phase. **/
69  bool isPlayingButReleased() const noexcept;
70 
71  /** Called by the MPESynthesiser to let the voice know that a new note has started on it.
72  This will be called during the rendering callback, so must be fast and thread-safe.
73  */
74  virtual void noteStarted() = 0;
75 
76  /** Called by the MPESynthesiser to let the voice know that its currently playing note has stopped.
77  This will be called during the rendering callback, so must be fast and thread-safe.
78 
79  If allowTailOff is false or the voice doesn't want to tail-off, then it must stop all
80  sound immediately, and must call clearCurrentNote() to reset the state of this voice
81  and allow the synth to reassign it another sound.
82 
83  If allowTailOff is true and the voice decides to do a tail-off, then it's allowed to
84  begin fading out its sound, and it can stop playing until it's finished. As soon as it
85  finishes playing (during the rendering callback), it must make sure that it calls
86  clearCurrentNote().
87  */
88  virtual void noteStopped (bool allowTailOff) = 0;
89 
90  /** Called by the MPESynthesiser to let the voice know that its currently playing note
91  has changed its pressure value.
92  This will be called during the rendering callback, so must be fast and thread-safe.
93  */
94  virtual void notePressureChanged() = 0;
95 
96  /** Called by the MPESynthesiser to let the voice know that its currently playing note
97  has changed its pitchbend value.
98  This will be called during the rendering callback, so must be fast and thread-safe.
99 
100  Note: You can call currentlyPlayingNote.getFrequencyInHertz() to find out the effective frequency
101  of the note, as a sum of the initial note number, the per-note pitchbend and the master pitchbend.
102  */
103  virtual void notePitchbendChanged() = 0;
104 
105  /** Called by the MPESynthesiser to let the voice know that its currently playing note
106  has changed its timbre value.
107  This will be called during the rendering callback, so must be fast and thread-safe.
108  */
109  virtual void noteTimbreChanged() = 0;
110 
111  /** Called by the MPESynthesiser to let the voice know that its currently playing note
112  has changed its key state.
113  This typically happens when a sustain or sostenuto pedal is pressed or released (on
114  an MPE channel relevant for this note), or if the note key is lifted while the sustained
115  or sostenuto pedal is still held down.
116  This will be called during the rendering callback, so must be fast and thread-safe.
117  */
118  virtual void noteKeyStateChanged() = 0;
119 
120  /** Renders the next block of data for this voice.
121 
122  The output audio data must be added to the current contents of the buffer provided.
123  Only the region of the buffer between startSample and (startSample + numSamples)
124  should be altered by this method.
125 
126  If the voice is currently silent, it should just return without doing anything.
127 
128  If the sound that the voice is playing finishes during the course of this rendered
129  block, it must call clearCurrentNote(), to tell the synthesiser that it has finished.
130 
131  The size of the blocks that are rendered can change each time it is called, and may
132  involve rendering as little as 1 sample at a time. In between rendering callbacks,
133  the voice's methods will be called to tell it about note and controller events.
134  */
135  virtual void renderNextBlock (AudioBuffer<float>& outputBuffer,
136  int startSample,
137  int numSamples) = 0;
138 
139  /** Renders the next block of 64-bit data for this voice.
140 
141  Support for 64-bit audio is optional. You can choose to not override this method if
142  you don't need it (the default implementation simply does nothing).
143  */
144  virtual void renderNextBlock (AudioBuffer<double>& /*outputBuffer*/,
145  int /*startSample*/,
146  int /*numSamples*/) {}
147 
148  /** Changes the voice's reference sample rate.
149 
150  The rate is set so that subclasses know the output rate and can set their pitch
151  accordingly.
152 
153  This method is called by the synth, and subclasses can access the current rate with
154  the currentSampleRate member.
155  */
156  virtual void setCurrentSampleRate (double newRate) { currentSampleRate = newRate; }
157 
158  /** Returns the current target sample rate at which rendering is being done.
159  Subclasses may need to know this so that they can pitch things correctly.
160  */
161  double getSampleRate() const noexcept { return currentSampleRate; }
162 
163  /** This will be set to an incrementing counter value in MPESynthesiser::startVoice()
164  and can be used to determine the order in which voices started.
165  */
166  uint32 noteOnTime = 0;
167 
168 protected:
169  //==============================================================================
170  /** Resets the state of this voice after a sound has finished playing.
171 
172  The subclass must call this when it finishes playing a note and becomes available
173  to play new ones.
174 
175  It must either call it in the stopNote() method, or if the voice is tailing off,
176  then it should call it later during the renderNextBlock method, as soon as it
177  finishes its tail-off.
178 
179  It can also be called at any time during the render callback if the sound happens
180  to have finished, e.g. if it's playing a sample and the sample finishes.
181  */
182  void clearCurrentNote() noexcept;
183 
184  //==============================================================================
185  double currentSampleRate = 0.0;
186  MPENote currentlyPlayingNote;
187 
188 private:
189  //==============================================================================
190  friend class MPESynthesiser;
191 
192  JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (MPESynthesiserVoice)
193 };
194 
195 } // namespace juce
196 
197 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
Base class for an MPE-compatible musical device that can play sounds.
virtual void setCurrentSampleRate(double newRate)
Changes the voice&#39;s reference sample rate.
double getSampleRate() const noexcept
Returns the current target sample rate at which rendering is being done.
Represents an MPE voice that an MPESynthesiser can use to play a sound.
virtual void renderNextBlock(AudioBuffer< double > &, int, int)
Renders the next block of 64-bit data for this voice.
MPENote getCurrentlyPlayingNote() const noexcept
Returns the MPENote that this voice is currently playing.
virtual bool isActive() const
Returns true if this voice is currently busy playing a sound.
This struct represents a playing MPE note.
Definition: juce_MPENote.h:43