1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
//! 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](https://github.com/rust-dsp/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`](scalar/trait.ScalarAtomBody.html) //! trait: //! * `f32` //! * `f64` //! * `i32` //! * `i64` //! * `bool` //! * `URID` //! * [`Literal`](literal/index.html): A proper UTF-8 string. //! * [`Object`](object/index.html): Compound type similar to tuples that maps URIDs to atoms. //! * [`Sequence`](sequence/index.html): Tuple with additional time stamps for every atom. //! Usually used for frame-perfect, event-based data. //! * [`AtomString`](string/index.html): An old-school ASCII string, also used for URIs. //! * [`Tuple`](tuple/index.html): Heterogenous array of atoms, including dynamically sized //! ones. //! * [`Vector`](vector/index.html): 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`](ports/struct.AtomInputPort.html). 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`](ports/struct.AtomOutputPort.html) //! can interpret this pointer and creates a writing frame for it using the //! [`write_atom_body`](ports/struct.AtomOutputPort.html#method.write_atom_body) method. //! //! Such [writing frames](frame/trait.WritingFrame.html) 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. extern crate lv2rs_urid as urid; mod atom; pub mod frame; pub mod literal; pub mod object; pub mod ports; pub mod scalar; pub mod sequence; pub mod string; pub mod tuple; pub mod uris; pub mod vector; pub use atom::*; /// Re-exportation module that contains all traits necessary to use lv2rs-atom. pub mod prelude { pub use crate::frame::{WritingFrame, WritingFrameExt}; pub use crate::scalar::ScalarAtomBody; // Atom bodies. pub use crate::atom::{Atom, AtomBody}; pub use crate::{ literal::Literal, object::Object, sequence::Sequence, string::AtomString, tuple::Tuple, vector::Vector, }; // Writing frame extensions pub use crate::{ literal::LiteralWritingFrame, object::ObjectWritingFrame, sequence::SequenceWritingFrame, tuple::TupleWritingFrame, vector::VectorWritingFrame, }; }