#include <juce_MPEInstrument.h>

Classes
class	Listener
struct	LegacyMode
struct	MPEDimension

Public Types
enum	TrackingMode { lastNotePlayedOnChannel , lowestNoteOnChannel , highestNoteOnChannel , allNotesOnChannel }

Public Member Functions
	MPEInstrument () noexcept
	MPEInstrument (MPEZoneLayout layout)
virtual	~MPEInstrument ()
MPEZoneLayout	getZoneLayout () const noexcept
void	setZoneLayout (MPEZoneLayout newLayout)
bool	isMemberChannel (int midiChannel) const noexcept
bool	isMasterChannel (int midiChannel) const noexcept
bool	isUsingChannel (int midiChannel) const noexcept
void	setPressureTrackingMode (TrackingMode modeToUse)
void	setPitchbendTrackingMode (TrackingMode modeToUse)
void	setTimbreTrackingMode (TrackingMode modeToUse)
virtual void	processNextMidiEvent (const MidiMessage &message)
virtual void	noteOn (int midiChannel, int midiNoteNumber, MPEValue midiNoteOnVelocity)
virtual void	noteOff (int midiChannel, int midiNoteNumber, MPEValue midiNoteOffVelocity)
virtual void	pitchbend (int midiChannel, MPEValue pitchbend)
virtual void	pressure (int midiChannel, MPEValue value)
virtual void	timbre (int midiChannel, MPEValue value)
virtual void	polyAftertouch (int midiChannel, int midiNoteNumber, MPEValue value)
virtual void	sustainPedal (int midiChannel, bool isDown)
virtual void	sostenutoPedal (int midiChannel, bool isDown)
void	releaseAllNotes ()
int	getNumPlayingNotes () const noexcept
MPENote	getNote (int index) const noexcept
MPENote	getNote (int midiChannel, int midiNoteNumber) const noexcept
MPENote	getNoteWithID (uint16 noteID) const noexcept
MPENote	getMostRecentNote (int midiChannel) const noexcept
MPENote	getMostRecentNoteOtherThan (MPENote otherThanThisNote) const noexcept
void	addListener (Listener *listenerToAdd)
void	removeListener (Listener *listenerToRemove)
void	enableLegacyMode (int pitchbendRange=2, Range< int > channelRange=Range< int >(1, 17))
bool	isLegacyModeEnabled () const noexcept
Range< int >	getLegacyModeChannelRange () const noexcept
void	setLegacyModeChannelRange (Range< int > channelRange)
int	getLegacyModePitchbendRange () const noexcept
void	setLegacyModePitchbendRange (int pitchbendRange)

Protected Attributes
CriticalSection	lock

Private Member Functions
void	resetLastReceivedValues ()
void	updateDimension (int midiChannel, MPEDimension &, MPEValue)
void	updateDimensionMaster (bool, MPEDimension &, MPEValue)
void	updateDimensionForNote (MPENote &, MPEDimension &, MPEValue)
void	callListenersDimensionChanged (const MPENote &, const MPEDimension &)
MPEValue	getInitialValueForNewNote (int midiChannel, MPEDimension &) const
void	processMidiNoteOnMessage (const MidiMessage &)
void	processMidiNoteOffMessage (const MidiMessage &)
void	processMidiPitchWheelMessage (const MidiMessage &)
void	processMidiChannelPressureMessage (const MidiMessage &)
void	processMidiControllerMessage (const MidiMessage &)
void	processMidiResetAllControllersMessage (const MidiMessage &)
void	processMidiAfterTouchMessage (const MidiMessage &)
void	handlePressureMSB (int midiChannel, int value) noexcept
void	handlePressureLSB (int midiChannel, int value) noexcept
void	handleTimbreMSB (int midiChannel, int value) noexcept
void	handleTimbreLSB (int midiChannel, int value) noexcept
void	handleSustainOrSostenuto (int midiChannel, bool isDown, bool isSostenuto)
const MPENote *	getNotePtr (int midiChannel, int midiNoteNumber) const noexcept
MPENote *	getNotePtr (int midiChannel, int midiNoteNumber) noexcept
const MPENote *	getNotePtr (int midiChannel, TrackingMode) const noexcept
MPENote *	getNotePtr (int midiChannel, TrackingMode) noexcept
const MPENote *	getLastNotePlayedPtr (int midiChannel) const noexcept
MPENote *	getLastNotePlayedPtr (int midiChannel) noexcept
const MPENote *	getHighestNotePtr (int midiChannel) const noexcept
MPENote *	getHighestNotePtr (int midiChannel) noexcept
const MPENote *	getLowestNotePtr (int midiChannel) const noexcept
MPENote *	getLowestNotePtr (int midiChannel) noexcept
void	updateNoteTotalPitchbend (MPENote &)

