Expand description
Bindings to Synthizer. For documentation of the library itself, see the book. This documentation covers aspects specific to the Rust bindings which map to the C bindings in a relatively straightforward manner
Handles
Synthizer Handles are reference-counted pointers which work like Arc
. All
the objects in this library that correspond to Synthizer objects (e.g.
BufferGenerator but not CustomStreamDef) impl Clone and internally
contain a handle. So, e.g:
use synthizer as syz;
let ctx = syz::Context::new()?;
// Refers to the same context.
let ctx2 = ctx.clone();
Initialization
To initialize the library, use either initialize or the LibraryConfig type. These will give you a InitializationGuard which must be kept alive for the duration of the program. After the InitializationGuard goes out of scope, Synthizer functions all error.
Properties
Properties are modeled as a property()
method which returns an
intermediate object that has methods on it. For example,
obj.playback_position().set(5.0)
. Object properties aren’t type checked
but error if using an object of the wrong type at runtime. An internal
trait, ToSyzHandle
, is implemented for all library types.
Common Functionality
All Synthizer objects implement a set of common methods on their struct.
When the Synthizer manual refers to things like syz_pause
, this can be
found as .pause()
on all applicable objects.
Userdata
Synthizer supports userdata, which can be used to tie application entities
to Synthizer objects via Arc<Any>
. This is set by e.g.
Handle::set_userdata. Note that unlike Synthizer itself, the Rust
bindings have to put userdata behind a std::sync::RwLock to offer thread
safety,.
Casting Objects
Synthizer itself is modeled as a hierarchy of “classes”. For example
Source is a “base class” of all sources. This is handled in Rust via
adding a cast_to
method to all Synthizer types, which can be used to
attempt to cast to other object types when possible. For example Source3D
to Source, but also Handle to Source3D.
Where this cast is infallible, From
impls are provided.
Custom Streams
Custom streams are possible via CustomStreamDef and register_stream_protocol. See the documentation on those types for more info. In general, it is possible to convert anything implementing std::io::Read and std::io::Seek to a custom stream by implementing CloseStream for that type or a wrapper struct thereof.
Optional Features
Synthizer has the following optional features:
asset_lru
: Enable support forasset_lru
viaAssetLruDecoder
, which implements theasset_lru
decoding traits.
Structs
Context
represents an audio device.DeleteBehaviorConfig
.InitializationGuard
shuts Synthizer down when dropped, and must be kept
alive for the duration of your program..initialize()
.new
and Default
are the equivalent of
syz_initRouteConfig
, e.g. a builder representing the default route.StreamHandle
binds Synthizer custom streams, as well as other kinds of
streaming functionality.Enums
Other
, since Synthizer hasn’t yet defined error
codes properly.Constants
Traits
Functions
(major, minor, patch)
tuple. This isn’t the version of the crate, but of the bound library.InitializationGuard
which must be kept
alive for the duration of your program.Type Definitions
syz_EchoTapConfig
type. Using this instead of a
dedicated struct prevents needing to clone your taps on the way to
Synthizer.