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

   1 //------------------------------------------------------------------------
   2 // Project     : VST SDK
   3 //
   4 // Category    : Interfaces
   5 // Filename    : pluginterfaces/vst/ivstunits.h
   6 // Created by  : Steinberg, 2005
   7 // Description : VST Units 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/funknown.h"
  20 #include "pluginterfaces/vst/vsttypes.h"
  21
  22 //------------------------------------------------------------------------
  23 #include "pluginterfaces/base/falignpush.h"
  24 //------------------------------------------------------------------------
  25
  26 //------------------------------------------------------------------------
  27 namespace Steinberg {
  28 class IBStream;
  29 //------------------------------------------------------------------------
  30 namespace Vst {
  31 //------------------------------------------------------------------------
  32 /** Special UnitIDs for UnitInfo */
  33 static const UnitID kRootUnitId = 0;        ///< identifier for the top level unit (root)
  34 static const UnitID kNoParentUnitId = -1;       ///< used for the root unit which does not have a parent.
  35
  36 //------------------------------------------------------------------------
  37 /** Special ProgramListIDs for UnitInfo */
  38 static const ProgramListID kNoProgramListId = -1;       ///< no programs are used in the unit.
  39
  40 //------------------------------------------------------------------------
  41 /** Basic Unit Description.
  42 \see IUnitInfo
  43 */
  44 struct UnitInfo
  45 {
  46         UnitID id;                                              ///< unit identifier
  47         UnitID parentUnitId;                    ///< identifier of parent unit (kNoParentUnitId: does not apply, this unit is the root)
  48         String128 name;                                 ///< name, optional for the root component, required otherwise
  49         ProgramListID programListId;    ///< id of program list used in unit (kNoProgramListId = no programs used in this unit)
  50 };
  51
  52 //------------------------------------------------------------------------
  53 /** Basic Program List Description.
  54 \see IUnitInfo
  55 */
  56 struct ProgramListInfo
  57 {
  58         ProgramListID id;                               ///< program list identifier
  59         String128 name;                                 ///< name of program list
  60         int32 programCount;                             ///< number of programs in this list
  61 };
  62
  63 //------------------------------------------------------------------------
  64 /** Special programIndex value for IUnitHandler::notifyProgramListChange */
  65 static const int32 kAllProgramInvalid = -1;             ///< all program information is invalid
  66
  67 //------------------------------------------------------------------------
  68 /** Host callback for unit support: Vst::IUnitHandler
  69 \ingroup vstIHost vst300
  70 - [host imp]
  71 - [extends IComponentHandler]
  72 - [released: 3.0.0]
  73 - [optional]
  74
  75 Host callback interface, used with IUnitInfo.
  76 Retrieve via queryInterface from IComponentHandler.
  77
  78 \see \ref vst3Units, IUnitInfo
  79 */
  80 class IUnitHandler : public FUnknown
  81 {
  82 public:
  83 //------------------------------------------------------------------------
  84         /** Notify host when a module is selected in plug-in GUI. */
  85         virtual tresult PLUGIN_API notifyUnitSelection (UnitID unitId) = 0;
  86
  87         /** Tell host that the plug-in controller changed a program list (rename, load, PitchName changes).
  88             \param listId is the specified program list ID to inform.
  89                 \param programIndex : when kAllProgramInvalid, all program information is invalid, otherwise only the program of given index. */
  90         virtual tresult PLUGIN_API notifyProgramListChange (ProgramListID listId, int32 programIndex) = 0;
  91
  92 //------------------------------------------------------------------------
  93         static const FUID iid;
  94 };
  95
  96 DECLARE_CLASS_IID (IUnitHandler, 0x4B5147F8, 0x4654486B, 0x8DAB30BA, 0x163A3C56)
  97
  98 //------------------------------------------------------------------------
  99 /** Host callback for extended unit support: Vst::IUnitHandler2
 100 \ingroup vstIHost vst365
 101 - [host imp]
 102 - [extends IUnitHandler]
 103 - [released: 3.6.5]
 104 - [optional]
 105
 106 Host callback interface, used with IUnitInfo.
 107 Retrieve via queryInterface from IComponentHandler.
 108
 109 The plug-in has the possibility to inform the host with notifyUnitByBusChange that something has
 110 changed in the bus - unit assignment, the host then has to recall IUnitInfo::getUnitByBus in order
 111 to get the new relations between busses and unit.
 112
 113 \see \ref vst3Units, IUnitHandler
 114 */
 115 class IUnitHandler2 : public FUnknown
 116 {
 117 public:
 118         //------------------------------------------------------------------------
 119         /** Tell host that assignment Unit-Bus defined by IUnitInfo::getUnitByBus has changed. */
 120         virtual tresult PLUGIN_API notifyUnitByBusChange () = 0;
 121
 122         //------------------------------------------------------------------------
 123         static const FUID iid;
 124 };
 125
 126 DECLARE_CLASS_IID (IUnitHandler2, 0xF89F8CDF, 0x699E4BA5, 0x96AAC9A4, 0x81452B01)
 127
 128 //------------------------------------------------------------------------
 129 /** Edit controller extension to describe the plug-in structure: Vst::IUnitInfo
 130 \ingroup vstIPlug vst300
 131 - [plug imp]
 132 - [extends IEditController]
 133 - [released: 3.0.0]
 134 - [optional]
 135
 136 IUnitInfo describes the internal structure of the plug-in.
 137 - The root unit is the component itself, so getUnitCount must return 1 at least.
 138 - The root unit id has to be 0 (kRootUnitId).
 139 - Each unit can reference one program list - this reference must not change.
 140 - Each unit, using a program list, references one program of the list.
 141
 142 \see \ref vst3Units, IUnitHandler
 143 */
 144 class IUnitInfo : public FUnknown
 145 {
 146 public:
 147 //------------------------------------------------------------------------
 148         /** Returns the flat count of units. */
 149         virtual int32 PLUGIN_API getUnitCount () = 0;
 150
 151         /** Gets UnitInfo for a given index in the flat list of unit. */
 152         virtual tresult PLUGIN_API getUnitInfo (int32 unitIndex, UnitInfo& info /*out*/) = 0;
 153
 154         /** Component intern program structure. */
 155         /** Gets the count of Program List. */
 156         virtual int32 PLUGIN_API getProgramListCount () = 0;
 157
 158         /** Gets for a given index the Program List Info. */
 159         virtual tresult PLUGIN_API getProgramListInfo (int32 listIndex, ProgramListInfo& info /*out*/) = 0;
 160
 161         /** Gets for a given program list ID and program index its program name. */
 162         virtual tresult PLUGIN_API getProgramName (ProgramListID listId, int32 programIndex, String128 name /*out*/) = 0;
 163
 164         /** Gets for a given program list ID, program index and attributeId the associated attribute value. */
 165         virtual tresult PLUGIN_API getProgramInfo (ProgramListID listId, int32 programIndex,
 166                 CString attributeId /*in*/, String128 attributeValue /*out*/) = 0;
 167
 168         /** Returns kResultTrue if the given program index of a given program list ID supports PitchNames. */
 169         virtual tresult PLUGIN_API hasProgramPitchNames (ProgramListID listId, int32 programIndex) = 0;
 170
 171         /** Gets the PitchName for a given program list ID, program index and pitch.
 172                 If PitchNames are changed the plug-in should inform the host with IUnitHandler::notifyProgramListChange. */
 173         virtual tresult PLUGIN_API getProgramPitchName (ProgramListID listId, int32 programIndex,
 174                 int16 midiPitch, String128 name /*out*/) = 0;
 175
 176         // units selection --------------------
 177         /** Gets the current selected unit. */
 178         virtual UnitID PLUGIN_API getSelectedUnit () = 0;
 179
 180         /** Sets a new selected unit. */
 181         virtual tresult PLUGIN_API selectUnit (UnitID unitId) = 0;
 182
 183         /** Gets the according unit if there is an unambiguous relation between a channel or a bus and a unit.
 184             This method mainly is intended to find out which unit is related to a given MIDI input channel. */
 185         virtual tresult PLUGIN_API getUnitByBus (MediaType type, BusDirection dir, int32 busIndex,
 186                 int32 channel, UnitID& unitId /*out*/) = 0;
 187
 188         /** Receives a preset data stream.
 189             - If the component supports program list data (IProgramListData), the destination of the data
 190                   stream is the program specified by list-Id and program index (first and second parameter)
 191                 - If the component supports unit data (IUnitData), the destination is the unit specified by the first
 192                   parameter - in this case parameter programIndex is < 0). */
 193         virtual tresult PLUGIN_API setUnitProgramData (int32 listOrUnitId, int32 programIndex, IBStream* data) = 0;
 194
 195 //------------------------------------------------------------------------
 196         static const FUID iid;
 197 };
 198
 199 DECLARE_CLASS_IID (IUnitInfo, 0x3D4BD6B5, 0x913A4FD2, 0xA886E768, 0xA5EB92C1)
 200
 201 //------------------------------------------------------------------------
 202 /** Component extension to access program list data: Vst::IProgramListData
 203 \ingroup vstIPlug vst300
 204 - [plug imp]
 205 - [extends IComponent]
 206 - [released: 3.0.0]
 207 - [optional]
 208
 209 A component can support program list data via this interface or/and
 210 unit preset data (IUnitData).
 211
 212 \see IUnitData, \ref vst3MultitimbralPrograms
 213 */
 214 class IProgramListData : public FUnknown
 215 {
 216 public:
 217 //------------------------------------------------------------------------
 218         /** Returns kResultTrue if the given Program List ID supports Program Data. */
 219         virtual tresult PLUGIN_API programDataSupported (ProgramListID listId) = 0;
 220
 221         /** Gets for a given program list ID and program index the program Data. */
 222         virtual tresult PLUGIN_API getProgramData (ProgramListID listId, int32 programIndex, IBStream* data) = 0;
 223
 224         /** Sets for a given program list ID and program index a program Data. */
 225         virtual tresult PLUGIN_API setProgramData (ProgramListID listId, int32 programIndex, IBStream* data) = 0;
 226
 227 //------------------------------------------------------------------------
 228         static const FUID iid;
 229 };
 230
 231 DECLARE_CLASS_IID (IProgramListData, 0x8683B01F, 0x7B354F70, 0xA2651DEC, 0x353AF4FF)
 232
 233 //------------------------------------------------------------------------
 234 /** Component extension to access unit data: Vst::IUnitData
 235 \ingroup vstIPlug vst300
 236 - [plug imp]
 237 - [extends IComponent]
 238 - [released: 3.0.0]
 239 - [optional]
 240
 241 A component can support unit preset data via this interface or
 242 program list data (IProgramListData).
 243
 244 \see \ref vst3ProgramLists
 245 */
 246 class IUnitData : public FUnknown
 247 {
 248 public:
 249 //------------------------------------------------------------------------
 250         /** Returns kResultTrue if the specified unit supports export and import of preset data. */
 251         virtual tresult PLUGIN_API unitDataSupported (UnitID unitID) = 0;
 252
 253         /** Gets the preset data for the specified unit. */
 254         virtual tresult PLUGIN_API getUnitData (UnitID unitId, IBStream* data) = 0;
 255
 256         /** Sets the preset data for the specified unit. */
 257         virtual tresult PLUGIN_API setUnitData (UnitID unitId, IBStream* data) = 0;
 258
 259 //------------------------------------------------------------------------
 260         static const FUID iid;
 261 };
 262
 263 DECLARE_CLASS_IID (IUnitData, 0x6C389611, 0xD391455D, 0xB870B833, 0x94A0EFDD)
 264
 265 //------------------------------------------------------------------------
 266 } // namespace Vst
 267 } // namespace Steinberg
 268
 269 //------------------------------------------------------------------------
 270 #include "pluginterfaces/base/falignpop.h"
 271 //------------------------------------------------------------------------