Private Attributes
Array< MPENote >	notes
MPEZoneLayout	zoneLayout
ListenerList< Listener >	listeners
uint8	lastPressureLowerBitReceivedOnChannel [16]
uint8	lastTimbreLowerBitReceivedOnChannel [16]
bool	isMemberChannelSustained [16]
LegacyMode	legacyMode
MPEDimension	pitchbendDimension
MPEDimension	pressureDimension
MPEDimension	timbreDimension

Detailed Description

This class represents an instrument handling MPE.

It has an MPE zone layout and maintains a state of currently active (playing) notes and the values of their dimensions of expression.

You can trigger and modulate notes:

by passing MIDI messages with the method processNextMidiEvent;
by directly calling the methods noteOn, noteOff etc.

The class implements the channel and note management logic specified in MPE. If you pass it a message, it will know what notes on what channels (if any) should be affected by that message.

The class has a Listener class that can be used to react to note and state changes and trigger some functionality for your application. For example, you can use this class to write an MPE visualiser.

If you want to write a real-time audio synth with MPE functionality, you should instead use the classes MPESynthesiserBase, which adds the ability to render audio and to manage voices.

See also: MPENote, MPEZoneLayout, MPESynthesiser

@tags{Audio}

Member Enumeration Documentation

◆ TrackingMode

enum juce::MPEInstrument::TrackingMode

The MPE note tracking mode. In case there is more than one note playing simultaneously on the same MIDI channel, this determines which of these notes will be modulated by an incoming MPE message on that channel (pressure, pitchbend, or timbre).

The default is lastNotePlayedOnChannel.

Enumerator
lastNotePlayedOnChannel	The most recent note on the channel that is still played (key down and/or sustained).
lowestNoteOnChannel	The lowest note (by initialNote) on the channel with the note key still down.
highestNoteOnChannel	The highest note (by initialNote) on the channel with the note key still down.
allNotesOnChannel	All notes on the channel (key down and/or sustained).

Constructor & Destructor Documentation

◆ MPEInstrument() [1/2]

juce::MPEInstrument::MPEInstrument ( )

noexcept

Constructor.

This will construct an MPE instrument with inactive lower and upper zones.

In order to process incoming MIDI messages call setZoneLayout, use the MPEZoneLayout constructor, define the layout via MIDI RPN messages, or set the instrument to legacy mode.

◆ MPEInstrument() [2/2]

juce::MPEInstrument::MPEInstrument ( MPEZoneLayout layout )

Constructs an MPE instrument with the specified zone layout.

◆ ~MPEInstrument()

juce::MPEInstrument::~MPEInstrument ( )

virtualdefault

Destructor.

Member Function Documentation

◆ addListener()

void juce::MPEInstrument::addListener ( Listener * listenerToAdd )

Adds a listener.

◆ callListenersDimensionChanged()

void juce::MPEInstrument::callListenersDimensionChanged	(	const MPENote &	note,
		const MPEDimension &	dimension )

private

◆ enableLegacyMode()

void juce::MPEInstrument::enableLegacyMode	(	int	pitchbendRange = 2,
		Range< int >	channelRange = Range<int> (1, 17) )

Puts the instrument into legacy mode. If legacy mode is already enabled this method does nothing.

As a side effect, this will discard all currently playing notes, and call noteReleased for all of them.

This special zone layout mode is for backwards compatibility with non-MPE MIDI devices. In this mode, the instrument will ignore the current MPE zone layout. It will instead take a range of MIDI channels (default: all channels 1-16) and treat them as note channels, with no master channel. MIDI channels outside of this range will be ignored.

Parameters

