atom-port
type: Specification
name: LV2 Atom Port
maintainer: David Robillard
comment: This extension describes port types that hold polymorphic values (atom:Atom). There are two such port types with equivalent buffer formats but different semantics: value ports (aport:ValuePort) and message ports (aport:MessagePort).

Atom Port
type: Class
subclass of: Port
comment: A port which contains a polymorphic value, or "atom". Ports of this type will be connected to a 32-bit aligned atom:Atom (i.e. a uint32_t type, immediately followed by a uint32_t size, immediately followed by that many bytes of data). This is an abstract port type. A port that is a aport:AtomPort MUST also have a more descriptive type that is a subClassOf aport:AtomPort which defines the port's semantics (typically aport:ValuePort or aport:MessagePort). Before calling a method on the plugin that writes to an AtomPort output, the host MUST set the size of the Atom in that output to the amount of available memory immediately following the Atom header. The plugin MUST write a valid Atom to that port (leaving it untouched is illegal). If there is no reasonable value to write to the port, the plugin MUST write null (the atom with both type and size equal to zero).

Value Port
type: Class
subclass of: Atom Port
comment: An AtomPort that interprets its data as a persistent and time-independent "value". If a plugin has fixed input values for all ports, all ValuePort outputs are also fixed regardless of the number of times the plugin is run. If a plugin has fixed input values for all ports except a ValuePort, each value V of that ValuePort corresponds to a single set of outputs for all ports. If an aport:ValuePort contains a reference then the blob it refers to is constant; plugin MUST NOT modify the blob in any way. Value ports can be thought of as purely functional ports: if a plugin callback has only value ports, then the plugin callback is a pure function.

Message Port
type: Class
subclass of: Atom Port
comment: An AtomPort that consumes or executes its value as a "message". The contents of a MessagePort are considered transient and/or time-dependent, and only apply for a single run invocation. Unlike a ValuePort, a MessagePort may be used to manipulate and access internal plugin state. Intuitively, a MessagePort contains a "command" or "event" (which is reacted to), NOT a "value" or "signal" (which is computed with).

supports
type: Property
domain: Port
range: AtomType
comment: Indicates that an atom port supports a certain value type. This is distinct from the port type - e.g. the port type ValuePort can hold atoms with many different types. This property is used to describe which atom types a port ``understands''.