launchy/
lib.rs

1/*!
2An interfacing library for your Novation Launchpads, providing both low-level access as well as
3powerful high-level abstractions.
4
5# High-level access through the Canvas API
6
7High-level access is possible through the [Canvas] API. The [`Canvas`] trait simply represents a grid of
8LEDs that can be written to, and consequently flushed to the actual hardware. A number of high-level
9utilities make the Canvas API a pleasure to use.
10
11```no_run
12use launchy::{CanvasMessage, Color, Canvas as _, MsgPollingWrapper as _};
13
14let (mut canvas, input_poller) = launchy::s::Canvas::guess_polling()?;
15
16for msg in input_poller.iter() {
17    match msg {
18        CanvasMessage::Press { .. } => canvas[msg.pad()] = Color::WHITE,
19        CanvasMessage::Release { .. } => canvas[msg.pad()] = Color::BLACK,
20    }
21    canvas.flush()?;
22}
23# Ok::<(), launchy::MidiError>(())
24```
25The above `match` statement could also be written in a more concise way:
26```no_run
27# use launchy::Color;
28# let (canvas, msg): (launchy::MockCanvas, launchy::CanvasMessage) = unimplemented!();
29canvas[msg.pad()] = if msg.is_press() { Color::WHITE } else { Color::BLACK };
30```
31
32# Low-level access
33
34Low-level access is provided via the `Input` and `Output` structs. Care has been taken to ensure
35that this library has 100% coverage of the Launchpads' functionality: all documented Launchpad
36features are accessible in Launchy's low-level API.
37
38This means you get the real deal: rapid LED updates, double buffering capabilities, device and
39firmware information.
40
41Furthermore, we know that a low-level API is not the
42place for hidden abstractions - and that's why every function in Launchy's low-level APIs
43corresponds to exactly one MIDI message (unless noted otherwise in the documentation). That way, the
44user has fine control over the data that's actually being sent.
45
46## Using double-buffering to produce a continuous red flash
47```no_run
48use launchy::{OutputDevice as _};
49use launchy::s::{Color, DoubleBuffering, DoubleBufferingBehavior, Buffer};
50
51let mut output = launchy::s::Output::guess()?;
52
53// Start editing buffer A
54output.control_double_buffering(DoubleBuffering {
55    copy: false,
56    flash: false,
57    edited_buffer: Buffer::A,
58    displayed_buffer: Buffer::B,
59})?;
60
61// Light all buttons red, using the rapid update feature - just 40 midi messages
62for _ in 0..40 {
63    output.set_button_rapid(
64        Color::RED, DoubleBufferingBehavior::None,
65        Color::RED, DoubleBufferingBehavior::None,
66    )?;
67}
68
69// Now buffer A is completely red and B is empty. Let's leverage the Launchpad S flash
70// feature to continually flash between both buffers, producing a red flash:
71output.control_double_buffering(DoubleBuffering {
72    copy: false,
73    flash: true, // this is the important bit
74    edited_buffer: Buffer::A,
75    displayed_buffer: Buffer::A,
76});
77# Ok::<(), launchy::MidiError>(())
78```
79*/
80
81pub mod util;
82
83mod protocols;
84
85#[macro_use]
86mod canvas;
87pub use canvas::*;
88
89mod midi_io;
90pub use midi_io::*;
91
92mod errors;
93pub use errors::*;
94
95pub mod launchpad_s;
96pub use launchpad_s as s;
97
98pub mod launchpad_mini;
99pub use launchpad_mini as mini;
100
101pub mod launchpad_mk2;
102pub use launchpad_mk2 as mk2;
103
104pub mod launchpad_mini_mk3;
105pub use launchpad_mini_mk3 as mini_mk3;
106
107pub mod launch_control;
108pub use launch_control as control;
109/// The MIDI API of the classic Launch Control and the Launch Control XL is identical
110pub use launch_control as launch_control_xl;
111pub use launch_control as control_xl;
112
113pub mod prelude {
114    pub use crate::canvas::{Canvas, Color, Pad};
115    pub use crate::midi_io::{InputDevice, MsgPollingWrapper, OutputDevice};
116}
117
118/// Identifier used for e.g. the midi port names etc.
119const APPLICATION_NAME: &str = "Launchy";
launchy/lib.rs

launchy/
lib.rs
