source/includes/vst3sdk/pluginterfaces/vst/ivstcomponent.h

   1 //-----------------------------------------------------------------------------
   2 // Project     : VST SDK
   3 //
   4 // Category    : Interfaces
   5 // Filename    : pluginterfaces/vst/ivstcomponent.h
   6 // Created by  : Steinberg, 04/2005
   7 // Description : Basic VST Interfaces
   8 //
   9 //-----------------------------------------------------------------------------
  10 // This file is part of a Steinberg SDK. It is subject to the license terms
  11 // in the LICENSE file found in the top-level directory of this distribution
  12 // and at www.steinberg.net/sdklicenses.
  13 // No part of the SDK, including this file, may be copied, modified, propagated,
  14 // or distributed except according to the terms contained in the LICENSE file.
  15 //-----------------------------------------------------------------------------
  16
  17 #pragma once
  18
  19 #include "pluginterfaces/base/ipluginbase.h"
  20 #include "pluginterfaces/vst/vsttypes.h"
  21
  22 //------------------------------------------------------------------------
  23 #include "pluginterfaces/base/falignpush.h"
  24 //------------------------------------------------------------------------
  25
  26 namespace Steinberg {
  27 class IBStream;
  28
  29 //------------------------------------------------------------------------
  30 /** All VST specific interfaces are located in Vst namespace */
  31 namespace Vst {
  32
  33 /** Standard value for PFactoryInfo::flags */
  34 const int32 kDefaultFactoryFlags = PFactoryInfo::kUnicode;
  35
  36 #define BEGIN_FACTORY_DEF(vendor,url,email) using namespace Steinberg; \
  37         SMTG_EXPORT_SYMBOL IPluginFactory* PLUGIN_API GetPluginFactory () {     \
  38         if (!gPluginFactory) \
  39         { \
  40                 static PFactoryInfo factoryInfo (vendor, url, email, Vst::kDefaultFactoryFlags); \
  41                 gPluginFactory = new CPluginFactory (factoryInfo);
  42
  43 //------------------------------------------------------------------------
  44 /** \defgroup vstBus VST busses
  45 Bus Description
  46
  47 A bus can be understood as a "collection of data channels" belonging together.
  48 It describes a data input or a data output of the plug-in.
  49 A VST component can define any desired number of busses.
  50 Dynamic usage of busses is handled in the host by activating and deactivating busses.
  51 All busses are initially inactive.
  52 The component has to define the maximum number of supported busses and it has to
  53 define which of them have to be activated by default after instantiation of the plug-in (This is
  54 only a wish, the host is allow to not follow it, and only activate the first bus for example).
  55 A host that can handle multiple busses, allows the user to activate busses which are initially all inactive.
  56 The kMain busses have to place before any others kAux busses.
  57
  58 See also: IComponent::getBusInfo, IComponent::activateBus
  59 */
  60 /*@{*/
  61
  62 //------------------------------------------------------------------------
  63 /** Bus media types */
  64 enum MediaTypes
  65 {
  66         kAudio = 0,             ///< audio
  67         kEvent,                 ///< events
  68         kNumMediaTypes
  69 };
  70
  71 //------------------------------------------------------------------------
  72 /** Bus directions */
  73 enum BusDirections
  74 {
  75         kInput = 0,             ///< input bus
  76         kOutput                 ///< output bus
  77 };
  78
  79 //------------------------------------------------------------------------
  80 /** Bus types */
  81 enum BusTypes
  82 {
  83         kMain = 0,              ///< main bus
  84         kAux                    ///< auxiliary bus (sidechain)
  85 };
  86
  87 //------------------------------------------------------------------------
  88 /** BusInfo:
  89 This is the structure used with getBusInfo, informing the host about what is a specific given bus.
  90 \n See also: Steinberg::Vst::IComponent::getBusInfo
  91 */
  92 struct BusInfo
  93 {
  94         MediaType mediaType;    ///< Media type - has to be a value of \ref MediaTypes
  95         BusDirection direction; ///< input or output \ref BusDirections
  96         int32 channelCount;             ///< number of channels (if used then need to be recheck after \ref
  97                                                         /// IAudioProcessor::setBusArrangements is called).
  98                                                         /// For a bus of type MediaTypes::kEvent the channelCount corresponds
  99                                                         /// to the number of supported MIDI channels by this bus
 100         String128 name;                 ///< name of the bus
 101         BusType busType;                ///< main or aux - has to be a value of \ref BusTypes
 102         uint32 flags;                   ///< flags - a combination of \ref BusFlags
 103         enum BusFlags
 104         {
 105                 /** The bus should be activated by the host per default on instantiation (activateBus call is requested).
 106                         By default a bus is inactive. */
 107                 kDefaultActive = 1 << 0,
 108                 /** The bus does not contain ordinary audio data, but data used for control changes at sample rate.
 109                         The data is in the same format as the audio data [-1..1].
 110                         A host has to prevent unintended routing to speakers to prevent damage.
 111                         Only valid for audio media type busses.
 112                         [released: 3.7.0] */
 113                 kIsControlVoltage = 1 << 1
 114         };
 115 };
 116
 117 /*@}*/
 118
 119 //------------------------------------------------------------------------
 120 /** I/O modes */
 121 enum IoModes
 122 {
 123         kSimple = 0,            ///< 1:1 Input / Output. Only used for Instruments. See \ref vst3IoMode
 124         kAdvanced,                      ///< n:m Input / Output. Only used for Instruments.
 125         kOfflineProcessing      ///< plug-in used in an offline processing context
 126 };
 127
 128 //------------------------------------------------------------------------
 129 /** Routing Information:
 130 When the plug-in supports multiple I/O busses, a host may want to know how the busses are related. The
 131 relation of an event-input-channel to an audio-output-bus in particular is of interest to the host
 132 (in order to relate MIDI-tracks to audio-channels)
 133 \n See also: IComponent::getRoutingInfo, \ref vst3Routing
 134 */
 135 struct RoutingInfo
 136 {
 137         MediaType mediaType;    ///< media type see \ref MediaTypes
 138         int32 busIndex;                 ///< bus index
 139         int32 channel;                  ///< channel (-1 for all channels)
 140 };
 141
 142 //------------------------------------------------------------------------
 143 // IComponent Interface
 144 //------------------------------------------------------------------------
 145 /** Component base interface: Vst::IComponent
 146 \ingroup vstIPlug vst300
 147 - [plug imp]
 148 - [released: 3.0.0]
 149 - [mandatory]
 150
 151 This is the basic interface for a VST component and must always be supported.
 152 It contains the common parts of any kind of processing class. The parts that
 153 are specific to a media type are defined in a separate interface. An implementation
 154 component must provide both the specific interface and IComponent.
 155 \see IPluginBase
 156 */
 157 class IComponent : public IPluginBase
 158 {
 159 public:
 160 //------------------------------------------------------------------------
 161         /** Called before initializing the component to get information about the controller class. */
 162         virtual tresult PLUGIN_API getControllerClassId (TUID classId) = 0;
 163
 164         /** Called before 'initialize' to set the component usage (optional). See \ref IoModes */
 165         virtual tresult PLUGIN_API setIoMode (IoMode mode) = 0;
 166
 167         /** Called after the plug-in is initialized. See \ref MediaTypes, BusDirections */
 168         virtual int32 PLUGIN_API getBusCount (MediaType type, BusDirection dir) = 0;
 169
 170         /** Called after the plug-in is initialized. See \ref MediaTypes, BusDirections */
 171         virtual tresult PLUGIN_API getBusInfo (MediaType type, BusDirection dir, int32 index, BusInfo& bus /*out*/) = 0;
 172
 173         /** Retrieves routing information (to be implemented when more than one regular input or output bus exists).
 174             The inInfo always refers to an input bus while the returned outInfo must refer to an output bus! */
 175         virtual tresult PLUGIN_API getRoutingInfo (RoutingInfo& inInfo, RoutingInfo& outInfo /*out*/) = 0;
 176
 177         /** Called upon (de-)activating a bus in the host application. The plug-in should only processed
 178            an activated bus, the host could provide less see \ref AudioBusBuffers in the process call
 179            (see \ref IAudioProcessor::process) if last busses are not activated. An already activated bus
 180            does not need to be reactivated after a IAudioProcessor::setBusArrangements call. */
 181         virtual tresult PLUGIN_API activateBus (MediaType type, BusDirection dir, int32 index,
 182                                                 TBool state) = 0;
 183
 184         /** Activates / deactivates the component. */
 185         virtual tresult PLUGIN_API setActive (TBool state) = 0;
 186
 187         /** Sets complete state of component. */
 188         virtual tresult PLUGIN_API setState (IBStream* state) = 0;
 189
 190         /** Retrieves complete state of component. */
 191         virtual tresult PLUGIN_API getState (IBStream* state) = 0;
 192
 193 //------------------------------------------------------------------------
 194         static const FUID iid;
 195 };
 196
 197 DECLARE_CLASS_IID (IComponent, 0xE831FF31, 0xF2D54301, 0x928EBBEE, 0x25697802)
 198
 199 //------------------------------------------------------------------------
 200 } // namespace Vst
 201 } // namespace Steinberg
 202
 203 //------------------------------------------------------------------------
 204 #include "pluginterfaces/base/falignpop.h"
 205 //------------------------------------------------------------------------