To create a Sled struct, you need to create a configuration file and provide its path to the constructor:

use spatial_led::<Sled, SledError>;
use palette::rgb::Rgb;
fn main() -> Result<(), SledError> {
    let mut sled = Sled::<Rgb>::new("/path/to/config.yap")?;
    Ok(())
}

A configuration file explains the layout of your LED strips in 2D space. This is used to pre-calculate some important information, speeding up complex draw calls.

Example config file:

center: (0.0, 0.5)
density: 30.0
--segments--
(-2, 0) --> (0.5, -1) --> (3.5, 0) -->
(2, 2) --> (-2, 2) --> (-2, 0)

For more information on how to write config files in this format, check out the docs.

Note the ::<Rgb> in the constructor. In previous versions of Sled, palette's Rgb struct was used interally for all color computation. Now, the choice is 100% yours! You just have to specify what data type you'd like to use.

#[derive(Debug)]
struct RGBW {
    r: f32,
    g: f32,
    b: f32,
    w: f32
}
let mut u8_sled = Sled::<(u8, u8, u8)>::new("/path/to/config.yap")?;
let mut rgbw_sled = Sled::<RGBW>::new("/path/to/config.yap")?;

u8_sled.set(4, (255, 0, 0))?; // set 5th led to red
rgbw_sled.set_all(RGBW {
    r: 0.0,
    g: 1.0,
    b: 0.0,
    w: 0.0
});

For all further examples we'll use palette's Rgb struct as our backing color format (we really do highly recommend it and encourage its use wherever it makes sense), but just know that you can use any data type that implements Debug, Default, and Copy.

Once you have your Sled struct, you can start drawing to it right away! Here’s a taste of some of the things Sled lets you do:

Set all vertices to white:

sled.set_vertices(Rgb::new(1.0, 1.0, 1.0));

Note that this is a custom terminal UI visualization that is not packaged as part of the sled library. It is ultimately up to you to decide how to visualize your LEDs; Sled just handles the computation.

Set all LEDs 2 units away from the center_point to red:

sled.set_at_dist(2.0, Rgb::new(1.0, 0.0, 0.0));
// or relative to any other point using:
// sled.set_at_dist_from(distance, pos, color)

Set each LED using a function of its direction from point (2, 1):

sled.map_by_dir_from(Vec2::new(2.0, 1.0), |dir| {
    let red = (dir.x + 1.0) * 0.5;
    let green = (dir.y + 1.0) * 0.5;
    Rgb::new(red, green, 0.5)
});

Dim one of the walls by 75%:

sled.modulate_segment(3, |led| led.color * 0.25)?;

Set all LEDs within the overlapping areas of two different circles to blue:

let circle_1: Filter = sled.within_dist_from(
    2.0,
    Vec2::new(1.0, 0.5)
);
    
let circle_2: Filter = sled.within_dist_from(
	2.5,
	Vec2::new(-1.0, 1.5)
);

let overlap = circle_1.and(&circle_2);
sled.set_filter(&overlap, Rgb::new(0.0, 0.0, 1.0));

For more examples, see the documentation comments on the Sled struct.

Once you’re ready to display these colors, you’ll probably want them packed in a nice contiguous array of RGB values. There are a few methods available to pack the information you need.

let colors_f32 = sled.colors();
// An Iterator of Rgbs, 32-bits/channel

for color in colors_f32 {
    let red: f32 = color.red;
    // -snip- //
}

A few other handy output methods:

let leds = sled.leds();
// An Iterator of Led structs (holds color, position, distance/angle relative from center, etc)

let positions = sled.positions();
// An Iterator of whatever type you chose to represent colors in.

let positions = sled.positions();
// An Iterator of Vec2s, representing the position of each LED

let colors_and_positions = sled.colors_and_positions();
// An Iterator of (COLOR_TYPE, Vec2) tuple pairs representing each LEDs color and position.

Drivers are useful for encapsulating everything you need to drive a lighting effect all in one place. Here's an example of what a simple one might look like:

let mut driver = Driver::<Rgb>::new(); // often auto-inferred

driver.set_startup_commands(|_sled, data| {
    data.set::<Vec<Rgb>>("colors", vec![
        Rgb::new(1.0, 0.0, 0.0),
        Rgb::new(0.0, 1.0, 0.0),
        Rgb::new(0.0, 0.0, 1.0),
    ]);
    Ok(())
});

