Specification of the Arcadia Asset Definition Language (draft, v0.2)

1 Introduction

This document specifies the Arcadia asset definition language, Arcadia ADL for short. It is a draft; it is authoritative over prose found elsewhere in this documentation and over the doc-comment examples found in the headers of the Arcadia.ADL module, which are known to be stale in places.

Sections 1 to 3 describe the language as a whole. Sections 4 to 6 specify one group of definition types each. Section 7 records the enumerations whose literals string entries are drawn from. Section 8 lists, completely and in one place, every type name the current implementation accepts; it is the authoritative inventory and supersedes any incomplete enumeration of type names in earlier drafts of this document.

A definition type is specified here exactly as far as the implementation reads it. Where the implementation accepts a string without constraining it, this document says so instead of inventing a value set. Where the implementation stores a name without resolving it, this document says so instead of claiming a link-time constraint that does not exist.

2 Notation

Adl assets are written in the Arcadia Data Definition Language (Arcadia DDL). The grammar productions used below are given in the notation of Arcadia Common Lexical Translations. A map entry line is written as name : value followed by a comma. The name is an identifier, the value a literal or a list of literals.

The following types of values occur:

• String, for example "Colors.Red",
• Number, an integer literal such as 255,
• Boolean, written as the String "true" or as the String "false", and
• List, a comma-separated list of values in square brackets, such as [ 1.0, 0.0 ].

Entry lists below are annotated with the precision the reader consumes a number with: Natural8, Natural32, Integer32, Real32, or Real64. An entry annotated optional may be omitted, and the annotation records the value the reader substitutes when it is omitted. An entry not annotated optional is mandatory; an omitted mandatory entry, an entry of the wrong value kind, and an entry unknown to the schema are all semantical errors.

3 Structure of an asset

An ADL asset is a DDL map. Every definition of every type has the entry type of type String and the entry name of type String:

asset : map
asset -> "type" : <string>
          "name" : <string>
          <type-specific entries>
      

The type entry selects the reader that processes the asset. It must be one of the type names listed in section 8; an unidentified type is a semantical error. The name entry is the name of the definition and must be unique within the application that loads the assets.

String entries that name other definitions are references. A reference is stored as a name while reading and is resolved while linking: the named definition must exist among the loaded definitions, and for the entries marked as such below the resolved definition must be of a required type. An unresolvable reference, or a reference to a definition of the wrong type, is an error reported while linking.

Not every entry that names another definition is resolved while linking. Each section below states for its own entries whether linking resolves and type-checks them, and the entry lists mark such entries as reference.

4 Visuals definitions

The visuals definitions describe colors, geometry, pixels, materials, and the models composed from them.

Color

Type name: "Color". A color with straight/unassociated red, green, blue and alpha components. RGB entries are required; alpha is optional and defaults to 255 (opaque). Explicit alpha 0 remains zero. Components are integers in [0, 255]; no premultiplication or color-space conversion is implied. Holds no references and therefore links trivially.

"type"  : "Color"
"name"  : <string>
"red"   : <number>    // Natural8, the red component
"green" : <number>    // Natural8, the green component
"blue"  : <number>    // Natural8, the blue component
"alpha" : <number>    // optional Natural8, defaults to 255
      

Both forms are valid:

{ type: "Color", name: "Colors.Red", red: 255, green: 0, blue: 0 }
{ type: "Color", name: "Colors.TranslucentRed", red: 255, green: 0, blue: 0, alpha: 128 }
      

Alpha is stored in the definition, not an instruction to enable blending. Existing RGB-only consumers intentionally retain their behavior: Media Fill/CheckerboardFill write opaque pixels (alpha 255), mesh-generator geometry conversion uses alpha 1, UI Button color state copies RGB only, and current example clear-color/text-run conversions use alpha 1. Explicit four-component vertex colors and material blend settings are separate contracts. No new transparency or material defaults are introduced. Graph expansion preserves explicit Color alpha when cloning local nodes.

