DSPRelated.com
Free Books

Generating the PD Plugin

The plugin may be compiled as follows:

  > faust -a puredata.cpp -o cpgrui-pd.cpp cpgrui.dsp
  > g++ -DPD -Wall -g -shared -Dmydsp=cpgrui \
        -o cpgrui~.pd_linux  cpgrui-pd.cpp
The first line uses faust to generate a compilable .cpp file, this time using the architecture file puredata.cpp which encapsulates the pd plugin API. The second line (which wraps) compiles cpgrui-pd.cpp to produce the dynamically loadable (binary) object file cpgrui~.pd_linux, which is our signal-processing plugin for pd. Such pd plugins are also called externals (externally compiled loadable modules). The filename extension ``.pd_linux'' indicates that the plugin was compiled on a Linux system.

Figure K.8 shows an example test patch,K.9 named cpgrui~-help.pd,K.10written (manually) for the generated plugin. By convention, the left inlet and outlet of a Faust-generated plugin correspond to control info and general-purpose messages. Any remaining inlets and outlets are signals.

Figure: Pure Data test patch cpgrui~-help.pd exercising features of the external pd plugin cpgrui~ generated by Faust using the puredata.cpp architecture file.
\includegraphics[width=3in]{eps/cpgruit-help}

A simple ``bang'' message to the control-inlet of the plugin (sent by clicking on the ``button'' drawn as a circle-within-square in Fig.K.8), results in a list being sent to the control (left) outlet describing all plugin controls and their current state. The print object in Fig.K.8 prints the received list in the main pd console window. For our example, we obtain the following bang-response in the pd console:

  print: nentry /faust/bandwidth-Hz 100 100 20 20000 10
  print: nentry /faust/frequency-Hz 1000 1000 20 20000 1
  print: hslider /faust/peak-gain 1 1 0 10 0.01
These are the three controls we expected corresponding to the frequency, bandwidth, and gain of the resonator. However, note that the message-names generated for the controls have changed. In particular, spaces have been replaced by hyphens, and parentheses have been removed, to observe pd naming rules for messages [31].

Controls may be queried or set to new values in the plugin by sending the following pd messages:

  • frequency-Hz [newval]
  • bandwidth-Hz [newval]
  • peak-gain [newval]
The longer form of the control name printed in the pd console, e.g.,
/faust/peak-gain, is the complete ``fully qualified path'' that can be used to address controls within a hierarchy of nested controls and abstractions. For example, if we were to add the instance argument ``foo'' to the plugin (by changing the contents of the plugin box to ``cpgrui~ foo'' in Fig.K.8), then the path to the peak-gain control, for example, would become /foo/faust/peak-gain (see [31] and the Faust documentation for more details and examples).

In the test-patch of Fig.K.8, the various controls are exercised using pd message boxes. For example, the message ``peak-gain'' with no argument causes the plugin to print the current value of the peak-gain parameter on its control outlet. Messages with arguments, such as ``peak-gain 0.01'', set the parameter to the argument value without generating an output message. The slider and number-box output raw numbers, so they must be routed through a message-box in order to prepend the controller name (``peak-gain'' in this case).

The plugin input signal (second inlet) comes from a noise~ object in Fig.K.8, and the output signal (second outlet) is routed to both channels of the D/A converter (for center panning).

In addition to the requested controls, all plugins generated using the puredata.cpp architecture file respond to the boolean ``active'' message, which, when given a ``false'' argument such as 0, tells the plugin to bypass itself. This too is illustrated in Fig.K.8. Note that setting active to ``true'' at load time using a loadbangK.11 message is not necessary; the plugin defaults to the active state when loaded and initialized--no active message is needed. The loadbang in this patch also turns on pd audio computation for convenience.


Next Section:
Generating a PD Plugin-Wrapper Abstraction
Previous Section:
Matlab diary: tmps.d