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 //------------------------------------------------------------------------ 272