Mesh

Type name: "Mesh". A polygonal mesh given explicitly by its vertex data.

"type"                                : "Mesh"
"name"                                : <string>
"ambientColor"                        : <string>   // reference to a Color definition
"vertexPositions"                     : <list of numbers>   // Real32
"vertexAmbientColors"                 : <list of numbers>   // Real32
"vertexAmbientColorTextureCoordinates" : <list of numbers>   // Real32
      

The number of vertices is derived, not written: it is one third of the length of vertexPositions. There is no numberOfVertices entry. The three lists are read into byte arrays and must satisfy the following; any violation is a semantical error:

• the length of vertexPositions is a multiple of three,
• the length of vertexAmbientColors is four times the number of vertices, and
• the length of vertexAmbientColorTextureCoordinates is twice the number of vertices.

The ambientColor entry is stored as a name; the current implementation does not resolve it while linking.

Mesh generators

A mesh generator describes a mesh procedurally. "Mesh" and the three generator types below share the base type MeshGenerator, so a reference required to denote a mesh generator accepts any of the four.

Every mesh generator carries the ambient color of the mesh it generates. As with "Mesh", the ambientColor entry is stored as a name and is not resolved while linking.

Type name: "BoxMeshGenerator". Generates a box with the given width, height, and depth.

"type"         : "BoxMeshGenerator"
"name"         : <string>
"width"        : <number>   // Real32
"height"       : <number>   // Real32
"depth"        : <number>   // Real32
"ambientColor" : <string>   // reference to a Color definition
      

Type name: "PlaneMeshGenerator". Generates a plane with the given width and height.

"type"         : "PlaneMeshGenerator"
"name"         : <string>
"width"        : <number>   // Real32
"height"       : <number>   // Real32
"ambientColor" : <string>   // reference to a Color definition
      

Type name: "SphereMeshGenerator". Generates a sphere with the given radius and number of segments.

"type"         : "SphereMeshGenerator"
"name"         : <string>
"radius"       : <number>   // Real32
"segments"     : <number>   // Natural32, the number of segments
"ambientColor" : <string>   // reference to a Color definition
      

PixelBuffer

Type name: "PixelBuffer". A rectangular buffer of pixels.

"type"       : "PixelBuffer"
"name"       : <string>
"width"      : <number>   // Natural32
"height"     : <number>   // Natural32
"operations" : <list of strings>   // references to pixel-buffer operation definitions
      

While linking, each operation reference is resolved, must be a pixel-buffer operation definition, and is linked recursively.

Pixel-buffer operations

Pixel-buffer operations produce the content of a pixel buffer. They are referenced by the operations entry of a "PixelBuffer" definition.

Type name: "PixelBufferOperations.FillOperation". Fills a pixel buffer with a color.

"type"  : "PixelBufferOperations.FillOperation"
"name"  : <string>
"color" : <string>   // reference to a Color definition
      

While linking, the color reference is resolved and must be a "Color" definition.

Type name: "PixelBufferOperations.CheckerboardFillOperation". Fills a pixel buffer with a checkerboard pattern.

"type"               : "PixelBufferOperations.CheckerboardFillOperation"
"name"               : <string>
"firstCheckerColor"  : <string>   // reference to a Color definition
"secondCheckerColor" : <string>   // reference to a Color definition
"checkerWidth"       : <number>   // Integer32
"checkerHeight"      : <number>   // Integer32
      

While linking, both color references are resolved and each must be a "Color" definition.

Texture

Type name: "Texture". A texture; a pixel buffer together with sampling properties.

"type"                : "Texture"
"name"                : <string>
"pixelBuffer"         : <string>   // reference to a PixelBuffer definition
"magnificationFilter" : <string>   // optional, a TextureFilter literal
"minificationFilter"  : <string>   // optional, a TextureFilter literal
"addressModeU"        : <string>   // optional, a TextureAddressMode literal
"addressModeV"        : <string>   // optional, a TextureAddressMode literal
      

