Scintillator ScinthDef File Format

Description of ScinthDef file format used by Scintillator synth server.
See also: VGen ScinthDef Synth-Definition-File-Format

This is the documentation for the file format used to describe a Video synth, called a ScinthDef, to the Scintillator synth server, scinsynth. The development file format is in YAML, making for easier human readability and debugging. However, despite the difference in format from SuperCollider SynthDef files, the ScinthDef files mostly follow the same structure so should look conceptually familiar. The primary differences are:

  • YAML can provide the length of a list of objects and so we omit sizes of lists as separate fields.

  • Constants are defined inline, instead of at the header block at the top of the file.

File Format

Top-Level Dictionary Spec

A ScinthDef file contains one or more YAML documents. Each document roughly follows the SuperCollider SynthDef structure except for that Constants are not identified verbatim but are rather provided directly in the input spec, in keeping with the desire to allow ScinthDef files to be human-readable, as well as the fact that the shader generation code inside of the synth does not require the constants to be separated out.

key

YAML type

notes

name

string

name of the ScinthDef, used as primary means of identification

shape

dictionary

A map describing the geometry to render the ScinthDef with

options

dictionary

A optional map describing rendering options for the ScinthDef

parameters

list

An optional key, if the ScinthDef has parameters, will be Parameter YAML dictionaries in an ordered list

vgens

list

the VGen YAML dictionaries in an ordered list

Shape Dictionary Spec

The sole required key for the shape dictionary is the name key, with the rest of the keys being dependent on the specific shape specified. Currently the only supported shape is the Quad, which takes two optional additional keys, widthEdges and heightEdges. Both have default values of 1 and indicate how many edges the quad should tesselate into.

Options Dictionary Spec

If ommitted the ScinthDef will use defaults for all values. The pairs of keys and values supported are detailed here. These are the same keys and values supported in the ScinthDef options dictionary.

key

values

polygonMode

fill

The default, fills the polygons completely.

line

Outlines the polygons only.

point

Draws the vertices as points only.

Parameter Dictionary Spec

key

YAML type

notes

name

string

Name of the parameter.

defaultValue

float

The default value of the parameter.

VGen Dictionary Spec

Individual VGens are specified as YAML dictionaries and have the following keys:

key

YAML type

notes

className

string

name of the VGen class, must match the name of a VGen configured on the server

rate

string

one of frame, shape, or pixel

sampler

dictionary

Only required for sampling VGens. Specifies sampler parameters.

inputs

list

input YAML dictionaries in an ordered list. May be absent if VGen has no inputs.

outputs

list

output YAML dictionaries in an ordered list

VGen Sampler Dictionary Spec

Sampling VGens must include the sampler dictionary, which contains configuration data for the image sampler. For more details see the documentation on Sampler parameters.

key

YAML type

notes

image

integer

Depending on imageArgType, either an image buffer number or the index of the parameter expected to contain the image buffer number.

imageArgType

string

Either constant, in which case image must be a valid image buffer number, or parameter, in which case image must be a valid parameter index.

minFilterMode

string

Optional. Either linear or nearest. Default is linear.

magFilterMode

string

Optional. Either linear or nearest. Default is linear.

enableAnisotropicFiltering

boolean

Optional. Default is true.

addressModeU

string

Optional. One of repeat, mirroredRepeat, clampToEdge, or clampToBorder. Default is clampToBorder.

addressModeV

string

Optional. One of repeat, mirroredRepeat, clampToEdge, or clampToBorder. Default is clampToBorder.

clampBorderColor

string

Optional. Ignored unless addressMode is clampToBorder, in which case it is one of transparentBlack, black, or white. Default is transparentBlack.

VGen Input Dictionary Spec

Inputs to VGens are polymorphic, and takes on a different structure depending on what kind of input is specified in the type field. All input dictionaries supply the type key as well as an optional name field:

key

YAML type

notes

name

string

An optional string, provided for readability

dimension

integer

The dimensionality of the input

type

string

An enumerated type, for possible values see below

The rest of the keys in the Input dictionary are a function of type and are detailed here:

type

format

vgen

key

YAML type

notes

vgenIndex

int

The index of the VGen providing output to this input

outputIndex

int

The output index on that VGen

constant

key

YAML type

notes

value

float

All constants will be treated as floating point numbers

parameter

key

YAML type

notes

index

int

The parameter index to use.

VGen Output Dictionary Spec

Output entries specify dimensions on each output.

key

YAML type

notes

dimension

integer

The dimension of this output.

Example

We execute the following code:

(
~k = ScinthDef.new(\foo, {
    BWOut.pr(VSinOsc.pr(200.0, 0.0, 0.9, 0.2));
});
~k.asYAML.postln;
)

And ScinthDef produces the following:

name: foo
shape:
    name: Quad
    widthEdges: 1
    heightEdges: 1
vgens:
    - className: VSinOsc
      rate: pixel
      inputs:
        - type: constant
          dimension: 1
          value: 200.0
        - type: constant
          dimension: 1
          value: 0.0
        - type: constant
          dimension: 1
          value: 0.9
        - type: constant
          dimension: 1
          value: 0.2
      outputs:
        - dimension: 1
    - className: BWOut
      rate: pixel
      inputs:
        - type: vgen
          vgenIndex: 0
          outputIndex: 0
          dimension: 1
      outputs:
        - dimension: 4
Last modified July 28, 2020: Update for a 0.0.7 Scintillator release (#5) (0177d81)