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.

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.

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

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.

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.

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.

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.

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.