Create your own Effects

This guide will help you in creating your own effects for Audectra. It contains a hands-on guide and a documentation of the interfaces between your effect and Audectra.

Hands-On Guides

Let us create your first effect for Audectra!

Requirements

To follow this guide, you’ll need Audectra v2 installed on your system and a code editor, like Notepad++ or Visual Code. Basic knowledge in C# coding would be recommended as well.

Create your effect

Before we start creating or own effect, lets take a look at the “Simple Color” effect, which is installed with Audectra. You can find all effects under the installation directory of Audectra, generally in the path “C:\ProgramData\Audectra\Extensions\Effects\”. This is also the path, were you store your own effects.

Open the file “SimpleColor.cs” in your code editor. I’ve added some additional comments for explanation purpose.

/**
* Copyright (c) Audectra e.U. - All Rights Reserved
* This effect is part of Audectra.
*/


using System;

using Audectra.GUI;
using Audectra.Graphics;
using Audectra.Graphics.Effects;

/* Your effects need to be in this namesapce. */
namespace Audectra.Extensions.Effects
{
/* Implement the EffectBase base class and the IExtension interface. */
class SimpleColor : EffectBase, IExtension
{
private IEffectHelper _helper;
private RgbColor _color;
private IRgbRender _render;

/* Enumeration for each value you want to be configurable in the layer settings. */
private enum ValueId
{
/* ValueId for the configurable color. */
ColorValue = 0,
}

/* This empty constructor is neccessary for Audectras extension loader engine. */
public SimpleColor() { }

/* This constructor will be called when a layer of your effect is being created. */
public SimpleColor(IEffectHelper effectHelper, int height, int width) : base(height, width)
{
/* Save the effect helper in your class, you will need it. */
_helper = effectHelper;

/* Set the default color. */
_color = new RgbColor(0, 0.5f, 0.5f);

/* Create a render for your effect using the effect helper. */
_render = _helper.CreateRender();
}

/* In this method you will be able to render your effect. It will be called for
each frame of your project, assuming this layer is enabled. */

public override IRgbRender Render(float dt)
{
/* Map every pixel in the render to the configured color */
_render.Map((color, x, y) => _color);
return _render;
}

/* To allow the user to configure your effect to their likings, you will need
to specify what exactly is configureable. In this method you will specify
what controls you request from Audectra for the layer settings side panel
of your effect. This method generally only gets called once per layer. */

public override void GenerateSettings(ILayerSettingsPanel settingsPanel)
{
/* Add a color group to the layer settings of this effect, such that
the user is able to choose or bind a color. */

settingsPanel.AddColorGroup(this, _color, (uint) ValueId.ColorValue);
}

/* Every time a configuration option you've secified above has changed, either
due user interaction in the layer settings or due a feature binding, this
method will be called, to inform you on which of your values has changed. */

public override void ValueChanged(uint valueId, object value)
{
/* The color value has been changed either by the user or a binding. Use the
effect helper to convert the value to a color. */

if ((ValueId)valueId == ValueId.ColorValue)
_color = _helper.ValueToColor(value);
}

/* Return the name of this effect. */
public string GetName()
{
return "Simple Color";
}

/* Return the version of this effect. */
public string GetVersion()
{
return "v1.0.0";
}

/* Return the author of this effect. */
public string GetAuthor()
{
return "Audectra";
}
}
}

Copy the effect file “SimpleColor.cs” to “CustomEffect.cs”, open it in your editor and change the name of your effect according to the following lines.

/* ... */

/* Your effects need to be in this namesapce. */
namespace Audectra.Extensions.Effects
{
/* Implement the EffectBase base class and the IExtension interface. */
class CustomEffect : EffectBase, IExtension
{
/* ... */

/* This empty constructor is neccessary for Audectras extension loader engine. */
public CustomEffect() { }

/* This constructor will be called when a layer of your effect is being created. */
public CustomEffect(IEffectHelper effectHelper, int height, int width) : base(height, width)
{
/* ... */
}

/* ... */

/* Return the name of this effect. */
public string GetName()
{
return "Custom Effect";
}

/* ... */
}
}

Check if your effect has been loaded correctly, by opening the general settings tab of Audectra and clicking on the “Extensions” button. This should open a window, where all extensions are listed.

In the extension list on the left hand side you should be able to see your custom effect.

  • If it is not listed in here, check if you have saved your effect file in the correct extensions path, which is specified above.
  • If your effect is marked in red, it means Audectra detected some errors while compiling your effect. Selecting your effect on the left side, will show you the detected errors on the right side.
  • If your effect is marked in green, it means Audectra has successfully compiled your effect and it can now be used when creating new layers.

Audectra will always compile new or changed effect files on startup. However, you can also trigger it by clicking on the “Refresh” button in the extensions settings above. Keep in mind though, that compiling changes on an effect will have no effect on previous instances of this effect.

Change Color on each Beat

Lets say, we want to change the color to a random color, but with full saturation and brightness, on each detected beat. We will utilize the HSV color space, because it fits perfectly our purpose. You can get more information about the HSV color space here.

Create a new method, which generates and returns a random color every time it gets called.

/* ... */

/* Your effects need to be in this namesapce. */
namespace Audectra.Extensions.Effects
{
/* Implement the EffectBase base class and the IExtension interface. */
class CustomEffect : EffectBase, IExtension
{
/* ... */
private Random _rand;

/* ... */

/* This constructor will be called when a layer of your effect is being created. */
public CustomEffect(IEffectHelper effectHelper, int height, int width) : base(height, width)
{
/* ... */

/* Initialize the random number generator. */
_rand = new Random();
}

/* Create a random color with full saturation and brightness every time
this method gets called. */

private RgbColor CreateRandomColor()
{
var hueValue = _rand.Next(360);
var randColor = new HsvColor(hueValue, 1, 1);

/* The HsvColor will implicitly be converted to RgbColor. */
return randColor;
}

/* ... */
}
}

Now the only thing we need to do, is to call this method on each detected beat. Take a look at how easy this can be done using the effect helper.

/* ... */

/* Your effects need to be in this namesapce. */
namespace Audectra.Extensions.Effects
{
/* Implement the EffectBase base class and the IExtension interface. */
class CustomEffect : EffectBase, IExtension
{
/* ... */
public override IRgbRender Render(float dt)
{
/* Create a new color on each beat. */
if (_helper.IsBeat())
{
_color = CreateRandomColor();
}

/* Map every pixel in the render to the configured color */
_render.Map((color, x, y) => _color);
return _render;
}

/* ... */
}
}

That’s it! Try out your custom effect on a new layer!