Broiler.Graphics 0.1.0-preview.12

Broiler.Graphics

Broiler.Graphics is the rendering component for Broiler. It owns a platform-neutral managed core — BBitmap, BCanvas, deterministic CPU rasterization, text and font handling, and the render-list pipeline — plus one presentation backend per platform. Image decoding deliberately lives outside this component: the core depends only on the Broiler.Media.Image abstraction, and the application supplies the concrete codecs.

Native API declarations live in Broiler.Native.Windows, Broiler.Native.Linux, and Broiler.Native.Android. All component dependencies are distributed via NuGet.org and managed centrally in Directory.Packages.props.

Preview release. Public APIs and behaviour are not frozen and may change before 1.0. The Windows backend uses native interop, and the rendering path is fed untrusted image data through codecs the application injects; both deserve explicit review before production or security-sensitive use. Substantial implementation work was AI-assisted, and human-review approval is revision-scoped — consult HUMAN_REVIEW.md for the reviewed revision and conditions before describing a checkout as approved. See the roadmap for what is still open.

Installation

All Broiler packages are published to NuGet.org. Preview packages require an explicit prerelease flag:

# Platform-neutral core
dotnet add package Broiler.Graphics --prerelease

Add the backend package for the platform you present on — backends are separate packages, and none is pulled in automatically:

# Windows (Direct2D / DirectWrite)
dotnet add package Broiler.Graphics.Windows --prerelease

# Linux (OpenGL / EGL)
dotnet add package Broiler.Graphics.Linux.OpenGL --prerelease

# Linux (Vulkan)
dotnet add package Broiler.Graphics.Linux.Vulkan --prerelease

# Android (EGL / OpenGL ES)
dotnet add package Broiler.Graphics.Android --prerelease

# Browser WebAssembly (Canvas 2D)
dotnet add package Broiler.Graphics.WebAssembly --prerelease

There is no meta-package: an application takes the core plus exactly the backends it presents with.

Quick Start

Basic Canvas Drawing (CPU Rasterizer)

Broiler.Graphics provides a fully managed, deterministic CPU rasterizer that works identically on all platforms:

using Broiler.Graphics.Color;
using Broiler.Graphics.Imaging;
using Broiler.Graphics.Rendering;
using System.Drawing;

// Create an RGBA bitmap
using var bitmap = new BBitmap(width: 800, height: 600);

// Open a drawing canvas
using (BCanvas canvas = bitmap.OpenCanvas())
{
    // Clear background
    canvas.FillRect(new RectangleF(0, 0, 800, 600), BColor.White);

    // Draw clipped and transformed geometry
    canvas.Save();
    canvas.PushClip(new RectangleF(50, 50, 700, 500));
    canvas.Translate(50, 50);

    // Draw colored rectangles
    canvas.FillRect(new RectangleF(0, 0, 200, 150), BColor.FromRgba(0x21, 0x96, 0xF3, 0xFF));
    canvas.StrokeRect(new RectangleF(0, 0, 200, 150), BColor.Black, strokeWidth: 2f);

    canvas.PopClip();
    canvas.Restore();
}

Injecting Image Codecs

The core references the image abstraction only (Broiler.Media.Image), never a concrete implementation. In your application composition root, register codecs from Broiler.Media.Image.Managed or custom providers:

using Broiler.Graphics.Imaging;
using Broiler.Media.Image.Codecs;

// Inject concrete codecs into the core catalog
BImageCodecs.Use(new MediaCodecCatalog(ManagedImageCodecs.CreateCodecs()));

Windows Direct2D Presentation

On Windows, Broiler.Graphics.Windows provides hardware-accelerated Direct2D rendering and windowing:

using Broiler.Graphics.Windows;

// Create a window with Direct2D presentation
using var window = new Direct2DWindow(new WindowOptions
{
    Title = "Broiler Graphics Application",
    Width = 1024,
    Height = 768
});

window.OnRender += (renderer, surface) =>
{
    // Render frames via Direct2D hardware acceleration
};

window.Run();

Packages

