HiseEvent

The event type of HISE.
This is an enhancement of the MIDI Standard and is used for all internal events in the audio path of HISE.
The MIDI standard (and its implementation of JUCE) have a few limitations and misses some convenient data. Therefore, a new event type was introduced, with the following additions:

• fixed size. The MIDI message has to have a dynamic size for handling SysEx messages, which is not used in 99,9999% of all cases. The HiseEvent simply ignores SysEx (there are better ways to communicate bigger chunks of data anyways) and uses a fixed size of 128bit per message. This makes copying / clearing the HiseEventBuffer trivially fast (just a memset / memcpy)
  
• note-on / note-off messages will be associated with a unique index (the EventID), which can be used to alter all voices that are started by the event.
  
• more types for internal actions like timer events, pitch / volume fades
  
• a timestamp that is baked into the message.
  
• 128 channels instead of 16 MIDI channels. 16 is a pretty low number and if you use the channel information to route the signals to certain Processors, you might hit this limitation pretty easily.
  
• a transpose amount that will be added on top of the actual note number. This heavily simplifies any MIDI processing that changes the note number because the note off event does not need to be transposed to match the note on in order to prevent stuck notes
  
• a few flags that describe the state and origin of the note (whether the message should be processed at all or if it was created internally).
  

Most of its methods aim to be fully compatible to the juce::MidiMessage class, so if you're used to this class, you will find your way around this class pretty quickly.

Public types

enum Type

Name	Description
Empty	an empty event (as created by the default constructor)
NoteOn	a note on event (which will get a unique EventID upon creation).
NoteOff	a note-off event (with the same EventID as its corresponding note-on)
Controller	a MIDI CC message
PitchBend	a 14-bit pitch-bend message
Aftertouch	an aftertouch message (both channel aftertouch and polyphonic aftertouch)
AllNotesOff	an all notes off message.
SongPosition	the position of the DAW transport
MidiStart	indicated the start of the playback in the DAW
MidiStop	indicates the stop of the DAW playback
VolumeFade	a volume fade that is applied to all voices started with the given EventID
PitchFade	a pitch fade that is applied to all voices started with the given EventID
TimerEvent	this event will fire the onTimer callback of MIDI Processors.
ProgramChange	the MIDI ProgramChange message.

Class methods

HiseEvent

HiseEvent()

Creates an empty HiseEvent.

HiseEvent

HiseEvent(const MidiMessage &message)

Creates a HiseEvent from a MIDI message.

HiseEvent

HiseEvent(Type type_, uint8 number_, uint8 value_, uint8 channel_=1)

Creates a HiseEvent with the given data.

HiseEvent

HiseEvent(const HiseEvent &other) noexcept

Creates a bit-wise copy of another event.

toMidiMesage

MidiMessage toMidiMesage() const

Converts the HiseEvent back to a MidiMessage. This isn't lossless obviously.

operator bool

operator bool() const noexcept

Allows using the empty check in a scoped if-condition.

operator==

bool operator==(const HiseEvent &other) const

checks whether the event is equal to another. This checks for bit-equality.

swapWith

void swapWith(HiseEvent &other)

Swaps the event with another.

getType

Type getType() const noexcept

Returns the Type of the HiseEvent.

getTypeAsString

String getTypeAsString() const noexcept

Returns a String representation of the type.

setType

void setType(Type t) noexcept

Changes the type. Don't use this unless you know why.

isIgnored

bool isIgnored() const noexcept

Checks if the message was marked as ignored (by a script).

ignoreEvent

void ignoreEvent(bool shouldBeIgnored) noexcept

Ignores the event. Ignored events will not be processed, but remain in the buffer (they are not cleared).

getEventId

uint16 getEventId() const noexcept

Returns the event ID of the message. The event IDs will be automatically created by HISE when it is processing the incoming MIDI messages and associates sequentially increasing IDS for each note-on and its corresponding note-off event.
Be aware the the event ID is stored as unsigned 16 bit integer, so it will wrap around- It's highly unlikely that you will hit any collisions, but you can't expect that older notes have a higher event ID.

setEventId

void setEventId(uint16 newEventId) noexcept

Sets the event ID of the HiseEvent. Normally you don't need to do this because HISE will automatically assign this to note-on / note-off messages, but for all the types that alter an existing event (like volume-fades), this can be used for setting the target event.

setArtificial

void setArtificial() noexcept

If the event was created artificially by a MIDI Processor , it will call this method. You don't need to use this yourself.

isArtificial

bool isArtificial() const noexcept

