Guillotine

A no-std, allocation-fre graphical user interface framework for embedded devices prioritizing efficiency and ergonomics. The UI declaration API is heavily inspired by GPUI. Built with (and inherits compatibility from) embedded-graphics.

Demo

A demo Guillotine UI on a Waveshare ESP32-C6 1.47" LCD board from the shellyctl project:

Quickstart

This example uses the optional flexbox feature.

use embedded_graphics::{
    mock_display::MockDisplay,
    mono_font::ascii::{FONT_6X10, FONT_9X18_BOLD},
    pixelcolor::Rgb565,
    prelude::Size,
};
use guillotine::{style::JustifyContent, *};

const CANVAS: Rgb565 = Rgb565::new(2, 4, 6);
const PANEL: Rgb565 = Rgb565::new(4, 9, 12);
const ACCENT: Rgb565 = Rgb565::new(7, 47, 25);

struct BasicView {
    greeting: &'static str,
}

impl Render for BasicView {
    // Render lets you declaratively build your UI tree.
    fn render(&self, cx: &Context<'_>) -> impl ElementBuilder {
        cx.column()
            .size(Size::new(320, 172))
            .padding(12)
            .gap(8)
            .background(CANVAS)
            .justify_content(JustifyContent::Center)
            .child(
                cx.row()
                    .child(cx.text("GUILLOTINE").flex_grow(1).font(Font::mono(&FONT_9X18_BOLD)))
                    .child(
                        cx.text("READY")
                            .padding((4, 9))
                            .background(ACCENT)
                            .font(Font::mono(&FONT_6X10)),
                    ),
            )
            .child(
                cx.row()
                    .gap(8)
                    .child(
                        cx.text(self.greeting)
                            .font(Font::mono(&FONT_6X10))
                            .flex(3)
                            .padding(10)
                            .background(PANEL),
                    )
                    .child(
                        cx.text("7 nodes, 54 bytes")
                            .font(Font::mono(&FONT_6X10))
                            .flex(2)
                            .padding(6)
                            .background(ACCENT),
                    ),
            )
    }
}

fn main() {
    // Display should implement embedded_graphics DrawTarget
    let display = MockDisplay::<Rgb565>::new();

    let view = BasicView { greeting: "Build tiny interfaces." };

    // Initialize stack-based storage for the frame. Capacity: 32 elements
    // and 128 bytes of UTF-8 text.
    let storage = FrameStorage::<Rgb565, 32, 128>::default();

    // Create a new UI with a direct display target. Used here for brevity;
    // if you have memory available, use `BufferedTarget`.
    let mut ui = Ui::new(DirectTarget::new(display), storage).with_background(CANVAS);

    // Render the view
    ui.render(&view).unwrap();
}

Frame Buffers

The framebuffer feature (on by default) provides a BufferedTarget type that works with caller-provided frame buffers. It is highly recommended to use this over DirectTarget, since it can dramatically increase frame rates and reduce flicker to near unnoticeable if you can cover the whole display.

use embedded_graphics::{pixelcolor::Rgb565, mock_display::MockDisplay};
use static_cell::ConstStaticCell;
use guillotine::{*, buffered::BufferedTarget};

/// The size of the frame buffer, should ideally cover your whole display
/// (width * height).
const FRAMEBUFFER_PIXELS: usize = 320 * 172;

/// Allocate the buffer in static memory with your
/// chosen color.
static FRAMEBUFFER: ConstStaticCell<[Rgb565; FRAMEBUFFER_PIXELS]> =
    ConstStaticCell::new([Rgb565::new(0, 0, 0); FRAMEBUFFER_PIXELS]);

fn main() {
    let mut display = MockDisplay::<Rgb565>::new();
    
    // Initialize stack-based storage for the frame. Capacity: 32 elements
    // and 128 bytes of UTF-8 text.
    let storage = FrameStorage::<Rgb565, 32, 128>::default();

    /// Initialize the buffered display target 
    let target = BufferedTarget::new(&mut display, FRAMEBUFFER.take());
    
    let mut ui = Ui::new(target, storage);

    // ... render something
}

Large buffers should generally use static storage (with static_cell). Small buffers can live on the stack if the stack size permits it.

Note that the memory used by an Rgb565 buffer is pixels x 2 bytes.

Picking Sizes

Ideally, your frame buffer covers the whole display. However, you can provide a buffer of any size, and render() will execute a greedy top-down traversal to find the first subtree that fits. Passing buffers that are smaller than the area of any element on the screen will fall back to direct drawing.

[!NOTE] If your frame buffer doesn't fit the root element, it is painted directly before its children are considered. An opaque root background may therefore appear as a visible clear before buffered children are presented, so you may still notice a flicker.

Memory Management

Guillotine does not require an allocator, and uses heapless to store fixed-capacity node and text arrays inline.

This library exposes FrameStorage as the frontend for all memory management. The FrameStorage signature looks like this:

pub struct FrameStorage<C: PixelColor, const N: usize = 64, const T: usize = 1024>

Since heapless stores data inline, capacity has to be specified upfront through const generics. FrameStorage contains 2 buffers:

1. nodes with capacity N (number of nodes): stores the tree of UI elements. 64 by default.
2. text with capacity T (bytes): stores the UTF-8 bytes for all text elements present in the UI. 1024 by default.

