Skip to content

Layer Settings

This feature allows effect designers to create settings for their effects, allowing end-users to further customize effects or bind specific setting values to music features.

Page Layout

Each effect can define multiple pages of layer settings, where each setting page can contain multiple setting groups. Further on, every settings group can contain multiple layer settings.

Layer Settings Page Layout

Info

Every layer setting must be contained in a settings group and every settings group in a settings page. However, it is not possible to create setting groups within other setting groups or setting pages within other setting pages.

Settings Builder

Each effect can define settings via the layer settings builder by overriding the GenerateSettings(...) method (see example below). For more information about the settings builder, take a look at the extension SDK documentation.

Available Settings

Currently, the following layer setting types are available for your effects.

Slider

The slider allows the user to manually change a layer setting within a given minimum and maximum range.

Bindable Slider

This setting type extends the basic slider, which is described above, and allows the user to bind its value to a custom expression.

Bindable Trigger

The bindable trigger allows the user to toggle a trigger either manually or by binding it to a custom condition.

Color Group

This layer setting type consists of three bindable sliders, which allow the user to change a color in either RGB or HSV color space. Unlike the setting types discussed above, this setting type represents a full settings group.

Events

Audectra notifies your effect every time a registered layer setting has changed or a trigger has been toggled. These notifications are delivered to the following methods of your effect.

Info

Both event sinks have a default implementation, which has to be overridden by your effect to receive these notifications (see example below).

OnSettingChanged

This event sink will be invoked every time a layer setting has changed (either manually by the user or through a binding). The settingId can be used to distinguish between multiple settings.

OnTrigger

Every time a trigger of your effect has been toggled (either manually by the user or through a binding), this event sink will be invoked. You can distinguish between multiple trigger by accessing the triggerId.

Example

Effect extension: Audectra/v0/Bars.cs

[MinWidth(4)]
[LandscapeAspectRatio()]
[EffectExtension("Bars", "Audectra", "1.3.0")]
class Bars : EffectExtensionBase
{
    // ...

    private enum SettingId
    {
        Color = 0,
        NumBars,
        MaxBarLife,
    }

    private enum TriggerId
    {
        BarBoom = 0,
    }

    // ...

    public override void GenerateSettings(ISettingsBuilder settingsBuilder)
    {
        settingsBuilder.PageBegin();
        settingsBuilder.AddColorGroup(_color, (uint)SettingId.Color);

        settingsBuilder.GroupBegin("Num Bars");
        settingsBuilder.AddSlider(_numBars, 1, _maxNumBars, (uint)SettingId.NumBars);
        settingsBuilder.GroupEnd();

        settingsBuilder.GroupBegin("Bar Life");
        settingsBuilder.AddBindableSlider(_maxBarLife, 0, 2.5f, (uint)SettingId.MaxBarLife);
        settingsBuilder.GroupEnd();

        settingsBuilder.GroupBegin("Trigger");
        settingsBuilder.AddBindableTrigger((uint)TriggerId.BarBoom);
        settingsBuilder.GroupEnd();

        settingsBuilder.PageEnd();
    }

    public override void OnSettingChanged(uint settingId, SettingValue value)
    {
        switch ((SettingId) settingId)
        {
            case SettingId.Color:
                _color = value;
                break;

            case SettingId.NumBars:
                lock (_barsLock)
                {
                    _numBars = value;
                    _barSize = (int)(Width / _numBars);
                    _lastBar = -1;
                    InitBars();
                }
                break;

            case SettingId.MaxBarLife:
                lock (_barsLock)
                {
                    _maxBarLife = value;
                }
                break;
        }
    }

    public override void OnTrigger(uint triggerId, bool risingEdge)
    {
        if (!risingEdge)
            return;

        switch ((TriggerId) triggerId)
        {
            case TriggerId.BarBoom:
            {
                int idxBar = GetNextBar();

                lock (_barsLock)
                {
                    _bars[idxBar].Value = _maxBarLife;
                    _bars[idxBar].MaxLife = _maxBarLife;
                    _bars[idxBar].Color = _color;
                }
            }
            break;
        }
    }

    // ...
}

The example above generates the following layer settings.

Layer Settings of Audectra/v0/Bars.cs