pub trait Driver: Send + Sync {
Show 53 methods
// Required methods
fn info(&self) -> &'static Info;
fn capabilities(&self) -> &'static Capabilities;
fn fields(&self) -> &'static [FieldInfo];
fn name_rules(&self) -> NameRules;
fn init_program(&self) -> Vec<u8> ⓘ;
fn check_program(&self, program: &[u8]) -> Result<(), DriverError>;
fn get(&self, program: &[u8], field: usize) -> Result<u16, DriverError>;
fn set(
&self,
program: &mut [u8],
field: usize,
value: u16,
) -> Result<(), DriverError>;
fn name(&self, program: &[u8]) -> Result<String, DriverError>;
fn set_name(
&self,
program: &mut [u8],
name: &str,
) -> Result<(), DriverError>;
fn file_formats(&self) -> &'static [FileFormat];
fn import(
&self,
ext: &str,
bytes: &[u8],
) -> Result<LibraryData, DriverError>;
fn export(
&self,
ext: &str,
lib: &LibraryData,
) -> Result<Vec<u8>, DriverError>;
fn curation(&self) -> Curation;
fn session(&self, channel: u8) -> Box<dyn DriverSession>;
fn simulator(&self) -> Box<dyn Simulator>;
fn port_hint(&self) -> &'static [&'static str];
fn recognize(&self, identity_reply: &[u8]) -> bool;
// Provided methods
fn control(&self, _program: &[u8], field: usize) -> Control { ... }
fn short_label(&self, field: usize) -> &'static str { ... }
fn label_in(&self, _program: &[u8], field: usize) -> Cow<'static, str> { ... }
fn emphasized(&self, _field: usize) -> bool { ... }
fn format_value(&self, program: &[u8], field: usize) -> String { ... }
fn format_raw(&self, field: usize, raw: u16) -> String { ... }
fn page_summary(&self, _program: &[u8], _page: usize) -> String { ... }
fn graphs(
&self,
_program: &[u8],
_page: usize,
_points: usize,
) -> Vec<Graph> { ... }
fn handles(&self, _program: &[u8], _page: usize) -> Vec<Handle> { ... }
fn drag(
&self,
_program: &[u8],
_page: usize,
_handle: usize,
_at: (f32, f32),
) -> Vec<(usize, u16)> { ... }
fn relevant(&self, _program: &[u8], _field: usize) -> bool { ... }
fn help(&self, _field: usize) -> Help { ... }
fn category(&self, _program: &[u8]) -> Option<&'static str> { ... }
fn categories(&self) -> &'static [&'static str] { ... }
fn mutability(&self, _field: usize) -> Mutability { ... }
fn characters(&self) -> &'static [Character] { ... }
fn macro_info(&self) -> [MacroInfo; 4] { ... }
fn generated_name(&self, character: usize, seed: u64) -> String { ... }
fn generate(
&self,
_recipe: &Recipe,
_base: Option<&[u8]>,
) -> Result<Vec<u8>, DriverError> { ... }
fn vary(
&self,
_program: &[u8],
_amount: f32,
_seed: u64,
) -> Result<Vec<u8>, DriverError> { ... }
fn breed(
&self,
_a: &[u8],
_b: &[u8],
_mix: f32,
_seed: u64,
) -> Result<Vec<u8>, DriverError> { ... }
fn needs(&self, _program: &[u8]) -> Vec<(UnitKind, u8)> { ... }
fn unit_param(
&self,
_program: &[u8],
_field: usize,
) -> Option<(UnitKind, u8, usize)> { ... }
fn morph(
&self,
a: &[u8],
b: &[u8],
t: f32,
seed: u64,
) -> Result<Vec<u8>, DriverError> { ... }
fn live_messages(
&self,
_program: &[u8],
_field: usize,
_channel: u8,
) -> Option<Vec<Vec<u8>>> { ... }
fn demo_library(&self) -> LibraryData { ... }
fn demo_simulator(&self) -> Box<dyn Simulator> { ... }
fn list_facet(&self) -> Option<usize> { ... }
fn firmware(&self, _identity_reply: &[u8]) -> Option<String> { ... }
fn program_slot(
&self,
_bank_msb: u8,
_bank_lsb: u8,
_program: u8,
) -> Option<u16> { ... }
fn panel_listener(&self) -> Option<Box<dyn PanelListener>> { ... }
fn setup_hint(&self) -> &'static str { ... }
fn tier(&self) -> u8 { ... }
fn voices(&self) -> &'static [u8] ⓘ { ... }
fn page_summary_in(
&self,
program: &[u8],
page: usize,
_compact: bool,
_tr: &dyn Fn(&str) -> String,
) -> String { ... }
}Expand description
One synth model: everything the apps know about it. Object-safe, so
apps can hold several at once, as &dyn Driver. A driver crate exposes
one as pub static DRIVER.
Methods without a default are required. The others have a default that suits a driver which does not use them.
Required Methods§
Sourcefn capabilities(&self) -> &'static Capabilities
fn capabilities(&self) -> &'static Capabilities
What the synth can do. Apps show only what this lists.
Sourcefn fields(&self) -> &'static [FieldInfo]
fn fields(&self) -> &'static [FieldInfo]
The program’s parameters. A field’s index in this slice is the
field argument of the other methods.
Sourcefn name_rules(&self) -> NameRules
fn name_rules(&self) -> NameRules
The limits of a program’s name.
Sourcefn init_program(&self) -> Vec<u8> ⓘ
fn init_program(&self) -> Vec<u8> ⓘ
A new program, valid, with a name that Driver::name_rules allow.
Sourcefn check_program(&self, program: &[u8]) -> Result<(), DriverError>
fn check_program(&self, program: &[u8]) -> Result<(), DriverError>
Refuses bytes that are not a whole, valid program.
Sourcefn get(&self, program: &[u8], field: usize) -> Result<u16, DriverError>
fn get(&self, program: &[u8], field: usize) -> Result<u16, DriverError>
The raw value of field in program. An error for a bad program
or field index.
Sourcefn set(
&self,
program: &mut [u8],
field: usize,
value: u16,
) -> Result<(), DriverError>
fn set( &self, program: &mut [u8], field: usize, value: u16, ) -> Result<(), DriverError>
Sets field in program to value, and changes no other field. An
error for a bad program, a bad field index, or a value outside
min..=max.
Sourcefn name(&self, program: &[u8]) -> Result<String, DriverError>
fn name(&self, program: &[u8]) -> Result<String, DriverError>
The program’s name, without padding.
Sourcefn set_name(&self, program: &mut [u8], name: &str) -> Result<(), DriverError>
fn set_name(&self, program: &mut [u8], name: &str) -> Result<(), DriverError>
Sets the program’s name. An error for a name that
Driver::name_rules refuse.
Sourcefn file_formats(&self) -> &'static [FileFormat]
fn file_formats(&self) -> &'static [FileFormat]
The synth’s own file formats that the driver reads and writes, the usual one first. Can be empty.
Sourcefn import(&self, ext: &str, bytes: &[u8]) -> Result<LibraryData, DriverError>
fn import(&self, ext: &str, bytes: &[u8]) -> Result<LibraryData, DriverError>
Read a vendor file of format ext.
Sourcefn export(&self, ext: &str, lib: &LibraryData) -> Result<Vec<u8>, DriverError>
fn export(&self, ext: &str, lib: &LibraryData) -> Result<Vec<u8>, DriverError>
Write a vendor file of format ext; import of the result gives
back lib.
Sourcefn curation(&self) -> Curation
fn curation(&self) -> Curation
Pages and sections of the editor. Required: a simple driver may
return curation_by_group(self.fields()), but says so on
purpose.
Sourcefn session(&self, channel: u8) -> Box<dyn DriverSession>
fn session(&self, channel: u8) -> Box<dyn DriverSession>
A new session with one synth that listens on MIDI channel
channel (0-15). A driver whose SysEx has no channel ignores it.
Sourcefn simulator(&self) -> Box<dyn Simulator>
fn simulator(&self) -> Box<dyn Simulator>
A new simulated synth, for the conformance suite and the tests.
Sourcefn port_hint(&self) -> &'static [&'static str]
fn port_hint(&self) -> &'static [&'static str]
Substrings of the MIDI port names this synth shows up as.
Sourcefn recognize(&self, identity_reply: &[u8]) -> bool
fn recognize(&self, identity_reply: &[u8]) -> bool
Whether identity_reply, an answer to
crate::sysex::DEVICE_INQUIRY, comes from this synth.
Provided Methods§
Sourcefn control(&self, _program: &[u8], field: usize) -> Control
fn control(&self, _program: &[u8], field: usize) -> Control
The widget for field. It may depend on other fields of program
(a depth that names chords in one mode and is a dial in another), so
apps query it again after an edit and rebuild the control when it
changes.
Sourcefn short_label(&self, field: usize) -> &'static str
fn short_label(&self, field: usize) -> &'static str
A compact label for use inside a titled section.
Sourcefn label_in(&self, _program: &[u8], field: usize) -> Cow<'static, str>
fn label_in(&self, _program: &[u8], field: usize) -> Cow<'static, str>
The label for field under program’s settings, when its job
changes with another field (a depth that is a chord in one mode and
a detune in another). Defaults to Driver::short_label.
Sourcefn emphasized(&self, _field: usize) -> bool
fn emphasized(&self, _field: usize) -> bool
Whether field is one of its section’s main controls, which apps
draw larger.
Sourcefn format_value(&self, program: &[u8], field: usize) -> String
fn format_value(&self, program: &[u8], field: usize) -> String
field’s value in program, for people, read in the context of
the program’s other fields. Empty when unreadable.
Sourcefn format_raw(&self, field: usize, raw: u16) -> String
fn format_raw(&self, field: usize, raw: u16) -> String
raw for field without a program (range tooltips, before/after
text). Values whose meaning depends on other fields show plainly.
Sourcefn page_summary(&self, _program: &[u8], _page: usize) -> String
fn page_summary(&self, _program: &[u8], _page: usize) -> String
A one-line description of page’s state in program, or empty.
Sourcefn graphs(&self, _program: &[u8], _page: usize, _points: usize) -> Vec<Graph>
fn graphs(&self, _program: &[u8], _page: usize, _points: usize) -> Vec<Graph>
Pictures of page in program; curves use about points points.
Sourcefn handles(&self, _program: &[u8], _page: usize) -> Vec<Handle>
fn handles(&self, _program: &[u8], _page: usize) -> Vec<Handle>
Draggable points on page’s first graph.
Sourcefn drag(
&self,
_program: &[u8],
_page: usize,
_handle: usize,
_at: (f32, f32),
) -> Vec<(usize, u16)>
fn drag( &self, _program: &[u8], _page: usize, _handle: usize, _at: (f32, f32), ) -> Vec<(usize, u16)>
The field values that put handle handle of page at at (graph
coordinates), only those that change.
Sourcefn relevant(&self, _program: &[u8], _field: usize) -> bool
fn relevant(&self, _program: &[u8], _field: usize) -> bool
Whether field does anything under program’s other settings;
editors hide fields that do not.
Sourcefn help(&self, _field: usize) -> Help
fn help(&self, _field: usize) -> Help
What field does to the sound, for the editor’s help. Empty by
default.
Sourcefn category(&self, _program: &[u8]) -> Option<&'static str>
fn category(&self, _program: &[u8]) -> Option<&'static str>
What kind of sound program is (for example “Bass”), if the driver
can tell.
Sourcefn categories(&self) -> &'static [&'static str]
fn categories(&self) -> &'static [&'static str]
Every value Driver::category can return, in display order, for
filters.
Sourcefn mutability(&self, _field: usize) -> Mutability
fn mutability(&self, _field: usize) -> Mutability
What generation may do to field. By default
Mutability::Restricted: generation keeps it.
Sourcefn characters(&self) -> &'static [Character]
fn characters(&self) -> &'static [Character]
The kinds of sound that Generate makes for this synth. Empty by default: the driver does not generate.
Sourcefn macro_info(&self) -> [MacroInfo; 4]
fn macro_info(&self) -> [MacroInfo; 4]
Titles and help for the four Macros, in their order.
Sourcefn generated_name(&self, character: usize, seed: u64) -> String
fn generated_name(&self, character: usize, seed: u64) -> String
A name for a generated program of character, from seed.
Sourcefn generate(
&self,
_recipe: &Recipe,
_base: Option<&[u8]>,
) -> Result<Vec<u8>, DriverError>
fn generate( &self, _recipe: &Recipe, _base: Option<&[u8]>, ) -> Result<Vec<u8>, DriverError>
A new program from recipe. Same recipe and base, same bytes.
Without a base, non-free fields are the init program’s. With
Some(base), every non-free (Mutability::Restricted or
Mutability::Fixed) field is the base’s, and every field on the
pages in recipe.keep comes back byte for byte from the base, even
a value out of range; only free fields on other pages are
generated.
Sourcefn vary(
&self,
_program: &[u8],
_amount: f32,
_seed: u64,
) -> Result<Vec<u8>, DriverError>
fn vary( &self, _program: &[u8], _amount: f32, _seed: u64, ) -> Result<Vec<u8>, DriverError>
A mutation of program by amount (0.0..=1.0). Only free fields
change; restricted and fixed fields stay as they are.
Sourcefn breed(
&self,
_a: &[u8],
_b: &[u8],
_mix: f32,
_seed: u64,
) -> Result<Vec<u8>, DriverError>
fn breed( &self, _a: &[u8], _b: &[u8], _mix: f32, _seed: u64, ) -> Result<Vec<u8>, DriverError>
A child of a and b; mix 0 is a, 1 is b. Free fields mix;
restricted and fixed fields are a’s, as they are. Out-of-range
parent values are clamped where they mix.
Sourcefn needs(&self, _program: &[u8]) -> Vec<(UnitKind, u8)>
fn needs(&self, _program: &[u8]) -> Vec<(UnitKind, u8)>
The user unit slots program relies on (a user oscillator its
mixer lets through, a user effect that is on), by kind. vary,
breed and morph never make a program select a slot none of its
parents selected.
Sourcefn unit_param(
&self,
_program: &[u8],
_field: usize,
) -> Option<(UnitKind, u8, usize)>
fn unit_param( &self, _program: &[u8], _field: usize, ) -> Option<(UnitKind, u8, usize)>
When field is, under program’s settings, a parameter of a user
unit: the unit’s kind and slot, and which of its parameters (from
0). Apps that know the unit show its own name and range there.
Sourcefn morph(
&self,
a: &[u8],
b: &[u8],
t: f32,
seed: u64,
) -> Result<Vec<u8>, DriverError>
fn morph( &self, a: &[u8], b: &[u8], t: f32, seed: u64, ) -> Result<Vec<u8>, DriverError>
Step t (0.0..=1.0) of the way from a to b: 0 is a, 1 is
b’s sound, and steps in between never turn back, so a row of them
goes smoothly from one to the other. Same inputs, same bytes; seed
decides where along the way each group of selectors switches.
Restricted and fixed fields are a’s. By default
morph_fields; a driver with coherence rules applies them on top.
Sourcefn live_messages(
&self,
_program: &[u8],
_field: usize,
_channel: u8,
) -> Option<Vec<Vec<u8>>>
fn live_messages( &self, _program: &[u8], _field: usize, _channel: u8, ) -> Option<Vec<Vec<u8>>>
The MIDI messages that set field to its value in program on the
sounding voices, in order, one complete message per inner Vec: a
transport sends each one separately, since some backends send only
the first event of a buffer. Callers pass channel 0-15. None
when only a whole-program audition can make the change. Only with
Capabilities::live_changes.
Sourcefn demo_library(&self) -> LibraryData
fn demo_library(&self) -> LibraryData
A library to explore without a synth. By default one generated program per character (none without characters).
Sourcefn demo_simulator(&self) -> Box<dyn Simulator>
fn demo_simulator(&self) -> Box<dyn Simulator>
The simulator demo mode connects to, holding whatever makes a demo
worth exploring. By default Driver::simulator.
Sourcefn list_facet(&self) -> Option<usize>
fn list_facet(&self) -> Option<usize>
A Control::Choice field program lists can filter by (a voice
mode), if any.
Sourcefn firmware(&self, _identity_reply: &[u8]) -> Option<String>
fn firmware(&self, _identity_reply: &[u8]) -> Option<String>
The firmware version an identity reply names, for people.
Sourcefn program_slot(
&self,
_bank_msb: u8,
_bank_lsb: u8,
_program: u8,
) -> Option<u16>
fn program_slot( &self, _bank_msb: u8, _bank_lsb: u8, _program: u8, ) -> Option<u16>
The program slot the synth’s panel picked, from the Bank Select
it sent last (CC 0 and CC 32) and a Program Change: apps follow it.
None when out of range or the driver does not say.
Sourcefn panel_listener(&self) -> Option<Box<dyn PanelListener>>
fn panel_listener(&self) -> Option<Box<dyn PanelListener>>
A decoder for what the synth’s panel sends as its knobs turn: apps
follow it. None when the driver does not say.
Sourcefn setup_hint(&self) -> &'static str
fn setup_hint(&self) -> &'static str
What to check on the synth when it does not answer the device inquiry (a setting that routes SysEx elsewhere), or empty.
Sourcefn tier(&self) -> u8
fn tier(&self) -> u8
The driver’s support tier (GOVERNANCE.md): 1 hardware-validated, 2 conformance-proven, 3 community. By default 3.
Sourcefn voices(&self) -> &'static [u8] ⓘ
fn voices(&self) -> &'static [u8] ⓘ
The polyphony of the models it covers, fewest first ([8, 16] for a
synth sold in 8- and 16-voice versions), or empty when unknown.
Sourcefn page_summary_in(
&self,
program: &[u8],
page: usize,
_compact: bool,
_tr: &dyn Fn(&str) -> String,
) -> String
fn page_summary_in( &self, program: &[u8], page: usize, _compact: bool, _tr: &dyn Fn(&str) -> String, ) -> String
Driver::page_summary for an app: compact asks for the shortest
form that still reads (narrow columns), and tr translates the
driver’s own phrases (templates with {name} placeholders, filled
after translating) and value names. By default, page_summary as
it is.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".