Animation and uniforms

Keeping time

The panel does not give a script the wall-clock time. Add up dt yourself:

local time = 0

function _update(dt)
  time = time + dt
end

function _draw()
  gfx.cls()
  local y = 32 + 20 * math.sin(time * 2)       -- up and down once every pi seconds
  gfx.rectfill(28, math.floor(y), 8, 8, 255, 120, 40)
end

Movement written as “speed times dt” runs at the same speed whatever the frame rate. Movement written as “one pixel per frame” does not.

Uniforms: values from outside

uniforms is a global table that is shared between your script and the outside world. Anything you send to the panel by name shows up in it on the next frame, while the script keeps running.

function _init()
  uniforms.speed = uniforms.speed or 1          -- a default until something is sent
end

local x = 0

function _update(dt)
  x = (x + 30 * uniforms.speed * dt) % gfx.width()
end

function _draw()
  gfx.cls()
  gfx.rectfill(math.floor(x), 28, 6, 6, 80, 220, 120)
end

To change it from the editor, use the Uniforms card: type the name speed, a value such as 3, and press Send. The square speeds up without the script restarting.

Numbers and vectors

A uniform is one number, or a group of two to four numbers:

You send	The script reads
2.5	uniforms.speed is the number 2.5
1, 0.5, 0	uniforms.tint is a vector; uniforms.tint.x, .y, .z or .r, .g, .b

function _draw()
  local tint = uniforms.tint or vec3(1, 1, 1)
  gfx.cls(math.floor(tint.r * 255), math.floor(tint.g * 255), math.floor(tint.b * 255))
end

Vectors are covered on the Fragment shaders page.

Rules

• Names are up to 15 characters: letters, digits and underscores, not starting with a digit.
• A panel holds up to 16 uniforms sent from outside.
• The script can also write to uniforms itself. That is how a shader gets its time: _update adds dt to uniforms.time and the shader reads it.
• A value sent from outside replaces what the script wrote, when it arrives.

Uniforms are the way to hook a script to anything: a slider on a web page, a sensor, a home-automation rule. The MQTT page shows the messages.

Next: Fragment shaders.