vvvv plugin interface

while in theory vvvv plugins can be written in many languages the following introduction only goes into detail with c#. from here on straight forward, step by step. this guide will lead you to your first working simple plugin from where you can easily go on coding your ideas.

• vvvv plugin interface
  • Choice of IDE - a development environment
  • Subversion - source code repository
  • Working Directories
  • PluginInterfaces
  • Utils
  • PluginTemplate
  • GUIPluginTemplate
  • The Hoster
  • Debugging and Tools
  • Writing Code
  • Versioning Plugins
  • Sharing your code
  • Cross Platform

Choice of IDE - a development environment

actually any IDE that can do .net 2.0 should do. you can even develop on linux using MonoDevelop compile over there and drop the same .dll onto vvvv, if you like it awkward. this article is referring to the the very comfortable, slim and free SharpDevelop IDE. Please note that so far only Visual Studio reliably allows debugging tasks such as setting breakpoints in your plugin code that actually break at runtime (see more below).

Subversion - source code repository

all code relevant to creating vvvv plugins is available from a public subversion repository on sourceforge. while you may use any subversion client to access the code this documentation refers to the use of the TortoiseSVN client.

If you are not familiar with the practice of Version Control, please read a short introduction to Version Control with Subversion before continuing, as you else may miss some concepts/terms we'll be referring to below.

Working Directories

do not make a complete svn-checkout of the
https://vvvv.svn.sourceforge.net/svnroot/vvvv/plugins/c#
directory as it will result in a wrong directory structure on your disk and relative links in solution files will be broken.

instead do yourself a favour and do all working on vvvv plugins in a good place on your disk. for a start it is recommended to create the following directory structure:
\vvvvplugins\_Hoster
\vvvvplugins\_PluginInterfaces
\vvvvplugins\_Utils
\vvvvplugins\_Samples\_PluginGUITemplate
\vvvvplugins\_Samples\_PluginTemplate
note that the naming of the \vvvvplugins directory is not important. only the subdirectories should be named exactly as mentioned since the sources come with project files that reference those directories relatively.

PluginInterfaces

vvvvs plugin system is essentially a COM-interface. therefore all you have to provide is a .dll file that implements a number of interfaces. these are collected in a file called PluginInterfaces.cs and can be checked out from the repository via the following link:

with TortoiseSVN installed just rightclick your _PluginInterfaces directory and click SVN Checkout enter the above url and press OK.

Utils

the utilities are a collection of math, color,.. functions that will make your coding easier. the .net framework already provides a lot of useful stuff. what we didn't find in there we stuffed into our utils. don't hesitate to let us know what you think we are still missing in there. here is the url to checkout the code from the repository:

PluginTemplate

now it is best to start from a simple sample that already compiles to a working .dll as is. rightclick your _PluginTemplate directory and checkout the following url:


in sharpdevelop open the PluginTemplate.sln solution and compile (F9). now you should have the PluginTemplate.dll in
\vvvvplugins\_Samples\_PluginTemplate\bin

you can see what it does by dragdropping the file onto a vvvv patch. but instead of working on the template you should now rather make a copy of the \_PluginTemplate directory and rename it. don't forget to delete the hidden \.svn directory inside the directory you just copied. this is from subversion and after the copy is no longer valid. just remove it, you'll get a new one should you decide to upload your code to the repository.

GUIPluginTemplate

if you want to create a plugin that has its own gui, then you may want to start from the GUI Template instead.

The Hoster

to simplify the process of creating and testing plugins (especially ones with a GUI) we have one more tool. the hoster allows you to testdrive plugins without the need of vvvv and do at least basic debugging of input and output values. checkout:

into your \_Hoster directory.

add your plugins project to the hosters solution. also don't forget to add a reference to your plugin. running the solution should now open the hoster with a list of available plugins. clicking a plugin will instantiate it and show inputs and outputs.

the hoster also lets you set all input pins via OSC and also sends sends the data of all outputs via OSC!

Debugging and Tools

There is an article on how to Debug vvvv plugins using visual studio 2005.
In theory the latest SharpDevelop (3.1) supports the same debugging features, but has problems automatically starting vvvv from the debugger, and also seems to ignore breakpoints in some plugins.
You can find some useful tools here (especially reflector i.e one is included with #develop but seems buggy) and here for debugging.

Writing Code

this is where your job begins.

the VVVVPluginInterface Specification is a browsable code documentation that tells you all about the interfaces offered by vvvv and available utility functions.

Browse
to find additional samples illustrating more advanced topics and functions of the PluginInterfaces including Enum and Node pin types, threading, and many others.

questions about writing plugins go into the dedicated plugins forum.

In order to create a consistent codebase among vvvv plugins we'd also like to ask you to conform to our Conventions.CodingStyle. when choosing a name for your nodes and pins make sure you read the Conventions.NodeAndPinNaming.

Versioning Plugins

still to come..we should develop a strategy of versioning plugins.

Sharing your code

we'd like to encourage you to not only share your plugins but also their sources and host them alongside other vvvv plugins on sourceforge. this way other people can learn from your work or help you improve it. sharing your sources requires you to chose an opensource license. all opensource provided by vvvv.org uses the LGPL which in short means that our plugins maybe used in binary form in any commercial application, but changing/improving their source code in any way requires the changes to be commited back to the community. therefore plugins under the LPGL can be shipped with vvvv. if you don't want to see your plugins shipped with vvvv it is of course up to you to choose a license prohibiting this.

if you need developer access to sourceforge/vvvv don't hesitate to contact iorec on vvvvs IRC channel.

Cross Platform

to whom it may concern: note that plugins you code this way are most likely running in hoster on other platforms like linux and osx too. this could come handy if you're developing something similar to TimelinerSA which is essentially the Timeliner plugin running in hoster.