driver.set_draw_commands(|sled, data, time| {
    let elapsed = time.elapsed.as_secs_f32();
    let colors = data.get::<Vec<Rgb>>("colors")?;
    let num_colors = colors.len();
    // clear our canvas each frame
    sled.set_all(Rgb::new(0.0, 0.0, 0.0));

    for i in 0..num_colors {
        let alpha = i as f32 / num_colors as f32;
        let angle = elapsed + (2.0 * PI * alpha);
        sled.set_at_angle(angle, colors[i]);
    }
    Ok(())
});

To start using the Driver, give it ownership over a Sled using .mount() and use .step() to manually refresh it.

let sled = Sled::<Rgb>::new("path/to/config.yap")?;
driver.mount(sled); // sled gets moved into driver here.

loop {
    driver.step();
    let colors = driver.colors();
    // display those colors however you want
}

.set_startup_commands() - Define a function or closure to run when driver.mount() is called. Grants mutable control over Sled and Data.

set_draw_commands() - Define a function or closure to run every time driver.step() is called. Grants mutable control over Sled, and immutable access to Data and Time.

set_compute_commands() - Define a function or closure to run every time driver.step() is called, scheduled right before draw commands. Grants immutable access to Sled and Time, and mutable control over Data.

If you need to retrieve ownership of your sled later, you can do:

let sled = driver.dismount();

If you don't need Drivers for your project, you can shed a dependency or two by disabling the drivers compiler feature.

For more examples of ways to use drivers, see the driver_examples folder in the spatial_led_examples repository.

fn startup(sled: &mut Sled, data: &mut Data) -> SledResult {
    data.set::<Vec<bool>>("wall_toggles", vec![true, false, true]);
    data.set::<Rgb>("room_color", Rgb::new(1.0, 0.0, 0.0));
    data.set("important_data", CustomDataType::new());
    // the compiler can usually infer the data type
    Ok(())
}

driver.set_startup_commands(startup);

let data: &Data = driver.data();
// or
let data: &mut Data = driver.data_mut();

let draw_commands = |sled, data, _time| {
    let wall_toggles = data.get::<Vec<bool>>("wall_toggles")?;
    let color = data.get::<Rgb>("room_color")?;
    let important_data: &CustomDataType = data.get("important_data")?;

    for i in 0..wall_toggles.len() {
        if wall_toggles[i] == true {
            sled.set_segment(i, *color)?;
        } else {
            sled.set_segment(i, Rgb::new(0.0, 0.0, 0.0))?;
        }
    }
    
    Ok(())
}

// Mutable reference to the whole vector
let walls_mut = data.get_mut::<Vec<bool>>("wall_toggles")?;
walls_mut[1] = true;

let all_due_north: Filter = sled.at_dir(Vec2::new(0.0, 1.0));
sled.for_each_in_filter(&all_due_north, |led| {
    led.color = Rgb::new(1.0, 1.0, 1.0);
});

driver.set_startup_commands(|sled, data| {
     let area: Filter = sled.within_dist_from(
         5.0, Vec2::new(-0.25, 1.5)
     );

    data.set("area_of_effect", area);
     Ok(())
 });
 driver.set_draw_commands(|sled, data, _| {
     let area_filter = data.get("area_of_effect")?;
     sled.map_filter(area_filter, |led| {
         // expensive computation
     });
     Ok(())
 });

let even_filter = sled.filter(|led| led.index() % 2 == 0);

let circle_a = sled.within_dist_from(
    5.0, Vec2::new(-0.25, 1.5)
);

let circle_b = sled.within_dist_from(
    4.0, Vec2::new(0.5, 0.5)
);

let ab_overlap = circle_a.and(&circle_b);
let ab_union = circle_a.or(&circle_b);

The Scheduler struct makes it super easy to schedule redraws at a fixed rate.

let mut scheduler = Scheduler::new(120.0);

scheduler.loop_forever(|| {
    driver.step();
});

Scheduler, by default, utilizes spin_sleep to minimize the high CPU usage you typically see when you spin to wait for the next update by default.

Here are a few other methods that you might also consider:

// loops until false is returned
scheduler.loop_while_true(|| {
    // -snip- //
    return true;
});

// loops until an error of any type is returned
scheduler.loop_until_err(|| {
    // -snip- //
    Ok(())
});

// best for times when you don't want to pass everything through a closure
loop {
    // -snip- //
    scheduler.sleep_until_next_frame();
}

You can define your own CustomScheduler backed by whatever sleeping method you prefer if you wish. If you'd like to trim away the spin_sleep dependency, you can also disable the spin_sleep feature flag.

If you don't need the Scheduler struct in general, you can disable the scheduler and spin_sleep flags.