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?

Reading

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.

Writing

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.

Modules

array	Special templates for dynamically sized atoms.
frame	Raw writing access to chunks of memory.
literal	UTF-8-encoded string.
object	Object- or Map-style atom container.
ports	Wrappers for raw atom IO.
prelude	Re-exportation module that contains all traits necessary to use lv2rs-atom.
scalar	Scalar (number-like) atoms
sequence	Atom tuple with time stamps for every contained atom.
string	ASCII string.
tuple	Heterogenous array of sized and unsized atoms.
uris	URIs of the atom library.
vector	Homogenous array of sized atoms.

Structs

Atom	Marker or header of an atom data structure.
AtomIterator	Iterator over atoms.

Enums

GetBodyError

Errors that may occur when calling Atom::get_body.

Traits

AtomBody

Abstraction of atom bodies.