VSXU - development is easier than you might think

[asterix]

I've recently been writing plugins for vsxu. I've never written c++ much in the past. So it came a suprise that I easily created several plugins in only a few days. I thought I'd write this article to give people a more plain english / noobs perspective on what is entailed.

I've been using VSXU's classy GUI for creating presets for many years now. I'd always wanted to write plugins but never managed to get a proper development environment in place.

JAW ran me through setting up an environment using freely available tools:

• notepad ++ (with a nice little directory browser plugin). I use this to edit / code my plugins.
• cmake - to create 'make' files that tells the compiler what to compile
• mingw32 - a compiler I run through windows powershell. It basically writes the .dll plugins that I can copy into a working version of vsxu's plugin directory
• GIT - kind of like svn. It allows you to upload and download from a shared online repository of vsxu. It keeps track of versions of each update so you can backtrack if you need to

There is a light tutorial on setting this up here although I'd like to rewrite it so that noobs like me can understand it too (I hate gits command line for example, but it has a very easy to use gui version). If you'd like assistance in the meantime, swing by the irc channel or forums at the vsxu website.

GETTING STARTED

Don't be scared off by the volume of code below, most of it is comments I've added to explain details. Writing your first plugin is really easy. Plugin C++ files and dll's are located in the vsxu/plugins/src/ folder

Open up the main.cpp file in each plugin directory and you'll notice that the files often contain multiple classes, each spitting out a different plugin. People familiar with object oriented programming will sift through this easily.

For your first plugin its best to choose a plugin type that is similar to what you want to achieve. For example if you want to output a mesh (like a cube or something more fancy) in your plugin, choose mesh.generators. It will generally have all the includes nested inside itself.


The class files are much like most object oriented class files. So if you're native to processing, web programming etc you should fit in quite nicely.

Defining Variables, Inputs and Outputs

This part is relatively easy. Declaring variables / inputs and outputs you'll use in your plugin

PHP Code:

class vsx_module_my_module_name : public vsx_module {
  // input variables - ready defines below for more explanation
  vsx_module_param_float* length;
  vsx_module_param_float3* scaling;
  // output variables
  vsx_module_param_mesh* result;
  // internal
  vsx_mesh mesh;
  vsx_vector scaling;
public: 


Information about your plugin that is shown in vsxu

PHP Code:

  void module_info(vsx_module_info* info)
  {
    info->identifier = "mesh;vertices;my_mesh_plugin_name";
   // a description that displays in the module browser
    info->description = "Generates a line with random offset\n"
    // tell vsxu to setup an output on the module
    info->out_param_spec = "mesh:mesh";
   // tell vsxu to setup an input on the module
    info->in_param_spec =
      "length:float,"
      "scaling:float3"
    ;
    info->component_class = "mesh";
  } 


Here we define the input / output / internal variables you'll use in your plugin. I've added some comments to explain some basic features.

PHP Code:

  void declare_params(vsx_module_param_list& in_parameters, vsx_module_param_list& out_parameters)
  {
    loading_done = true;
// set a float input labelled length! a float is a number with decimal places ie 2.45645 :)
    (vsx_module_param_float*)in_parameters.create(VSX_MODULE_PARAM_ID_FLOAT,"length");
    length->set(1.0f);

// float 3's handle like an array of 3 float variables. Handy for storing x,y,z into a single input / output.
    scaling = (vsx_module_param_float3*)in_parameters.create(VSX_MODULE_PARAM_ID_FLOAT3,"scaling");
    scaling->set(1,0); // x = 1
    scaling->set(1,1); // y = 1
    scaling->set(1,2); // z = 2
//outputs  
    result = (vsx_module_param_mesh*)out_parameters.create(VSX_MODULE_PARAM_ID_MESH,"mesh");
//outputs an empty mesh
    result->set_p(mesh);
  } 


MAKE IT DO SOMETHING INTERESTING

Finally, the run function which basically runs every frame. This is where your plugin does something useful. Processing users will be familiar with this concept.

PHP Code:

  void run()
  {
    // pull a float value from vsxu input
float someValue = length->get();
// you can set an output using set->() , but we only have a mesh to output so we won't do that here

// pull an x value in the float 3 array. Where x is the first float value stored in the float  3 array.
float xValue = scaling->get(0);

// draw a square by defining x,y,z co-ordinates for each point

/* This is a comment, just to show you the position of the vertices ( a corner of the square)
0 0
0 X
*/
    mesh.data->vertices[0] = vsx_vector( 0.5f,-0.5f, 0.0f);

/* In this case, the vertices is positioned at x=.5 , y= .5, z=0
0 X
0 0
*/
    mesh.data->vertices[1] = vsx_vector( 0.5f, 0.5f, 0.0f);

/* the f in the variable only signifies that it is a float value.
X 0
0 0
*/
    mesh.data->vertices[2] = vsx_vector( -0.5f, 0.5f, 0.0f);

/* You'll notice I'm drawing the square (referred to as a quad anti-clockwise. Open GL needs you to do this so it knows which way the square is facing.
0 0
X 0
*/
   mesh.data->vertices[3] = vsx_vector( -0.5f,-0.5f,0.0f);


// this is how you send your mesh to vsxus output on the module
    mesh.timestamp++;
    result->set_p(mesh);

  }
}; 


Its then just a matter of telling vsxu to create your module in the settings at the bottom of the page in define_module and destroy_module, as well as adding an extra number to get_num_modules .

Once you're done, compile your module, and copy the .dll file into the relevant plugin folder in vsxu artiste

[sleepytom]

Or you could write FFGL plugins which work in applications with a large number of users...

[asterix]

Sure you could. But I think alot of vj's haven't really looked into developing their own plugins for anything because the concepts aren't so clear, which is the aim of this post

[jaw]

FFGL can't push mesh data around and so on, so it's not as flexible for purely generative stuff.

Plus you can also define your own data types in VSXu if you need...

I think comparing VSXu and FFGL is kind of pointless, a better comparison would be vvvv or OpenFrameworks.

[vdmoKstaTi]

Originally Posted by sleepytom

Or you could write FFGL plugins which work in applications with a large number of users...

agreed. there is a good method by using OpenFrameworks to make FFGL plugins.

http://code.google.com/p/ofxffglplugin/

I found it to be pretty straightforward to use.. been playing with this since December 2010. Visual C++ Express 2008 is a good editor to use with this.


.........


but Pete, awesome job bro... look foward to see some of your new ninja tools in action

[bilderbuchi]

I tried the ofxffglplugin a couple weeks ago, my code compiled (using codeblocks, not msvc , though), but was not visible in any ffgl host. gave up after dicking around for a week...

[sleepytom]

I'm not sure that codeblocks is supported - i've used both MSVC and Xcode to make plugins which work.

I do find it irritating trying to use MSVC - most of the OF developers seem to use codeblocks but nobody has made the ofFFGL codeblocks package. I got stuck trying to combine 2 OF plugins in MSVC - it was really easy in Xcode...

[bilderbuchi]

It's not supported inasmuch as there's no C::B files in the packaged version. That's just a bundle of settings and file paths for a certain IDE, though, so if there were a way to get all the meaningful settings out of an MSVC file in a non-painful way, or alternatively know all the stuff one has to adjust from a default/empty oF/C::B project file, one could create a project file.
I have neither, so I asked Resolume for advice since they are the originators of the project, and got an answer from Joris to the effect that 'that was done for the love, on the side, and so we can't support it since we have no time'. Never gotten around to asking Daniel if he would do it in his sparetime, which was what Joris recommended to do. I figured that by that time you'd already have made your blanking plugin yourself, and I had other stuff in the queue. :-P