juicewrld-desktopsrc-taurihostvst3sdkpluginterfacesvstivstnoteexpression.h
1.4.2Released Nov 21, 2026
ivstnoteexpression.h
319 lines14.5 KBC++//------------------------------------------------------------------------// Project : VST SDK//// Category : Interfaces// Filename : pluginterfaces/vst/ivstnoteexpression.h// Created by : Steinberg, 10/2010// Description : VST Note Expression Interfaces////-----------------------------------------------------------------------------// This file is part of a Steinberg SDK. It is subject to the license terms// in the LICENSE file found in the top-level directory of this distribution// and at www.steinberg.net/sdklicenses. // No part of the SDK, including this file, may be copied, modified, propagated,// or distributed except according to the terms contained in the LICENSE file.//----------------------------------------------------------------------------- once "pluginterfaces/base/funknown.h" "pluginterfaces/vst/vsttypes.h"//------------------------------------------------------------------------ "pluginterfaces/base/falignpush.h"//------------------------------------------------------------------------//------------------------------------------------------------------------namespace Steinberg {namespace Vst {//------------------------------------------------------------------------/** \ingroup vst3typedef *//**@{*//** Note Expression Types */typedef uint32 NoteExpressionTypeID;/** Note Expression Value */typedef double NoteExpressionValue;/**@}*///------------------------------------------------------------------------/** NoteExpressionTypeIDs describes the type of the note expression.VST predefines some types like volume, pan, tuning by defining their ranges and curves.Used by NoteExpressionEvent::typeId and NoteExpressionTypeID::typeId\see NoteExpressionTypeInfo*/enum NoteExpressionTypeIDs : uint32{ kVolumeTypeID = 0, ///< Volume, plain range [0 = -oo , 0.25 = 0dB, 0.5 = +6dB, 1 = +12dB]: plain = 20 * log (4 * norm) kPanTypeID, ///< Panning (L-R), plain range [0 = left, 0.5 = center, 1 = right] kTuningTypeID, ///< Tuning, plain range [0 = -120.0 (ten octaves down), 0.5 none, 1 = +120.0 (ten octaves up)] ///< plain = 240 * (norm - 0.5) and norm = plain / 240 + 0.5 ///< oneOctave is 12.0 / 240.0; oneHalfTune = 1.0 / 240.0; kVibratoTypeID, ///< Vibrato kExpressionTypeID, ///< Expression kBrightnessTypeID, ///< Brightness kTextTypeID, ///< See NoteExpressionTextEvent kPhonemeTypeID, ///< TODO: kCustomStart = 100000, ///< start of custom note expression type ids kCustomEnd = 200000, ///< end of custom note expression type ids //--- Dedicated for MIDI 2.0 Note Expression Type IDs -------- //--- Reserved for Assignable Per Note Controller -------- kMidi2AssignablePerNoteControllerStart = 201000, kMidi2AssignablePerNoteControllerEnd = 201255, //--- Reserved for Registered Per Note Controller -------- kMidi2RegisteredPerNoteControllerStart = 202000, kMidi2RegisteredPerNoteControllerPlayingPosition = kMidi2RegisteredPerNoteControllerStart + 0x0C, kMidi2RegisteredPerNoteControllerEnd = 202255, //--- Reserved for Note On Attribute --------------------- kMidi2NoteOnAttributeStart = 203000, /** Orchestral Profile Specific */ kMidi2NoteOnOrchestralArticulationStart = kMidi2NoteOnAttributeStart + 0x10, kMidi2NoteOnOrchestralArticulationEnd = kMidi2NoteOnAttributeStart + 0x1F, kMidi2NoteOnAttributeEnd = 203255, //--- Reserved for Note Off Attribute -------------------- kMidi2NoteOffAttributeStart = 204000, /** Orchestral Profile Specific */ kMidi2NoteOffOrchestralArticulation = kMidi2NoteOffAttributeStart + 0x10, kMidi2NoteOffAttributeEnd = 204255, //--- ----------------------------------------------------- kInvalidTypeID = 0xFFFFFFFF ///< indicates an invalid note expression type};//------------------------------------------------------------------------/** Description of a Note Expression TypeThis structure is part of the NoteExpressionTypeInfo structure, it describes for givenNoteExpressionTypeID its default value (for example 0.5 for a kTuningTypeID (kIsBipolar: centered)),its minimum and maximum (for predefined NoteExpressionTypeID the full range is predefined too) and astepCount when the given NoteExpressionTypeID is limited to discrete values (like on/off state).\see NoteExpressionTypeInfo*/struct NoteExpressionValueDescription{ NoteExpressionValue defaultValue; ///< default normalized value [0,1] NoteExpressionValue minimum; ///< minimum normalized value [0,1] NoteExpressionValue maximum; ///< maximum normalized value [0,1] int32 stepCount; ///< number of discrete steps (0: continuous, 1: toggle, discrete value otherwise - see \ref vst3ParameterIntro)}; SMTG_OS_WINDOWS && !SMTG_PLATFORM_64 "pluginterfaces/vst/vstpshpack4.h"//------------------------------------------------------------------------/** Note Expression Value event. Used in \ref Event (union)A note expression event affects one single playing note (referring its noteId).This kind of event is send from host to the plug-in like other events (NoteOnEvent,NoteOffEvent,...) in \ref ProcessData during the process call. Note expression events for a specificnoteId can only occur after a NoteOnEvent. The host must take care that the event list (\refIEventList) is properly sorted. Expression events are always absolute normalized values [0.0, 1.0].The predefined types have a predefined mapping of the normalized values (see \refNoteExpressionTypeIDs) \sa INoteExpressionController*/struct NoteExpressionValueEvent{ NoteExpressionTypeID typeId; ///< see \ref NoteExpressionTypeID int32 noteId; ///< associated note identifier to apply the change NoteExpressionValue value; ///< normalized value [0.0, 1.0].};//------------------------------------------------------------------------/** Note Expression Int event. Used in \ref Event (union)Same as NoteExpressionValueEvent but use a uint64 instead of a NoteExpressionValue (double)\ingroup vstIPlug vst380- [released: 3.8.0]*/struct NoteExpressionIntValueEvent{ NoteExpressionTypeID typeId; ///< see \ref NoteExpressionTypeID int32 noteId; ///< associated note identifier to apply the change uint64 value;};//------------------------------------------------------------------------/** Note Expression Text event. Used in Event (union)A Expression event affects one single playing note. \sa INoteExpressionController\see NoteExpressionTypeInfo*/struct NoteExpressionTextEvent{ NoteExpressionTypeID typeId; ///< see \ref NoteExpressionTypeID (kTextTypeID or kPhoneticTypeID) int32 noteId; ///< associated note identifier to apply the change uint32 textLen; ///< the number of characters (TChar) between the beginning of text and the terminating ///< null character (without including the terminating null character itself) const TChar* text; ///< UTF-16, null terminated}; SMTG_OS_WINDOWS && !SMTG_PLATFORM_64 "pluginterfaces/base/falignpop.h"//------------------------------------------------------------------------/** NoteExpressionTypeInfo is the structure describing a note expression supported by the plug-in.This structure is used by the method \ref INoteExpressionController::getNoteExpressionInfo.\see INoteExpressionController*/struct NoteExpressionTypeInfo{ NoteExpressionTypeID typeId; ///< unique identifier of this note Expression type String128 title; ///< note Expression type title (e.g. "Volume") String128 shortTitle; ///< note Expression type short title (e.g. "Vol") String128 units; ///< note Expression type unit (e.g. "dB") int32 unitId; ///< id of unit this NoteExpression belongs to (see \ref vst3Units), in order to sort the note expression, it is possible to use unitId like for parameters. -1 means no unit used. NoteExpressionValueDescription valueDesc; ///< value description see \ref NoteExpressionValueDescription ParamID associatedParameterId; ///< optional associated parameter ID (for mapping from note expression to global (using the parameter automation for example) and back). Only used when kAssociatedParameterIDValid is set in flags. int32 flags; ///< NoteExpressionTypeFlags (see below) enum NoteExpressionTypeFlags { kIsBipolar = 1 << 0, ///< event is bipolar (centered), otherwise unipolar kIsOneShot = 1 << 1, ///< event occurs only one time for its associated note (at begin of the noteOn) kIsAbsolute = 1 << 2, ///< This note expression will apply an absolute change to the sound (not relative (offset)) kAssociatedParameterIDValid = 1 << 3,///< indicates that the associatedParameterID is valid and could be used };};//------------------------------------------------------------------------/** Extended plug-in interface IEditController for note expression event support:Vst::INoteExpressionController\ingroup vstIPlug vst350- [plug imp]- [extends IEditController]- [released: 3.5.0]- [optional]With this plug-in interface, the host can retrieve all necessary note expression informationsupported by the plug-in. Note expression information (\ref NoteExpressionTypeInfo) are specific forgiven channel and event bus.Note that there is only one NoteExpressionTypeID per given channel of an event bus.The method getNoteExpressionStringByValue allows conversion from a normalized value to a stringrepresentation and the getNoteExpressionValueByString method from a string to a normalized value.When the note expression state changes (for example when switching presets) the plug-in needsto inform the host about it via \ref IComponentHandler::restartComponent (kNoteExpressionChanged).*/class INoteExpressionController : public FUnknown{public: /** Returns number of supported note change types for event bus index and channel. * \note [UI-thread & Connected] */ virtual int32 PLUGIN_API getNoteExpressionCount (int32 busIndex /*in*/, int16 channel /*in*/) = 0; /** Returns note change type info. * \note [UI-thread & Connected] */ virtual tresult PLUGIN_API getNoteExpressionInfo (int32 busIndex /*in*/, int16 channel /*in*/, int32 noteExpressionIndex /*in*/, NoteExpressionTypeInfo& info /*out*/) = 0; /** Gets a user readable representation of the normalized note change value. * \note [UI-thread & Connected] */ virtual tresult PLUGIN_API getNoteExpressionStringByValue ( int32 busIndex /*in*/, int16 channel /*in*/, NoteExpressionTypeID id /*in*/, NoteExpressionValue valueNormalized /*in*/, String128 string /*out*/) = 0; /** Converts the user readable representation to the normalized note change value. * \note [UI-thread & Connected] */ virtual tresult PLUGIN_API getNoteExpressionValueByString ( int32 busIndex /*in*/, int16 channel /*in*/, NoteExpressionTypeID id /*in*/, const TChar* string /*in*/, NoteExpressionValue& valueNormalized /*out*/) = 0;//------------------------------------------------------------------------ static const FUID iid;};DECLARE_CLASS_IID (INoteExpressionController, 0xB7F8F859, 0x41234872, 0x91169581, 0x4F3721A3)//------------------------------------------------------------------------//------------------------------------------------------------------------/** KeyswitchTypeIDs describes the type of a key switch\see KeyswitchInfo*/enum KeyswitchTypeIDs : uint32{ kNoteOnKeyswitchTypeID = 0, ///< press before noteOn is played kOnTheFlyKeyswitchTypeID, ///< press while noteOn is played kOnReleaseKeyswitchTypeID, ///< press before entering release kKeyRangeTypeID ///< key should be maintained pressed for playing};/** \ingroup vst3typedef */typedef uint32 KeyswitchTypeID;//------------------------------------------------------------------------/** KeyswitchInfo is the structure describing a key switchThis structure is used by the method \ref IKeyswitchController::getKeyswitchInfo.\see IKeyswitchController*/struct KeyswitchInfo{ KeyswitchTypeID typeId; ///< see KeyswitchTypeID String128 title; ///< name of key switch (e.g. "Accentuation") String128 shortTitle; ///< short title (e.g. "Acc") int32 keyswitchMin; ///< associated main key switch min (value between [0, 127]) int32 keyswitchMax; ///< associated main key switch max (value between [0, 127]) int32 keyRemapped; /** optional remapped key switch (default -1), the plug-in could provide one remapped key for a key switch (allowing better location on the keyboard of the key switches) */ int32 unitId; ///< id of unit this key switch belongs to (see \ref vst3Units), -1 means no unit used. int32 flags; ///< not yet used (set to 0)};//------------------------------------------------------------------------/** Extended plug-in interface IEditController for key switches support: Vst::IKeyswitchController\ingroup vstIPlug vst350- [plug imp]- [extends IEditController]- [released: 3.5.0]- [optional]When a (instrument) plug-in supports such interface, the host could get from the plug-in the currentset of used key switches (megatrig/articulation) for a given channel of a event bus and thenautomatically use them (like in Cubase 6) to create VST Expression Map (allowing to associatedsymbol to a given articulation / key switch).*/class IKeyswitchController : public FUnknown{public: /** Returns number of supported key switches for event bus index and channel. * \note [UI-thread & Connected] */ virtual int32 PLUGIN_API getKeyswitchCount (int32 busIndex /*in*/, int16 channel /*in*/) = 0; /** Returns key switch info. * \note [UI-thread & Connected] */ virtual tresult PLUGIN_API getKeyswitchInfo (int32 busIndex /*in*/, int16 channel /*in*/, int32 keySwitchIndex /*in*/, KeyswitchInfo& info /*out*/) = 0;//------------------------------------------------------------------------ static const FUID iid;};DECLARE_CLASS_IID (IKeyswitchController, 0x1F2F76D3, 0xBFFB4B96, 0xB99527A5, 0x5EBCCEF4)//------------------------------------------------------------------------} // namespace Vst} // namespace Steinberg//------------------------------------------------------------------------ "pluginterfaces/base/falignpop.h"//------------------------------------------------------------------------