CoreCanvas 0.4.0

CoreCanvas

A high-performance cross-platform UI library for framebuffer development. Build rich UIs with hardware-accelerated rendering, inspired by classic systems like the Commodore 64 and Amiga.

⚠️ Development Status: CoreCanvas is currently in pre-1.0 development (v0.4.0 - cross-platform architecture). The API is functional but may change between releases. See VERSIONING.md for details.

Features

• 🚀 High-Performance Rendering - Direct framebuffer access with 60 FPS @ minimal CPU usage
• 🎨 Hardware Sprite-Style Cursor - Non-destructive cursor rendering using composite buffers
• 🎯 Scene Stack Architecture - Built-in scene management with modal dialogs and backdrops
• 📦 Built-in Components - Label, Button, TextInput with consistent styling
• ⚡ Z-Index Layering - Full layering support with click-to-front and automatic sorting
• ⌨️ Input Handling - Mouse, touchscreen, and keyboard support via Linux evdev
• 🔤 Advanced Font System - TrueType fonts (SkiaSharp) + 8x8 bitmap fonts with caching
• 🎮 Optimized for Embedded - Perfect for Raspberry Pi, kiosks, and framebuffer devices
• 🌐 Cross-Platform Architecture - Platform-agnostic core with OS-specific implementations

Quick Start

Installation

Add CoreCanvas to your project:

dotnet add package CoreCanvas
dotnet add package CoreCanvas.Platform.Linux  # For Linux framebuffer

For a specific version (recommended during 0.x development):

dotnet add package CoreCanvas --version 0.4.*
dotnet add package CoreCanvas.Platform.Linux --version 0.4.*

Simplest Example (Linux)

using CoreCanvas.Core;
using CoreCanvas.UI;
using CoreCanvas.Components;
using CoreCanvas.Graphics;
using CoreCanvas.Demo;  // For LinuxPlatformBootstrap

// Create application with platform bootstrap
var app = LinuxPlatformBootstrap.CreateApplication();

// Setup UI on startup
app.OnStartup += () => {
    var scene = new Scene("Hello");
    scene.Container.Add(new Label(app.FontManager, "Hello CoreCanvas!") { 
        X = 10, Y = 10, Width = 300, Height = 40 
    });
    app.SetScene(scene);
};

app.Run(); // Blocks until ESC or Ctrl+C

With Configuration and TrueType Fonts

var config = new ApplicationConfig
{
    Width = 800,
    Height = 480,
    TargetFps = 60,
    BackgroundColor = Color.DarkBlue,
    UseTrueTypeFonts = true,
    DefaultFontFamily = "Liberation Sans",
    DefaultFontSize = 14
};

var app = LinuxPlatformBootstrap.CreateApplication(config);

app.OnStartup += () => {
    var scene = new Scene("Main Menu");
    
    var button = new Button(app.FontManager, "Click Me") { 
        X = 10, Y = 50, Width = 150, Height = 40 
    };
    button.OnClick += () => Console.WriteLine("Button clicked!");
    scene.Container.Add(button);
    
    app.SetScene(scene);
};

app.Run();

Using Dialogs

app.OnStartup += () => {
    var scene = new Scene("Main");
    
    var showDialogBtn = new Button(app.FontManager, "Show Dialog") { 
        X = 10, Y = 10, Width = 150, Height = 40 
    };
    showDialogBtn.OnClick += () => {
        var dialog = new Dialog("Confirm", 300, 200);
        dialog.Container.Add(new Label(app.FontManager, "Are you sure?") { 
            X = 10, Y = 10 
        });
        
        var okBtn = new Button(app.FontManager, "OK") { 
            X = 10, Y = 60, Width = 80, Height = 35 
        };
        okBtn.OnClick += () => {
            Console.WriteLine("Confirmed!");
            app.PopScene();  // Close dialog
        };
        dialog.Container.Add(okBtn);
        
        app.PushScene(dialog);  // Show modal dialog
    };
    scene.Container.Add(showDialogBtn);
    
    app.SetScene(scene);
};

Input Handling

CoreCanvas automatically handles input through the application lifecycle:

var config = new ApplicationConfig
{
    MouseDevice = "/dev/input/event4",  // Auto-detected if not specified
    KeyboardDevice = "/dev/input/event0"  // Auto-detected if not specified
};

var app = LinuxPlatformBootstrap.CreateApplication(config);

