Skip to main content

Driver

Trait Driver 

Source
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§

Source

fn info(&self) -> &'static Info

Which synth this driver serves.

Source

fn capabilities(&self) -> &'static Capabilities

What the synth can do. Apps show only what this lists.

Source

fn fields(&self) -> &'static [FieldInfo]

The program’s parameters. A field’s index in this slice is the field argument of the other methods.

Source

fn name_rules(&self) -> NameRules

The limits of a program’s name.

Source

fn init_program(&self) -> Vec<u8> ⓘ

A new program, valid, with a name that Driver::name_rules allow.

Source

fn check_program(&self, program: &[u8]) -> Result<(), DriverError>

Refuses bytes that are not a whole, valid program.

Source

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.

Source

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.

Source

fn name(&self, program: &[u8]) -> Result<String, DriverError>

The program’s name, without padding.

Source

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.

Source

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.

Source

fn import(&self, ext: &str, bytes: &[u8]) -> Result<LibraryData, DriverError>

Read a vendor file of format ext.

Source

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.

Source

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.

Source

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.

Source

fn simulator(&self) -> Box<dyn Simulator>

A new simulated synth, for the conformance suite and the tests.

Source

fn port_hint(&self) -> &'static [&'static str]

Substrings of the MIDI port names this synth shows up as.

Source

fn recognize(&self, identity_reply: &[u8]) -> bool

Whether identity_reply, an answer to crate::sysex::DEVICE_INQUIRY, comes from this synth.

Provided Methods§

Source

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.

Source

fn short_label(&self, field: usize) -> &'static str

A compact label for use inside a titled section.

Source

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.

Source

fn emphasized(&self, _field: usize) -> bool

Whether field is one of its section’s main controls, which apps draw larger.

Source

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.

Source

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.

Source

fn page_summary(&self, _program: &[u8], _page: usize) -> String

A one-line description of page’s state in program, or empty.

Source

fn graphs(&self, _program: &[u8], _page: usize, _points: usize) -> Vec<Graph>

Pictures of page in program; curves use about points points.

Source

fn handles(&self, _program: &[u8], _page: usize) -> Vec<Handle>

Draggable points on page’s first graph.

Source

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.

Source

fn relevant(&self, _program: &[u8], _field: usize) -> bool

Whether field does anything under program’s other settings; editors hide fields that do not.

Source

fn help(&self, _field: usize) -> Help

What field does to the sound, for the editor’s help. Empty by default.

Source

fn category(&self, _program: &[u8]) -> Option<&'static str>

What kind of sound program is (for example “Bass”), if the driver can tell.

Source

fn categories(&self) -> &'static [&'static str]

Every value Driver::category can return, in display order, for filters.

Source

fn mutability(&self, _field: usize) -> Mutability

What generation may do to field. By default Mutability::Restricted: generation keeps it.

Source

fn characters(&self) -> &'static [Character]

The kinds of sound that Generate makes for this synth. Empty by default: the driver does not generate.

Source

fn macro_info(&self) -> [MacroInfo; 4]

Titles and help for the four Macros, in their order.

Source

fn generated_name(&self, character: usize, seed: u64) -> String

A name for a generated program of character, from seed.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

fn demo_library(&self) -> LibraryData

A library to explore without a synth. By default one generated program per character (none without characters).

Source

fn demo_simulator(&self) -> Box<dyn Simulator>

The simulator demo mode connects to, holding whatever makes a demo worth exploring. By default Driver::simulator.

Source

fn list_facet(&self) -> Option<usize>

A Control::Choice field program lists can filter by (a voice mode), if any.

Source

fn firmware(&self, _identity_reply: &[u8]) -> Option<String>

The firmware version an identity reply names, for people.

Source

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.

Source

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.

Source

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.

Source

fn tier(&self) -> u8

The driver’s support tier (GOVERNANCE.md): 1 hardware-validated, 2 conformance-proven, 3 community. By default 3.

Source

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.

Source

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".

Implementors§