CoreCanvas 0.3.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.3.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 optimized partial updates
• 🎨 Hardware Sprite-Style Cursor - Non-destructive cursor rendering using composite buffers
• 📝 XML-Based UI Definition - Define your UI in simple XML files
• 🎯 Built-in Components - Label, Button, TextInput with more coming
• ⌨️ Input Handling - Mouse, touchscreen, and keyboard support via Linux evdev
• 🔤 Built-in Font Renderer - 8x8 bitmap font with scalable rendering
• 🎮 Optimized for Embedded - Perfect for embedded Linux, Raspberry Pi, and kiosk applications

Quick Start

Installation

Add CoreCanvas to your project:

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

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

dotnet add package CoreCanvas --version 0.3.0
dotnet add package CoreCanvas.Platform.Linux --version 0.3.0  # For Linux

Simplest Example (Linux)

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

var app = LinuxPlatformBootstrap.CreateApplication();
app.OnStartup += () => {
    var scene = new Scene("Hello");
    scene.Container.Add(new Label(app.FontManager, "Hello CoreCanvas!") { X = 10, Y = 10 });
    app.SetScene(scene);
};
app.Run(); // Blocks until ESC or Ctrl+C

With Configuration

var config = new ApplicationConfig
{
    Width = 800,
    Height = 480,
    TargetFps = 60,
    BackgroundColor = Color.DarkBlue
};

var app = new CoreCanvasApplication(config);

// Add components
var button = new Button(app.TextRenderer, "Click Me") { X = 10, Y = 50, Width = 150, Height = 40 };
button.OnClick += () => Console.WriteLine("Button clicked!");
app.RootContainer.Add(button);

app.Run();

Low-Level API (Advanced)

For power users who need complete control:

// Create framebuffer manually
var fb = new Framebuffer(800, 480);
fb.Clear(50, 0, 0);

// Create text renderer
var tr = new TextRenderer("", 20, fb);

// Create UI manually
var ui = new UiContainer();
ui.Add(new Label(tr, "Hello!") { X = 10, Y = 10 });

// Manual render loop
while (true) {
    ui.Render(fb);
    fb.CompositeWithCursor(cursorX, cursorY);
    fb.WriteCompositeToScreen();
    Thread.Sleep(16);
}

XML-Based UI

Define your UI in XML:

<UI>
  <Label x="10" y="10" width="780" height="40" text="Welcome to CoreCanvas" />
  <Button x="10" y="60" width="200" height="50" text="Start" onclick="start" />
  <TextInput x="10" y="120" width="780" height="40" />
</UI>

Load it in your code:

var ui = UiLoader.Load("ui.xml", tr);

Input Handling

CoreCanvas supports mouse, touchscreen, and keyboard input:

using CoreCanvas.Input;

// Setup input device
var input = new EvdevReader("/dev/input/event4", fbWidth, fbHeight);

// In your main loop
input.Poll();
fb.MouseX = input.X;
fb.MouseY = input.Y;
ui.HandleMouse(input.X, input.Y, input.Pressed);

Rendering Loop

For smooth animation and cursor rendering:

while (true)
{
    var (cursorX, cursorY) = fb.GetMousePosition();
    
    // Render UI components
    ui.Render(fb);
    
    // Composite cursor on top (hardware sprite style!)
    fb.CompositeWithCursor(cursorX, cursorY);
    fb.WriteCompositeToScreen();
    
    // Clear dirty flags
    foreach (var c in ui.Components)
        c.Dirty = false;
    
    Thread.Sleep(16); // ~60 FPS
}

Components

Label

var label = new Label(tr, "Hello World")
{
    X = 10,
    Y = 10,
    Width = 200,
    Height = 30
};

Button

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

TextInput

var input = new TextInput(tr)
{
    X = 10,
    Y = 100,
    Width = 400,
    Height = 40
};

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:

• Direct framebuffer access (no X11 overhead)
• Partial update optimization
• Hardware sprite-style cursor (non-destructive)
• Efficient dirty rectangle tracking
• Zero-copy buffer operations using Span<T>

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

• 📖 docs/README_DOCS_INDEX.md - Documentation index
• 📖 docs/LIBRARY_GUIDE.md - Developer guide
• 📖 docs/APPLICATION_API.md - Complete API reference
• 📖 docs/FONT_SYSTEM.md - Font system documentation

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!