An omitted sampling property is the None element of its enumeration; the engine then uses its own default. An unknown literal is a semantical error. While linking, the pixelBuffer reference is resolved and must be a "PixelBuffer" definition.

Material

Type name: "Material". The material a model is rendered with.

"type"                    : "Material"
"name"                    : <string>
"materialType"            : <string>   // a MaterialType literal
"ambientColorSource"      : <string>   // an AmbientColorSource literal
"ambientColorTexture"     : <string>   // reference to a Texture definition
"blendSourceFunction"     : <string>   // optional, a BlendFunction literal
"blendDestinationFunction" : <string>   // optional, a BlendFunction literal
      

An omitted blend function is the None element of the BlendFunction enumeration. While linking, the ambientColorTexture reference is resolved and must be a "Texture" definition.

Model

Type name: "Model". A model, a mesh rendered with a material.

"type"     : "Model"
"name"     : <string>
"mesh"     : <string>   // reference to a Mesh or mesh generator definition
"material" : <string>   // reference to a Material definition
      

While linking, the mesh reference is resolved and must be a definition of the base type MeshGenerator, that is, a "Mesh", "BoxMeshGenerator", "PlaneMeshGenerator", or "SphereMeshGenerator" definition; and the material reference is resolved and must be a "Material" definition.

5 Audials definitions

The audials definitions describe sample buffers and the digital signal processing definitions that synthesize them, along with finite and streaming sound-source nodes.

SampleBuffer

Type name: "SampleBuffer". A sample buffer synthesized by a digital signal processing definition.

"type"     : "SampleBuffer"
"name"     : <string>
"duration" : <number>   // Natural32, the duration in seconds
"dsp"      : <string>   // reference to a DSP definition
      

While linking, the dsp reference is resolved and is linked recursively.

DSPStreamProvider

Type name: "DSPStreamProvider". An incrementally rendered DSP source.

"type"       : "DSPStreamProvider"
"name"       : <string>
"dsp"        : <string>   // reference to a DSP definition
"sampleRate" : <number>   // Natural32, frames per second
"duration"   : <number>   // optional Natural32, seconds; absent means infinite
      

When present, duration limits the provider to that many seconds of frames at sampleRate. When absent, the provider keeps producing frames until its consumer is stopped. The dsp reference is resolved and linked recursively.

SoundSourceNode

Type name: "SoundSourceNode". A runtime node playing a pre-rendered sample buffer.

"type"         : "SoundSourceNode"
"name"         : <string>
"sampleBuffer" : <string>   // reference to a SampleBuffer definition
"isLooping"    : <boolean>  // optional, default false
"volume"       : <number>   // optional Real32, default 1.0
      

The sampleBuffer reference is resolved and linked recursively.

StreamingSoundSourceNode

Type name: "StreamingSoundSourceNode". A runtime node pulling audio chunks from a provider.

"type"     : "StreamingSoundSourceNode"
"name"     : <string>
"provider" : <string>   // reference to a DSPStreamProvider definition
"volume"   : <number>   // optional Real32, default 1.0
      

The provider reference is resolved and linked recursively. The node plays until its provider reaches end-of-stream or playback is stopped; a provider with no duration does not reach end-of-stream on its own.

Digital signal processing definitions

A digital signal processing definition describes a signal. It is referenced by the dsp entry of a "SampleBuffer" definition.

Type name: "DSP.Constant". A constant signal.

"type"  : "DSP.Constant"
"name"  : <string>
"value" : <number>   // Real32
      

Type name: "DSP.SineWave". A sine wave.

"type"      : "DSP.SineWave"
"name"      : <string>
"frequency" : <number>   // strictly positive Integer32, frequency in hertz
      

Type name: "DSP.SawtoothWave". A sawtooth wave.

