Dynamic Parameters

When creating a dynamic parameter, you can control how dynamic it is. The most dynamic, frame dynamic, are evaluated anew for every single frame of control values that are sent out to the lights. If, on the other hand, you want the value to be calculated when the effect is started, and then stay constant, you can create the parameter with a false value for frame-dynamic?

Parameters can get their values from a show variable. Any number of values can be stored in the show, by assigning them a keyword with the function:

You can then refer to that stored value whenever you are building a dynamic parameter (for example when you are passing in the :hue parameter for a Color Parameter as described below), by simply using the keyword (in this example, :key), and the current value stored in the show variable will be used.

This keyword shorthand is just a convenience mechanism provided by functions like build-color-param. You can also explicitly build a reference to a show variable like this:

The most common reason you might want to use the explicit creation function is that you can control details about the binding by passing in optional keyword parameters:

As an example of using these parameters, consider:

This would cause the dynamic parameter to have a numeric value which is twice the value found in the show variable named :key.

When you use the keyword shorthand to bind to a show variable in building another dynamic parameter, the type and default are assumed from the context in which you are using the variable.

Oscillated parameters vary over time, at a speed controlled by a Metronome (usually the main show metronome, synced to DJ equipment) and so can make the lights appear to be reacting intelligently to the music being played. The timing information produced by the metronome is fed into an Oscillator, which determines the shape of the wave that controls its value, and the frequency at which it oscillates, related to beats, bars, or phrases of the underlying metronome. The resulting value can then be scaled to meet the needs of whatever is being generated (a dimmer level, color component, or light rotation). Oscillated parameters are created by calling afterglow.effects.oscillators/build-oscillated-param.

The oscillator parameter is an Oscillator created by one of the functions in afterglow.effects.oscillators which, as described above, determines how to react to the time information provided by the metronome. Additionally, you can supply one of the following optional keyword parameters:

The keyword parameters :min, :max, and :metronome can themselves be bound to show variables by passing in the keyword with which the show variable was created. The frame-dynamic setting of such variable bindings will be controlled by the frame-dynamic setting of the oscillated parameter being created.

Like oscillated parameters (above), step parameters vary over time, at a speed controlled by a Metronome (usually the main show metronome, synced to DJ equipment). But rather than moving back and forth, step parameters increase steadily over time, because they are designed to control the progression of a chase. Step parameters are created by calling afterglow.effects.params/build-step-param.

With no arguments, this creates a step parameter that starts out with the value 1 for the duration of the beat closest to when you created it, and the value will jump up by one as each subsequent beat occurs:

If a less-abrupt transition between stages in the chase is desired, a fade can be added between them by passing a value with the optional keyword argument :fade-fraction. When omitted, the default value is 0, meaning no time is spent fading, which results in the kind of abrupt steps seen in the graph above. Passing a value of 0.2 would cause the parameter to spend 1/5 of its time fading: During the final 0.1 of the beat, it would ramp up towards the midpoint of the next value, and then finish that ramp during the first 0.1 of the next beat, as shown in the following graph:

The graph shows that most of each beat is spent with the step parameter steady at its expected value, but the first and last tenths are a linear fade from and to the next value. Changing the fade fraction to 0.5 causes half the time to be spent fading, and only half sitting at the beat’s assigned value:

That trend continues until the maximum possible fade-fraction value of 1 is used, which causes all of each beat to be spent fading, so the step parameter continuously fades through values, reaching the value assigned to a given beat at the midpoint of that beat:

In addition to linear fades, you can smooth out the start and end of the fades by using a sine-shaped fade curve, by passing the optional keyword argument :fade-curve with the value :sine. Here is what that looks like with a continuous fade:

The smoothing effect of the sine curve option becomes even more evident when you configure the step parameter to fade for only part of the beat:

Of course, as the amount of time spent fading gets compressed, the smoothing is less obvious, although it is still there. Dropping back to fading over just the first and last tenth of the beat looks like this:

When the fade fraction is 0, it does not matter what the fade curve is, because no fading takes place.

You can also have the step parameter increment for each bar or phrase, rather than each beat, by passing the optional keyword argument :interval with the value :bar or :phrase. And, as with oscillators, you can use the optional keyword argument :interval-ratio to have the parameter run at the specified fraction or multiple of the chosen interval. The way that :interval-ratio works is illustrated in the Ratios section of the oscillator documentation.

