Realizer plugin SDK

Introduction

Realizer plugins are bundled libraries extending the functionality of the application in the form of a module. Modules can input and/or output audio, video and abstract signals, furthermore there are no restrictions to what a module can do. Thanks to the plugin SDK developing a plugin is quite easy and numerous examples are provided in the "plugin" directory of the source code.

Short note on how it works

plugindef.xml

The plugin bundle contains a file named "plugindef.xml" in which the plugin its inputs, outputs and attributes are defined. The host will allocate buffers for image and audio signals and make inputs and outputs based upon the definitions in that file.

virtual functions

Any plugin should be derived from RealizerPlugin. All you have to do is override the right combination of methods so the host application can call the plugin

• If your plugin does need to input and/or output image signals, override RealizerPlugin::Paint
• If your plugin does need to input and/or output audio signals, override RealizerPlugin::ProcessAudio
• If your plugin does need to input abstract data, override RealizerPlugin::FreshInputData
• If your plugin owns attributes, over RealizerPlugin::onSetAttribute
• If your plugin needs notification on notifiable host events, override RealizerPlugin::notify
• If your needs to be called at a fixed clock rate, override RealizerPlugin::Intr

Of course you can also make a plugin that inputs audio and outputs video (for example an Oscilloscope)

host functions

A set of functions of the Host which the plugin can call. Generally the Host functions provide services to the plugin, such as:

• getting access to the abstract inputs and outputs (example Host::findOutputByName)
• getting information about configuration (example Host::requestHostInfo )
• subscribing the plugin to the interrupt ( Host::requestInterrupt )
• creating data structures ( Host::createImage )

Hands on

Probably the easiest way to get started is by just making a plugin. This section explains a sort of general approach on doing this in a few steps. You need to have XCode installed.

step1 : make the project

In "pluginSDK" directory you will find an application named "newPlugin.app". This will create an XCode project and the required source files. Of course you can also do this by hand. Click the "newPlugin.app" , fill in a name for your plugin, and a project should be opened automatically.

step2 : test your plugin

Build the plugin in XCode and locate the product "yourplugin".bundle in the build directory of your newly created plugin folder.
Copy the plugin into the "PlugIns" folder located in the Realizer.app bundle. Test the plugin in a patch.

step3 : adapt the plugin

Now you know the "system" works in general you can adapt the plugin to make it the plugin you really want. Generally spoken the following things should be done.

• adapt plugindef.xml :
  Define only the inputs, outputs and attributes your plugin needs. As a naming convention we tend to always name image inputs "image in", audio input "audio in" ... abstract inputs and outputs may need a more revealing name then just "value in" , "value out" .

• get pointers to the abstract inputs and outputs :
  Assuming that your plugin owns abstract inputs and outputs, you need to get pointers to those using Host::findInputByName and Host::findOutputByName. N.B. Your plugin doesn't need to have pointers to "image" and "audio" in- and outputs. The process functions RealizerPlugin::Paint and RealizerPlugin::ProcessAudio will provide the plugin with the appropriate input and output buffers.

• implement only the functions your plugin needs :
  Assuming that you're adapting the default generated plugin, you should remove the functionality that your plugin doesn't use. I.E. when your plugin doesn't in -or output audio remove the RealizerPlugin::ProcessAudio function in both header and source file

Numerous examples of plugins can be found in the "plugin" directory of the source code.

---