pitchbendRange	The note pitchbend range in semitones to use when in legacy mode. Must be between 0 and 96, otherwise behaviour is undefined. The default pitchbend range in legacy mode is +/- 2 semitones.
channelRange	The range of MIDI channels to use for notes when in legacy mode. The default is to use all MIDI channels (1-16).

To get out of legacy mode, set a new MPE zone layout using setZoneLayout.

◆ getHighestNotePtr() [1/2]

const MPENote * juce::MPEInstrument::getHighestNotePtr ( int midiChannel ) const

privatenoexcept

◆ getHighestNotePtr() [2/2]

MPENote * juce::MPEInstrument::getHighestNotePtr ( int midiChannel )

privatenoexcept

◆ getInitialValueForNewNote()

MPEValue juce::MPEInstrument::getInitialValueForNewNote	(	int	midiChannel,
		MPEDimension &	dimension ) const

private

◆ getLastNotePlayedPtr() [1/2]

const MPENote * juce::MPEInstrument::getLastNotePlayedPtr ( int midiChannel ) const

privatenoexcept

◆ getLastNotePlayedPtr() [2/2]

MPENote * juce::MPEInstrument::getLastNotePlayedPtr ( int midiChannel )

privatenoexcept

◆ getLegacyModeChannelRange()

Range< int > juce::MPEInstrument::getLegacyModeChannelRange ( ) const

noexcept

Returns the range of MIDI channels (1-16) to be used for notes when in legacy mode.

◆ getLegacyModePitchbendRange()

int juce::MPEInstrument::getLegacyModePitchbendRange ( ) const

noexcept

Returns the pitchbend range in semitones (0-96) to be used for notes when in legacy mode.

◆ getLowestNotePtr() [1/2]

const MPENote * juce::MPEInstrument::getLowestNotePtr ( int midiChannel ) const

privatenoexcept

◆ getLowestNotePtr() [2/2]

MPENote * juce::MPEInstrument::getLowestNotePtr ( int midiChannel )

privatenoexcept

◆ getMostRecentNote()

MPENote juce::MPEInstrument::getMostRecentNote ( int midiChannel ) const

noexcept

Returns the most recent note that is playing on the given midiChannel (this will be the note which has received the most recent note-on without a corresponding note-off), if there is such a note. Otherwise, this returns an invalid MPENote (check with note.isValid() before use!)

◆ getMostRecentNoteOtherThan()

MPENote juce::MPEInstrument::getMostRecentNoteOtherThan ( MPENote otherThanThisNote ) const

noexcept

Returns the most recent note that is not the note passed in. If there is no such note, this returns an invalid MPENote (check with note.isValid() before use!).

This helper method might be useful for some custom voice handling algorithms.

◆ getNote() [1/2]

MPENote juce::MPEInstrument::getNote ( int index ) const

noexcept

Returns the note at the given index.

If there is no such note, returns an invalid MPENote. The notes are sorted such that the most recently added note is the last element.

◆ getNote() [2/2]

MPENote juce::MPEInstrument::getNote	(	int	midiChannel,
		int	midiNoteNumber ) const

noexcept

Returns the note currently playing on the given midiChannel with the specified initial MIDI note number, if there is such a note. Otherwise, this returns an invalid MPENote (check with note.isValid() before use!)

◆ getNotePtr() [1/4]

const MPENote * juce::MPEInstrument::getNotePtr	(	int	midiChannel,
		int	midiNoteNumber ) const

privatenoexcept

◆ getNotePtr() [2/4]

MPENote * juce::MPEInstrument::getNotePtr	(	int	midiChannel,
		int	midiNoteNumber )

privatenoexcept

◆ getNotePtr() [3/4]

const MPENote * juce::MPEInstrument::getNotePtr	(	int	midiChannel,
		TrackingMode	mode ) const

privatenoexcept

◆ getNotePtr() [4/4]

MPENote * juce::MPEInstrument::getNotePtr	(	int	midiChannel,
		TrackingMode	mode )

privatenoexcept

◆ getNoteWithID()

MPENote juce::MPEInstrument::getNoteWithID ( uint16 noteID ) const

noexcept

Returns the note with a given ID.

◆ getNumPlayingNotes()

int juce::MPEInstrument::getNumPlayingNotes ( ) const