As one example of :inteval-ratio specifically applied to step parameters, here is what the preceding graph would look like if the interval ratio was changed to a value of one half, meaning that the step parameter increases every half of a beat:

Finally, if you would like the beat numbers to be counted from a time that is different than when you created the step parameter, you can pass a metronome snapshot along with the keyword argument :starting, and beats will be counted so that the first beat is the one that occured closest to that snapshot.

For maximum flexibility, any of the parameters to build-step-param can themselves be dynamic parameters from the show. If none of them are, a more efficient version of the step parameter is built, precalculating as much as possible.

Color parameters are an extremely flexible way of dynamically assigning color. The basic way to create one is to call afterglow.effects.params/build-color-param.

By itself this call would simply return a non-dynamic black color. However, you will use one or more of the following optional keyword parameters to get the dynamic color you want:

All of these parameters, except for frame-dynamic, can themselves be dynamic parameters, such as show variables (with the convenience shorthand of just passing in the keyword by which the show variable was stored) or oscillated parameters.

Refer to Working with Color for a refresher on the meaning of the basic color components. It would not make sense to pass all of these parameters, because some will override others, but here is how they are evaluated:

Finally, the result of all this is the color that is returned by the dynamic parameter. Afterglow tries to be as efficient about this as possible, and do as much calculation as it can when the parameter is created. If there are no frame dynamic parameters, it will return a fixed color. But you can easily use frame-dynamic oscillated parameters and get lovely shifting rainbow cues, as shown in the effect examples.

There are three different kinds of parameters which tell fixtures how to move. They differ in the way that you express direction or aim.

Spatial parameters allow you to base an effect parameter on the physical arrangement or relationships between fixtures in your light show. The way to create one is to call afterglow.effects.params/build-spatial-param.

The required parameters are the fixtures and/or heads over which you want this parameter to be calculated, and a function which, when invoked with a fixture or head, returns a number or a dynamic Number parameter.

If desired, the results returned for all included heads can be scaled to fall within a standard range. Scaling is activated using the optional keyword parameters :max and :min. If neither is supplied, scaling is not performed. Passing a value for only :max activates scaling with a default minimum value of 0, and passing a value for only :min activates scaling with a default maximum value of 255. The maximum value must be larger than the minimum value.

As noted above, the values returned by f can themselves be dynamic parameters, such as show variables (with the convenience shorthand of just passing in the keyword by which the show variable was stored) or oscillated parameters. If frame-dynamic is not explicitly set, the spatial parameter will be frame dynamic if any value returned by f is frame-dynamic.

Useful things that f can do include calculating the distance of the head from some point, either in 3D or along an axis, its angle from some line, and so on. These can allow the creation of lighting gradients across all or part of a show. Spatial parameters make excellent building blocks for color, direction and aim parameters, as shown in the effect examples.

Sometimes you want to build a cue parameter by combining some other values using a simple expression. While you can certainly do this by implementing the low-level IParam protocol, Afterglow provides a helper function, build-param-formula to eliminate most of the boilerplate involved in that approach. You can see an example of it being used in build-ratio-param in the examples namespace, which takes the beats and cycles cue parameters chosen by a user, and divides them to create the ratio that an oscillated parameter needs:

The build-param-formula function takes the param-type of the parameter you want to create (in this case a Number), a function calc-fn that will be called to calculate the parameter value when needed (in this case, an anonymous function that simply divides its first argument by its second), and then the list of other dynamic parameters that will be evaluated and fed as input to calc-fn. This is a very compact way to perform calculations to combine or transform other dynamic parameters.

If you want to perform geometric transformations on Aim and Direction parameters, there are some helper functions for that as well. build-direction-transformer takes an incoming direction parameter and a Java3D Transform3D object which will be used to transform it. Both can by dynamic parameters, including keywords that will be looked up as show variables. Similarly, build-aim-transformer applies a transformation parameter to an aim parameter.

Since dynamic parameters are such a source of flexibility, they can get complex quickly, especially when you are driving them from external systems via MIDI events. Here are a few tips on how you can check whether the parameter is doing what you expect, and how it is feeding into the effects you are creating with it.