Crate launchy

Expand description

An interfacing library for your Novation Launchpads, providing both low-level access as well as powerful high-level abstractions.

§High-level access through the Canvas API

High-level access is possible through the Canvas API. The Canvas trait simply represents a grid of LEDs that can be written to, and consequently flushed to the actual hardware. A number of high-level utilities make the Canvas API a pleasure to use.

use launchy::{CanvasMessage, Color, Canvas as _, MsgPollingWrapper as _};

let (mut canvas, input_poller) = launchy::s::Canvas::guess_polling()?;

for msg in input_poller.iter() {
    match msg {
        CanvasMessage::Press { .. } => canvas[msg.pad()] = Color::WHITE,
        CanvasMessage::Release { .. } => canvas[msg.pad()] = Color::BLACK,
    }
    canvas.flush()?;
}

The above match statement could also be written in a more concise way:

canvas[msg.pad()] = if msg.is_press() { Color::WHITE } else { Color::BLACK };

§Low-level access

Low-level access is provided via the Input and Output structs. Care has been taken to ensure that this library has 100% coverage of the Launchpads’ functionality: all documented Launchpad features are accessible in Launchy’s low-level API.

This means you get the real deal: rapid LED updates, double buffering capabilities, device and firmware information.

Furthermore, we know that a low-level API is not the place for hidden abstractions - and that’s why every function in Launchy’s low-level APIs corresponds to exactly one MIDI message (unless noted otherwise in the documentation). That way, the user has fine control over the data that’s actually being sent.

§Using double-buffering to produce a continuous red flash

use launchy::{OutputDevice as _};
use launchy::s::{Color, DoubleBuffering, DoubleBufferingBehavior, Buffer};

let mut output = launchy::s::Output::guess()?;

// Start editing buffer A
output.control_double_buffering(DoubleBuffering {
    copy: false,
    flash: false,
    edited_buffer: Buffer::A,
    displayed_buffer: Buffer::B,
})?;

// Light all buttons red, using the rapid update feature - just 40 midi messages
for _ in 0..40 {
    output.set_button_rapid(
        Color::RED, DoubleBufferingBehavior::None,
        Color::RED, DoubleBufferingBehavior::None,
    )?;
}

// Now buffer A is completely red and B is empty. Let's leverage the Launchpad S flash
// feature to continually flash between both buffers, producing a red flash:
output.control_double_buffering(DoubleBuffering {
    copy: false,
    flash: true, // this is the important bit
    edited_buffer: Buffer::A,
    displayed_buffer: Buffer::A,
});

Re-exports§

pub use launchpad_s as s;
pub use launchpad_mini as mini;
pub use launchpad_mk2 as mk2;
pub use launchpad_mini_mk3 as mini_mk3;
pub use launch_control as control;
pub use launch_control as launch_control_xl;
pub use launch_control as control_xl;

Modules§

launch_control: Launch Control low-level API
launchpad_mini: Launchpad Mini low-level API
launchpad_mini_mk3: Launchpad Mini MK3 low-level API
launchpad_mk2: Launchpad MK2 low-level API
launchpad_s: Launchpad S low-level API
prelude
util

Structs§

CanvasIterator: An iterator over the buttons of a given Canvas. Create an iterator by calling .iter() on a Canvas.
CanvasLayout: Imagine this - you have multiple launchpads, you line them up, and now you use the Launchpads as if they were a single device?! You can do that, with CanvasLayout.
CanvasLayoutPoller: Utility to be able to process messages from a CanvasLayout by polling
Color: A simple float-based color struct. Each component should lie in 0..=1, but it can also be outside that range. If outside, it will be clipped for some operations
DeviceCanvas: A generic Canvas implementation for all launchpads, that relies on a DeviceSpec. You as a user of the library don’t need to access this struct directly. Use the “Canvas” type aliases that each launchpad module provides, for example launchy::mk2::Canvas or launchy::s::Canvas.
DeviceCanvasPoller: Utility to be able to process messages from a CanvasLayout by polling
InputDeviceHandler: A handler for a Launchpad input connection. This variant is used when an input connection is initiated with callback
InputDeviceHandlerPolling: A handler for a Launchpad input connection that can be polled for new messages. The actual polling methods are implemented inside MsgPollingWrapper. Look there for documentation on how to poll messages.
IterFor: An iterator that yields canvas input messages for some user-defined time duration. For more information, see MsgPollingWrapper::iter_for
MockCanvas
Pad: A 2d point that represents a single pad on a grid of pads. For convenience, the coordinates can be negative.
PaddingCanvas: A canvas wrapper that fills holes and other irregularities to provide a perfectly rectangular grid.

Enums§

CanvasMessage
MidiError
Rotation

Traits§

Canvas: A trait that abstracts over the specifics of a Launchpad and allows generic access and manipulation of a Launchpad’s LEDs.
DeviceSpec: Launchpad’s implement this trait to signify how they can be used as a Canvas. Based on this specification, DeviceCanvas provides a generic Canvas implemention that can be used for all devices.
InputDevice
MsgPollingWrapper
OutputDevice

Crate launchyCopy item path