"type"      : "DSP.SawtoothWave"
"name"      : <string>
"frequency" : <number>   // strictly positive Integer32, frequency in hertz
      

Both oscillator asset readers require frequency in 1..INT32_MAX. Zero is not silence and negative values do not request reversed phase: nonpositive Integer32 frequencies raise Arcadia_Status_SemanticalError during ADL reading, before definition construction or Engine DSP creation. This also applies to generated definitions read after graph expansion. The class constructors/factories still represent the full signed Integer32 domain; reader validation does not change their ABI or native Media's separate nonpositive-frequency ArgumentValueInvalid guard.

Type name: "DSP.WhiteNoise". White noise. Has no extra entries.

"type" : "DSP.WhiteNoise"
"name" : <string>
      

DSP.Gain, DSP.LowPass and DSP.Mix

These ordinary assets share one operator definition and reader. Each requires string type and name entries. Gain requires a string input reference and numeric gain; LowPass requires a string input reference and numeric cutoff. Mix requires a nonempty inputs list of string references, preserving order and duplicates. Entries belonging to another variant, unknown entries, duplicate entries and wrong entry types are semantical errors.

{ type: "DSP.Gain", name: "Quiet", input: "Tone", gain: 0.25 }
{ type: "DSP.LowPass", name: "Filtered", input: "Quiet", cutoff: 850 }
{ type: "DSP.Mix", name: "Combined", inputs: ["Tone", "Filtered"] }
      

Mix uses unnormalized unity-gain summation in the defined input order. It does not divide by the input count, normalize to a peak, clamp, compress, limit or apply automatic gain compensation. One input passes through; duplicate entries are rendered and summed individually. Two inputs each producing 0.75 produce 1.5; samples outside [-1, +1] are valid inside the floating-point graph. Native Media Mix with zero inputs emits silence, but the ADL asset still requires a nonempty inputs list. Output conversion and any future optional gain/limiter node are separate concerns.

DSP repeatability is scoped to identical state, topology, inputs, seeds, sample rate/configuration and execution environment (binary, compiler/FP settings and runtime). Fresh deterministic renders must match sample bit patterns, not just numerically equal promoted values. Supported streaming topologies preserve their sequence across chunk partitions. Cross-platform numerical equivalence requires operator-specific reference tolerances and actual platform gates; cross-platform bitwise identity is not promised. Non-finite inputs and NaN payload behavior need explicit operator policy. Native shared-state rendering/seed/reset semantics and tested topology limits are documented in the Media DSP reproducibility profile; ADL source expansion does not add a runtime scheduling/cache mechanism.

Parameters are converted to Real32, without reader-side positivity or clamping restrictions. Zero gain is valid; cutoff positivity is checked later by the native Media LowPass constructor. References need not exist while reading; unresolved names fail during linking with NotFound. Ordinary operator linking resolves references recursively but does not validate their DSP family; unsupported DSP definitions are rejected later by the Engine DSP factory. This does not grant graph-local Gain/LowPass support or change the separate graph-local Mix validation rules.

6 User interface definitions

The user-interface definitions describe widgets and the panels that contain them. The widget definitions share a rectangle, described by the entries left and bottom, the coordinates of the lower-left corner in canvas coordinates, and by the entries width and height. All five widget types are read by a single reader, and each of them validates its own schema.

The alignment entries horizontalAlignment, verticalAlignment, mainAlignment, and crossAlignment are ordinary strings. The current implementation stores the value as written and does not constrain its literal set, so the accepted values are an engine concern rather than a language constraint.

UI.Button

Type name: "UI.Button". A rectangular user-interface button.

