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 "vsttypes.h" 21 22 //------------------------------------------------------------------------ 23 #include "pluginterfaces/base/falignpush.h" 24 //------------------------------------------------------------------------ 25 26 namespace Steinberg { 27 class IBStream; 28 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 doesn't 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. 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 //------------------------------------------------------------------------ 100 /** Host callback for extended unit support. 101 \ingroup vstIHost vst365 102 - [host imp] 103 - [extends IUnitHandler] 104 - [released: 3.6.5] 105 - [optional] 106 107 Host callback interface, used with IUnitInfo. 108 Retrieve via queryInterface from IComponentHandler. 109 110 \see \ref vst3Units, IUnitHandler */ 111 //------------------------------------------------------------------------ 112 class IUnitHandler2 : public FUnknown 113 { 114 public: 115 //------------------------------------------------------------------------ 116 /** Tell host that assignment Unit-Bus defined by IUnitInfo::getUnitByBus has changed. */ 117 virtual tresult PLUGIN_API notifyUnitByBusChange () = 0; 118 119 //------------------------------------------------------------------------ 120 static const FUID iid; 121 }; 122 123 DECLARE_CLASS_IID (IUnitHandler2, 0xF89F8CDF, 0x699E4BA5, 0x96AAC9A4, 0x81452B01) 124 125 126 //------------------------------------------------------------------------ 127 /** Edit controller extension to describe the Plug-in structure. 128 \ingroup vstIPlug vst300 129 - [plug imp] 130 - [extends IEditController] 131 - [released: 3.0.0] 132 - [optional] 133 134 IUnitInfo describes the internal structure of the Plug-in. 135 - The root unit is the component itself, so getUnitCount must return 1 at least. 136 - The root unit id has to be 0 (kRootUnitId). 137 - Each unit can reference one program list - this reference must not change. 138 - Each unit using a program list, references one program of the list. 139 140 \see \ref vst3Units, IUnitHandler */ 141 //------------------------------------------------------------------------ 142 class IUnitInfo: public FUnknown 143 { 144 public: 145 //------------------------------------------------------------------------ 146 /** Returns the flat count of units. */ 147 virtual int32 PLUGIN_API getUnitCount () = 0; 148 149 /** Gets UnitInfo for a given index in the flat list of unit. */ 150 virtual tresult PLUGIN_API getUnitInfo (int32 unitIndex, UnitInfo& info /*out*/) = 0; 151 152 /** Component intern program structure. */ 153 /** Gets the count of Program List. */ 154 virtual int32 PLUGIN_API getProgramListCount () = 0; 155 156 /** Gets for a given index the Program List Info. */ 157 virtual tresult PLUGIN_API getProgramListInfo (int32 listIndex, ProgramListInfo& info /*out*/) = 0; 158 159 /** Gets for a given program list ID and program index its program name. */ 160 virtual tresult PLUGIN_API getProgramName (ProgramListID listId, int32 programIndex, String128 name /*out*/) = 0; 161 162 /** Gets for a given program list ID, program index and attributeId the associated attribute value. */ 163 virtual tresult PLUGIN_API getProgramInfo (ProgramListID listId, int32 programIndex, 164 CString attributeId /*in*/, String128 attributeValue /*out*/) = 0; 165 166 /** Returns kResultTrue if the given program index of a given program list ID supports PitchNames. */ 167 virtual tresult PLUGIN_API hasProgramPitchNames (ProgramListID listId, int32 programIndex) = 0; 168 169 /** Gets the PitchName for a given program list ID, program index and pitch. 170 If PitchNames are changed the Plug-in should inform the host with IUnitHandler::notifyProgramListChange. */ 171 virtual tresult PLUGIN_API getProgramPitchName (ProgramListID listId, int32 programIndex, 172 int16 midiPitch, String128 name /*out*/) = 0; 173 174 // units selection -------------------- 175 /** Gets the current selected unit. */ 176 virtual UnitID PLUGIN_API getSelectedUnit () = 0; 177 178 /** Sets a new selected unit. */ 179 virtual tresult PLUGIN_API selectUnit (UnitID unitId) = 0; 180 181 /** Gets the according unit if there is an unambiguous relation between a channel or a bus and a unit. 182 This method mainly is intended to find out which unit is related to a given MIDI input channel. */ 183 virtual tresult PLUGIN_API getUnitByBus (MediaType type, BusDirection dir, int32 busIndex, 184 int32 channel, UnitID& unitId /*out*/) = 0; 185 186 /** Receives a preset data stream. 187 - If the component supports program list data (IProgramListData), the destination of the data 188 stream is the program specified by list-Id and program index (first and second parameter) 189 - If the component supports unit data (IUnitData), the destination is the unit specified by the first 190 parameter - in this case parameter programIndex is < 0). */ 191 virtual tresult PLUGIN_API setUnitProgramData (int32 listOrUnitId, int32 programIndex, IBStream* data) = 0; 192 193 //------------------------------------------------------------------------ 194 static const FUID iid; 195 }; 196 197 DECLARE_CLASS_IID (IUnitInfo, 0x3D4BD6B5, 0x913A4FD2, 0xA886E768, 0xA5EB92C1) 198 199 //------------------------------------------------------------------------ 200 /** Component extension to access program list data. 201 \ingroup vstIPlug vst300 202 - [plug imp] 203 - [extends IComponent] 204 - [released: 3.0.0] 205 - [optional] 206 207 A component can either support program list data via this interface or 208 unit preset data (IUnitData), but not both! 209 210 \see \ref vst3UnitPrograms */ 211 //------------------------------------------------------------------------ 212 class IProgramListData: public FUnknown 213 { 214 public: 215 //------------------------------------------------------------------------ 216 /** Returns kResultTrue if the given Program List ID supports Program Data. */ 217 virtual tresult PLUGIN_API programDataSupported (ProgramListID listId) = 0; 218 219 /** Gets for a given program list ID and program index the program Data. */ 220 virtual tresult PLUGIN_API getProgramData (ProgramListID listId, int32 programIndex, IBStream* data) = 0; 221 222 /** Sets for a given program list ID and program index a program Data. */ 223 virtual tresult PLUGIN_API setProgramData (ProgramListID listId, int32 programIndex, IBStream* data) = 0; 224 225 //------------------------------------------------------------------------ 226 static const FUID iid; 227 }; 228 229 DECLARE_CLASS_IID (IProgramListData, 0x8683B01F, 0x7B354F70, 0xA2651DEC, 0x353AF4FF) 230 231 //------------------------------------------------------------------------ 232 /** Component extension to access unit data. 233 \ingroup vstIPlug vst300 234 - [plug imp] 235 - [extends IComponent] 236 - [released: 3.0.0] 237 - [optional] 238 239 A component can either support unit preset data via this interface or 240 program list data (IProgramListData), but not both! 241 242 \see \ref vst3UnitPrograms */ 243 //------------------------------------------------------------------------ 244 class IUnitData: public FUnknown 245 { 246 public: 247 //------------------------------------------------------------------------ 248 /** Returns kResultTrue if the specified unit supports export and import of preset data. */ 249 virtual tresult PLUGIN_API unitDataSupported (UnitID unitID) = 0; 250 251 /** Gets the preset data for the specified unit. */ 252 virtual tresult PLUGIN_API getUnitData (UnitID unitId, IBStream* data) = 0; 253 254 /** Sets the preset data for the specified unit. */ 255 virtual tresult PLUGIN_API setUnitData (UnitID unitId, IBStream* data) = 0; 256 257 //------------------------------------------------------------------------ 258 static const FUID iid; 259 }; 260 261 DECLARE_CLASS_IID (IUnitData, 0x6C389611, 0xD391455D, 0xB870B833, 0x94A0EFDD) 262 263 //------------------------------------------------------------------------ 264 } // namespace Vst 265 } // namespace Steinberg 266 267 //------------------------------------------------------------------------ 268 #include "pluginterfaces/base/falignpop.h" 269 //------------------------------------------------------------------------ 270