RasterizerBackend.Native is undocumented and always unregistered

[vchelaru]

Summary

KernSmith.RasterizerBackend (v0.15.2, still present in v0.15.3) has 5 members:

public enum RasterizerBackend
{
    FreeType,
    Gdi,
    DirectWrite,
    StbTrueType,
    Native,
}

Native has no backing implementation and is never registered:

• No KernSmith.Rasterizers.* package exists for it on NuGet (checked all packages under the kaltinril/Kernsmith publisher).
• The core KernSmith package (checked 0.15.2 and 0.15.3) has no IRasterizer implementer for it.
• RasterizerFactory.IsRegistered(RasterizerBackend.Native) returns false, and RasterizerFactory.Create(RasterizerBackend.Native) throws:

  Rasterizer backend 'Native' is not registered. Available backends: FreeType, Gdi, StbTrueType. Install the corresponding NuGet package (e.g., KernSmith.Rasterizers.StbTrueType) and ensure it is referenced by your project.

• README.md, CHANGELOG.md, and COMPARISON.md only document/list FreeType, GDI, DirectWrite, and StbTrueType — Native isn't mentioned anywhere (the only "native" hits are unrelated: Native AOT, native bold/italic face lookup, etc).

The enum's own XML doc summary says: "Native KernSmith rasterizer. Pure C#, cross-platform. No external dependencies." — which reads like a planned built-in backend that was never shipped, but there's no way to tell from the outside whether it's coming, abandoned, or a mistake.

Repro

using KernSmith.Rasterizer;

RasterizerFactory.IsRegistered(RasterizerBackend.Native); // false
RasterizerFactory.Create(RasterizerBackend.Native);       // throws "not registered"

Ask

Either:

1. Document Native (README backend table + XML doc) as planned/experimental with a status, or
2. Remove it from the enum until it has a real implementation, since right now it's a silent trap — it type-checks and compiles but always fails at runtime with no indication in the docs of why.

Environment

• KernSmith 0.15.2 / 0.15.3
• net8.0-windows7.0, Windows

[kaltinril]

Thanks for the writeup — the report is accurate, and "there's no way to tell from the outside whether it's coming, abandoned, or a mistake" is exactly the problem.

Status: it's coming. Native is a fully custom pure-C# rasterizer being built out in phases. The scaffold + core table parsing (head/hhea/hmtx/maxp/OS2/cmap) and glyf/loca outline parsing are already merged; outline extraction, the scanline rasterizer, and IRasterizer integration are the remaining phases. Until that last one lands, NativeRasterizer.RasterizeGlyph throws NotImplementedException, so the package is deliberately not published — the publish workflow packs backends by explicit path and Native isn't in the list. That's why IsRegistered is false for you and always will be from a released build.

So none of it was a mistake, but all of it was invisible, and the enum's XML doc actively claimed otherwise.

Going with your option 1, keeping the value so the public API doesn't change shape when the backend ships:

• XML doc rewritten to lead with "Not usable yet" — it explains there's no published package, that Create will throw, that the value is reserved for the in-development backend, and points at FreeType/GDI/DirectWrite/StbTrueType.
• RasterizerFactory.Create gets a Native-specific message. The generic remedy you hit ("Install the corresponding NuGet package…") was the worst part of the trap — it sends you looking for a package that doesn't exist. Native now says it's still in development and not published to NuGet yet.
• KernSmith.Rasterizers.Native set to IsPackable=false. Something your report didn't catch: RELEASING.md documents a solution-wide dotnet pack, which would have produced a real KernSmith.Rasterizers.Native package on NuGet whose render methods throw. That hole is now closed.

Deliberately not adding Native to the README backend table, COMPARISON.md, the docs site, or the CLI --rasterizer options — the convention here is that a backend only appears in user-facing docs once it actually renders. This change is about the enum no longer lying, not about promoting it early.

Leaving this open until Native actually renders, since that's the real fix.