[][src]Crate lv2rs_atom

The purpose of this crate is to provide safe, idiomatic and easy-to-use means to use the type system introduced by the LV2 atom library. This type system is (relatively) portable and can be used to exchange information of arbitrary type among LV2 plugins.

This is a frozen prototype and therefore, development of this crate will not continue here. Further development continues as rust-lv2.

What are atoms?

On an abstract level, every atom consist of a header, which contains the URID of the atom type and a size in bytes, and body, a chunk of memory with the specified size. The interpretation of this body is dependent on the atom type and one of the features of this crate. Since this data is supposed to be "plain old data" and therefore must not contain references to other objects, the host does not need to "understand" the atoms; It simply copies the data.

There are several types of atoms which can be used to express almost any data:

  • Numbers: All types that implement the ScalarAtomBody trait:
    • f32
    • f64
    • i32
    • i64
    • bool
    • URID
  • Literal: A proper UTF-8 string.
  • Object: Compound type similar to tuples that maps URIDs to atoms.
  • Sequence: Tuple with additional time stamps for every atom. Usually used for frame-perfect, event-based data.
  • AtomString: An old-school ASCII string, also used for URIs.
  • Tuple: Heterogenous array of atoms, including dynamically sized ones.
  • Vector: Homogenous array of sized atoms, like numbers.

How does it work?


In vanilla LV2, everything is expressed with floating-point numbers. The host passes a pointer to a floating pointer number to the plugin and the plugin uses the number the pointer points to. Reading atoms is similiar, but not completely the same:

The host passes a pointer to an atom header to the plugin. Now, the plugin has to interpret this header. It looks at the size and the type noted in the header and tries to "widen" the reference to a fully-grown atom reference. Since this might be a delicate task, it is done by the AtomInputPort. Some atoms are easy to use, for example floats, but some require special methods to be usefull.


If a plugin has to write information to an atom port, the host provides the plugin with a pointer to a chunk of free space it can write to. An AtomOutputPort can interpret this pointer and creates a writing frame for it using the write_atom_body method.

Such writing frames are able to write data to the provided chunk. However, most of their methods are unsafe since they do not check the resulting output for meaningfulness. Instead, you should use the safe methods provided by the writing frame extensions, which are tailored for specific atoms and guarantee the consistency of the resulting output. You can read more about them in their specific module descriptions.



Special templates for dynamically sized atoms.


Raw writing access to chunks of memory.


UTF-8-encoded string.


Object- or Map-style atom container.


Wrappers for raw atom IO.


Re-exportation module that contains all traits necessary to use lv2rs-atom.


Scalar (number-like) atoms


Atom tuple with time stamps for every contained atom.


ASCII string.


Heterogenous array of sized and unsized atoms.


URIs of the atom library.


Homogenous array of sized atoms.



Marker or header of an atom data structure.


Iterator over atoms.



Errors that may occur when calling Atom::get_body.



Abstraction of atom bodies.