From 75d9abb53e74c011da9746aba006f3ead957c5d0 Mon Sep 17 00:00:00 2001 From: David Cosby Date: Mon, 16 Dec 2024 23:29:02 -0700 Subject: [PATCH] documented custom color type stuff --- README.md | 29 ++++++++++++++++++++++++++--- src/lib.rs | 30 +++++++++++++++++++++++++++--- 2 files changed, 53 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a60d390..e1acc82 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,6 @@ Sled is an ergonomic rust library that maps out the shape of your LED strips in - It does not interface directly with your GPIO pins to control your LED hardware. Each project will be different, so it's up to you to bring your own glue. Check out the [Raspberry Pi example](https://github.com/DavJCosby/spatial_led_examples/tree/main/raspberry_pi) to get an idea what that might look like. - It does not allow you to represent your LEDs in 3D space. Could be a fun idea in the future, but it's just not planned for the time being. -> This project is still somewhat early in development so please report any bugs you discover! Pull requests are more than welcome! - See the [spatial_led_examples](https://github.com/DavJCosby/spatial_led_examples) repository for examples of Sled in action! ## The Basics @@ -49,6 +47,31 @@ density: 30.0 (2, 2) --> (-2, 2) --> (-2, 0) ``` > For more information on how to write config files in this format, check out the [docs](https://docs.rs/spatial_led/latest/spatial_led/struct.Sled.html#method.new). + +Note the `::` in the constructor. In previous versions of Sled, [palette's Rgb struct](https://docs.rs/palette/latest/palette/rgb/struct.Rgb.html) 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. + +```rust +#[derive(Default, 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::::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`. + ### Drawing 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: @@ -137,7 +160,7 @@ For basic applications, the Sled struct gives you plenty of power. Odds are thou 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: ```rust -let mut driver = Driver::new(); +let mut driver = Driver::::new(); // often auto-inferred use spatial_led::driver_macros::*; driver.set_startup_commands(|_sled, data| { diff --git a/src/lib.rs b/src/lib.rs index 3be2d2f..8e317d3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -4,7 +4,7 @@ //!
//!
//! -//! Sled is a rust library for creating spatial lighting effects for individually addressable LED strips. API ergonomics and performance are top priorities for this project. That said, Sled is still in its early stages of development which means there is plenty of room for improvement in both categories. +//! Sled is an ergonomic rust library that maps out the shape of your LED strips in 2D space to help you create stunning lighting effects. //! //! What Sled **does** do: //! - It exposes an API that lets you: @@ -24,7 +24,7 @@ //! ## The Basics //! In absence of an official guide, this will serve as a basic introduction to Sled. From here, you can use the documentation comments to learn what else Sled offers. //! ### Setup -//! To [create](Sled::new) a [Sled] struct, you need to create a configuration file and provide its path to the constructor: +//! To [create](Sled::new) a [Sled] struct, you need to create a configuration file and provide its path to the constructor. //! ```rust, ignore //! use spatial_led::Sled; //! use palette::rgb::Rgb; @@ -42,6 +42,30 @@ //! (2, 2) --> (-2, 2) --> (-2, 0) //! ``` //! See [Sled::new()] for more information on this config format. +//! +//! //! Note the `::` in the constructor. In previous versions of Sled, [palette's Rgb struct](https://docs.rs/palette/latest/palette/rgb/struct.Rgb.html) 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. +//! +//! ```rust, ignore +//! # use spatial_led::Sled; +//! #[derive(Default, Debug, Copy, Clone)] +//! 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::::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`. //! //! ### Drawing //! 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: @@ -153,7 +177,7 @@ //! # use spatial_led::{Sled}; //! # use palette::rgb::Rgb; //! use spatial_led::driver::Driver; -//! let mut driver = Driver::new(); +//! let mut driver = Driver::::new(); // often auto-inferred //! //! driver.set_startup_commands(|_sled, data| { //! data.set::>("colors", vec![