noexcept

Returns the number of MPE notes currently played by the instrument.

◆ getZoneLayout()

MPEZoneLayout juce::MPEInstrument::getZoneLayout ( ) const

noexcept

Returns the current zone layout of the instrument. This happens by value, to enforce thread-safety and class invariants.

Note: If the instrument is in legacy mode, the return value of this method is unspecified.

◆ handlePressureLSB()

void juce::MPEInstrument::handlePressureLSB	(	int	midiChannel,
		int	value )

privatenoexcept

◆ handlePressureMSB()

void juce::MPEInstrument::handlePressureMSB	(	int	midiChannel,
		int	value )

privatenoexcept

◆ handleSustainOrSostenuto()

void juce::MPEInstrument::handleSustainOrSostenuto	(	int	midiChannel,
		bool	isDown,
		bool	isSostenuto )

private

◆ handleTimbreLSB()

void juce::MPEInstrument::handleTimbreLSB	(	int	midiChannel,
		int	value )

privatenoexcept

◆ handleTimbreMSB()

void juce::MPEInstrument::handleTimbreMSB	(	int	midiChannel,
		int	value )

privatenoexcept

◆ isLegacyModeEnabled()

bool juce::MPEInstrument::isLegacyModeEnabled ( ) const

noexcept

Returns true if the instrument is in legacy mode, false otherwise.

◆ isMasterChannel()

bool juce::MPEInstrument::isMasterChannel ( int midiChannel ) const

noexcept

Returns true if the given MIDI channel (1-16) is a master channel (channel 1 or 16).

In legacy mode, this will always return false.

◆ isMemberChannel()

bool juce::MPEInstrument::isMemberChannel ( int midiChannel ) const

noexcept

Returns true if the given MIDI channel (1-16) is a note channel in any of the MPEInstrument's MPE zones; false otherwise.

When in legacy mode, this will return true if the given channel is contained in the current legacy mode channel range; false otherwise.

◆ isUsingChannel()

bool juce::MPEInstrument::isUsingChannel ( int midiChannel ) const

noexcept

Returns true if the given MIDI channel (1-16) is used by any of the MPEInstrument's MPE zones; false otherwise.

When in legacy mode, this will return true if the given channel is contained in the current legacy mode channel range; false otherwise.

◆ noteOff()

void juce::MPEInstrument::noteOff	(	int	midiChannel,
		int	midiNoteNumber,
		MPEValue	midiNoteOffVelocity )

virtual

Request a note-off.

If there is a matching playing note, this will release the note (except if it is sustained by a sustain or sostenuto pedal) and call the noteReleased callback.

◆ noteOn()

void juce::MPEInstrument::noteOn	(	int	midiChannel,
		int	midiNoteNumber,
		MPEValue	midiNoteOnVelocity )

virtual

Request a note-on on the given channel, with the given initial note number and velocity.

If the message arrives on a valid note channel, this will create a new MPENote and call the noteAdded callback.

◆ pitchbend()

void juce::MPEInstrument::pitchbend	(	int	midiChannel,
		MPEValue	pitchbend )

virtual

Request a pitchbend on the given channel with the given value (in units of MIDI pitchwheel position).

Internally, this will determine whether the pitchwheel move is a per-note pitchbend or a master pitchbend (depending on midiChannel), take the correct per-note or master pitchbend range of the affected MPE zone, and apply the resulting pitchbend to the affected note(s) (if any).

◆ polyAftertouch()

void juce::MPEInstrument::polyAftertouch	(	int	midiChannel,
		int	midiNoteNumber,
		MPEValue	value )

virtual

Request a poly-aftertouch change for a given note number.

The change will be broadcast to all notes sharing the channel and note number of the change message.

◆ pressure()

void juce::MPEInstrument::pressure	(	int	midiChannel,
		MPEValue	value )

virtual

Request a pressure change on the given channel with the given value.

This will modify the pressure dimension of the note currently held down on this channel (if any). If the channel is a zone master channel, the pressure change will be broadcast to all notes in this zone.

◆ processMidiAfterTouchMessage()

void juce::MPEInstrument::processMidiAfterTouchMessage ( const MidiMessage & message )

private

◆ processMidiChannelPressureMessage()