Input is automatically routed to components based on z-index (topmost component receives events first).

Finding Input Devices

# List all input devices
ls -la /dev/input/by-id/

# Show device details
cat /proc/bus/input/devices | grep -E "Name|Handlers"

Architecture

Scene Stack System

CoreCanvas uses a scene stack for managing UI screens:

// Base scene (full screen)
var mainScene = new Scene("Main Menu");
app.SetScene(mainScene);  // Replaces current base scene

// Modal dialog (overlays base scene)
var dialog = new Dialog("Settings", 400, 300);
app.PushScene(dialog);  // Adds on top of scene stack

// Close dialog
app.PopScene();  // Removes topmost scene

Z-Index Layering

Components support z-index for layering control:

var background = new Button(...) { ZIndex = -10 };  // Behind everything
var button = new Button(...) { ZIndex = 0 };        // Default layer
var overlay = new Label(...) { ZIndex = 100 };      // Always on top

// Click to bring to front
button.OnClick += () => button.BringToFront(scene.Container);

Rendering Pipeline

1. Clear BackBuffer (clean UI, no cursor)
2. Render base scene
3. Render dialogs (if any) with dimmed backdrop
4. Composite cursor sprite onto clean buffer
5. Present composite to framebuffer (/dev/fb0)

This architecture ensures 60 FPS with no cursor trails!

Components

All components support positioning, sizing, z-index layering, and dirty tracking.

Label

var label = new Label(app.FontManager, "Hello World")
{
    X = 10,
    Y = 10,
    Width = 200,
    Height = 30,
    ZIndex = 0
};

Button

var button = new Button(app.FontManager, "Click Me")
{
    X = 10,
    Y = 50,
    Width = 150,
    Height = 40,
    ZIndex = 0
};
button.OnClick += () => Console.WriteLine("Clicked!");

TextInput

var input = new TextInput(app.FontManager)
{
    X = 10,
    Y = 100,
    Width = 400,
    Height = 40,
    ZIndex = 0
};
input.Text = "Type here...";

Use Cases

• 🖥️ Kiosk Applications - Full-screen touchscreen interfaces
• 🎮 Embedded Systems - Raspberry Pi and similar devices
• 📺 Digital Signage - Information displays and dashboards
• 🏭 Industrial Controls - HMI interfaces for machinery
• 🚗 Automotive Displays - In-vehicle information systems

Requirements

• .NET 9.0 or later
• Linux with framebuffer support (/dev/fb0)
• Input devices via evdev (/dev/input/eventX)

Performance

CoreCanvas is designed for high performance with aggressive optimizations:

• 60 FPS @ <5% CPU on Raspberry Pi 4
• Zero-allocation hot paths - No GC pressure during rendering
• Composite cursor rendering - Hardware sprite-style (no cursor trails)
• Dirty rectangle tracking - Only render changed components
• SIMD acceleration - AVX2/SSE2 for buffer operations
• Scene stack caching - Invalidation-based array caching
• Pre-rendered static resources - Cursor, fonts cached once
• Span<T> everywhere - Zero-copy buffer operations

See docs/PERFORMANCE_OPTIMIZATION_SUMMARY.md for details.

Project Structure

CoreCanvas is organized into logical subsystems:

src/
├── CoreCanvas/                   # Platform-agnostic core
│   ├── Core/                     # Application lifecycle and configuration
│   ├── Graphics/                 # Rendering abstractions
│   ├── Fonts/                    # Text rendering (bitmap and TrueType)
│   ├── UI/                       # Components, scenes, and dialogs
│   └── Input/                    # Input interfaces
├── CoreCanvas.Platform.Linux/    # Linux implementation
│   ├── Graphics/                 # Framebuffer and rendering
│   └── Input/                    # evdev input handling
└── CoreCanvas.Demo/              # Example applications

Documentation

• 📖 Quick Start - Get started in 5 minutes
• 📖 Cross-Platform Architecture - Understanding the design
• 📖 Library Guide - Integration guide for consumers
• 📖 API Reference - Complete API documentation
• 📖 Font System - TrueType and bitmap fonts
• 📖 Z-Index Layering - Component layering system
• 📖 Performance Guide - Optimization patterns
• 📖 All Documentation - Full documentation index

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please open an issue or PR on GitHub.

Credits

Created by BogenTech. Inspired by classic computer systems that made UI programming fun!