core-usage.md

Core Usage Guide

This document explains how to generate Slug binary data (.slug) with SlugSharp.Core.

1. Main Entry Point

The simplest API is:

byte[] SlugCompiler.Compile(string fontPath, GeneratorOptions? options = null)

• fontPath: path to a .ttf/.otf font.
• options: optional generation controls.
• Returns: binary bytes in the repository's SLUGGISH format.

2. Minimal Example

using SlugSharp.Core;

var bytes = SlugCompiler.Compile("fonts/SpaceMono-Regular.ttf");
File.WriteAllBytes("SpaceMono.slug", bytes);

3. Configure Generation

Use GeneratorOptions:

var options = new GeneratorOptions
{
    BandCount = 16,
    FullRange = false,
    Whitelist = new HashSet<int> { 32, 65, 66, 67 } // space, A, B, C
};

var bytes = SlugCompiler.Compile("fonts/SpaceMono-Regular.ttf", options);

Option semantics

• BandCount (default: 16)
  • Controls band partitioning granularity used by the generated band texture.
  • Must be greater than 0.
• FullRange (default: false)
  • When true, includes all glyphs mapped from the font charmap.
  • Takes precedence over Whitelist.
• Whitelist (default: null)
  • If FullRange is false, restricts output to listed Unicode code points.
  • Glyph index 0 (.notdef) is always retained as fallback.

4. Validate Output

SluggishParser performs structural validation:

SluggishParser.Validate(bytes);

It checks:

• Header magic (SLUGGISH).
• Curves texture block dimensions and size.
• Bands texture block dimensions and size.
• Optional metrics footer consistency.

5. Advanced Flow (Raw + Manual Export)

If you want access to intermediate generated data:

using SlugSharp.Core;

var generator = new SlugGenerator(new GeneratorOptions { FullRange = true });
var raw = generator.Generate("fonts/SpaceMono-Regular.ttf");

// raw.CodePoints, raw.CurvesList, raw.BandOffsets, raw.CurveOffsets, raw.Metrics

var bytes = SluggishWriter.Export(raw);

This is useful when you need diagnostics, custom post-processing, or inspection before serialization.

6. Runtime Integration Notes

Typical runtime pipeline:

1. Generate .slug bytes offline or at runtime.
2. Upload curves and bands textures to GPU.
3. Use a Slug-compatible shader path (see renderingShaders/).
4. Map code points to glyph records and render quads.

7. Common Errors

• InvalidOperationException: Unable to load font
  • Font path is wrong or unreadable.
• ArgumentOutOfRangeException for BandCount
  • Set BandCount to a positive integer (>= 1).
• InvalidDataException from SluggishParser.Validate
  • Binary is corrupted or incomplete.

8. Testing

The test suite in SlugSharp.Tests covers:

• Deterministic compilation.
• Whitelist and full-range behaviors.
• Binary structure correctness.
• Parser rejection of malformed binaries.

Run locally:

dotnet test SlugSharp.sln -c Release

9. Charset File Input (Core + CLI)

SlugSharp.Core provides CharsetFileParser to load a text file into code points:

using SlugSharp.Core;

var whitelist = CharsetFileParser.LoadCodePoints("charset.txt");
var bytes = SlugCompiler.Compile("fonts/SpaceMono-Regular.ttf", new GeneratorOptions
{
    Whitelist = whitelist
});

CLI equivalent:

dotnet run --project SlugSharp.CLI -- fonts/SpaceMono-Regular.ttf out.slug --charset-file=charset.txt

Supported charset.txt token formats:

• Literal UTF-8 characters: ABC中가
• Decimal code points: 65 66 67
• Hex code points: U+4E2D, 0xAC00
• Inclusive ranges: 32-126, A-Z, U+4E00-U+9FFF, 0xAC00-0xD7AF
• Comments with # or //

Options interaction:

• FullRange = true still takes precedence over whitelist-based filtering.
• CLI merges --whitelist and --charset-file when both are provided.
• Duplicate entries are sanitized automatically (deduplicated).

Validation and audit helpers:

# validate only
dotnet run --project SlugSharp.CLI -- fonts/SpaceMono-Regular.ttf out.slug --charset-file=charset.txt --validate-charset

# print sanitized code points
dotnet run --project SlugSharp.CLI -- fonts/SpaceMono-Regular.ttf out.slug --charset-file=charset.txt --print-charset

10. Progress and Timing (Optional)

Core supports optional progress callbacks through GeneratorOptions.ProgressCallback:

using SlugSharp.Core;

var options = new GeneratorOptions
{
    ProgressInterval = 100,
    ProgressCallback = update =>
    {
        Console.WriteLine($"{update.Stage} t={update.ElapsedMilliseconds}ms emitted={update.EmittedGlyphCount}");
    }
};

var result = SlugCompiler.CompileWithReport("fonts/SpaceMono-Regular.ttf", options, validateOutput: true);
Console.WriteLine($"Total: {result.Report.TotalMilliseconds} ms");

CLI equivalents:

# summary timings only
dotnet run --project SlugSharp.CLI -- fonts/SpaceMono-Regular.ttf out.slug --timings

# live progress + timings
dotnet run --project SlugSharp.CLI -- fonts/SpaceMono-Regular.ttf out.slug --progress --progress-interval=100