"type"                     : "UI.Button"
"name"                     : <string>
"left"                     : <number>   // Integer32
"bottom"                   : <number>   // Integer32
"width"                    : <number>   // Natural32
"height"                   : <number>   // Natural32
"text"                     : <string>   // the button label
"horizontalAlignment"      : <string>   // optional, defaults to "Center"
"verticalAlignment"        : <string>   // optional, defaults to "Center"
"backgroundColor"          : <string>   // optional, reference to a Color definition
"hoveredBackgroundColor"   : <string>   // optional, reference to a Color definition
"pressedBackgroundColor"   : <string>   // optional, reference to a Color definition
"disabledBackgroundColor"  : <string>   // optional, reference to a Color definition
"focusedBackgroundColor"   : <string>   // optional, reference to a Color definition
"backgroundRed"            : <number>   // optional, Natural8, defaults to 56
"backgroundGreen"          : <number>   // optional, Natural8, defaults to 120
"backgroundBlue"           : <number>   // optional, Natural8, defaults to 240
"pixelSize"                : <number>   // optional, Natural32, defaults to 24
"borderWidth"              : <number>   // optional, Natural32, defaults to 0
"borderRed"                : <number>   // optional, Natural8, defaults to 87
"borderGreen"              : <number>   // optional, Natural8, defaults to 104
"borderBlue"               : <number>   // optional, Natural8, defaults to 118
      

The text entry is the label associated with the button. An omitted alignment entry becomes "Center". Each of the five *BackgroundColor entries names a "Color" definition; an omitted hoveredBackgroundColor, pressedBackgroundColor, disabledBackgroundColor, or focusedBackgroundColor falls back to backgroundColor, which may itself be omitted. While linking, every one of the five color references that is present is resolved and must be a "Color" definition.

The backgroundRed, backgroundGreen, and backgroundBlue entries are the background color as 8-bit RGB components. pixelSize is the text size in pixels, borderWidth the border thickness in pixels, and borderRed, borderGreen, borderBlue the border color as 8-bit RGB components.

UI.Label

Type name: "UI.Label". A user-interface text label.

"type"                : "UI.Label"
"name"                : <string>
"left"                : <number>   // Integer32
"bottom"              : <number>   // Integer32
"width"               : <number>   // Natural32
"height"              : <number>   // Natural32
"text"                : <string>   // the label text
"horizontalAlignment" : <string>
"verticalAlignment"   : <string>
"red"                 : <number>   // Natural8, the red component
"green"               : <number>   // Natural8, the green component
"blue"                : <number>   // Natural8, the blue component
"alpha"               : <number>   // Natural8, the alpha component
"pixelSize"           : <number>   // Natural32
      

The red, green, blue, and alpha entries describe the text color as 8-bit components. Unlike "UI.Button", no entry of this definition is optional.

UI.StackPanel

Type name: "UI.StackPanel". A panel that stacks its children along one axis.

"type"                   : "UI.StackPanel"
"name"                   : <string>
"left"                   : <number>   // Integer32
"bottom"                 : <number>   // Integer32
"width"                  : <number>   // Natural32
"height"                 : <number>   // Natural32
"vertical"               : <string>   // Boolean
"gap"                    : <number>   // Integer32
"paddingLeft"            : <number>   // Integer32
"paddingBottom"          : <number>   // Integer32
"paddingRight"           : <number>   // Integer32
"paddingTop"             : <number>   // Integer32
"mainAlignment"          : <string>
"crossAlignment"         : <string>
"children"               : <list of strings>   // references to user-interface definitions
"backgroundModel"        : <string>   // optional, reference to a Model definition
"backgroundBorderWidth"  : <number>   // optional, Natural32, defaults to 0
      

The vertical entry selects the stack axis. Each element of the children list names a child definition; the children are added in list order. While linking, the backgroundModel reference, when present, is resolved.

UI.SegmentedChoice

Type name: "UI.SegmentedChoice". A user-interface control that offers a choice among labeled segments.