void juce::MPEInstrument::processMidiChannelPressureMessage ( const MidiMessage & message )

private

◆ processMidiControllerMessage()

void juce::MPEInstrument::processMidiControllerMessage ( const MidiMessage & message )

private

◆ processMidiNoteOffMessage()

void juce::MPEInstrument::processMidiNoteOffMessage ( const MidiMessage & message )

private

◆ processMidiNoteOnMessage()

void juce::MPEInstrument::processMidiNoteOnMessage ( const MidiMessage & message )

private

◆ processMidiPitchWheelMessage()

void juce::MPEInstrument::processMidiPitchWheelMessage ( const MidiMessage & message )

private

◆ processMidiResetAllControllersMessage()

void juce::MPEInstrument::processMidiResetAllControllersMessage ( const MidiMessage & message )

private

◆ processNextMidiEvent()

void juce::MPEInstrument::processNextMidiEvent ( const MidiMessage & message )

virtual

Process a MIDI message and trigger the appropriate method calls (noteOn, noteOff etc.)

You can override this method if you need some special MIDI message treatment on top of the standard MPE logic implemented here.

◆ releaseAllNotes()

void juce::MPEInstrument::releaseAllNotes ( )

Discard all currently playing notes.

This will also call the noteReleased listener callback for all of them.

◆ removeListener()

void juce::MPEInstrument::removeListener ( Listener * listenerToRemove )

Removes a listener.

◆ resetLastReceivedValues()

void juce::MPEInstrument::resetLastReceivedValues ( )

private

◆ setLegacyModeChannelRange()

void juce::MPEInstrument::setLegacyModeChannelRange ( Range< int > channelRange )

Re-sets the range of MIDI channels (1-16) to be used for notes when in legacy mode.

◆ setLegacyModePitchbendRange()

void juce::MPEInstrument::setLegacyModePitchbendRange ( int pitchbendRange )

Re-sets the pitchbend range in semitones (0-96) to be used for notes when in legacy mode.

◆ setPitchbendTrackingMode()

void juce::MPEInstrument::setPitchbendTrackingMode ( TrackingMode modeToUse )

Set the MPE tracking mode for the pitchbend dimension.

◆ setPressureTrackingMode()

void juce::MPEInstrument::setPressureTrackingMode ( TrackingMode modeToUse )

Set the MPE tracking mode for the pressure dimension.

◆ setTimbreTrackingMode()

void juce::MPEInstrument::setTimbreTrackingMode ( TrackingMode modeToUse )

Set the MPE tracking mode for the timbre dimension.

◆ setZoneLayout()

void juce::MPEInstrument::setZoneLayout ( MPEZoneLayout newLayout )

Re-sets the zone layout of the instrument to the one passed in. As a side effect, this will discard all currently playing notes, and call noteReleased for all of them.

This will also disable legacy mode in case it was enabled previously.

◆ sostenutoPedal()

void juce::MPEInstrument::sostenutoPedal	(	int	midiChannel,
		bool	isDown )

virtual

Request a sostenuto pedal press or release.

If midiChannel is a zone's master channel, this will act on all notes in that zone; otherwise, nothing will happen.

◆ sustainPedal()

void juce::MPEInstrument::sustainPedal	(	int	midiChannel,
		bool	isDown )

virtual

Request a sustain pedal press or release.

If midiChannel is a zone's master channel, this will act on all notes in that zone; otherwise, nothing will happen.

◆ timbre()

void juce::MPEInstrument::timbre	(	int	midiChannel,
		MPEValue	value )

virtual

Request a third dimension (timbre) change on the given channel with the given value.

This will modify the timbre dimension of the note currently held down on this channel (if any). If the channel is a zone master channel, the timbre change will be broadcast to all notes in this zone.

◆ updateDimension()

void juce::MPEInstrument::updateDimension	(	int	midiChannel,
		MPEDimension &	dimension,
		MPEValue	value )

private

◆ updateDimensionForNote()

void juce::MPEInstrument::updateDimensionForNote	(	MPENote &	note,
		MPEDimension &	dimension,
		MPEValue	value )

private

◆ updateDimensionMaster()

void juce::MPEInstrument::updateDimensionMaster	(	bool	isLowerZone,
		MPEDimension &	dimension,
		MPEValue	value )