Returns true if this method was created artificially.
Events that come in as MIDI message (no matter if their origin is in an actual key press or if there was a previous MIDI processor (like an arpeggiator) that created it, will be flagged as "non-artificial". Events that are created within HISE are flagged as "artificial".
This information can be useful sometimes in order to prevent endless recursive loops. Also, the HiseEventBuffer::Iterator class can be told to skip artificial events.

setTransposeAmount

void setTransposeAmount(int newTransposeValue) noexcept

Sets the transpose amount of the given event ID.
Unlike changing the note-number directly, this method will keep the original note number so that you don't have to process the note-off number to match the note-on.
This is the recommended way of handling all note-number processing in HISE.

getTransposeAmount

int getTransposeAmount() const noexcept

Returns the transpose amount. Be aware that you need to take this into account when you need the actual note-number of an HiseEvent.

setCoarseDetune

void setCoarseDetune(int semiToneDetune) noexcept

Sets the coarse detune amount in semitones.

getCoarseDetune

int getCoarseDetune() const noexcept

Returns the coarse detune amount in semitones.

setFineDetune

void setFineDetune(int newCents) noexcept

Sets the fine detune amount in cents.

getFineDetune

int getFineDetune() const noexcept

Returns the fine detune amount int cents.

getPitchFactorForEvent

double getPitchFactorForEvent() const

Returns a ready to use pitch factor (from 0.5 ... 2.0)

getFrequency

double getFrequency() const

Returns the frequency in hertz. Uses all event properties.

setGain

void setGain(int decibels) noexcept

Sets the gain in decibels for this note.

getGain

int getGain() const noexcept

returns the gain in decibels.

getGainFactor

float getGainFactor() const noexcept

Returns the gain factor (from 0...1) for the given event.

isVolumeFade

bool isVolumeFade() const noexcept

Returns true if the event is a volume fade.

isPitchFade

bool isPitchFade() const noexcept

Returns true if the event is a pitch fade.

getFadeTime

int getFadeTime() const noexcept

Returns the fade time for both pitch and volume fades.

isTimerEvent

bool isTimerEvent() const noexcept

Returns true if the event is a timer event.

getTimerIndex

int getTimerIndex() const noexcept

Returns the index of the timer slot.

getTimeStamp

int getTimeStamp() const noexcept

Returns the timestamp of the message. The timestamp is the offset from the current buffer start. If the timestamp is bigger than the current buffer size, the message will be delayed until the buffer range contains the time stamp.

setTimeStamp

void setTimeStamp(int newTimestamp) noexcept

Sets the timestamp to a sample offset in the future.

addToTimeStamp

void addToTimeStamp(int delta) noexcept

Adds the delta value to the timestamp.

getChannel

int getChannel() const noexcept

Returns the MIDI channel.

setChannel

void setChannel(int newChannelNumber) noexcept

Sets the MIDI channel. Note that in HISE you have 256 MIDI channels.

isNoteOn

bool isNoteOn(bool returnTrueForVelocity0=false) const noexcept

Copied from MidiMessage.

isNoteOff

bool isNoteOff() const noexcept

Copied from MidiMessage.

isNoteOnOrOff

bool isNoteOnOrOff() const noexcept

Copied from MidiMessage.

getNoteNumber

int getNoteNumber() const noexcept

Copied from MidiMessage.

setNoteNumber

void setNoteNumber(int newNoteNumber) noexcept

Copied from MidiMessage.

getVelocity

uint8 getVelocity() const noexcept

Copied from MidiMessage.

getFloatVelocity

float getFloatVelocity() const noexcept

Copied from MidiMessage.

setVelocity

void setVelocity(uint8 newVelocity) noexcept

Copied from MidiMessage.

isPitchWheel

bool isPitchWheel() const noexcept

Copied from MidiMessage.

getPitchWheelValue

int getPitchWheelValue() const noexcept

Copied from MidiMessage.

setPitchWheelValue

void setPitchWheelValue(int position) noexcept

Copied from MidiMessage.

setFadeTime

void setFadeTime(int fadeTime) noexcept

Sets the fade time for the event type. Only valid for VolumeFade and PitchFade types.

setStartOffset

void setStartOffset(uint16 startOffset) noexcept

Adds a offset to the event. Unlike the timestamp, this will not delay the event to the future, but tell the sound generator to skip the given amount when the voice starts. This can be used for eg. skipping the attack phase of samples.

getStartOffset

uint16 getStartOffset() const noexcept

Returns the start offset of the event.

isChannelPressure

bool isChannelPressure() const noexcept

Copied from MidiMessage.

getChannelPressureValue

int getChannelPressureValue() const noexcept

Copied from MidiMessage.

setChannelPressureValue

void setChannelPressureValue(int pressure) noexcept

Copied from MidiMessage.

isAftertouch

bool isAftertouch() const noexcept

Copied from MidiMessage.

getAfterTouchValue

int getAfterTouchValue() const noexcept

Copied from MidiMessage.

setAfterTouchValue

void setAfterTouchValue(int noteNumber, int aftertouchAmount) noexcept

Copied from MidiMessage.

isController

bool isController() const noexcept

Copied from MidiMessage.

isControllerOfType

bool isControllerOfType(int controllerType) const noexcept

Copied from MidiMessage.

getControllerNumber

int getControllerNumber() const noexcept

Copied from MidiMessage.

getControllerValue

int getControllerValue() const noexcept

Copied from MidiMessage.

setControllerNumber

void setControllerNumber(int controllerNumber) noexcept

Copied from MidiMessage.

setControllerValue

void setControllerValue(int controllerValue) noexcept

Copied from MidiMessage.

isProgramChange

bool isProgramChange() const noexcept

Copied from MidiMessage.

getProgramChangeNumber

int getProgramChangeNumber() const noexcept

Copied from MidiMessage.

isEmpty

bool isEmpty() const noexcept

Returns true if the HiseEvent is empty.

isAllNotesOff

bool isAllNotesOff() const noexcept

Copied from MidiMessage.

isMidiStart

bool isMidiStart() const noexcept

Copied from MidiMessage.

isMidiStop

bool isMidiStop() const noexcept

Copied from MidiMessage.

isSongPositionPointer

bool isSongPositionPointer() const noexcept

Copied from MidiMessage.

getSongPositionPointerMidiBeat

int getSongPositionPointerMidiBeat() const noexcept

Copied from MidiMessage.

setSongPositionValue

void setSongPositionValue(int positionInMidiBeats)

Copied from MidiMessage.

toDebugString

String toDebugString() const

Returns a string for debugging purposes.