258 lines
12 KiB
C++
258 lines
12 KiB
C++
//------------------------------------------------------------------------
|
|
// 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.
|
|
//-----------------------------------------------------------------------------
|
|
|
|
#pragma once
|
|
|
|
#include "pluginterfaces/base/funknown.h"
|
|
#include "vsttypes.h"
|
|
|
|
//------------------------------------------------------------------------
|
|
#include "pluginterfaces/base/falignpush.h"
|
|
//------------------------------------------------------------------------
|
|
|
|
namespace Steinberg {
|
|
namespace Vst {
|
|
typedef uint32 NoteExpressionTypeID;
|
|
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
|
|
#if SMTG_CPP11
|
|
: uint32
|
|
#endif
|
|
{
|
|
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, ///< TODO:
|
|
kPhonemeTypeID, ///< TODO:
|
|
|
|
kCustomStart = 100000, ///< start of custom note expression type ids
|
|
kCustomEnd = 200000, ///< end of custom note expression type ids
|
|
|
|
kInvalidTypeID = 0xFFFFFFFF ///< indicates an invalid note expression type
|
|
};
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Description of a Note Expression Type
|
|
This structure is part of the NoteExpressionTypeInfo structure, it describes for given NoteExpressionTypeID 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 a stepCount 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)
|
|
};
|
|
|
|
#if SMTG_OS_WINDOWS && !SMTG_PLATFORM_64
|
|
#include "pluginterfaces/vst/vstpshpack4.h"
|
|
#endif
|
|
//------------------------------------------------------------------------
|
|
/** 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 specific noteId can only occur after a NoteOnEvent. The host must take care that the event list (\ref IEventList) 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 \ref NoteExpressionTypeIDs)
|
|
\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 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
|
|
};
|
|
|
|
#if SMTG_OS_WINDOWS && !SMTG_PLATFORM_64
|
|
#include "pluginterfaces/base/falignpop.h"
|
|
#endif
|
|
|
|
//------------------------------------------------------------------------
|
|
/** 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 vst3UnitsIntro), 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
|
|
\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 information supported by the Plug-in.
|
|
Note expression information (\ref NoteExpressionTypeInfo) are specific for given 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 string representation
|
|
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 needs
|
|
to 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. */
|
|
virtual int32 PLUGIN_API getNoteExpressionCount (int32 busIndex, int16 channel) = 0;
|
|
|
|
/** Returns note change type info. */
|
|
virtual tresult PLUGIN_API getNoteExpressionInfo (int32 busIndex, int16 channel, int32 noteExpressionIndex, NoteExpressionTypeInfo& info /*out*/) = 0;
|
|
|
|
/** Gets a user readable representation of the normalized note change value. */
|
|
virtual tresult PLUGIN_API getNoteExpressionStringByValue (int32 busIndex, int16 channel, NoteExpressionTypeID id, NoteExpressionValue valueNormalized /*in*/, String128 string /*out*/) = 0;
|
|
|
|
/** Converts the user readable representation to the normalized note change value. */
|
|
virtual tresult PLUGIN_API getNoteExpressionValueByString (int32 busIndex, int16 channel, NoteExpressionTypeID id, 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
|
|
#if SMTG_CPP11
|
|
: uint32
|
|
#endif
|
|
{
|
|
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
|
|
};
|
|
|
|
typedef uint32 KeyswitchTypeID;
|
|
|
|
//------------------------------------------------------------------------
|
|
/** KeyswitchInfo is the structure describing a key switch
|
|
This 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 vst3UnitsIntro), -1 means no unit used.
|
|
|
|
int32 flags; ///< not yet used (set to 0)
|
|
};
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Extended Plug-in interface IEditController for key switches support
|
|
\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 current set
|
|
of used key switches (megatrig/articulation) for a given channel of a event bus and then automatically use them (like in Cubase 6) to
|
|
create VST Expression Map (allowing to associated symbol to a given articulation / key switch).
|
|
*/
|
|
//------------------------------------------------------------------------
|
|
class IKeyswitchController: public FUnknown
|
|
{
|
|
public:
|
|
/** Returns number of supported key switches for event bus index and channel. */
|
|
virtual int32 PLUGIN_API getKeyswitchCount (int32 busIndex, int16 channel) = 0;
|
|
|
|
/** Returns key switch info. */
|
|
virtual tresult PLUGIN_API getKeyswitchInfo (int32 busIndex, int16 channel, int32 keySwitchIndex, KeyswitchInfo& info /*out*/) = 0;
|
|
|
|
//------------------------------------------------------------------------
|
|
static const FUID iid;
|
|
};
|
|
|
|
DECLARE_CLASS_IID (IKeyswitchController, 0x1F2F76D3, 0xBFFB4B96, 0xB99527A5, 0x5EBCCEF4)
|
|
|
|
//------------------------------------------------------------------------
|
|
} // namespace Vst
|
|
} // namespace Steinberg
|
|
|
|
//------------------------------------------------------------------------
|
|
#include "pluginterfaces/base/falignpop.h"
|
|
//------------------------------------------------------------------------
|