Arcadia ADL Concepts and Terms
This document introduces the concepts and terms used by the Arcadia asset
definition language, Arcadia ADL for short, and by the Arcadia.ADL
module that processes it.
Assets and definitions
An asset is a piece of data that an application needs in order to run, such as a color, a material, a mesh, a model, a texture, a pixel buffer, or a sample buffer. Assets are stored as text files and are collected next to the programs that use them.
ADL assets describe definitions. A definition has a name and a
type. Names are fully-qualified, dot-separated strings that are unique
within an application, for example Colors.Red. The type selects
the kind of definition and therefore the reader that processes the asset.
Definitions, the container
The Arcadia.ADL.Definitions type is a container that maps
definition names to definitions. An application reads all of its assets into a
single container and then links the container, at which point every reference
between definitions is resolved.
Readers and the context
A reader processes the assets of one definition type. Each reader owns the schema of its type: a description, written in the Arcadia Data Definition Schema Language (Arcadia DDLS), of the map entries a definition of this type may and must have, and of the type of each entry. Before a reader constructs a definition it validates the asset against its schema; an asset that violates its schema is rejected with a semantical error.
The Arcadia.ADL.Context type is a registry of readers. A context
maps the string type entry of an asset to the reader of that type;
reading an asset whose type has no reader is an error.
References
Many definitions refer to other definitions. A reference names another
definition; in the ADL text a reference is written as a string that contains
the fully-qualified name of the referenced definition. While an asset is being
read, a reference is stored as a Arcadia.ADL.Reference, which
holds the name of the referenced definition but not yet the definition itself.
References are resolved during linking. Resolving a reference looks the name
up in the container of definitions. If the referenced definition does not
exist, a not-found error is raised. A definition may further require that a
reference points to a definition of a particular type; for example, the
pixelBuffer entry of a texture must reference a pixel-buffer
definition.
Two phases: reading and linking
Processing ADL assets is split into two phases:
- In the reading phase the text of each asset is parsed into a DDL map, validated against the schema of its type, and turned into a definition. Definitions created in this phase hold unresolved references.
- In the linking phase every reference is resolved and every required type check is performed. Linking is idempotent: resolving an already resolved reference does nothing.
The two phases may be interleaved by reading further assets after a partial link, because linking only needs the referenced definitions to be present in the container when it is performed.
The definition graph
A definition graph is distinct from the opt-in graph-composition front end. That front end expands named templates and parameterized instances into ordinary definitions before linking; it is not a runtime interpreter or an additional mixer. Its supported local types and validation limits are specified separately.
Definitions and their references form a directed acyclic graph. Typical edges of this graph are:
- a material references the texture it uses as its ambient-color source,
- a texture references the pixel buffer it samples,
- a pixel buffer references the fill operations that produce its content,
- a fill operation references the colors it uses,
- a model references the mesh and the material it is rendered with,
- a mesh references the color of its vertices, and
- a sample buffer references the digital signal processing definition that synthesizes it.
Linking a definition also links the definitions it references, so linking the container links the whole graph.
Defaults and the engine
Some definition types have entries whose meaning is given by an enumeration
and that may be omitted. An omitted entry is represented by the
None element of the enumeration; it selects the default of the
engine that consumes the definition. For example, the context sampling
properties of a texture, magnificationFilter,
minificationFilter, addressModeU, and
addressModeV, may be omitted; the engine then uses its own
default filters and address modes.
Terminology
The following table lists recurring terms of this documentation.
| Term | Meaning |
|---|---|
| asset | A text file that describes a definition. |
| definition | A named, typed description processed from an asset. |
| reference | A link from one definition to another definition, by name. |
| reader | An object that validates and processes the assets of one type. |
| schema | The description of the map entries a definition of a type may and must have. |
| linking | The resolution of all references of a container of definitions. |