Re-architect to pre-calculate a buffer for each frame (#90)

👩‍🔬 🧪 💥 

If we can off-load sending bits to the LEDs using hardware, then we can prepare the bits for the next frame while the current frame is being sent.

This change is a big step towards making this possible.

One realization to make this work is that yes [the `generic_const_exprs` feature](https://doc.rust-lang.org/beta/unstable-book/language-features/generic-const-exprs.html) would make no-alloc much nicer, BUT IN THE MEANTIME we can achieve the same outcomes (with a worse user experience) by using generic constants without expressions. Since you can't do constant calculations using generics (e.g. we can't calculate the buffer size needed using other generic types we already have, such as the type of LED which has a constant function for this), the user must calculate them on their side and pass in to your type arguments. We can use all our builder pattern skills to make this as ergonomic as possible.

Changes:

- Change `Driver` (and `DriverAsync`) trait interface

```rust
pub trait Driver {
    /// The error type that may be returned by the driver.
    type Error;

    /// The color type accepted by the driver.
    type Color;

    /// The word of the frame buffer.
    type Word;

    /// Encodes an update frame buffer for the LED hardware.
    ///
    /// # Type Parameters
    ///
    /// * `PIXEL_COUNT` - Number of pixels in frame
    /// * `FRAME_BUFFER_SIZE` - Length of encoded frame buffer, in words.
    /// * `Pixels` - Iterator of colors for each pixel
    /// * `Color` - Type of each pixel
    ///
    /// # Arguments
    ///
    /// * `pixels` - Iterator of colors for each pixel
    /// * `brightness` - Global brightness scaling factor (0.0 to 1.0)
    /// * `correction` - Color correction factors
    ///
    /// # Returns
    ///
    /// Result with frame buffer
    fn encode<const PIXEL_COUNT: usize, const FRAME_BUFFER_SIZE: usize, Pixels, Color>(
        &mut self,
        pixels: Pixels,
        brightness: f32,
        correction: ColorCorrection,
    ) -> Vec<Self::Word, FRAME_BUFFER_SIZE>
    where
        Pixels: IntoIterator<Item = Color>,
        Self::Color: FromColor<Color>;

    /// Writes frame buffer to the LED hardware.
    ///
    /// # Type Parameters
    ///
    /// * `FRAME_BUFFER_SIZE` - Length of encoded frame buffer, in words.
    ///
    /// # Arguments
    ///
    /// * `frame` - Frame buffer
    ///
    /// # Returns
    ///
    /// Result indicating success or an error
    fn write<const FRAME_BUFFER_SIZE: usize>(
        &mut self,
        frame: Vec<Self::Word, FRAME_BUFFER_SIZE>,
        brightness: f32,
        correction: ColorCorrection,
    ) -> Result<(), Self::Error>;

    /// Shows a frame on the LED hardware.
    ///
    /// # Type Parameters
    ///
    /// * `PIXEL_COUNT` - Number of pixels in frame
    /// * `FRAME_BUFFER_SIZE` - Length of encoded frame buffer, in words.
    /// * `Pixels` - Iterator of colors for each pixel
    /// * `Color` - Type of each pixel
    ///
    /// # Arguments
    ///
    /// * `pixels` - Iterator of colors for each pixel
    /// * `brightness` - Global brightness scaling factor (0.0 to 1.0)
    /// * `correction` - Color correction factors
    ///
    /// # Returns
    ///
    /// Result indicating success or an error
    fn show<const PIXEL_COUNT: usize, const FRAME_BUFFER_SIZE: usize, I, C>(
        &mut self,
        pixels: I,
        brightness: f32,
        correction: ColorCorrection,
    ) -> Result<(), Self::Error>
    where
        I: IntoIterator<Item = C>,
        Self::Color: FromColor<C>,
    {
        let frame_buffer =
            self.encode::<PIXEL_COUNT, FRAME_BUFFER_SIZE, _, _>(pixels, brightness, correction);
        self.write(frame_buffer, brightness, correction)
    }
}
```

- Until  [the `generic_const_exprs` feature](https://doc.rust-lang.org/beta/unstable-book/language-features/generic-const-exprs.html) is stable, we aren't able to use associated constants, const functions, or expressions in the Blinksy code to calculate constants at compile-time. Instead, we must receive pre-calculated constants from the user as a generic. The best we can do is make it easy as possible by providing good types, traits, and const functions for the user to use.
- To build a `Control`, you now need to provide a `FRAME_BUFFER_SIZE` constant.
  - So for example, to build a frame buffer to drive Ws2812 LEDs: 

```
      .with_frame_buffer_size::<{ Ws2812::frame_buffer_size(Layout::PIXEL_COUNT) }>()
```

- Re-factor clockless and clocked drivers into common pattern
  - There is a generic driver for each type: `ClocklessDriver` and `ClockedDriver`.
  - You construct the generic driver by combining an Led with a Writer, both of that type.
  - All drivers and all writers are made through builders.
  - So for example: the clockless RMT driver for a WS2812 LED:

```rust
let driver = ClocklessDriver::default()
    .with_led::<Ws2812>()
    .with_writer(ClocklessRmt::default()
        .with_led::<Ws2812>()
        .with_rmt_buffer_size::<{ rmt_buffer_size::<Ws2812>(Layout::PIXEL_COUNT) }>()
        .with_channel(/* rmt channel */)
        .with_pin(/* rmt pin */)
        .build()
    );
```

  - Another example: the clocked SPI driver for an APA102 LED:

```rust
let driver = ClockedDriver::default()
    .with_led::<Apa102>()
    .with_writer(/* spi bus */)
```

- Clockless and clocked writers are also constructed through builders.
- Move LED definitions to `crate::leds` module, remove `Led` suffix from structs.

Author: ahdinosaur

CHANGELOG.md

@@ -12,15 +12,155 @@ Migration guide (0.10 -> UNRELEASED)
 +  .with_layout::<Layout, { Layout::PIXEL_COUNT }>()
 ```
 
-- `Driver::write` now expects a `const PIXEL_COUNT: usize` generic constant as the first type argument.
+- `ControlBuilder` now has a `with_frame_buffer_size` to provide a `FRAME_BUFFER_SIZE` constant.
+  - So for example, to build a frame buffer to drive Ws2812 LEDs:
+
+```diff
++  .with_frame_buffer_size::<{ Ws2812::frame_buffer_size(Layout::PIXEL_COUNT) }>()
+```
+
+If using the `gledopto` high-level helper macros, this should be all you need to change.
+
+Below are changes for lower-level interfaces:
+
+- Change `Driver` (and `DriverAsync`) traits:
+
+```rust
+pub trait Driver {
+    /// The error type that may be returned by the driver.
+    type Error;
+
+    /// The color type accepted by the driver.
+    type Color;
+
+    /// The word of the frame buffer.
+    type Word;
+
+    /// Encodes an update frame buffer for the LED hardware.
+    ///
+    /// # Type Parameters
+    ///
+    /// * `PIXEL_COUNT` - Number of pixels in frame
+    /// * `FRAME_BUFFER_SIZE` - Length of encoded frame buffer, in words.
+    /// * `Pixels` - Iterator of colors for each pixel
+    /// * `Color` - Type of each pixel
+    ///
+    /// # Arguments
+    ///
+    /// * `pixels` - Iterator of colors for each pixel
+    /// * `brightness` - Global brightness scaling factor (0.0 to 1.0)
+    /// * `correction` - Color correction factors
+    ///
+    /// # Returns
+    ///
+    /// Result with frame buffer
+    fn encode<const PIXEL_COUNT: usize, const FRAME_BUFFER_SIZE: usize, Pixels, Color>(
+        &mut self,
+        pixels: Pixels,
+        brightness: f32,
+        correction: ColorCorrection,
+    ) -> Vec<Self::Word, FRAME_BUFFER_SIZE>
+    where
+        Pixels: IntoIterator<Item = Color>,
+        Self::Color: FromColor<Color>;
+
+    /// Writes frame buffer to the LED hardware.
+    ///
+    /// # Type Parameters
+    ///
+    /// * `FRAME_BUFFER_SIZE` - Length of encoded frame buffer, in words.
+    ///
+    /// # Arguments
+    ///
+    /// * `frame` - Frame buffer
+    ///
+    /// # Returns
+    ///
+    /// Result indicating success or an error
+    fn write<const FRAME_BUFFER_SIZE: usize>(
+        &mut self,
+        frame: Vec<Self::Word, FRAME_BUFFER_SIZE>,
+        brightness: f32,
+        correction: ColorCorrection,
+    ) -> Result<(), Self::Error>;
+
+    /// Shows a frame on the LED hardware.
+    ///
+    /// # Type Parameters
+    ///
+    /// * `PIXEL_COUNT` - Number of pixels in frame
+    /// * `FRAME_BUFFER_SIZE` - Length of encoded frame buffer, in words.
+    /// * `Pixels` - Iterator of colors for each pixel
+    /// * `Color` - Type of each pixel
+    ///
+    /// # Arguments
+    ///
+    /// * `pixels` - Iterator of colors for each pixel
+    /// * `brightness` - Global brightness scaling factor (0.0 to 1.0)
+    /// * `correction` - Color correction factors
+    ///
+    /// # Returns
+    ///
+    /// Result indicating success or an error
+    fn show<const PIXEL_COUNT: usize, const FRAME_BUFFER_SIZE: usize, I, C>(
+        &mut self,
+        pixels: I,
+        brightness: f32,
+        correction: ColorCorrection,
+    ) -> Result<(), Self::Error>
+    where
+        I: IntoIterator<Item = C>,
+        Self::Color: FromColor<C>,
+    {
+        let frame_buffer =
+            self.encode::<PIXEL_COUNT, FRAME_BUFFER_SIZE, _, _>(pixels, brightness, correction);
+        self.write(frame_buffer, brightness, correction)
+    }
+}
+```
+
+- Until  [the `generic_const_exprs` feature](https://doc.rust-lang.org/beta/unstable-book/language-features/generic-const-exprs.html) is stable, we aren't able to use associated constants, const functions, or expressions in the Blinksy code to calculate constants at compile-time. Instead, we must receive pre-calculated constants from the user as a generic. The best we can do is make it easy as possible by providing good types, traits, and const functions for the user to use.
+- Built-in LED drivers have been refactored:
+  - There is a generic driver for each type: `ClocklessDriver` and `ClockedDriver`.
+  - You construct the generic driver by combining an Led with a Writer, both of that type.
+  - All drivers and all writers are made through the builder pattern.
+  - So for example: the clockless RMT driver for a WS2812 LED:
+
+```rust
+let driver = ClocklessDriver::default()
+    .with_led::<Ws2812>()
+    .with_writer(ClocklessRmt::default()
+        .with_led::<Ws2812>()
+        .with_rmt_buffer_size::<{ rmt_buffer_size::<Ws2812>(Layout::PIXEL_COUNT) }>()
+        .with_channel(/* rmt channel */)
+        .with_pin(/* rmt pin */)
+        .build()
+    );
+```
+
+  - Another example: the clocked SPI driver for an APA102 LED:
+
+```rust
+let driver = ClockedDriver::default()
+    .with_led::<Apa102>()
+    .with_writer(/* spi bus */)
+```
+
+- Clockless and clocked writers are also constructed through the builder pattern.
+- Move LED definitions to `blinksy::leds` module, remove `Led` suffix from structs.
+- `blinksy-esp` RMT driver expects `RMT_BUFFER_SIZE`.
+  - Each memory block on the RMT driver has a size of 64, with a max of 8 memory blocks.
+  - If async, you should use `64`.
+  - If blocking and not too many LEDs, you should use `rmt_buffer_size::<Led>(Layout::PIXEL_COUNT)`.
+  - If blocking and too many LEDs, you should use `64`.
 
 Breaking changes:
 
+- [#90](https://github.com/ahdinosaur/blinksy/pull/90): Re-architect to pre-calculate a buffer for each frame
 - [#82](https://github.com/ahdinosaur/blinksy/pull/82): Use pixels buffer
   - Write all colors from `Pattern` iterator to pixel buffer, then write pixel buffer to LEDs with `Driver`.
 - [#87](https://github.com/ahdinosaur/blinksy/pull/87): Refactor clocked LED drivers
 
-
 ## 0.10
 
 Yee haw `blinksy` now supports async!

Cargo.lock

@@ -179,7 +179,7 @@ For all examples, see:
 - [Desktop examples in `./blinksy-desktop/examples`](./blinksy-desktop/examples)
 - [Embedded (with Gledopto) examples in `./esp/gledopto/examples`](./esp/gledopto/examples)
 
-### Embedded Gledopto: 3D Cube with Nosie Pattern
+### Embedded Gledopto: 3D Cube with Noise Pattern
 
 https://github.com/user-attachments/assets/36a2c6ad-7ae6-4498-85b3-ed76d0b62264
 
@@ -195,6 +195,7 @@ https://github.com/user-attachments/assets/36a2c6ad-7ae6-4498-85b3-ed76d0b62264
 use blinksy::{
     layout::{Layout3d, Shape3d, Vec3},
     layout3d,
+    leds::Ws2812,
     patterns::noise::{noise_fns, Noise3d, NoiseParams},
     ControlBuilder,
 };
@@ -272,6 +273,7 @@ fn main() -> ! {
             ..Default::default()
         })
         .with_driver(ws2812!(p, Layout::PIXEL_COUNT))
+        .with_frame_buffer_size::<{ Ws2812::frame_buffer_size(Layout::PIXEL_COUNT) }>()
         .build();
 
     control.set_brightness(0.2);
@@ -327,6 +329,7 @@ fn main() {
                 ..Default::default()
             })
             .with_driver(driver)
+            .with_frame_buffer_size::<{ PanelLayout::PIXEL_COUNT }>()
             .build();
 
         loop {
@@ -358,21 +361,25 @@ https://github.com/user-attachments/assets/703fe31d-e7ca-4e08-ae2b-7829c0d4d52e
 use blinksy::{
     layout::Layout1d,
     layout1d,
+    leds::Ws2812,
     patterns::rainbow::{Rainbow, RainbowParams},
     ControlBuilder,
 };
-use gledopto::{board, elapsed, main, ws2812};
+use gledopto::{board, bootloader, elapsed, main, ws2812};
+
+bootloader!();
 
 #[main]
 fn main() -> ! {
     let p = board!();
 
-    layout1d!(Layout, 60 * 5);
+    layout1d!(Layout, 50);
 
     let mut control = ControlBuilder::new_1d()
         .with_layout::<Layout, { Layout::PIXEL_COUNT }>()
         .with_pattern::<Rainbow>(RainbowParams::default())
-        .with_driver(ws2812!(p, Layout::PIXEL_COUNT))
+        .with_driver(ws2812!(p, Layout::PIXEL_COUNT, buffered))
+        .with_frame_buffer_size::<{ Ws2812::frame_buffer_size(Layout::PIXEL_COUNT) }>()
         .build();
 
     control.set_brightness(0.2);
@@ -399,24 +406,28 @@ fn main() -> ! {
 use blinksy::{
     layout::Layout1d,
     layout1d,
+    leds::Ws2812,
     patterns::rainbow::{Rainbow, RainbowParams},
     ControlBuilder,
 };
 use embassy_executor::Spawner;
-use gledopto::{board, elapsed, init_embassy, main_embassy, ws2812_async};
+use gledopto::{board, bootloader, elapsed, init_embassy, main_embassy, ws2812_async};
+
+bootloader!();
 
 #[main_embassy]
 async fn main(_spawner: Spawner) {
     let p = board!();
 
     init_embassy!(p);
 
-    layout1d!(Layout, 60 * 5);
+    layout1d!(Layout, 50);
 
     let mut control = ControlBuilder::new_1d_async()
         .with_layout::<Layout, { Layout::PIXEL_COUNT }>()
         .with_pattern::<Rainbow>(RainbowParams::default())
-        .with_driver(ws2812_async!(p, Layout::PIXEL_COUNT))
+        .with_driver(ws2812_async!(p, Layout::PIXEL_COUNT, buffered))
+        .with_frame_buffer_size::<{ Ws2812::frame_buffer_size(Layout::PIXEL_COUNT) }>()
         .build();
 
     control.set_brightness(0.2);
@@ -446,10 +457,11 @@ https://github.com/user-attachments/assets/1c1cf3a2-f65c-4152-b444-29834ac749ee
 use blinksy::{
     layout::{Layout2d, Shape2d, Vec2},
     layout2d,
+    leds::Apa102,
     patterns::noise::{noise_fns, Noise2d, NoiseParams},
     ControlBuilder,
 };
-use gledopto::{board, bootloader, elapsed, main, ws2812};
+use gledopto::{apa102, board, bootloader, elapsed, main};
 
 bootloader!();
 
@@ -472,6 +484,7 @@ fn main() -> ! {
         .with_layout::<Layout, { Layout::PIXEL_COUNT }>()
         .with_pattern::<Noise2d<noise_fns::Perlin>>(NoiseParams::default())
         .with_driver(apa102!(p))
+        .with_frame_buffer_size::<{ Apa102::frame_buffer_size(Layout::PIXEL_COUNT) }>()
         .build();
 
     control.set_brightness(0.2);

README.md

@@ -17,4 +17,5 @@ blinksy = { path = "../blinksy", version = "0.10" }
 egui = "0.28"
 egui-miniquad = "0.15.0"
 glam = { version = "0.30.1" }
+heapless = "0.9.1"
 miniquad = "0.4"

blinksy-desktop/Cargo.toml

@@ -20,6 +20,7 @@ fn main() {
                 ..Default::default()
             })
             .with_driver(driver)
+            .with_frame_buffer_size::<{ StripLayout::PIXEL_COUNT }>()
             .build();
 
         loop {

blinksy-desktop/examples/1d-rainbow.rs

@@ -30,6 +30,7 @@ fn main() {
                 ..Default::default()
             })
             .with_driver(driver)
+            .with_frame_buffer_size::<{ PanelLayout::PIXEL_COUNT }>()
             .build();
 
         loop {

blinksy-desktop/examples/2d-noise.rs

@@ -30,6 +30,7 @@ fn main() {
                 ..Default::default()
             })
             .with_driver(driver)
+            .with_frame_buffer_size::<{ PanelLayout::PIXEL_COUNT }>()
             .build();
 
         loop {

blinksy-desktop/examples/2d-rainbow.rs

@@ -68,6 +68,7 @@ fn main() {
                 ..Default::default()
             })
             .with_driver(driver)
+            .with_frame_buffer_size::<{ TunnelLayout::PIXEL_COUNT }>()
             .build();
 
         loop {

blinksy-desktop/examples/3d-arcs.rs

@@ -78,6 +78,7 @@ fn main() {
                 ..Default::default()
             })
             .with_driver(driver)
+            .with_frame_buffer_size::<{ CubeFaceLayout::PIXEL_COUNT }>()
             .build();
 
         loop {

blinksy-desktop/examples/3d-cube-face-noise.rs

@@ -47,6 +47,7 @@ fn main() {
                 position_scalar: 0.25,
             })
             .with_driver(driver)
+            .with_frame_buffer_size::<{ CubeVolumeLayout::PIXEL_COUNT }>()
             .build();
 
         loop {