Published on May 26, 2020

Watch the video above for a walkthrough, or read below if that fits your learning style!

To get the most out of this tutorial, you'll want some familiarity with OpenGL and C++. You don't need to be an expert, but you'll want to have some basic familiarity with concepts like vertex shaders, fragment shaders, and texture mapping.

If you're looking for online resources, I recommend The Book of Shaders. However, if you really want a good foundation, I highly recommend this book, Computer Graphics Programming in OpenGL with C++. This has helped me with basically everything I do with computer graphics even if I'm not directly using either OpenGL or C++.

You'll also need Git and Visual Studio installed.

Step 1. Running the Examples

Resolume's FFGL repository

Check out the repo above and open up the included solution file at build/windows/FFGLPlugins.sln

Once it's imported, you can see the folders here for the different types of plugins you can create. sources are also known as generators - they take no texture input and create an output just from the code you write. effects have one input texture, and mixers have two or more input textures.
I'm going to focus on effects since that should give you an idea of how to use textures and variables controlled by Resolume.

Next, let's export one of the example plugins just to make sure we can do this process from start to finish.  Let's take the effect AddSubtract and go ahead and build it (by right-clicking the project file and clicking Build).

Open Resolume 7. Go to Preferences->Video and make sure that Resolume's looking in the right folder for your FFGL plugin.

Step 2. Duplicate the Project Files

You can follow the steps here: Create your first plugin

If you have Git Bash installed or some other bash-like command prompt, try running this function from the FFGL repository directory (subbing "Vignette" for the name of your plugin):

# first parameter is the effect filename to use. CamelCase, no spaces
create_effect () {
  cp build/windows/AddSubtract.vcxproj build/windows/$1.vcxproj
  sed -i "/ProjectGuid/d" build/windows/$1.vcxproj
  sed -i "s/AddSubtract/$1/g" build/windows/$1.vcxproj

  cp -r source/plugins/AddSubtract source/plugins/$1
  cd source/plugins/$1
  mv AddSubtract.cpp $1.cpp
  mv AddSubtract.h $1.h
  sed -i "s/AddSubtract/$1/g" $1.cpp
  sed -i "s/AddSubtract/$1/g" $1.h
  cd ../../..

create_effect "Vignette"

Step 3. Add a Float Parameter

Let's go into the constructor here and we'll replace the RGB sliders with a simple float parameter. It ranges from 0 to 1, very straightforward. To do that, just add a parameter like this:
AddParam( ffglqs::Param::Create( "Sensitivity" ) );
You can namespace ffglqs if you prefer.

That is actually all you have to do to get the parameter set up. The function SendParams is going to take care of setting uniform variables and all the stuff you'd expect to do to get your shaders and your variables connected.

Make sure SetMinInputs and SetMaxInputs reflect the number of inputs you're using.

Step 4. Developing Your Shader

One way you can start writing your effects is to just come into this frag shader code and start making edits. This will work fine if you can write perfect code, but if you make mistakes, you'll find that this part is a huge headache. Say you make a typo (like, missing a semicolon) and go to build your shader. It will build just fine, and then it loads in Resolume, but nothing happens and you don't get any error messages.

For editing shaders, I like to use VS Code with a few shader plugins. First, there's glsl-snippets, which gives you autocompletion and function descriptions - SUPER helpful.
The other plugin I use is GLSL Linter - the alternate GLSL Lint works fine too. Make sure you read the installation instructions - basically what you do is you need to install the shader validator - so you go to this github page, go to releases and grab the appropriate package. Unzip it. In VSCode, after you have this installed, open user settings and make sure your GLSLang Validator path is filled in.

Give your file a .frag extension - this lets the validator know that you're writing a fragment shader (assuming that's what you're using).

Sidenote: Shadertory

If you want to use something like ShaderToy to develop your shaders, you totally can, but there are a couple differences you should know about. ShaderToy uses OpenGL 3.0 ESS, which is pretty old at this point. You'll notice we're using OpenGL 4.1 for our FFGL plugin. I could be wrong, but I don't think you're able to change the OpenGL version on ShaderToy, which is too bad.

The signatures to the functions main() in FFGL and mainImage() in ShaderToy are different. Basically, in ShaderToy you end up doing a bunch of math with the screen resolution and mouse coordinates. In this project, since uv is a vec2 with both coordinates from 0 to 1, you don't need to know the exact resolution.

Step 5. Debugging

One of the nice things about Resolume 7 is you can make changes to your plugins without having to close and restart Resolume. To do that, just make sure you clear out any instances of your plugin like this. ... Then you can make changes over in Visual Studio

Lastly, I wanted to cover how to use the debugger. This is important when your plugin "just doesn't work" and you need to see the error messages.

In Visual Studio, Make sure your build target is Debug instead of Release. In the Debug menu, and click Attach to Process, then find your Resolume process and click Attach. Now, when you load your plugin in Resolume, you'll see error messages in your output panel.


Email me or try Resolume Forums