?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
Fix last commit
[carla.git] / source / includes / vst3sdk / pluginterfaces / vst / ivstrepresentation.h
blobfe6e8df0fbde1fcb510397954c9f865a1bc614e9
1 //------------------------------------------------------------------------
2 // Project : VST SDK
3 //
4 // Category : Interfaces
5 // Filename : pluginterfaces/vst/ivstrepresentation.h
6 // Created by : Steinberg, 08/2010
7 // Description : VST Representation Interface
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 //------------------------------------------------------------------------
33 /** RepresentationInfo is the structure describing a representation
34 This structure is used in the function \see IXmlRepresentationController::getXmlRepresentationStream.
35 \see IXmlRepresentationController
36 */
37 struct RepresentationInfo
38 {
39 RepresentationInfo ()
40 {
41 memset (vendor, 0, kNameSize);
42 memset (name, 0, kNameSize);
43 memset (version, 0, kNameSize);
44 memset (host, 0, kNameSize);
45 }
46
47 RepresentationInfo (char8* _vendor, char8* _name = nullptr, char8* _version = nullptr, char8* _host = nullptr)
48 {
49 memset (vendor, 0, kNameSize);
50 if (_vendor)
51 strcpy (vendor, _vendor);
52 memset (name, 0, kNameSize);
53 if (_name)
54 strcpy (name, _name);
55 memset (version, 0, kNameSize);
56 if (_version)
57 strcpy (version, _version);
58 memset (host, 0, kNameSize);
59 if (_host)
60 strcpy (host, _host);
61 }
62
63 enum
64 {
65 kNameSize = 64
66 };
67 char8 vendor[kNameSize]; ///< Vendor name of the associated representation (remote) (eg. "Yamaha").
68 char8 name[kNameSize]; ///< Representation (remote) Name (eg. "O2").
69 char8 version[kNameSize]; ///< Version of this "Remote" (eg. "1.0").
70 char8 host[kNameSize]; ///< Optional: used if the representation is for a given host only (eg. "Nuendo").
71 };
72
73
74 //------------------------------------------------------------------------
75 //------------------------------------------------------------------------
76 /** Extended plug-in interface IEditController for a component: Vst::IXmlRepresentationController
77 \ingroup vstIPlug vst350
78 - [plug imp]
79 - [extends IEditController]
80 - [released: 3.5.0]
81 - [optional]
82
83 A representation based on XML is a way to export, structure, and group plug-ins parameters for a specific remote (hardware or software rack (such as quick controls)).
84 \n
85 It allows to describe each parameter more precisely (what is the best matching to a knob, different title lengths matching limited remote display,...).\n See an \ref Example.
86 \n\n
87 - A representation is composed of pages (this means that to see all exported parameters, the user has to navigate through the pages).
88 - A page is composed of cells (for example 8 cells per page).
89 - A cell is composed of layers (for example a cell could have a knob, a display, and a button, which means 3 layers).
90 - A layer is associated to a plug-in parameter using the ParameterID as identifier:
91 - it could be a knob with a display for title and/or value, this display uses the same parameterId, but it could an another one.
92 - switch
93 - link which allows to jump directly to a subpage (another page)
94 - more... See Vst::LayerType
95 .
96
97 \n
98 This representation is implemented as XML text following the Document Type Definition (DTD): http://dtd.steinberg.net/VST-Remote-1.1.dtd
99
100 \section Example
101 Here an example of what should be passed in the stream of getXmlRepresentationStream:
102
103 \code
104 <?xml version="1.0" encoding="utf-8"?>
105 <!DOCTYPE vstXML PUBLIC "-//Steinberg//DTD VST Remote 1.1//EN" "http://dtd.steinberg.net/VST-Remote-1.1.dtd">
106 <vstXML version="1.0">
107 <plugin classID="341FC5898AAA46A7A506BC0799E882AE" name="Chorus" vendor="Steinberg Media Technologies" />
108 <originator>My name</originator>
109 <date>2010-12-31</date>
110 <comment>This is an example for 4 Cells per Page for the Remote named ProductRemote
111 from company HardwareCompany.</comment>
112
113 <!-- ===================================== -->
114 <representation name="ProductRemote" vendor="HardwareCompany" version="1.0">
115 <page name="Root">
116 <cell>
117 <layer type="knob" parameterID="0">
118 <titleDisplay>
119 <name>Mix dry/wet</name>
120 <name>Mix</name>
121 </titleDisplay>
122 </layer>
123 </cell>
124 <cell>
125 <layer type="display"></layer>
126 </cell>
127 <cell>
128 <layer type="knob" parameterID="3">
129 <titleDisplay>
130 <name>Delay</name>
131 <name>Dly</name>
132 </titleDisplay>
133 </layer>
134 </cell>
135 <cell>
136 <layer type="knob" parameterID="15">
137 <titleDisplay>
138 <name>Spatial</name>
139 <name>Spat</name>
140 </titleDisplay>
141 </layer>
142 </cell>
143 </page>
144 <page name="Page 2">
145 <cell>
146 <layer type="LED" ledStyle="spread" parameterID="2">
147 <titleDisplay>
148 <name>Width +</name>
149 <name>Widt</name>
150 </titleDisplay>
151 </layer>
152 <!--this is the switch for shape A/B-->
153 <layer type="switch" switchStyle="pushIncLooped" parameterID="4"></layer>
154 </cell>
155 <cell>
156 <layer type="display"></layer>
157 </cell>
158 <cell>
159 <layer type="LED" ledStyle="singleDot" parameterID="17">
160 <titleDisplay>
161 <name>Sync Note +</name>
162 <name>Note</name>
163 </titleDisplay>
164 </layer>
165 <!--this is the switch for sync to tempo on /off-->
166 <layer type="switch" switchStyle="pushIncLooped" parameterID="16"></layer>
167 </cell>
168 <cell>
169 <layer type="knob" parameterID="1">
170 <titleDisplay>
171 <name>Rate</name>
172 </titleDisplay>
173 </layer>
174 </cell>
175 </page>
176 </representation>
177 </vstXML>
178 \endcode
179 */
180 class IXmlRepresentationController : public FUnknown
181 {
182 public:
183 /** Retrieves a stream containing a XmlRepresentation for a wanted representation info */
184 virtual tresult PLUGIN_API getXmlRepresentationStream (RepresentationInfo& info /*in*/,
185 IBStream* stream /*out*/) = 0;
186
187 //------------------------------------------------------------------------
188 static const FUID iid;
189 };
190
191 DECLARE_CLASS_IID (IXmlRepresentationController, 0xA81A0471, 0x48C34DC4, 0xAC30C9E1, 0x3C8393D5)
192
193 //------------------------------------------------------------------------
194 /** Defines for XML representation Tags and Attributes */
195
196 #define ROOTXML_TAG "vstXML"
197
198 #define COMMENT_TAG "comment"
199 #define CELL_TAG "cell"
200 #define CELLGROUP_TAG "cellGroup"
201 #define CELLGROUPTEMPLATE_TAG "cellGroupTemplate"
202 #define CURVE_TAG "curve"
203 #define CURVETEMPLATE_TAG "curveTemplate"
204 #define DATE_TAG "date"
205 #define LAYER_TAG "layer"
206 #define NAME_TAG "name"
207 #define ORIGINATOR_TAG "originator"
208 #define PAGE_TAG "page"
209 #define PAGETEMPLATE_TAG "pageTemplate"
210 #define PLUGIN_TAG "plugin"
211 #define VALUE_TAG "value"
212 #define VALUEDISPLAY_TAG "valueDisplay"
213 #define VALUELIST_TAG "valueList"
214 #define REPRESENTATION_TAG "representation"
215 #define SEGMENT_TAG "segment"
216 #define SEGMENTLIST_TAG "segmentList"
217 #define TITLEDISPLAY_TAG "titleDisplay"
218
219 #define ATTR_CATEGORY "category"
220 #define ATTR_CLASSID "classID"
221 #define ATTR_ENDPOINT "endPoint"
222 #define ATTR_INDEX "index"
223 #define ATTR_FLAGS "flags"
224 #define ATTR_FUNCTION "function"
225 #define ATTR_HOST "host"
226 #define ATTR_LEDSTYLE "ledStyle"
227 #define ATTR_LENGTH "length"
228 #define ATTR_LINKEDTO "linkedTo"
229 #define ATTR_NAME "name"
230 #define ATTR_ORDER "order"
231 #define ATTR_PAGE "page"
232 #define ATTR_PARAMID "parameterID"
233 #define ATTR_STARTPOINT "startPoint"
234 #define ATTR_STYLE "style"
235 #define ATTR_SWITCHSTYLE "switchStyle"
236 #define ATTR_TEMPLATE "template"
237 #define ATTR_TURNSPERFULLRANGE "turnsPerFullRange"
238 #define ATTR_TYPE "type"
239 #define ATTR_UNITID "unitID"
240 #define ATTR_VARIABLES "variables"
241 #define ATTR_VENDOR "vendor"
242 #define ATTR_VERSION "version"
243
244 //------------------------------------------------------------------------
245 /** Defines some predefined Representation Remote Names */
246 #define GENERIC "Generic"
247 #define GENERIC_4_CELLS "Generic 4 Cells"
248 #define GENERIC_8_CELLS "Generic 8 Cells"
249 #define GENERIC_12_CELLS "Generic 12 Cells"
250 #define GENERIC_24_CELLS "Generic 24 Cells"
251 #define GENERIC_N_CELLS "Generic %d Cells"
252 #define QUICK_CONTROL_8_CELLS "Quick Controls 8 Cells"
253
254 //------------------------------------------------------------------------
255 /** Layer Types used in a VST XML Representation */
256 namespace LayerType
257 {
258 enum
259 {
260 kKnob = 0, ///< a knob (encoder or not)
261 kPressedKnob, ///< a knob which is used by pressing and turning
262 kSwitchKnob, ///< knob could be pressed to simulate a switch
263 kSwitch, ///< a "on/off" button
264 kLED, ///< LED like VU-meter or display around a knob
265 kLink, ///< indicates that this layer is a folder linked to an another INode (page)
266 kDisplay, ///< only for text display (not really a control)
267 kFader, ///< a fader
268 kEndOfLayerType
269 };
270
271 /** FIDString variant of the LayerType */
272 static const FIDString layerTypeFIDString[] = {
273 "knob"
274 ,"pressedKnob"
275 ,"switchKnob"
276 ,"switch"
277 ,"LED"
278 ,"link"
279 ,"display"
280 ,"fader"
281 ,nullptr
282 };
283 };
284
285 //------------------------------------------------------------------------
286 /** Curve Types used in a VST XML Representation */
287 namespace CurveType
288 {
289 const CString kSegment = "segment"; ///<
290 const CString kValueList = "valueList"; ///<
291 };
292
293 //------------------------------------------------------------------------
294 /** Attributes used to defined a Layer in a VST XML Representation */
295 namespace Attributes
296 {
297 const CString kStyle = ATTR_STYLE; ///< string attribute : See AttributesStyle for available string value
298 const CString kLEDStyle = ATTR_LEDSTYLE; ///< string attribute : See AttributesStyle for available string value
299 const CString kSwitchStyle = ATTR_SWITCHSTYLE; ///< string attribute : See AttributesStyle for available string value
300 const CString kKnobTurnsPerFullRange = ATTR_TURNSPERFULLRANGE; ///< float attribute
301 const CString kFunction = ATTR_FUNCTION; ///< string attribute : See AttributesFunction for available string value
302 const CString kFlags = ATTR_FLAGS; ///< string attribute : See AttributesFlags for available string value
303 };
304
305 //------------------------------------------------------------------------
306 /** Attributes Function used to defined the function of a Layer in a VST XML Representation */
307 namespace AttributesFunction
308 {
309 /// Global Style
310 const CString kPanPosCenterXFunc = "PanPosCenterX"; ///< Gravity point X-axis (L-R) (for stereo: middle between left and right)
311 const CString kPanPosCenterYFunc = "PanPosCenterY"; ///< Gravity point Y-axis (Front-Rear)
312 const CString kPanPosFrontLeftXFunc = "PanPosFrontLeftX"; ///< Left channel Position in X-axis
313 const CString kPanPosFrontLeftYFunc = "PanPosFrontLeftY"; ///< Left channel Position in Y-axis
314 const CString kPanPosFrontRightXFunc = "PanPosFrontRightX"; ///< Right channel Position in X-axis
315 const CString kPanPosFrontRightYFunc = "PanPosFrontRightY"; ///< Right channel Position in Y-axis
316 const CString kPanRotationFunc = "PanRotation"; ///< Rotation around the Center (gravity point)
317 const CString kPanLawFunc = "PanLaw"; ///< Panning Law
318 const CString kPanMirrorModeFunc = "PanMirrorMode"; ///< Panning Mirror Mode
319 const CString kPanLfeGainFunc = "PanLfeGain"; ///< Panning LFE Gain
320 const CString kGainReductionFunc = "GainReduction"; ///< Gain Reduction for compressor
321 const CString kSoloFunc = "Solo"; ///< Solo
322 const CString kMuteFunc = "Mute"; ///< Mute
323 const CString kVolumeFunc = "Volume"; ///< Volume
324 };
325
326 //------------------------------------------------------------------------
327 /** Attributes Style associated a specific Layer Type in a VST XML Representation */
328 namespace AttributesStyle
329 {
330 /// Global Style
331 const CString kInverseStyle = "inverse"; ///< the associated layer should use the inverse value of parameter (1 - x).
332
333 /// LED Style
334 const CString kLEDWrapLeftStyle = "wrapLeft"; ///< |======>----- (the default one if not specified)
335 const CString kLEDWrapRightStyle = "wrapRight"; ///< -------<====|
336 const CString kLEDSpreadStyle = "spread"; ///< ---<==|==>---
337 const CString kLEDBoostCutStyle = "boostCut"; ///< ------|===>--
338 const CString kLEDSingleDotStyle = "singleDot"; ///< --------|----
339
340 /// Switch Style
341 const CString kSwitchPushStyle = "push"; ///< Apply only when pressed, unpressed will reset the value to min.
342 const CString kSwitchPushIncLoopedStyle = "pushIncLooped"; ///< Push will increment the value. When the max is reached it will restart with min.
343 ///< The default one if not specified (with 2 states values it is a OnOff switch).
344 const CString kSwitchPushDecLoopedStyle = "pushDecLooped"; ///< Push will decrement the value. When the min is reached it will restart with max.
345 const CString kSwitchPushIncStyle = "pushInc"; ///< Increment after each press (delta depends of the curve).
346 const CString kSwitchPushDecStyle = "pushDec"; ///< Decrement after each press (delta depends of the curve).
347 const CString kSwitchLatchStyle = "latch"; ///< Each push-release will change the value between min and max.
348 ///< A timeout between push and release could be used to simulate a push style (if timeout is reached).
349 };
350
351 //------------------------------------------------------------------------
352 /** Attributes Flags defining a Layer in a VST XML Representation */
353 namespace AttributesFlags
354 {
355 const CString kHideableFlag = "hideable"; ///< the associated layer marked as hideable allows a remote to hide or make it not usable a parameter when the associated value is inactive
356 };
357
358 //------------------------------------------------------------------------
359 } // namespace Vst
360 } // namespace Steinberg
361
362 //------------------------------------------------------------------------
363 #include "pluginterfaces/base/falignpop.h"
364 //------------------------------------------------------------------------