"type"           : "UI.SegmentedChoice"
"name"           : <string>
"left"           : <number>   // Integer32
"bottom"         : <number>   // Integer32
"width"          : <number>   // Natural32
"height"         : <number>   // Natural32
"selectedIndex"  : <number>   // Natural32
"labels"         : <list of strings>   // the segment labels
"pixelSize"      : <number>   // optional, Natural32, defaults to 24
"borderWidth"    : <number>   // optional, Natural32, defaults to 0
"borderRed"      : <number>   // optional, Natural8, defaults to 87
"borderGreen"    : <number>   // optional, Natural8, defaults to 104
"borderBlue"     : <number>   // optional, Natural8, defaults to 118
      

The labels list holds the text of each segment in order; the selectedIndex entry selects one of them. The labels strings are segment text, not references.

UI.Slider

Type name: "UI.Slider". A user-interface control that selects a value within a range.

"type"    : "UI.Slider"
"name"    : <string>
"left"    : <number>   // Integer32
"bottom"  : <number>   // Integer32
"width"   : <number>   // Natural32
"height"  : <number>   // Natural32
"minimum" : <number>   // Real64
"maximum" : <number>   // Real64
"value"   : <number>   // Real64
"step"    : <number>   // Real64
      

The four range entries describe the selection interval and the increment the control snaps to. No entry of this definition is optional.

UI.Toggle

Type name: "UI.Toggle". A user-interface control that is either on or off.

"type"    : "UI.Toggle"
"name"    : <string>
"left"    : <number>   // Integer32
"bottom"  : <number>   // Integer32
"width"   : <number>   // Natural32
"height"  : <number>   // Natural32
"checked" : <string>   // Boolean
      

Definitions without a reader

The Arcadia.ADL module defines three further user-interface definition types, "Canvas", "Container", and "ScrollPanel", that share the container interface "UI.StackPanel" implements. No reader is registered for them, so an asset cannot carry them as its type entry; they occur only in the C interface of the module. This document does not specify their entries.

7 Enumerations

Several string entries are enumerated. The literal of an enumeration element is a string, and an unknown literal is a semantical error. In the C interface of the Arcadia.ADL module each enumeration is a type of its own, and the None element is its default. The literals are:

• BlendFunction: "Zero", "One", "SourceColor", "OneMinusSourceColor", "DestinationColor", "OneMinusDestinationColor", "SourceAlpha", "OneMinusSourceAlpha", "DestinationAlpha", "OneMinusDestinationAlpha".
• AmbientColorSource: "Mesh", "Vertex", "Texture", "TextureVertex".
• MaterialType: "Blinn-Phong".
• TextureFilter: "Linear", "Nearest".
• TextureAddressMode: "ClampToBorder", "ClampToEdge", "MirroredRepeat", "Repeat".

The alignment strings of section 6 are not drawn from an enumeration at the language level: the user-interface reader stores whatever string it is given. Boolean string values are likewise accepted as spelled by the DDL scanner, that is, as "true" and "false".

8 Registered type names

The Arcadia.ADL module registers exactly one reader per type name below. A type entry not listed here is a semantical error. The table is complete as of this draft and is the authoritative inventory of asset types; the sections that specify the types give the entry lists.

Graph composition uses separate front-end forms, including GraphDefinition and GraphInstance. They are processed by the graph batch entry point, not registered as asset readers.

Type name	Section
"Color"	4 Visuals definitions
"Mesh"	4 Visuals definitions
"BoxMeshGenerator"	4 Visuals definitions
"PlaneMeshGenerator"	4 Visuals definitions
"SphereMeshGenerator"	4 Visuals definitions
"PixelBuffer"	4 Visuals definitions
"PixelBufferOperations.FillOperation"	4 Visuals definitions
"PixelBufferOperations.CheckerboardFillOperation"	4 Visuals definitions
"Texture"	4 Visuals definitions
"Material"	4 Visuals definitions
"Model"	4 Visuals definitions
"SampleBuffer"	5 Audials definitions
"DSP.Constant"	5 Audials definitions
"DSP.SineWave"	5 Audials definitions
"DSP.SawtoothWave"	5 Audials definitions
"DSP.WhiteNoise"	5 Audials definitions
"DSP.Gain"	5 Audials definitions
"DSP.LowPass"	5 Audials definitions
"DSP.Mix"	5 Audials definitions
"UI.Button"	6 User interface definitions
"UI.Label"	6 User interface definitions
"UI.StackPanel"	6 User interface definitions
"UI.SegmentedChoice"	6 User interface definitions
"UI.Slider"	6 User interface definitions
"UI.Toggle"	6 User interface definitions

