435 lines
20 KiB
C++
435 lines
20 KiB
C++
//------------------------------------------------------------------------
|
|
// Project : VST SDK
|
|
//
|
|
// Category : Interfaces
|
|
// Filename : pluginterfaces/vst/ivsteditcontroller.h
|
|
// Created by : Steinberg, 09/2005
|
|
// Description : VST Edit Controller 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/ipluginbase.h"
|
|
#include "vsttypes.h"
|
|
|
|
//------------------------------------------------------------------------
|
|
#include "pluginterfaces/base/falignpush.h"
|
|
//------------------------------------------------------------------------
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Class Category Name for Controller Component */
|
|
//------------------------------------------------------------------------
|
|
#ifndef kVstComponentControllerClass
|
|
#define kVstComponentControllerClass "Component Controller Class"
|
|
#endif
|
|
|
|
//------------------------------------------------------------------------
|
|
namespace Steinberg {
|
|
class IPlugView;
|
|
class IBStream;
|
|
|
|
//------------------------------------------------------------------------
|
|
namespace Vst {
|
|
//------------------------------------------------------------------------
|
|
/** Controller Parameter Info. */
|
|
//------------------------------------------------------------------------
|
|
struct ParameterInfo
|
|
{
|
|
//------------------------------------------------------------------------
|
|
ParamID id; ///< unique identifier of this parameter (named tag too)
|
|
String128 title; ///< parameter title (e.g. "Volume")
|
|
String128 shortTitle; ///< parameter shortTitle (e.g. "Vol")
|
|
String128 units; ///< parameter unit (e.g. "dB")
|
|
int32 stepCount; ///< number of discrete steps (0: continuous, 1: toggle, discrete value otherwise
|
|
///< (corresponding to max - min, for example: 127 for a min = 0 and a max = 127) - see \ref vst3parameterIntro)
|
|
ParamValue defaultNormalizedValue; ///< default normalized value [0,1] (in case of discrete value: defaultNormalizedValue = defDiscreteValue / stepCount)
|
|
UnitID unitId; ///< id of unit this parameter belongs to (see \ref vst3UnitsIntro)
|
|
|
|
int32 flags; ///< ParameterFlags (see below)
|
|
enum ParameterFlags
|
|
{
|
|
kNoFlags = 0, ///< no flags wanted
|
|
kCanAutomate = 1 << 0, ///< parameter can be automated
|
|
kIsReadOnly = 1 << 1, ///< parameter cannot be changed from outside (implies that kCanAutomate is false)
|
|
kIsWrapAround = 1 << 2, ///< attempts to set the parameter value out of the limits will result in a wrap around [SDK 3.0.2]
|
|
kIsList = 1 << 3, ///< parameter should be displayed as list in generic editor or automation editing [SDK 3.1.0]
|
|
|
|
kIsProgramChange = 1 << 15, ///< parameter is a program change (unitId gives info about associated unit
|
|
///< - see \ref vst3UnitPrograms)
|
|
kIsBypass = 1 << 16 ///< special bypass parameter (only one allowed): Plug-in can handle bypass
|
|
///< (highly recommended to export a bypass parameter for effect Plug-in)
|
|
};
|
|
//------------------------------------------------------------------------
|
|
};
|
|
|
|
//------------------------------------------------------------------------
|
|
/** View Types used for IEditController::createView */
|
|
//------------------------------------------------------------------------
|
|
namespace ViewType {
|
|
const CString kEditor = "editor";
|
|
}
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Flags used for IComponentHandler::restartComponent */
|
|
//------------------------------------------------------------------------
|
|
enum RestartFlags
|
|
{
|
|
kReloadComponent = 1 << 0, ///< The Component should be reloaded [SDK 3.0.0]
|
|
kIoChanged = 1 << 1, ///< Input and/or Output Bus configuration has changed [SDK 3.0.0]
|
|
kParamValuesChanged = 1 << 2, ///< Multiple parameter values have changed
|
|
///< (as result of a program change for example) [SDK 3.0.0]
|
|
kLatencyChanged = 1 << 3, ///< Latency has changed (IAudioProcessor.getLatencySamples) [SDK 3.0.0]
|
|
kParamTitlesChanged = 1 << 4, ///< Parameter titles or default values or flags have changed [SDK 3.0.0]
|
|
kMidiCCAssignmentChanged = 1 << 5, ///< MIDI Controller Assignments have changed [SDK 3.0.1]
|
|
kNoteExpressionChanged = 1 << 6, ///< Note Expression has changed (info, count, PhysicalUIMapping, ...) [SDK 3.5.0]
|
|
kIoTitlesChanged = 1 << 7, ///< Input and/or Output bus titles have changed [SDK 3.5.0]
|
|
kPrefetchableSupportChanged = 1 << 8, ///< Prefetch support has changed (\see IPrefetchableSupport) [SDK 3.6.1]
|
|
kRoutingInfoChanged = 1 << 9 ///< RoutingInfo has changed (\see IComponent) [SDK 3.6.6]
|
|
};
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Host callback interface for an edit controller.
|
|
\ingroup vstIHost vst300
|
|
- [host imp]
|
|
- [released: 3.0.0]
|
|
- [mandatory]
|
|
|
|
Allow transfer of parameter editing to component (processor) via host and support automation.
|
|
Cause the host to react on configuration changes (restartComponent)
|
|
|
|
\see IEditController */
|
|
//------------------------------------------------------------------------
|
|
class IComponentHandler: public FUnknown
|
|
{
|
|
public:
|
|
//------------------------------------------------------------------------
|
|
/** To be called before calling a performEdit (e.g. on mouse-click-down event). */
|
|
virtual tresult PLUGIN_API beginEdit (ParamID id) = 0;
|
|
|
|
/** Called between beginEdit and endEdit to inform the handler that a given parameter has a new value. */
|
|
virtual tresult PLUGIN_API performEdit (ParamID id, ParamValue valueNormalized) = 0;
|
|
|
|
/** To be called after calling a performEdit (e.g. on mouse-click-up event). */
|
|
virtual tresult PLUGIN_API endEdit (ParamID id) = 0;
|
|
|
|
/** Instructs host to restart the component. This should be called in the UI-Thread context!
|
|
\param flags is a combination of RestartFlags */
|
|
virtual tresult PLUGIN_API restartComponent (int32 flags) = 0;
|
|
|
|
//------------------------------------------------------------------------
|
|
static const FUID iid;
|
|
};
|
|
|
|
DECLARE_CLASS_IID (IComponentHandler, 0x93A0BEA3, 0x0BD045DB, 0x8E890B0C, 0xC1E46AC6)
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Extended Host callback interface IComponentHandler2 for an edit controller
|
|
\ingroup vstIHost vst310
|
|
- [host imp]
|
|
- [extends IComponentHandler]
|
|
- [released: 3.1.0]
|
|
- [optional]
|
|
|
|
One part handles:
|
|
- Setting dirty state of Plug-in
|
|
- requesting the host to open the editor
|
|
|
|
The other part handles parameter group editing from Plug-in UI. It wraps a set of \ref IComponentHandler::beginEdit /
|
|
\ref IComponentHandler::performEdit / \ref IComponentHandler::endEdit functions (see \ref IComponentHandler)
|
|
which should use the same timestamp in the host when writing automation.
|
|
This allows for better synchronizing multiple parameter changes at once.
|
|
|
|
\section IComponentHandler2Example Examples of different use cases
|
|
\code
|
|
//--------------------------------------
|
|
// in case of multiple switch buttons (with associated ParamID 1 and 3)
|
|
// on mouse down :
|
|
hostHandler2->startGroupEdit ();
|
|
hostHandler->beginEdit (1);
|
|
hostHandler->beginEdit (3);
|
|
hostHandler->performEdit (1, 1.0);
|
|
hostHandler->performEdit (3, 0.0); // the opposite of paramID 1 for example
|
|
....
|
|
// on mouse up :
|
|
hostHandler->endEdit (1);
|
|
hostHandler->endEdit (3);
|
|
hostHandler2->finishGroupEdit ();
|
|
....
|
|
....
|
|
//--------------------------------------
|
|
// in case of multiple faders (with associated ParamID 1 and 3)
|
|
// on mouse down :
|
|
hostHandler2->startGroupEdit ();
|
|
hostHandler->beginEdit (1);
|
|
hostHandler->beginEdit (3);
|
|
hostHandler2->finishGroupEdit ();
|
|
....
|
|
// on mouse move :
|
|
hostHandler2->startGroupEdit ();
|
|
hostHandler->performEdit (1, x); // x the wanted value
|
|
hostHandler->performEdit (3, x);
|
|
hostHandler2->finishGroupEdit ();
|
|
....
|
|
// on mouse up :
|
|
hostHandler2->startGroupEdit ();
|
|
hostHandler->endEdit (1);
|
|
hostHandler->endEdit (3);
|
|
hostHandler2->finishGroupEdit ();
|
|
\endcode
|
|
\see IComponentHandler
|
|
\see IEditController*/
|
|
//------------------------------------------------------------------------
|
|
class IComponentHandler2: public FUnknown
|
|
{
|
|
public:
|
|
//------------------------------------------------------------------------
|
|
/** Tells host that the Plug-in is dirty (something besides parameters has changed since last save),
|
|
if true the host should apply a save before quitting. */
|
|
virtual tresult PLUGIN_API setDirty (TBool state) = 0;
|
|
|
|
/** Tells host that it should open the Plug-in editor the next time it's possible.
|
|
You should use this instead of showing an alert and blocking the program flow (especially on loading projects). */
|
|
virtual tresult PLUGIN_API requestOpenEditor (FIDString name = ViewType::kEditor) = 0;
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Starts the group editing (call before a \ref IComponentHandler::beginEdit),
|
|
the host will keep the current timestamp at this call and will use it for all \ref IComponentHandler::beginEdit
|
|
/ \ref IComponentHandler::performEdit / \ref IComponentHandler::endEdit calls until a \ref finishGroupEdit (). */
|
|
virtual tresult PLUGIN_API startGroupEdit () = 0;
|
|
|
|
/** Finishes the group editing started by a \ref startGroupEdit (call after a \ref IComponentHandler::endEdit). */
|
|
virtual tresult PLUGIN_API finishGroupEdit () = 0;
|
|
|
|
//------------------------------------------------------------------------
|
|
static const FUID iid;
|
|
};
|
|
|
|
DECLARE_CLASS_IID (IComponentHandler2, 0xF040B4B3, 0xA36045EC, 0xABCDC045, 0xB4D5A2CC)
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Extended Host callback interface IComponentHandlerBusActivation for an edit controller.
|
|
\ingroup vstIHost vst368
|
|
- [host imp]
|
|
- [extends IComponentHandler]
|
|
- [released: 3.6.8]
|
|
- [optional]
|
|
|
|
Allows the Plug-in to request the host to activate or deactivate a specific bus,
|
|
if the host accepts it will call later on IComponent::activateBus (see \ref IComponent::activateBus).
|
|
Useful especially for Instrument with more than 1 outputs, where the user could request
|
|
from the Plug-in UI a given output bus activation.
|
|
|
|
\see \ref IComponentHandler */
|
|
//------------------------------------------------------------------------
|
|
class IComponentHandlerBusActivation : public FUnknown
|
|
{
|
|
public:
|
|
//------------------------------------------------------------------------
|
|
/** request the host to activate or deactivate a specific bus. */
|
|
virtual tresult PLUGIN_API requestBusActivation (MediaType type, BusDirection dir, int32 index,
|
|
TBool state) = 0;
|
|
|
|
//------------------------------------------------------------------------
|
|
static const FUID iid;
|
|
};
|
|
|
|
DECLARE_CLASS_IID (IComponentHandlerBusActivation, 0x067D02C1, 0x5B4E274D, 0xA92D90FD, 0x6EAF7240)
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Edit controller component interface.
|
|
\ingroup vstIPlug vst300
|
|
- [plug imp]
|
|
- [released: 3.0.0]
|
|
- [mandatory]
|
|
|
|
The Controller part of an effect or instrument with parameter handling (export, definition, conversion...).
|
|
\see IComponent::getControllerClassId, IMidiMapping */
|
|
//------------------------------------------------------------------------
|
|
class IEditController: public IPluginBase
|
|
{
|
|
public:
|
|
//------------------------------------------------------------------------
|
|
/** Receives the component state. */
|
|
virtual tresult PLUGIN_API setComponentState (IBStream* state) = 0;
|
|
|
|
/** Sets the controller state. */
|
|
virtual tresult PLUGIN_API setState (IBStream* state) = 0;
|
|
|
|
/** Gets the controller state. */
|
|
virtual tresult PLUGIN_API getState (IBStream* state) = 0;
|
|
|
|
// parameters -------------------------
|
|
/** Returns the number of parameters exported. */
|
|
virtual int32 PLUGIN_API getParameterCount () = 0;
|
|
/** Gets for a given index the parameter information. */
|
|
virtual tresult PLUGIN_API getParameterInfo (int32 paramIndex, ParameterInfo& info /*out*/) = 0;
|
|
|
|
/** Gets for a given paramID and normalized value its associated string representation. */
|
|
virtual tresult PLUGIN_API getParamStringByValue (ParamID id, ParamValue valueNormalized /*in*/, String128 string /*out*/) = 0;
|
|
/** Gets for a given paramID and string its normalized value. */
|
|
virtual tresult PLUGIN_API getParamValueByString (ParamID id, TChar* string /*in*/, ParamValue& valueNormalized /*out*/) = 0;
|
|
|
|
/** Returns for a given paramID and a normalized value its plain representation
|
|
(for example 90 for 90db - see \ref vst3AutomationIntro). */
|
|
virtual ParamValue PLUGIN_API normalizedParamToPlain (ParamID id, ParamValue valueNormalized) = 0;
|
|
/** Returns for a given paramID and a plain value its normalized value. (see \ref vst3AutomationIntro) */
|
|
virtual ParamValue PLUGIN_API plainParamToNormalized (ParamID id, ParamValue plainValue) = 0;
|
|
|
|
/** Returns the normalized value of the parameter associated to the paramID. */
|
|
virtual ParamValue PLUGIN_API getParamNormalized (ParamID id) = 0;
|
|
/** Sets the normalized value to the parameter associated to the paramID. The controller must never
|
|
pass this value-change back to the host via the IComponentHandler. It should update the according
|
|
GUI element(s) only!*/
|
|
virtual tresult PLUGIN_API setParamNormalized (ParamID id, ParamValue value) = 0;
|
|
|
|
// handler ----------------------------
|
|
/** Gets from host a handler. */
|
|
virtual tresult PLUGIN_API setComponentHandler (IComponentHandler* handler) = 0;
|
|
|
|
// view -------------------------------
|
|
/** Creates the editor view of the Plug-in, currently only "editor" is supported, see \ref ViewType.
|
|
The life time of the editor view will never exceed the life time of this controller instance. */
|
|
virtual IPlugView* PLUGIN_API createView (FIDString name) = 0;
|
|
|
|
//------------------------------------------------------------------------
|
|
static const FUID iid;
|
|
};
|
|
|
|
DECLARE_CLASS_IID (IEditController, 0xDCD7BBE3, 0x7742448D, 0xA874AACC, 0x979C759E)
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Knob Mode */
|
|
//------------------------------------------------------------------------
|
|
enum KnobModes
|
|
{
|
|
kCircularMode = 0, ///< Circular with jump to clicked position
|
|
kRelativCircularMode, ///< Circular without jump to clicked position
|
|
kLinearMode ///< Linear: depending on vertical movement
|
|
};
|
|
|
|
typedef int32 KnobMode; ///< Knob Mode
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Edit controller component interface extension.
|
|
\ingroup vstIPlug vst310
|
|
- [plug imp]
|
|
- [extends IEditController]
|
|
- [released: 3.1.0]
|
|
- [optional]
|
|
|
|
Extension to inform the Plug-in about the host Knob Mode,
|
|
and to open the Plug-in about box or help documentation.
|
|
|
|
\see IEditController*/
|
|
//------------------------------------------------------------------------
|
|
class IEditController2: public FUnknown
|
|
{
|
|
public:
|
|
/** Host could set the Knob Mode for the Plug-in. Return kResultFalse means not supported mode. \see KnobModes. */
|
|
virtual tresult PLUGIN_API setKnobMode (KnobMode mode) = 0;
|
|
|
|
/** Host could ask to open the Plug-in help (could be: opening a PDF document or link to a web page).
|
|
The host could call it with onlyCheck set to true for testing support of open Help.
|
|
Return kResultFalse means not supported function. */
|
|
virtual tresult PLUGIN_API openHelp (TBool onlyCheck) = 0;
|
|
|
|
/** Host could ask to open the Plug-in about box.
|
|
The host could call it with onlyCheck set to true for testing support of open AboutBox.
|
|
Return kResultFalse means not supported function. */
|
|
virtual tresult PLUGIN_API openAboutBox (TBool onlyCheck) = 0;
|
|
|
|
//------------------------------------------------------------------------
|
|
static const FUID iid;
|
|
};
|
|
|
|
DECLARE_CLASS_IID (IEditController2, 0x7F4EFE59, 0xF3204967, 0xAC27A3AE, 0xAFB63038)
|
|
|
|
//------------------------------------------------------------------------
|
|
/** MIDI Mapping Interface.
|
|
\ingroup vstIPlug vst301
|
|
- [plug imp]
|
|
- [extends IEditController]
|
|
- [released: 3.0.1]
|
|
- [optional]
|
|
|
|
MIDI controllers are not transmitted directly to a VST component. MIDI as hardware protocol has
|
|
restrictions that can be avoided in software. Controller data in particular come along with unclear
|
|
and often ignored semantics. On top of this they can interfere with regular parameter automation and
|
|
the host is unaware of what happens in the Plug-in when passing MIDI controllers directly.
|
|
|
|
So any functionality that is to be controlled by MIDI controllers must be exported as regular parameter.
|
|
The host will transform incoming MIDI controller data using this interface and transmit them as normal
|
|
parameter change. This allows the host to automate them in the same way as other parameters.
|
|
CtrlNumber could be typical MIDI controller value extended to some others values like pitch bend or
|
|
after touch (see \ref ControllerNumbers).
|
|
If the mapping has changed, the Plug-in should call IComponentHandler::restartComponent (kMidiCCAssignmentChanged)
|
|
to inform the host about this change. */
|
|
//------------------------------------------------------------------------
|
|
class IMidiMapping: public FUnknown
|
|
{
|
|
public:
|
|
|
|
/** Gets an (preferred) associated ParamID for a given Input Event Bus index, channel and MIDI Controller.
|
|
* @param[in] busIndex - index of Input Event Bus
|
|
* @param[in] channel - channel of the bus
|
|
* @param[in] midiControllerNumber - see \ref ControllerNumbers for expected values (could be bigger than 127)
|
|
* @param[in] id - return the associated ParamID to the given midiControllerNumber
|
|
*/
|
|
virtual tresult PLUGIN_API getMidiControllerAssignment (int32 busIndex, int16 channel,
|
|
CtrlNumber midiControllerNumber, ParamID& id/*out*/) = 0;
|
|
|
|
//------------------------------------------------------------------------
|
|
static const FUID iid;
|
|
};
|
|
|
|
DECLARE_CLASS_IID (IMidiMapping, 0xDF0FF9F7, 0x49B74669, 0xB63AB732, 0x7ADBF5E5)
|
|
|
|
//------------------------------------------------------------------------
|
|
/** Parameter Editing from Host.
|
|
\ingroup vstIPlug vst350
|
|
- [plug imp]
|
|
- [extends IEditController]
|
|
- [released: 3.5.0]
|
|
- [optional]
|
|
|
|
If this interface is implemented by the edit controller and when performing edits from outside
|
|
the Plug-in (host / remote) of a not automatable and not read only flagged parameter (kind of helper parameter),
|
|
the host will start with a beginEditFromHost before calling setParamNormalized and end with an endEditFromHost.
|
|
Here the sequencing, the host will call:
|
|
- beginEditFromHost ()
|
|
- setParamNormalized ()
|
|
- setParamNormalized ()
|
|
- ...
|
|
- endEditFromHost ()
|
|
\see IEditController */
|
|
//------------------------------------------------------------------------
|
|
class IEditControllerHostEditing : public FUnknown
|
|
{
|
|
public:
|
|
/** Called before a setParamNormalized sequence, a endEditFromHost will be call at the end of the editing action. */
|
|
virtual tresult PLUGIN_API beginEditFromHost (ParamID paramID) = 0;
|
|
|
|
/** Called after a beginEditFromHost and a sequence of setParamNormalized. */
|
|
virtual tresult PLUGIN_API endEditFromHost (ParamID paramID) = 0;
|
|
|
|
//------------------------------------------------------------------------
|
|
static const FUID iid;
|
|
};
|
|
|
|
DECLARE_CLASS_IID (IEditControllerHostEditing, 0xC1271208, 0x70594098, 0xB9DD34B3, 0x6BB0195E)
|
|
|
|
//------------------------------------------------------------------------
|
|
} // namespace Vst
|
|
} // namespace Steinberg
|
|
|
|
//------------------------------------------------------------------------
|
|
#include "pluginterfaces/base/falignpop.h"
|
|
//------------------------------------------------------------------------
|