Permutable / API

run function

Gives you a minimal user interface with controls for the parameters you set up in your program.

Parameter Type Description
program program Your program
[options] object Runtime options
Options
Key Type Description
[container] HTMLElement Which container element to run in. Defaults to: document.body
[width] number Use a fixed width. If ommited it will use the width of the container
[height] number Use a fixed height. If ommited it will use the height of the container
[ratio] number Use a fixed pixel ratio. Defaults to: window.devicePixelRatio
run(program)

mix function

Gives you an interface for composing and controlling multiple programs with a single output.

Parameter Type Description
programs Array of program Your programs
mix([program1, program2])

Program object

A program is described by a plain object

Attribute Type Description
name string A name for your program
[params] object An object describing the parameters for the program. The keys should be short descriptive names of the parameter, for example "radius". The value should be an object describing the parameter
setup function A setup function that will run once the program is loaded. In it, the canvas element is being provided as an argument. An update function can be returned from the setup function. It will be called anytime the params changes and has one argument – an object containing the values of all the parameters

Example:

{
  name: 'Rectangle',
  params: {
    hue: {
      type: 'number',
      value: 50,
      max: 360
    },
    radius: {
      type: 'number',
      value: 0.5
    }
  },
  setup: function (canvas) {
    // This function is called once when the program loads

    return function update (values) {
      // This function is called whenever any of the parameter changes
      console.log(values) // { hue: 50, radius: 0.5 }
    }
  }
}

Parameter object

A parameter is described by a plain object

Attribute Type Description
type string The parameter type
[...options] mixed Type-specific options

Type 'bpm'

A special parameter meant to set tempo (beats per minute). Output value type: BPM as a number

{
  type: 'bpm'
}

Type 'camera'

Camera input from getUserMedia. Output value type: An <video /> element (can be used directly with drawImage or as a texture image)

{
  type: 'camera'
}

Type 'file'

Select one or more files from file system. Output value is either a single File or an array of them depending on multiple option. The output value can optionally be pre-processed using process option

Option Type Default Description
[accept] string Which file types to accept. See valid formatting
[multiple] boolean false Allow multiple files
[process] function Pre-process files for easier consumption later

Example:

{
  type: 'file'
}

Example, returning an array buffer:

{
  type: 'file',
  process: async file => file.arrayBuffer()
}

Example, prossesing a text file:

{
  type: 'file',
  accept: 'text/plain',
  process: async file => file.text()
}

Example, prossesing multiple images and returning an array of image elements:

{
  type: 'file',
  accept: 'image/*',
  multiple: true,
  process: files => files.map(file => {
    const image = new Image()
    image.src = URL.createObjectURL(file)
    return image
  })
}

Type 'number'

Ouput value type: number

Option Type Default Description
[value] number 0 Initial value
[min] number 0 Minimum value
[max] number 1 Maximum value
[step] number 0.01 Increments

Example with inital value:

{
  type: 'number',
  value: 0.5
}

Example with all options:

{
  type: 'number',
  value: 20,
  min: 10,
  max: 70,
  step: 1
}

Type 'timer'

A timer is updated continuously through requestAnimationFrame. Output value type: The time since the program started as a number

{
  type: 'timer'
}

Type 'toggle'

A toggle works like a toggle switch. Ouput value type: boolean

Option Type Default Description
[active] boolean true Initial state

Example with initial deactivated state:

{
  type: 'toggle',
  active: false
}

Type 'trigger'

A trigger is similar to a spring-loaded switch, it is only active when pressed down. Ouput value type: boolean

{
  type: 'trigger'
}