The three operator type names share one reader. The base type MeshGenerator is not among them, so no asset may use it as its type entry; it occurs only in the requirement on the mesh entry of a "Model" definition in section 4. The definition types "Canvas", "Container", and "ScrollPanel" of section 6 have no reader and therefore do not appear.

9 Graph composition

Graph composition is an opt-in source expansion pass over a batch of DDL map nodes. It produces ordinary ADL definitions before normal linking; it is not a runtime graph interpreter. Callers use Arcadia_ADL_Graphs_readFromNodes, not an ordinary asset reader, to process the front-end forms below.

Templates, instances and parameters

A GraphDefinition has a nonempty name and a nodes list of local maps with distinct names. A GraphInstance has a nonempty name, a graph naming its template, and a bindings list. Templates and instances are collected before expansion, so a template need not precede its instance in the batch. The name segment __graph is reserved for generated names.

Each template has exactly one Graph.Output with name, referenceType and source strings. A Graph.Parameter declares either referenceType: "Color" or valueType: "Integer32", not both. Reference bindings use { parameter: "P", source: "Existing.Definition" }; value bindings use { parameter: "P", value: 440 }. Missing, duplicate and unknown parameter bindings are rejected. A reference binding must name an existing definition; its existence alone does not establish that definition's type.

[
  {
    type: "GraphDefinition", name: "Templates.Tone",
    nodes: [
      { type: "Graph.Parameter", name: "Frequency", valueType: "Integer32" },
      { type: "DSP.SineWave", name: "tone", frequency: "Frequency" },
      { type: "Graph.Output", name: "output", referenceType: "DSP.SineWave", source: "tone" }
    ]
  },
  {
    type: "GraphInstance", name: "Sounds.Tone", graph: "Templates.Tone",
    bindings: [ { parameter: "Frequency", value: 440 } ]
  }
]
      

The example generates a sine-wave definition named Sounds.Tone.output. It does not itself render audio.

A dual-tone template can combine two sine nodes using the existing DSP.Mix definition. Its inputs is a nonempty, ordered list of local DSP names; each target must be a DSP.SineWave or another DSP.Mix. Repeated references remain repeated entries, not a deduplicated input list.

[
  {
    type: "GraphDefinition", name: "Templates.DualTone",
    nodes: [
      { type: "Graph.Parameter", name: "Low", valueType: "Integer32" },
      { type: "Graph.Parameter", name: "High", valueType: "Integer32" },
      { type: "DSP.SineWave", name: "low", frequency: "Low" },
      { type: "DSP.SineWave", name: "high", frequency: "High" },
      { type: "DSP.Mix", name: "mix", inputs: ["high", "low"] },
      { type: "Graph.Output", name: "output", referenceType: "DSP.Mix", source: "mix" }
    ]
  },
  {
    type: "GraphInstance", name: "Sounds.DualTone", graph: "Templates.DualTone",
    bindings: [ { parameter: "Low", value: 220 }, { parameter: "High", value: 880 } ]
  },
  { type: "SampleBuffer", name: "Sounds.Buffer", duration: 1, dsp: "Sounds.DualTone.output" }
]
      

