Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Visamp Docs

Oscillators

oscillator returns deterministic float samples of the shared animation time used by $TIME_SEC. All arguments are optional numeric expressions; integers are accepted and named arguments may appear in any order.

oscillator::sin(min: 0.0, max: 1.0, period: 1.0, phase: 0.0)
oscillator::cos(min: 0.0, max: 1.0, period: 1.0, phase: 0.0)
oscillator::saw(min: 0.0, max: 1.0, period: 1.0, phase: 0.0)
oscillator::triangle(min: 0.0, max: 1.0, period: 1.0, phase: 0.0)
oscillator::square(min: 0.0, max: 1.0, period: 1.0, phase: 0.0, duty: 0.5)

These signatures are expressions, not complete scripts.

ArgumentDefaultMeaning
min0.0Lower bound
max1.0Upper bound
period1.0Seconds for a complete cycle; strictly positive
phase0.0Cycle offset; positive advances, 0.25 advances a quarter-cycle
duty0.5Square only: fraction spent at max, inclusive range 0..1

Every argument must be finite. min must not exceed max. Equal bounds return that value, but all other arguments are still validated. Invalid literal values produce validation errors; invalid dynamic values produce runtime errors. Unknown arguments, duplicate arguments and unsupported types are errors. There are no interval, linear, or boomerang aliases.

For time t in seconds, wrap t / period + phase into [0, 1) to obtain p, including negative times and offsets. Return min + (max - min) * w(p):

Functionw(p)Start at phase zero
sin(1 + sin(2 * pi * p)) / 2Midpoint, rising
cos(1 + cos(2 * pi * p)) / 2Maximum
sawpMinimum
triangle1 - abs(2 * p - 1)Minimum, rising
square1 if p < duty, otherwise 0Maximum if duty is positive

Saw resets to the minimum exactly at a cycle boundary, with no extra maximum sample. Triangle rises for half the period and falls for half. Square switches to minimum exactly at the duty boundary. Duty 0 is constant minimum; duty 1 is constant maximum.

Evaluate each frame

Calls sample the current timeline. They do not create an oscillator object or make a one-time assignment reactive. Evaluate in render or on_frame to animate. Dynamic period and phase changes immediately resample the current time and may cause a jump. All calls within a frame share a timestamp, independent of call order or frame rate. Host timeline pause freezes samples; resume, seek, restart and loop follow that timeline. A first call midway through playback uses the current time, not a private clock.

context 2d
render {
  draw::background(color: $COLOR_BLACK)
  // Smooth movement around the centre over five seconds.
  let x = oscillator::sin(min: -1.0, max: 1.0, period: 5.0)
  // Starting at the minimum.
  let y = oscillator::sin(min: -1.0, max: 1.0, period: 5.0, phase: -0.25)
  // Two seconds for the full constant-speed rise and fall.
  let size = oscillator::triangle(min: 0.5, max: 1.5, period: 2.0)
  let hue = oscillator::saw(period: 3.0)
  let flash = oscillator::square(duty: 0.2)
  let glow = oscillator::sin()
  draw::circle(
    x: $WIDTH / 2 + x * 100,
    y: $HEIGHT / 2 + y * 100,
    radius: size * 30,
    color: color::hsl(h: hue, s: 0.8, l: 0.3 + glow * 0.2 + flash * 0.1)
  )
}

For GPU point fields, evaluate oscillators into a per-frame local before using that value with per-point arithmetic. Per-point oscillator arguments are not supported by the GPU expression subset.