unicorn-hat-extras

High-level convenience features for the unicorn-hat library.

This crate provides text rendering, scrolling animations, and frame buffers built on top of the core unicorn-hat crate. Perfect for creating ticker-tape displays, notifications, and smooth animations on your Pimoroni Unicorn HAT.

Features

📝 Text Rendering: 5×5 bitmap font optimized for 8×8 displays
📜 Scrolling Animations: Smooth text scrolling in all 4 directions
🎞️ Frame Buffers: Double-buffering for flicker-free animations
🎨 Easy Integration: Works seamlessly with core primitives and drawing functions

Installation

Add both crates to your Cargo.toml:

[dependencies]
unicorn-hat = "0.1"
unicorn-hat-extras = "0.1"

Quick Start

Simple Text Display

use unicorn_hat::{UnicornHat, RGB8, PixelBuffer};
use unicorn_hat_extras::font::{draw_text, FONT_5X5};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hat = UnicornHat::new()?;

    // Draw "HI" in green at position (0, 1)
    draw_text(&mut hat, &FONT_5X5, 0, 1, "HI", RGB8::GREEN)?;
    hat.display()?;

    Ok(())
}

Scrolling Ticker Tape

use std::thread;
use std::time::Duration;
use unicorn_hat::{UnicornHat, RGB8};
use unicorn_hat_extras::font::FONT_5X5;
use unicorn_hat_extras::scroller::{Scroller, Direction};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hat = UnicornHat::new()?;
    let mut scroller = Scroller::new(
        "HELLO WORLD",
        &FONT_5X5,
        RGB8::CYAN,
        Direction::Left,
    );

    // Animate scrolling text
    for _ in 0..100 {
        hat.clear();
        scroller.render(&mut hat)?;
        hat.display()?;
        scroller.step();
        thread::sleep(Duration::from_millis(50));
    }

    Ok(())
}

Double-Buffered Animation

use unicorn_hat::{UnicornHat, RGB8, PixelBuffer};
use unicorn_hat_extras::frame::Frame;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hat = UnicornHat::new()?;

    // Prepare frame off-screen
    let mut frame = Frame::new();
    frame.set_pixel(3, 3, RGB8::RED)?;
    frame.set_pixel(4, 4, RGB8::BLUE)?;

    // Display the complete frame at once
    hat.show_frame(frame.get_all())?;

    Ok(())
}

Examples

Run the included examples to see what's possible:

# Horizontal scrolling ticker tape
sudo cargo run -p unicorn-hat-extras --example ticker_tape

# Vertical scrolling demonstrations
sudo cargo run -p unicorn-hat-extras --example vertical_scroll

# Frame buffer and animation techniques
sudo cargo run -p unicorn-hat-extras --example double_buffer

API Overview

Font Module (`font`)

FONT_5X5: 5×5 pixel bitmap font (ASCII 32-126)
draw_char(buffer, font, x, y, ch, color): Draw a single character
draw_text(buffer, font, x, y, text, color): Draw a text string

Coordinates can be negative for smooth off-screen rendering and scrolling effects.

Scroller Module (`scroller`)

Scroller::new(text, font, color, direction): Create a scrolling text animation
scroller.step(): Advance the scroll position
scroller.render(buffer): Draw the current frame
scroller.set_speed(pixels_per_step): Control scroll speed
scroller.is_complete(): Check if text has scrolled off-screen

Supports all 4 directions: Left, Right, Up, Down.

Frame Module (`frame`)

Frame::new(): Create an 8×8 off-screen buffer
Frame::with_color(color): Create a frame filled with a color
frame.set_pixel(x, y, color): Modify pixels off-screen
frame.get_all(): Get the complete frame buffer
UnicornHat::show_frame(frame_data): Display a frame buffer

Use Frame for double-buffering and preparing complex scenes before display.

Font Details

The included FONT_5X5 font covers printable ASCII (characters 32-126) and is optimized for readability on small 8×8 displays. Each character is 5 pixels wide and 5 pixels tall, with automatic 1-pixel spacing between characters.

Performance Tips

Use Frame for complex scenes to avoid partial updates being visible
Adjust Scroller speed with set_speed() to match your desired animation framerate
Call hat.clear() before rendering each frame for smooth scrolling
Negative coordinates are handled efficiently - no need to check bounds manually

Integration with Core Library

All extras functions work with any type implementing the PixelBuffer trait, including:

UnicornHat (direct hardware rendering)
Frame (off-screen rendering)
TestBuffer (for unit testing)

This means you can mix and match core primitives (lines, rectangles, gradients) with text rendering and scrolling seamlessly.

Requirements

Requires the unicorn-hat core library
Hardware: Pimoroni Unicorn HAT (8×8) on Raspberry Pi
Must run with sudo (see main unicorn-hat crate docs for details)

License

MIT License - see the workspace root LICENSE file for details.

More Information

For more details about the core library, hardware setup, and permissions, see the main README.

unicorn-hat-extras 0.1.0