afterglow.effects.oscillators

Provide a variety of waveforms at frequencies related to the show metronome to facilitate building visually and musically pleasing effects.

build-oscillated-param

(build-oscillated-param osc & {:keys [min max metronome frame-dynamic], :or {min 0, max 255, frame-dynamic true}})

Returns a number parameter that is driven by an oscillator. By default will be frame-dynamic, since it oscillates, but if you pass a false value for :frame-dynamic, the value will be fixed once it is assigned to an effect, acting like a random number generator with the oscillator’s range. If you don’t specify a :metronome to use, the main metronome in *show* will be used.

The values returned by the oscillator will be mapped onto the range from 0 to 255. If you would like to use a different range, you can pass in alternate numbers with the optional keyword arguments :min and :max. If the values you supply result in a maximum that is less than or equal to the minimum, the oscillated parameter will be stuck at the value you gave with :min.

build-oscillator

(build-oscillator shape-fn & {:keys [interval interval-ratio phase], :or {interval :beat, interval-ratio 1, phase 0.0}})

Returns an oscillator which generates a waveform relative to the phase of the current beat, bar, or phrase. The shape of the wave is determined by the first argument, shape-fn.

In the simplest case, shape-fn is a function that takes a single argument, the curent phase of the oscillator, which ranges from 0 to 1, and returns what the value fo the oscillator should be at that phase in its waveform. The value returned by shape-fn must also range from 0 to 1.

If the shape of the oscillator needs to be able to change over time depending on the value of a dynamic parameter, then shape-fn will instead implement IVariableShape in order to be able to resolve those parameters.

All of the standard oscillators provided by Afterglow are built in this way. For example, an upwards-sloping sawtooth wave would be created by passing a shape-fn that simply returns its argument:

(build-oscillator (fn [phase] phase))

For examples of how to generate other kinds of waveforms, view the source for sine, square, and triangle.

With no additional arguments, the waveform is defined by calling shape-fn with a phase argument that ramps upward from 0 to 1 over the course of each beat.

Passing the value :bar or :phrase with the optional keyword argument :interval makes the wave cycle over a bar or phrase instead.

Supplying a value with :interval-ratio will run the oscillator at the specified fraction or multiple of the chosen interval (beat, bar, or phrase), and supplying a :phase will offset the oscillator from the underlying metronome phase by that amount. (See the documentation for an expanded explanation illustrated with graphs.)

The arguments after shape-fn can be dynamic parameters.

IOscillator

protocol

A waveform generator for building effects that vary at frequencies related to a show metronome.

members

evaluate

(evaluate this show snapshot head)

Determine the value of this oscillator at a given moment of the show. In addition to the metronome snapshot, the show and (if applicable) fixture head must be passed in case any oscillator configuration arguments rely on dynamic or spatial parameters.

resolve-non-frame-dynamic-elements

(resolve-non-frame-dynamic-elements this show snapshot head)

Called when an effect is created using this oscillator. Returns a version of itself where any non frame-dynamic input parameters have been resolved.

IVariableShape

protocol

Shape functions which can change over time (depending on the value of dynamic parameters) use this protocol rather than being a simple function, so they can get the context needed for evaluating their dynamic parameters.

members

simplify-unless-frame-dynamic

(simplify-unless-frame-dynamic this show snapshot head)

If none of the dynamic parameters used by the shape function are dynamic to the level of individual frames, return a simple shape function based on their current values which can replace this variable shape function but run faster. Otherwise returns itself.

value-for-phase

(value-for-phase this phase show snapshot head)

Calculate the value of the oscillator’s waveform at the specified phase, with support for resolving dynamic parameters that it may depend on. phase ranges from 0 to 1, and so must the return value from this function.

sawtooth

(sawtooth & {:keys [down? interval interval-ratio phase], :or {down? false, interval :beat, interval-ratio 1, phase 0.0}})

Returns an oscillator which generates a sawtooth wave relative to the phase of the current beat, bar, or phrase. With no arguments, it creates a sawtooth wave that ramps upward from 0 to 1 over the course of each beat.

Passing true with :down? creates an inverse sawtooth wave (one that ramps downward from 1 to 0 over the course of the interval).

Passing the value :bar or :phrase with the optional keyword argument :interval makes the wave cycle over a bar or phrase instead.

Supplying a value with :interval-ratio will run the oscillator at the specified fraction or multiple of the chosen interval (beat, bar, or phrase), and supplying a :phase will offset the oscillator from the underlying metronome phase by that amount. (See the documentation for an expanded explanation illustrated with graphs.)

The arguments can be dynamic parameters.

sine

(sine & {:keys [interval interval-ratio phase], :or {interval :beat, interval-ratio 1, phase 0.0}})

Returns an oscillator which generates a sine wave relative to the phase of the current beat, bar, or phrase. With no arguments, it creates a sine wave that curves upward from 0 to 1 over the first half of each beat, then back down to 0 through the end of the beat.

Passing the value :bar or :phrase with the optional keyword argument :interval makes the wave cycle over a bar or phrase instead.

Supplying a value with :interval-ratio will run the oscillator at the specified fraction or multiple of th chosen interval (beat, bar, or phrase), and supplying a :phase will offset the oscillator from the underlying metronome phase by that amount. (See the documentation for an expanded explanation illustrated with graphs.)

All the arguments can be dynamic parameters.

square

(square & {:keys [width interval interval-ratio phase], :or {width 0.5, interval :beat, interval-ratio 1, phase 0.0}})

Returns an oscillator which generates a square wave relative to the phase of the current beat, bar, or phrase. With no arguments, it creates a square wave that starts at 1 at the start of each beat, and drops to 0 at the midpoint.

Specifying a value with :width adjusts how much of the time the wave is on (high); the default is 0.5, lower values cause it to turn off sooner, larger values later. In any case the width must be within the range 0.0 to 1.0. A value of zero means the oscillator is always off, and a value of one means it is always on.

Passing the value :bar or :phrase with the optional keyword argument :interval makes the wave cycle over a bar or phrase instead.

Supplying a value with :interval-ratio will run the oscillator at the specified fraction or multiple of a beat, and supplying a :phase will offset the oscillator from the underlying metronome phase by that amount. (See the documentation for an expanded explanation illustrated with graphs.)

The arguments can be dynamic parameters.

triangle

(triangle & {:keys [interval interval-ratio phase], :or {interval :beat, interval-ratio 1, phase 0.0}})

Returns an oscillator which generates a triangle wave relative to the phase of the current beat, bar, or phrase. With no arguments, it creates a triangle wave that ramps upward from 0 to 1 over the first half of each beat, then back down to 0 through the end of the beat.

Passing the value :bar or :phrase with the optional keyword argument :interval makes the wave cycle over a bar or phrase instead.

Supplying a value with :interval-ratio will run the oscillator at the specified fraction or multiple of the chosen interval (beat, bar, or phrase), and supplying a :phase will offset the oscillator from the underlying metronome phase by that amount. (See the documentation for an expanded explanation illustrated with graphs.)

All the arguments can be dynamic parameters.