It's recommended to tune N and T to fit the specifics of your UI. FrameStorage exposes some methods to help you do that:

• usage() returns the used length of both buffers.
• capacity() returns the capacity of both buffers.

[!NOTE] These buffers are only populated after calls to render(), and will contain the element tree and text bytes for the currently rendered frame.

Layout

By default, Guillotine supports a limited subset of the flexbox layout engine. Rows are start-aligned containers along the horizontal axis with support for gaps, and columns are their vertical counterpart.

Flexbox

More complete flexbox support is gated behind a flexbox feature and is turned off by default, because these flexbox properties require the layout tree to be traversed twice, demanding extra compute and slightly render latency.

With flexbox on, you'll get access to CSS-like flexbox functionality, including justify-content and align-items (for containers), and flex-grow and flex for items.

[!TIP] Some properties, like AlignItems::Stretch, currently have a complexity of O(N x D), where N is the number of nodes and D is the tree depth. For small trees, this shouldn't be a problem, but keep it in mind if you have more complex layouts.

Refer to flexbox.rs for a flexbox layout example:

Styling

Insets and the box model

Margin, padding, and border widths accept CSS-like physical-edge shorthands:

cx.column()
    .margin(10)                 // all edges
    .padding((4, 8))            // vertical, horizontal
    .border((1, 2, 3))          // top, horizontal, bottom
    .margin((4, 8, 12, 16));    // top, right, bottom, left

Use Insets::new(top, right, bottom, left) when a named value is clearer. Insets are non-negative pixel lengths. Guillotine doesn't currently support percentages, auto, logical edges, negative margins, margin collapsing, per-edge border colors, or border styles. Adjacent margins in rows and columns add together.

size, width, and height configure border-box dimensions: padding and border are placed inside them, and margin is added outside. Width and height are independent; an omitted dimension is sized automatically from the element's contents. Configured dimensions grow to contain padding and border when parent constraints allow.

Examples

See the examples README.

Core Concepts

Declarative Definition

• Explain the idea of declaratively building your UI

Status: implemented ✅

Hybrid Immediate & Retained Mode

Status: unimplemented ❌

Similar tree-based layout to X

• GPUI

Status: implemented ✅

State Management

Layout Engine

• Conceptually similar to Flutter (i.e. constraints go down, sizes go up)
  • constraints flow downward, sizes flow upward, positions flow downward
• Requirement: single pass.

Status: implemented ✅

Why?

I was trying to build a clean-looking dashboard on a small LCD screen powered by an ESP32-C6, that's supposed to monitor and display the power consumption of my home lab (project here). I wanted to do this in Rust, with the esp-rs ecosystem. The ecosystem is quite mature, but I couldn't really find a UI framework that was:

1. Performant
2. Very low memory footprint (no Slint / LVGL)
3. Beautiful

Additionally, I wanted to learn what it would take to build something like this.

Roadmap

v0.0.1

• Try to mimic GPUI declaration style: https://github.com/zed-industries/zed/blob/main/crates/gpui/examples/hello_world.rs
• Low-level Element / ParentElement trait for custom elements and widgets
• Support generic PixelColor
• Full immediate mode redrawing
• Make repo ready for publishing:
  • README documentation (a la Dioxus)
  • Rustdoc documentation
  • Examples
    • Sizing (insets)
    • Fonts
    • Cool
    • ESP32
  • Fix exports
  • Dual Apache / MIT license
  • Fix sdl2 vendoring for embedded-graphics-simulator
• TextStyle fonts
• Support for non-interactive elements:
  • Row
  • (formatted) Text
  • Column

v0.1.0

• No alloc

v0.2.1

• framebuffer feature with frame buffer support

v0.3.0

• Refactored layout engine
• Support flexbox layout (flexbox feature)

v0.3.1

• Support for absolute positioning (relative by default). Introduces a new explicit position property to Style.

v0.3.2

• New elements
  • Dialogs / Modals (floating containers)
  • Charts
  • Spinner (going to be interesting as this is essentially a self-rendering element). Will probably require a global frame_rate to be set on the Ui. However, this would be a full retained mode approach with an async polling loop. Another approach is to first implement incremental redrawing, and rely on the caller to call render() at their chosen rate. However, each render() would do a bunch of compute, so probably not super efficient?

Backlog

• Mirrored debugger / inspector:
  • When plugged into an MCU, this feature launches an interactive inspector on your host machine (think the Chrome inspector). Displays realtime total / per element memory consumption, frame rendering times, boxes, frame buffer utilization etc. Builds on the embedded-graphics simulator.
• Add memory usage for examples
  • cargo binutils for examples in CI (cargo size). This will detect regressions.
• Documentation
  • Guide for finding the ideal FrameStorage capacity.
• Benchmarks for:
  • Frame rendering
  • Frame drawing
• Stats for frame buffers (to determine optimal sizing)
• Incremental drawing behind an inremental feature
• Explicit behaviour:
  • Hidden
  • Visible
  • Scroll
• Custom elements
• Support for interaction behind an interaction feature
• Support interactive elements:
  • Button
  • Slider

Prior Work & Inspiration

• Clay by Nic Barker
• Kolibri by Yandrik
• GPUI by Zed
• Taffy by Dioxus Labs
• embedded-gui by Leftger