diff options
Diffstat (limited to 'doc/html/vstparamstruct.html')
| -rw-r--r-- | doc/html/vstparamstruct.html | 566 |
1 files changed, 566 insertions, 0 deletions
diff --git a/doc/html/vstparamstruct.html b/doc/html/vstparamstruct.html new file mode 100644 index 0000000..eb0630a --- /dev/null +++ b/doc/html/vstparamstruct.html @@ -0,0 +1,566 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> +<title>VST SDK 2.4: VST Parameters Structure</title> +<link href="doxygen.css" rel="stylesheet" type="text/css"> +<link href="tabs.css" rel="stylesheet" type="text/css"> +</head><body> +<!-- Generated by Doxygen 1.4.7 --> +<div class="tabs"> + <ul> + <li><a href="main.html"><span>Main Page</span></a></li> + <li><a href="namespaces.html"><span>Namespaces</span></a></li> + <li><a href="annotated.html"><span>Classes</span></a></li> + <li><a href="files.html"><span>Files</span></a></li> + <li><a href="dirs.html"><span>Directories</span></a></li> + <li><a href="pages.html"><span>Related Pages</span></a></li> + </ul></div> +<h1><a class="anchor" name="vstparamstruct">VST Parameters Structure</a></h1><h2>Introduction</h2> + +<p> +In general, VST Plug-Ins present a flat, unsorted list of parameters to the host application, and finally to the user. +The VST Parameters Structure XML definition provides an easy way to structure parameters of existing VST Plug-Ins hierarchically, without having to recompile the Plug-In binary. +</p> + +<p> +<u>Windows</u>:<br> +<br> +The host application searches for a <b>.vstxml</b> file next to the Plug-In DLL (e.g. if your Plug-In is in '...\Vstplugins\MyEffect.dll' the corresponding XML file must be named '...\Vstplugins\MyEffect.vstxml'). +Alternatively, the Parameter Structure XML can be embedded in the DLL as a resource (resource type <b>VSTXML</b>, resource identifier <b>1</b>). +Please note that an external .vstxml file always overrides the embedded resource! +</p> + +<p> +<u>Mac OS X</u>:<br> +<br> +The .vstxml file is in the Resources Folder of the bundle and its name is constructed from the CFBundleName. +</p> + +<p class="subhead">Example:</p> + +<table cellpadding="0" cellspacing="0" border="1"> +<tr> + <td class="md"> +<pre> +<<b>VSTPluginProperties</b>> + <<b>VSTParametersStructure</b>> + <font color=#989898><!-- Value Types: --></font> + <<a href="#ValueType">ValueType</a> name="<font color=#980000>SwitchOnOff</font>"> + <<a href="#Entry">Entry</a> name="Off" value="[0, 0.5["/> + <<a href="#Entry">Entry</a> name="On" value="[0.5, 1]"/> + </ValueType> + + <font color=#989898><!-- Templates: --></font> + <<a href="#Template">Template</a> name="<font color=#0000FF>Channel</font>"> + <<a href="#Param">Param</a> name="Bypass" shortName="Byp." type="<font color=#980000>SwitchOnOff</font>" id="<font color=#009800>offset</font>+1"/> + ... + </Template> + + <font color=#989898><!-- Global: --></font> + <<a href="#Param">Param</a> name="Volume" shortName="Vol." label="dB" id="0"/> + + <<a href="#Group">Group</a> name="Channel 1" template="<font color=#0000FF>Channel</font>" values="<font color=#009800>offset</font>=10"/> + <<a href="#Group">Group</a> name="Channel 2" template="<font color=#0000FF>Channel</font>" values="<font color=#009800>offset</font>=20"/> + ... + </<b>VSTParametersStructure</b>> +</<b>VSTPluginProperties</b>></pre> + </td> +</tr> +</table> + +<p> +The following tags are used to describe a parameter structure: +</p> + +<p> +<table border=0> + <tr> + <td width=150>VSTPluginProperties</td> + <td>optional root tag</td> + </tr> + <tr> + <td width=150>VSTParametersStructure</td> + <td>parameters structure tag</td> + </tr> + <tr> + <td><a href="#Param">Param</a></td> + <td>describes a single parameter with name, label, id etc.</td> + </tr> + <tr> + <td><a href="#Group">Group</a></td> + <td>encloses a group of parameters, can be nested</td> + </tr> + <tr> + <td><a href="#Template">Template</a></td> + <td>defines a parameter group, can be "instanciated" multiple times</td> + </tr> + <tr> + <td><a href="#ValueType">ValueType</a></td> + <td>definition of an internal value type, contains a list of <a href="#Entry">Entry</a> tags</td> + </tr> + <tr> + <td><a href="#Entry">Entry</a></td> + <td>describes a single state of a <a href="#ValueType">ValueType</a></td> + </tr> +</table> +</p> + +<p class="subhead">Advanced topics:</p> + +<ul> + <li><a href="#RelativeAddressing">Relative Parameter Addressing</a> + <li><a href="#Examples">Example</a> +</ul> + + +<hr noshade size="4"> + +<h2>XML Definitions Reference</h2> + +<a name="Param"></a> +<h2>Param</h2> + +<table cellpadding="0" cellspacing="0" border="0"> +<tr> + <td class="md"> + <div class="xmltag"> + <<span class="tagname">Param</span> <span class="mandatory">id</span>="..." name="..." + label="..." shortName="..." type="..." numberOfStates="..." defaultValue="..."/> + </div> + </td> +</tr> +</table> + +<p> +Describes a Plug-In parameter. +</p> + +<p class="subhead">Attributes:</p> + +<p> +<table border=0 cellspacing=6> + <tr> + <td width=150 valign=top> + id + </td> + <td> + corresponds to zero-based index in flat parameter list.<br> + can either be an integer constant (e.g. "100") or an expression which evaluates + to an integer (e.g. "offset + 1"). + See <a href="#RelativeAddressing">Relative Parameter Addressing</a> for details. + </td> + </tr> + <tr> + <td valign=top> + name + </td> + <td> + parameter name visible to the user (e.g. "Volume"). + </td> + </tr> + <tr> + <td valign=top> + label + </td> + <td> + parameter label visible in generic editor or on remote control (e.g. "dB") + </td> + </tr> + <tr> + <td valign=top> + shortName + </td> + <td> + short parameter name, displayed on remote controls.<br> + can be a list of several names of different lengths, separated by colons + (e.g. "OSC Frequ., OSCFrq., Frq"). The host application selects best fitting string + for current remote displays. + </td> + </tr> + <tr> + <td valign=top> + type + </td> + <td> + user defined (see <a href="#ValueType">ValueType</a>) + or predefined value type. Default type is a linear fader between 0.0 and 1.0<br> + <br> + <u>Predefined types</u>:<br> + - switch : parameter toggles between 0 and 1 + </td> + </tr> + <tr> + <td valign=top> + numberOfStates + </td> + <td> + defines how many states this parameter can have:<br> + <br> + <small> + state N = [N / numberOfStates, (N + 1) / numberOfStates[<br> + state N = (long)(value * numberOfStates) + </small> + </td> + </tr> + <tr> + <td valign=top> + defaultValue + </td> + <td> + default value normalized between [0.0, 1.0] + </td> + </tr> +</table> +</p> + +<p class="subhead">Remarks:</p> + +<p> +Most VST Plug-Ins already provide parameter attributes like name, label, etc. and support string conversion. +The XML description always <u>overwrites</u> Plug-In -provided attributes! +Everything not described in XML is taken from the Plug-In at runtime. +</p> + +<hr noshade size="4"> + +<a name="Group"></a> +<h3>Group</h3> + +<table cellpadding="0" cellspacing="0" border="0"> +<tr> + <td class="md"> + <div class="xmltag"> + <<span class="tagname">Group</span> <span class="mandatory">name</span>="..." template="..." values="..."/> + </div> + </td> +</tr> +</table> + +<p> +Groups are used to create hierarchical parameter structures. A <Group> either contains <<a href="#Param">Param</a>> tags directly, +or is defined by a <a href="#Template">Template</a>. +</p> + +<p class="subhead">Attributes:</p> + +<p> +<table border=0 cellspacing=6> + <tr> + <td width=150 valign=top> + name + </td> + <td> + group name visible to the user (e.g. "Channel 1", "LFO Section",...) + </td> + </tr> + <tr> + <td valign=top> + template + </td> + <td> + Name of <a href="#Template">template</a> defining this group (optional). + </td> + </tr> + <tr> + <td valign=top> + values + </td> + <td> + List of arguments passed to the template + (see <a href="#RelativeAddressing">Relative Parameter Addressing</a> for details).<br> + <br> + Each arguments consists of a name and an integer value (e.g. "offset=100"). + Multiple arguments are separated by semicolons, whitespaces are ignored + (e.g. "offset1=100; offset2=100"). + </td> + </tr> +</table> +</p> + +<hr noshade size="4"> + +<a name="Template"></a> +<h3>Template</h3> + +<table cellpadding="0" cellspacing="0" border="0"> +<tr> + <td class="md"> + <div class="xmltag"> + <<span class="tagname">Template</span> <span class="mandatory">name</span>="..."/> + </div> + </td> +</tr> +</table> + +<p> +Assume a Plug-In with 16 channels, each consisting of an identical set of parameters. You only have to +describe a channel once as a template and create 16 "instances" using the <Group> tag. +If each channel contains let's say 20 parameters, which appear continuously in the flat parameter list, +they can be addressed using an offset value instead of absolute indices +(see <a href="#RelativeAddressing">Relative Parameter Addressing</a> for details). +</p> + +<p class="subhead">Attributes:</p> + +<p> +<table border=0 cellspacing=6> + <tr> + <td width=150 valign=top> + name + </td> + <td> + internal template name, referred to by <a href="#Group">groups</a>. + </td> + </tr> +</table> +</p> + +<hr noshade size="4"> + +<a name="ValueType"></a> +<h3>ValueType</h3> + +<table cellpadding="0" cellspacing="0" border="0"> +<tr> + <td class="md"> + <div class="xmltag"> + <<span class="tagname">ValueType</span> <span class="mandatory">name</span>="..." label="..."/> + </div> + </td> +</tr> +</table> + +<p> +Defines an internal value type by a list of <<a href="#Entry">Entry</a>> tags. +</p> + +<p class="subhead">Attributes:</p> + +<p> +<table border=0 cellspacing=6> + <tr> + <td width=150 valign=top> + name + </td> + <td> + internal value type name, referred to by <a href="#Param">parameters</a>. + </td> + </tr> + <tr> + <td valign=top> + label + </td> + <td> + value label (e.g. "dB") + </td> + </tr> +</table> +</p> + +<p class="subhead">Remarks:</p> + +<p> +The <i>label</i> attribute is used as parameter label if the <i>label</i> field of a <<a href="#Param">Param</a>> +tag using this value type is empty. +</p> + +<hr noshade size="4"> + +<a name="Entry"></a> +<h3>Entry</h3> + +<table cellpadding="0" cellspacing="0" border="0"> +<tr> + <td class="md"> + <div class="xmltag"> + <<span class="tagname">Entry</span> <span class="mandatory">name</span>="..." value="..."/> + </div> + </td> +</tr> +</table> + +<p> +Each entry in a <<a href="#ValueType">ValueType</a>> list provides a string representation for +a certain parameter state. A simple example would be a toggle parameter with two +states named "On" and "Off". The string "Off" should be displayed if the normalized parameter value is between +0.0 and 0.5 (exclusively), and "On" if it is >= 0.5 and <= 1.0. +</p> + +<p class="subhead">Attributes:</p> + +<p> +<table border=0 cellspacing=6> + <tr> + <td width=150 valign=top> + name + </td> + <td> + name of parameter state, displayed to the user (e.g. "On", "Off", "Sine", "Square",...) + </td> + </tr> + <tr> + <td valign=top> + value + </td> + <td> + optional: describes the parameter range this state corresponds to, + using the mathematical range definition [a, b].<br> + <br> + Exclusive range:<br> + e.g. "[0.0,0.5[" -> if value >= 0.0 and < 0.5<br> + <br> + Inclusive range:<br> + e.g. "[0.5,1.0]" -> if value >= 0.5 and <= 1.0 + </td> + </tr> +</table> +</p> + +<p class="subhead">Remarks:</p> + +<p> +The value range is optional. If not specified, the limits of a state are calculated based on the total number of entries +in the value type:<br> +<br> +a = index / total<br> +b = (index + 1) / total;<br> +</p> + +<hr noshade size="4"> + +<a name="RelativeAddressing"></a> +<h2>Relative Parameter Addressing</h2> + +<p> +Relative parameter addressing is used to describe parameter IDs inside <a href="#Template">templates</a>. +Instead of assigning a parameter index directly, an expression - mostly consisting of a "base address" variable and +a constant offset value - can be used. The variable is passed to the template each time it is "instanciated" as a +<a href="#Group">group</a>. +</p> + +<p class="subhead">Example:</p> + +<p> +<table border=0> +<tr> + <td valign=top> + <div align=center>Parameter list:</div> + + <pre> +... + +11: Volume CH1 +... + +21: Volume CH2 +... + +31: Volume CH3 +... + </pre> + </td> + <td valign=top> + <div align=center>XML code:</div><br> + + <table cellpadding="0" cellspacing="0" border="1"> + <tr> + <td class="md"> +<pre> +<<b>Template</b> name="Channel"> + <<b>Param</b> name="Volume" id="<font color=#009800>offset</font>+1"/> +</<b>Template</b>> + +<<b>Group</b> name="CH 1" template="Channel" values="<font color=#009800>offset</font>=10"/> +<<b>Group</b> name="CH 2" template="Channel" values="<font color=#009800>offset</font>=20"/> +<<b>Group</b> name="CH 3" template="Channel" values="<font color=#009800>offset</font>=30"/> +</pre> + </td> + </tr> + </table> + + + </td> +</tr> +</table> +</p> + +<hr noshade size="4"> + +<a name="Examples"></a> +<h2>Example</h2> + +<table cellpadding="0" cellspacing="0" border="1"> +<tr> + <td class="md"> +<pre> +<!-- =========================================================== --> +<!-- XML definition of VST parameters for Dynamics Plug-In====== --> +<!-- Draft 0.1================================================== --> +<!-- Date: 14.11.2005=========================================== --> +<!-- =========================================================== --> + +<VSTPluginProperties> + + <VSTParametersStructure> + <!-- Create Global Params================================== --> + <Param name="Routing" shortName="Rout" id="13"/> + + <!-- Create AutoGate Group================================= --> + <Group name="AutoGate"> + <Param name="On" type="<font color=#009800>switch</font>" id="0"/> + <Param name="Thresh" shortName="ThrHo" label="dB" id="3"/> + <Param name="Attack" shortName="Att" label="ms" id="4"/> + <Param name="Hold" label="ms" id="5"/> + <Param name="Release" shortName="Rel" label="ms" id="6"/> + <Param name="Auto" id="7"/> + <Param name="Mode" id="9"/> + <Param name="Calib" id="10"/> + <Param name="LowFreq" shortName="LoFrq" label="Hz" id="11"/> + <Param name="HighFreq" shortName="HiFrq" label="Hz" id="12"/> + </Group> + + <!-- Create Compressor Group======================================= --> + <Group name="Compressor"> + <Param name="On" type="<font color=#009800>switch</font>" id="1"/> + <Param name="Thresh" shortName="ThrHo" label="dB" id="14"/> + <Param name="Ratio" id="15"/> + <Param name="Attack" shortName="Att" label="ms" id="16"/> + <Param name="Release" shortName="Rel" label="ms" id="17"/> + <Param name="MakeUp" shortName="MkUp" label="dB" id="18"/> + <Param name="Auto" id="19"/> + <Param name="RMS" id="20"/> + </Group> + + <!-- Create Limiter Group======================================= --> + <Group name="Limiter"> + <Param name="On" type="<font color=#009800>switch</font>" id="2"/> + <Param name="Thresh" shortName="ThrHo" label="dB" id="21"/> + <Param name="Release" shortName="Rel" label="ms" id="22"/> + <Param name="Auto" id="23"/> + </Group> + + </VSTParametersStructure> +</VSTPluginProperties> + +</pre> + </td> +</tr> +</table> + <html> + +<head> + <title>Empty</title> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="Author" content="mario"> +</head> + +<body> + +<br/> +<hr width="100%" size="2" align="left" /> +<div align=left> +Copyright ©2006 <a href="http://www.steinberg.net" target="_blank"><u>Steinberg Media Technologies</u></a>. +All Rights Reserved. +</div> +</body> + +</html> |