lv2rs_atom/
lib.rs

1//! The purpose of this crate is to provide safe, idiomatic and easy-to-use means to use the type
2//! system introduced by the LV2 atom library. This type system is (relatively) portable and can be
3//! used to exchange information of arbitrary type among LV2 plugins.
4//! 
5//! This is a frozen prototype and therefore, development of this crate will not continue here. Further
6//! development continues as [rust-lv2](https://github.com/rust-dsp/rust-lv2).
7//!
8//! ## What are atoms?
9//!
10//! On an abstract level, every atom consist of a header, which contains the URID of the atom type
11//! and a size in bytes, and body, a chunk of memory with the specified size. The interpretation of
12//! this body is dependent on the atom type and one of the features of this crate. Since this data is
13//! supposed to be "plain old data" and therefore must not contain references to other objects,
14//! the host does not need to "understand" the atoms; It simply copies the data.
15//!
16//! There are several types of atoms which can be used to express almost any data:
17//!
18//! * Numbers: All types that implement the [`ScalarAtomBody`](scalar/trait.ScalarAtomBody.html)
19//! trait:
20//!     * `f32`
21//!     * `f64`
22//!     * `i32`
23//!     * `i64`
24//!     * `bool`
25//!     * `URID`
26//! * [`Literal`](literal/index.html): A proper UTF-8 string.
27//! * [`Object`](object/index.html): Compound type similar to tuples that maps URIDs to atoms.
28//! * [`Sequence`](sequence/index.html): Tuple with additional time stamps for every atom.
29//! Usually used for frame-perfect, event-based data.
30//! * [`AtomString`](string/index.html): An old-school ASCII string, also used for URIs.
31//! * [`Tuple`](tuple/index.html): Heterogenous array of atoms, including dynamically sized
32//! ones.
33//! * [`Vector`](vector/index.html): Homogenous array of sized atoms, like numbers.
34//!
35//! ## How does it work?
36//!
37//! ### Reading
38//!
39//! In vanilla LV2, everything is expressed with floating-point numbers. The host passes a pointer
40//! to a floating pointer number to the plugin and the plugin uses the number the pointer points to.
41//! Reading atoms is similiar, but not completely the same:
42//!
43//! The host passes a pointer to an atom header to the plugin. Now, the plugin has to interpret this
44//! header. It looks at the size and the type noted in the header and tries to "widen" the reference
45//! to a fully-grown atom reference. Since this might be a delicate task, it is done by the
46//! [`AtomInputPort`](ports/struct.AtomInputPort.html). Some atoms are easy to use, for example
47//! floats, but some require special methods to be usefull.
48//!
49//! ### Writing
50//!
51//! If a plugin has to write information to an atom port, the host provides the plugin with a pointer
52//! to a chunk of free space it can write to. An [`AtomOutputPort`](ports/struct.AtomOutputPort.html)
53//! can interpret this pointer and creates a writing frame for it using the
54//! [`write_atom_body`](ports/struct.AtomOutputPort.html#method.write_atom_body) method.
55//!
56//! Such [writing frames](frame/trait.WritingFrame.html) are able to write data to the provided
57//! chunk. However, most of their methods are unsafe since they do not check the resulting output
58//! for meaningfulness. Instead, you should use the safe methods provided by the writing frame
59//! extensions, which are tailored for specific atoms and guarantee the consistency of the resulting
60//! output. You can read more about them in their specific module descriptions.
61extern crate lv2rs_urid as urid;
62
63mod atom;
64pub mod frame;
65pub mod literal;
66pub mod object;
67pub mod ports;
68pub mod scalar;
69pub mod sequence;
70pub mod string;
71pub mod tuple;
72pub mod uris;
73pub mod vector;
74
75pub use atom::*;
76
77/// Re-exportation module that contains all traits necessary to use lv2rs-atom.
78pub mod prelude {
79    pub use crate::frame::{WritingFrame, WritingFrameExt};
80    pub use crate::scalar::ScalarAtomBody;
81
82    // Atom bodies.
83    pub use crate::atom::{Atom, AtomBody};
84    pub use crate::{
85        literal::Literal, object::Object, sequence::Sequence, string::AtomString, tuple::Tuple,
86        vector::Vector,
87    };
88
89    // Writing frame extensions
90    pub use crate::{
91        literal::LiteralWritingFrame, object::ObjectWritingFrame, sequence::SequenceWritingFrame,
92        tuple::TupleWritingFrame, vector::VectorWritingFrame,
93    };
94}
lv2rs_atom/lib.rs

lv2rs_atom/
lib.rs