Every package ships XML documentation for IntelliSense and a .snupkg symbol package, and is built deterministically with SourceLink.

Dependency Direction

Broiler.Graphics.Windows       -> Broiler.Graphics -> Broiler.Media.Image   (abstraction only)
Broiler.Graphics.Windows       -> Broiler.Media.Video                       (declares the HWND video target)
Broiler.Graphics.Linux.OpenGL  -> Broiler.Graphics.Linux -> Broiler.Graphics
Broiler.Graphics.Linux.Vulkan  -> Broiler.Graphics.Linux -> Broiler.Graphics
Broiler.Graphics.Android       -> Broiler.Graphics
Broiler.Graphics.WebAssembly   -> Broiler.Graphics

Backend Status

The Linux demo is the composition root for graphics plus input. It can open the OpenGL X11 preview window and wire Linux evdev keyboard/mouse providers while pausing delivery when the X11 window loses focus. It also prints OS/runtime, display-server, OpenGL driver, Vulkan device, and evdev diagnostics. See the roadmap for remaining Linux milestones.

Repository Layout

src/                     runtime assemblies, one directory per package
src/tests/               self-hosted test runner executables
src/demos/               Windows and Linux demo applications (never packaged)
eng/                     packaging scripts, test runners, and metadata
docs/                    roadmap, packaging, and CI/CD documentation
.github/workflows/       CI and release publishing pipelines
Broiler.Graphics.slnx    solution containing all libraries, tests, and demos
Directory.Packages.props central package dependency versions
NuGet.config             hermetic NuGet.org configuration

External dependencies (Broiler.Media.*, Broiler.Input.*, Broiler.Native.*) are managed centrally in Directory.Packages.props and resolved directly from NuGet.org.

Building and Testing

Prerequisites:

• .NET 10 SDK
• PowerShell 7 (or Windows PowerShell 5.1+)
• Node.js 24
• Bash (Git Bash on Windows)

Build the solution and run tests:

dotnet build Broiler.Graphics.slnx -c Release
bash ./eng/run-tests.sh Release
node --test eng/resolve-preview-version.test.mjs

The test script automatically executes the core, WebAssembly, and Android test suites, and explicitly compiles and executes the platform-specific suite for the host operating system (Windows Direct2D or Linux).

Demos

Run the Windows demo:

dotnet run --project src/demos/Broiler.Graphics.Windows.Demo -c Debug

Run the Linux demo:

dotnet run --project src/demos/Broiler.Graphics.Linux.Demo -c Debug

The Linux demo accepts options after --: --vulkan selects the Vulkan path, --window --enable-evdev-input --interactive opens the X11 preview window and wires evdev input, and --artifact-dir=<path> writes diagnostics artifacts to a specified path.

Packaging and Releases

Package all 7 shipping libraries locally:

pwsh -File eng/pack.ps1

Verify consumer restores against NuGet.org:

pwsh -File eng/verify-feed.ps1 -Target nuget

Releases are published exclusively to NuGet.org via GitHub Actions. See CI, packages, and releases for detailed release procedures and automation.

Preview Status

This is preview software. The security and stability guidelines recorded in HUMAN_REVIEW.md apply:

• The component is preview software and is neither fully optimized nor final.
• Public APIs and behaviour may change while development continues.
• Image decoding parses complex binary input and must be treated as security-sensitive. Do not decode untrusted input in security-sensitive environments without sandboxing, resource limits, fuzzing, and review.
• The Windows backend uses native Windows APIs and Direct2D/DirectWrite/DXGI/D3D interop. Correct and security-relevant usage of every involved API is not guaranteed by a first-preview review.
• No dedicated fuzzing campaign, SAST report, dependency scan, or independent security audit is recorded. This review is not a production security audit.

Broiler.Graphics is an independent Broiler component. It is not part of, maintained by, or endorsed by HTML Renderer or Yantra JS.

Documentation

• CI, packages, and releases
• Current roadmap
• Human-review record

License

Broiler.Graphics is licensed under the Apache License 2.0. Third-party material, if present, retains the license identified with that material.