private

◆ updateNoteTotalPitchbend()

void juce::MPEInstrument::updateNoteTotalPitchbend ( MPENote & note )

private

Member Data Documentation

◆ isMemberChannelSustained

bool juce::MPEInstrument::isMemberChannelSustained[16]

private

◆ lastPressureLowerBitReceivedOnChannel

uint8 juce::MPEInstrument::lastPressureLowerBitReceivedOnChannel[16]

private

◆ lastTimbreLowerBitReceivedOnChannel

uint8 juce::MPEInstrument::lastTimbreLowerBitReceivedOnChannel[16]

private

◆ legacyMode

LegacyMode juce::MPEInstrument::legacyMode

private

◆ listeners

ListenerList<Listener> juce::MPEInstrument::listeners

private

◆ lock

CriticalSection juce::MPEInstrument::lock

protected

◆ notes

Array<MPENote> juce::MPEInstrument::notes

private

◆ pitchbendDimension

MPEDimension juce::MPEInstrument::pitchbendDimension

private

◆ pressureDimension

MPEDimension juce::MPEInstrument::pressureDimension

private

◆ timbreDimension

MPEDimension juce::MPEInstrument::timbreDimension

private

◆ zoneLayout

MPEZoneLayout juce::MPEInstrument::zoneLayout

private

The documentation for this class was generated from the following files:

/home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/juce_audio_basics/mpe/juce_MPEInstrument.h
/home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/juce_audio_basics/mpe/juce_MPEInstrument.cpp

Classes

Public Types

Public Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ TrackingMode

Constructor & Destructor Documentation

◆ MPEInstrument() [1/2]

◆ MPEInstrument() [2/2]

◆ ~MPEInstrument()

Member Function Documentation

◆ addListener()

◆ callListenersDimensionChanged()

◆ enableLegacyMode()

◆ getHighestNotePtr() [1/2]

◆ getHighestNotePtr() [2/2]

◆ getInitialValueForNewNote()

◆ getLastNotePlayedPtr() [1/2]

◆ getLastNotePlayedPtr() [2/2]

◆ getLegacyModeChannelRange()

◆ getLegacyModePitchbendRange()

◆ getLowestNotePtr() [1/2]

◆ getLowestNotePtr() [2/2]

◆ getMostRecentNote()

◆ getMostRecentNoteOtherThan()

◆ getNote() [1/2]

◆ getNote() [2/2]

◆ getNotePtr() [1/4]

◆ getNotePtr() [2/4]

◆ getNotePtr() [3/4]

◆ getNotePtr() [4/4]

◆ getNoteWithID()

◆ getNumPlayingNotes()

◆ getZoneLayout()

◆ handlePressureLSB()

◆ handlePressureMSB()

◆ handleSustainOrSostenuto()

◆ handleTimbreLSB()

◆ handleTimbreMSB()

◆ isLegacyModeEnabled()

◆ isMasterChannel()

◆ isMemberChannel()

◆ isUsingChannel()

◆ noteOff()

◆ noteOn()

◆ pitchbend()

◆ polyAftertouch()

◆ pressure()

◆ processMidiAfterTouchMessage()

◆ processMidiChannelPressureMessage()

◆ processMidiControllerMessage()

◆ processMidiNoteOffMessage()

◆ processMidiNoteOnMessage()

◆ processMidiPitchWheelMessage()

◆ processMidiResetAllControllersMessage()

◆ processNextMidiEvent()

◆ releaseAllNotes()

◆ removeListener()

◆ resetLastReceivedValues()

◆ setLegacyModeChannelRange()

◆ setLegacyModePitchbendRange()

◆ setPitchbendTrackingMode()

◆ setPressureTrackingMode()

◆ setTimbreTrackingMode()

◆ setZoneLayout()

◆ sostenutoPedal()

◆ sustainPedal()

◆ timbre()

◆ updateDimension()

◆ updateDimensionForNote()

◆ updateDimensionMaster()

◆ updateNoteTotalPitchbend()

Member Data Documentation

◆ isMemberChannelSustained

◆ lastPressureLowerBitReceivedOnChannel

◆ lastTimbreLowerBitReceivedOnChannel

◆ legacyMode