PdVst: VST - Pd Bridging Plugin
-------------------------------

v0.0.2


-How PdVst Works-

PdVst consists of two main parts, a VST plugin and a custom version of Pd.
When a PdVst plugin is opened by the host application, a setup file is read to
determine information about the plugin, such as the Pd patch file to use, the 
number of parameters, etc., and the custom version of Pd is started and opens
the Pd patch file whose name was found in the setup file. 


-Installation-

1) Copy the pdvst folder to the directory that contains the 
   application (e.g. Cubase.exe) that you want to use PdVst with
   (e.g. c:\Program Files\Steinberg\Cubase VST\)
2) Copy your .pdv, .pd, and any dependant Pd external .dll library files to the 
   pdvst directory.
3) Copy your plugin .dll file (e.g. Pd_Gain.dll) to the vst plugins directory
   for the application (e.g. c:\Program Files\Steinberg\Cubase VST\VstPlugins\)


-Creating VST Plugins from Pd Patches-

1) Create a new .pdv setup file (see -The .pdv Setup File- section). The file
   must be named the same as the plugin (e.g. for a plugin named Pd_Gain you
   would create a file named Pd_Gain.pdv). Place this file and all dependant
   files (.pd files, external Pd library .dll files, etc.) in the pdvst 
   directory of the application you wish to use the plguin with.
2) Make a copy of the pdvst-template.dll file and rename the same as the plugin
   and .pdv file (e.g. for a plugin named Pd_Gain you would copy 
   pdvst-template.dll to a new file named Pd_Gain.dll). Move your new plugin 
   .dll file to the vst plugins folder of the application.
   
   
-The .pdv Setup File-

This file contains all of the information about your plugin. The format is ASCII  
text with keys and values separated by an '=' character and each key and value 
pair separated by a carriage return. Comments are demarked with a '#' charcater.
For an example, see Pd_Gain.pdv and Pd_Synth.pdv. 

  -Keys-

    CHANNELS = <integer>
    Number of audio input and output channels. For now, 2 is probably safe. 

    MAIN = <string>
    The .pd file for Pd to open when the plugin is opened. 

    ID = <string[4]>
    The 4-character unique ID for the VST plugin. This is required by VST and 
    just needs to be a unique string of four characters. 

    SYNTH = <TRUE/FALSE>
    Boolean value stating whether this plugin is an instrument (VSTi) or an effect. 
    
    CUSTOMGUI = <TRUE/FALSE>
    Boolean value stating whether the Pd patch uses a custom GUI (e.g. GrIPD) 

    DEBUG = <TRUE/FALSE>
    Boolean value stating whether to display the Pd GUI when the plugin is opened. 

    LIB = <string>
    External libraries (without file extension) separated by commas. Paths are relative 
    to the pdvst directory. 

    PARAMETERS = <integer>
    Number of parameters the plugin uses (up to 128). 

    NAMEPARAMETER<integer> = <string>
    Display name for parameters. Used when CUSTOMGUI is false or the VST host doesn't 
    support custom editors. 

    PROGRAM = <string>
    Declares a new VST program and sets the name (up to 128 programs can be declared) 

    PARAMETER<integer> = <float>
    Defines the parameter values for the last declare program. <float> must be 
    between 0 and 1 inclusive. 


-Pd/VST Communication-

When the plugin is opened, the .pd patch file declared in the .pdv setup file's MAIN key 
will be opend. For VST effects, the Pd patch will receive its incoming audio stream from 
the adc~ object. For VST instruments (VSTi), the patch will receive incoming MIDI data 
from the Pd objects notein, ctlin, and pgmin. Pd patches should output their audio stream 
to the dac~ object. 

For purposes such as GUI interaction and VST automation, your patch may need to communicate 
further with the VST host. Three special Pd send/recieve symbols can be used in your Pd patch. 
For an example, see the pd-gain.pd file.


  rvstparameter<integer>
  Use this symbol to receive parameter values from the VST host. Values will be floats 
  between 0 and 1 inclusive. 

  svstparameter<integer>
  Use this symbol to send parameter values to the VST host. Values should be floats 
  between 0 and 1 inclusive. 

  rvstopengui
  Use this symbol to receive notification the patch's GUI should be opened or closed. 
  The value will be either 1 or 0. 


Note: for most VST hosts, parameters for VST instruments are recorded as sysex data, so be 
sure to disable any MIDI message filtering in the VST host. 