This generates Sounds.DualTone.__graph.high, Sounds.DualTone.__graph.low, and one published mix at Sounds.DualTone.output. Linking the ordinary SampleBuffer.dsp reference resolves that published mix. Separate instances receive distinct generated definitions. Local declaration order does not change generated names or the order of mix input references. This is source expansion into the existing native ADL/Media DSP path, not new sample-processing functionality or a runtime graph interpreter.

Current supported surface

Category	Accepted forms
Ordinary graph-local nodes	Color, PixelBuffer, PixelBufferOperations.FillOperation, PixelBufferOperations.CheckerboardFillOperation, DSP.SineWave, DSP.Mix
Output referenceType	PixelBuffer, DSP.SineWave or DSP.Mix
Reference-field rewriting	CheckerboardFillOperation's firstCheckerColor/secondCheckerColor; PixelBuffer's operations list; DSP.Mix's ordered inputs list
Value-field substitution	DSP.SineWave.frequency from an Integer32 parameter

Other string fields are not automatically treated as graph references. Sine frequency bindings must be Integer32 numbers. Negative bindings are rejected by the existing graph binding check; zero passes that check but is rejected when the expanded node is read by the ordinary SineWave reader. In both cases the graph batch read raises Arcadia_Status_SemanticalError, before Engine or Media construction. Valid oscillator asset frequency is strictly positive (1..INT32_MAX); zero does not mean silence. The graph expander does not duplicate the ordinary-reader domain rule. Ordinary reader support for DSP.Gain or DSP.LowPass does not make those types valid graph-local nodes. DSP reference parameters are not supported: reference parameters remain Color-only. Multiple outputs, nested graph instances, general value types and parameter defaults are not supported by this front end.

Generated names and processing order

For instance I, an internal node L is named I.__graph.L. The output's source is instead named I.outputName; it is not also emitted under its internal name. Parameter and output declaration nodes are not ordinary asset definitions and do not receive reader registrations. The caller links the resulting definitions with Arcadia_ADL_Definitions_link afterward.

Ordinary batch definitions are read first, allowing bindings to refer to them. All instance bindings and generated nodes are then validated/staged before generated-node reading starts. Publication reads those nodes one at a time. This is not a whole-batch transaction: an error can leave ordinary definitions or an already-read prefix of generated definitions in the destination. No rollback guarantee for reader or allocation failures is established by staging alone.

Validation limits

Output referenceType is allow-listed but is not cross-checked against its source's type. The collector rejects unresolved names in its registered reference fields, references to Graph.Output, incompatible reference families, and cycles among local reference edges with Arcadia_Status_SemanticalError. Mix inputs must target supported local DSP nodes, not parameters or external definition names. These checks cover the registered fields above, not every string field of every asset: in particular, FillOperation has no registered reference-field descriptor. Ordinary readers and linking retain their own validation responsibilities.

Expanded Mix nodes retain the ordered unity-gain summation contract of ordinary DSP.Mix: no normalization, clamping, compression, limiting or automatic gain compensation. Duplicate references are rendered and added individually, and samples outside [-1, +1] are valid in the floating-point graph. The graph-local inputs list remains nonempty even though the native Media mixer can emit zero-input silence. Output conversion and optional gain/limiter nodes are separate concerns. Source expansion alone does not prove rendered sample equivalence or cross-platform bit-identical audio.

Identical fresh deterministic graphs must repeat bitwise within the same controlled binary/runtime/FP environment, including topology, input order, sample rate, configuration and seeds. For supported streaming topologies, sequential chunks reproduce the one-shot sequence. GraphDualTone compares fresh and partial-chunk samples byte-for-byte; its numerical sine-sum reference is a separate tolerance check. Native Media graph seed/reset propagation follows stored node order. Shared or duplicate stateful runtime subgraphs are not automatically covered by partition independence: native rendering evaluates each reference and provides no output cache. Cross-platform validation needs operator-specific numerical tolerances and multiple executed platform gates; no cross-platform bitwise identity is promised, and source expansion alone establishes none of those numerical gates.