Scintillator ScinthDef File Format | SuperCollider 3.13.0 Help

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 dictionaries in an ordered list
`tweens`	list	An optional key, an ordered list of tween dictionaries
`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

Specifies the parameters that can be modifed by OSC commands such as /scin_n_set while Scinth instances of this ScinthDef are running.

key	YAML type	notes
`name`	string	Name of the parameter.
`defaultValue`	float	The default value of the parameter.

Tween Dictionary Spec

As Scintillator precomputes tween curves at ScinthDef time and saves them into textures, tweens are specified separately from VGens. This ordered list of dictionary entries allows VGens to specify tween curves as inputs by choosing an index.

key	YAML type	notes
`levels`	list	A list of either individual float elements or sublists of 1, 2, or 4 float elements, describing tween targets.
`durations`	list	A list of individual float elements, of the same length as levels less 1, giving durations of segments in seconds.
`curves`	int or list	Determines the shape of the envelope segments. If one string is provided all segments are assigned that shape, or can be a list of the same length as durations that specifies individual shapes for each segment. For the list of currently supported shapes see the ScinTween documentation.
`sampleRate`	float	Specified as samples per second, controls how often the entire tweening function should be sampled
`dimension`	int	A number, either 1, 2, or 4, describing the dimension of the level values
`loop`	boolean	On optional key, default false. If present describes if the tween should loop on its values.

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.
`tween`	dictionary	Only present when a Tween input is present, specifies the index of the Tween to use.
`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 VSampler 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`.

Tween

A VGen that requires a bound Tween for sampling should specify the tween index of the VGen to bind using the tween dictionary.

key	YAML type	notes
`index`	integer	The index of specific Tween in the ScinthDef `tweens` table to use.

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

helpfile source: /tmp/tmpjbuo4r8ibaryon_Scintillator/Scintillator/Reference/Scintillator-ScinthDef-File-Format.schelp
link::Scintillator/Reference/Scintillator-ScinthDef-File-Format::

Scintillator ScinthDef File FormatExtension

Scintillator ScinthDef File Format
Extension