Broiler.Graphics 0.1.0-preview.5

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. Their package versions are managed centrally in Directory.Packages.props. Publish Native before releasing dependent backends. Explicit uses of native driver descriptions or OpenGL/Vulkan exception types now require their Broiler.Native namespaces.

Preview release. 0.1.0-preview.1 is the first published preview. 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

Preview packages need an explicit prerelease opt-in:

dotnet add package Broiler.Graphics --prerelease

Broiler.Graphics is the platform-neutral core and rasterizes on the CPU on its own. Add the backend package for the platform you present on — they are separate packages, and none is pulled in automatically:

dotnet add package Broiler.Graphics.Windows --prerelease

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

Consuming Broiler packages from GitHub Packages

NuGet.config maps Broiler.* to the Broiler-Platform GitHub Packages feed and other dependencies to NuGet.org. Local restores need read:packages credentials; CI uses GITHUB_TOKEN with access to the upstream packages. See CI, packages, and releases for setup and publishing.

Packages

Every package ships XML documentation 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

The core references the image abstraction only, never an implementation. The application composition root supplies the concrete codecs:

BImageCodecs.Use(new MediaCodecCatalog(ManagedImageCodecs.CreateCodecs()));

Backend status

The Linux demo is the current composition root for graphics plus input. It can open the OpenGL X11 preview window and, with explicit raw-input acknowledgement, 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 selected evdev-device diagnostics. The roadmap holds the remaining Linux validation and implementation work.

Repository layout

src/                     runtime assemblies, one directory per package
src/tests/               one self-hosted test runner executable per assembly
src/demos/               Windows and Linux demo applications (never packaged)
eng/                     vendored packaging metadata, package icon, test script
docs/                    roadmap
.github/workflows/       CI and publish pipelines
Broiler.Media/           submodule; supplies the image and video abstractions
Broiler.Input/           submodule; keyboard and mouse providers for the Linux demo
Broiler.Graphics.slnx    solution over every project in src/

Cross-component dependencies are git submodules at the repository root, and between them they close the graph — every project reference resolves inside a checkout of this repository.

Broiler.Media supplies Broiler.Media.Image to the core and Broiler.Media.Video to the Windows backend, and its managed codecs act as the composition root for the test runners. Broiler.Input supplies the evdev keyboard and mouse providers, and only the Linux demo references it — no package depends on it.

Broiler.Media in turn declares Broiler.Graphics as a submodule of its own, but only its -Windows configuration needs it. Initialise one level, as below, and the cycle stops.

Building and testing

The repository uses package dependencies and requires no submodules. Build the neutral projects, then run the suites for the current host:

dotnet build Broiler.Graphics.slnx -c Release
bash ./eng/run-tests.sh Release

The script runs the core, WebAssembly, and Android suites, and explicitly builds and runs the Windows or Linux suite. Projects use Debug or Release; platform providers and demos can also be built directly by project path.

Demos

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

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

The Linux demo takes 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 the diagnostics artifacts somewhere specific.

dotnet run --project src/demos/Broiler.Graphics.Linux.Demo -c Debug -- --window --enable-evdev-input --interactive

Packaging and releases

pwsh -File eng/pack.ps1

This packs and verifies all seven packages, including providers excluded from normal solution builds. CI tests on Linux and Windows; Publish reuses CI and publishes its verified artifacts. Manual runs default to a dry run and select the next unused preview. See CI, packages, and releases for feed credentials, dependency versions, tags, and NuGet.org publishing.

Preview status

This is first-preview software, and the security and stability warnings recorded in HUMAN_REVIEW.md apply to any published preview:

• The component is preview software and is neither fully optimized nor final.
• Public APIs and behaviour may change while the global refactoring continues.
• Image decoding is injected from Broiler.Media, 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 additional 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

• 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. The license provides the software on an "AS IS" basis, without warranties or conditions.