# alphapixel/slughorn architecture

> Architecture diagram of the GitHub repository alphapixel/slughorn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alphapixel/slughorn
- Repository: https://github.com/alphapixel/slughorn

## Overview

#### Purpose and Deployment Boundary
`slughorn` is a C++20, graphics-API-agnostic vector-content preparation library implementing the Slug GPU vector-rendering technique. It converts authored or imported curves into GPU-uploadable atlas data; host applications own shaders, GPU resources, and drawing. Public aggregation and implementation are centered in `slughorn/slughorn.hpp` and `slughorn/slughorn.cpp`. CMake builds the library and optional integrations via `CMakeLists.txt`.

#### Entry Points
Native consumers include `slughorn/slughorn.hpp` plus focused backend headers. A Canvas-inspired authoring API begins at `slughorn/canvas.hpp`. Python/offline processing is exposed through pybind11 binding units rooted at `ext/python/slughorn.cpp` and `ext/python/slughorn-python.hpp`. Command-line launchers are supplied as `bin/slughorn`, `bin/slughorn-msdf`, and `bin/slughorned`.

#### Unified Shape Model and GPU Handoff
The core model represents curves, shapes, layered composite shapes, fills, masks, and rendering metadata in the unified source of truth. `slughorn/slughorn.hpp` defines the central API/model, while `slughorn/render.hpp` packages render-facing atlas/geometry data. The key boundary is explicit: slughorn prepares CPU-side data and constraints; an external OpenGL, Vulkan, WebGPU, Metal, DirectX, or scene-graph frontend uploads and renders it.

#### Authoring and Import Adapters
All sources converge on quadratic Bézier-oriented shape data:
- Native paths, text-like layout operations, gradients, and composition: `slughorn/canvas.hpp`.
- SVG paths and gradients through NanoSVG: `slughorn/nanosvg.hpp`.
- Font outlines and COLRv0/COLRv1 color-glyph layers: `slughorn/freetype.hpp` and `slughorn/emoji.hpp`.
- Existing drawing-system path ingestion: `slughorn/cairo.hpp`, `slughorn/skia.hpp`, and `slughorn/blend2d.hpp`.

These adapters are intentionally input-side only; they do not import the source library’s renderer or GPU ownership model.

#### Curve Processing and Atlas Preparation
Curve decomposition and scanline/atlas-oriented processing turn path geometry into data suitable for exact per-fragment curve evaluation. The core processing surface is `slughorn/slughorn.hpp`; tessellation-related utilities are isolated in `slughorn/tessellate.hpp`. MSDF generation is supported through the vendored `ext/msdfgen`, complementing curve atlas data for effects such as inside/outside coverage.

#### Composition, Masks, and Render Semantics
Shapes can be assembled into ordered `CompositeShape` layers with individual transforms and fill behavior, including procedural or arbitrary-shape masks. Render descriptors separate geometry preparation from frontend-specific material/shader decisions. Relevant public boundaries are `slughorn/render.hpp`, `slughorn/canvas.hpp`, and `slughorn/serial.hpp`, the latter supporting interchange/serialization including the project’s glTF-compatible JSON direction.

#### Runtimes and Dependencies
The primary runtime is native C++20. Python bindings use vendored pybind11 (`ext/pybind11`) and expose core, canvas, render, SVG, FreeType, emoji, and tessellation capabilities through files such as `ext/python/slughorn-core.cpp` and `ext/python/slughorn-render.cpp`. Vendored dependencies include NanoSVG (`ext/nanosvg`), earcut (`ext/earcut`), JSON (`ext/json`), and MSDF generation (`ext/msdfgen`). Skia-related build arguments reside in `ext/skia-args.gn`; Skia, Cairo, Blend2D, and FreeType are adapter ecosystems rather than slughorn’s rendering runtime.

Main entry points: [`slughorn/slughorn.hpp`](https://github.com/alphapixel/slughorn/blob/main/slughorn/slughorn.hpp) (Core model & API), [`slughorn/slughorn.cpp`](https://github.com/alphapixel/slughorn/blob/main/slughorn/slughorn.cpp) (Core implementation), [`ext/python/slughorn.cpp`](https://github.com/alphapixel/slughorn/blob/main/ext/python/slughorn.cpp) (Python module), [`slughorn/render.hpp`](https://github.com/alphapixel/slughorn/blob/main/slughorn/render.hpp) (Render descriptors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_core_api["Core model &amp; API<br/>C++20 library<br/>[slughorn.hpp]"]
  node_render_data["Render descriptors<br/>GPU handoff<br/>[render.hpp]"]
  node_serialization["Serialization<br/>interchange API<br/>[serial.hpp]"]
end

subgraph group_pipeline["Preparation Pipeline"]
  node_core_impl["Core implementation<br/>C++ implementation<br/>[slughorn.cpp]"]
  node_tessellation["Tessellation utilities<br/>geometry processing<br/>[tessellate.hpp]"]
  node_msdf["MSDF generation<br/>vendored processor"]
end

subgraph group_adapters["Input Adapters"]
  node_canvas["Canvas authoring<br/>authoring API<br/>[canvas.hpp]"]
  node_svg["SVG adapter<br/>import adapter<br/>[nanosvg.hpp]"]
  node_font["FreeType outlines<br/>font adapter<br/>[freetype.hpp]"]
  node_emoji["Color glyph layers<br/>font adapter<br/>[emoji.hpp]"]
  node_drawing_adapters["Drawing path adapters<br/>import adapters<br/>[cairo.hpp]"]
end

subgraph group_python["Python Runtime"]
  node_python_entry["Python module<br/>pybind11 bindings<br/>[slughorn.cpp]"]
  node_python_bindings["Python binding units<br/>binding surface<br/>[slughorn-core.cpp]"]
  node_pybind11["pybind11<br/>vendored dependency"]
end

node_build["CMake build<br/>[CMakeLists.txt]"]
node_native_consumers{{"Native consumers<br/>host application"}}
node_gpu_frontends{{"Graphics frontends<br/>external renderer"}}
node_cli["CLI launchers<br/>command-line tools"]

node_build -->|"builds"| node_core_impl
node_core_api -->|"implemented by"| node_core_impl
node_canvas -->|"authors shapes"| node_core_api
node_svg -->|"imports paths"| node_core_api
node_font -->|"imports outlines"| node_core_api
node_emoji -->|"adds color layers"| node_core_api
node_drawing_adapters -->|"ingests paths"| node_core_api
node_core_impl -->|"uses"| node_tessellation
node_core_impl -->|"generates distance fields"| node_msdf
node_core_impl -->|"prepares atlas data"| node_render_data
node_core_api -->|"serializes model"| node_serialization
node_native_consumers -->|"uses"| node_core_api
node_render_data -->|"uploaded and rendered by"| node_gpu_frontends
node_pybind11 -->|"binds with"| node_python_entry
node_python_entry -->|"loads"| node_python_bindings
node_python_bindings -->|"exposes"| node_core_api
node_cli -.->|"launches processing"| node_python_entry

click node_build "https://github.com/alphapixel/slughorn/blob/main/CMakeLists.txt"
click node_core_api "https://github.com/alphapixel/slughorn/blob/main/slughorn/slughorn.hpp"
click node_core_impl "https://github.com/alphapixel/slughorn/blob/main/slughorn/slughorn.cpp"
click node_render_data "https://github.com/alphapixel/slughorn/blob/main/slughorn/render.hpp"
click node_canvas "https://github.com/alphapixel/slughorn/blob/main/slughorn/canvas.hpp"
click node_tessellation "https://github.com/alphapixel/slughorn/blob/main/slughorn/tessellate.hpp"
click node_serialization "https://github.com/alphapixel/slughorn/blob/main/slughorn/serial.hpp"
click node_svg "https://github.com/alphapixel/slughorn/blob/main/slughorn/nanosvg.hpp"
click node_font "https://github.com/alphapixel/slughorn/blob/main/slughorn/freetype.hpp"
click node_emoji "https://github.com/alphapixel/slughorn/blob/main/slughorn/emoji.hpp"
click node_drawing_adapters "https://github.com/alphapixel/slughorn/blob/main/slughorn/cairo.hpp"
click node_msdf "https://github.com/alphapixel/slughorn/tree/main/ext/msdfgen"
click node_python_entry "https://github.com/alphapixel/slughorn/blob/main/ext/python/slughorn.cpp"
click node_python_bindings "https://github.com/alphapixel/slughorn/blob/main/ext/python/slughorn-core.cpp"
click node_pybind11 "https://github.com/alphapixel/slughorn/tree/main/ext/pybind11"
click node_cli "https://github.com/alphapixel/slughorn/blob/main/bin/slughorn"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_api,node_render_data,node_serialization toneBlue
class node_core_impl,node_tessellation,node_msdf toneAmber
class node_canvas,node_svg,node_font,node_emoji,node_drawing_adapters toneMint
class node_python_entry,node_python_bindings,node_pybind11 toneRose
class node_build,node_native_consumers,node_gpu_frontends,node_cli toneNeutral
```

## Components

### Public API

- [Core model & API](https://github.com/alphapixel/slughorn/blob/main/slughorn/slughorn.hpp): C++20 library · Unified shapes, curves, fills, masks, and metadata. · `slughorn/slughorn.hpp`
- [Render descriptors](https://github.com/alphapixel/slughorn/blob/main/slughorn/render.hpp): GPU handoff · CPU-side atlas and geometry packages for host renderers. · `slughorn/render.hpp`
- [Serialization](https://github.com/alphapixel/slughorn/blob/main/slughorn/serial.hpp): interchange API · Supports serialization and glTF-compatible JSON direction. · `slughorn/serial.hpp`

### Preparation Pipeline

- [Core implementation](https://github.com/alphapixel/slughorn/blob/main/slughorn/slughorn.cpp): C++ implementation · `slughorn/slughorn.cpp`
- [Tessellation utilities](https://github.com/alphapixel/slughorn/blob/main/slughorn/tessellate.hpp): geometry processing · `slughorn/tessellate.hpp`
- [MSDF generation](https://github.com/alphapixel/slughorn/tree/main/ext/msdfgen): vendored processor · Generates distance-field data alongside curve atlas data. · `ext/msdfgen`

### Input Adapters

- [Canvas authoring](https://github.com/alphapixel/slughorn/blob/main/slughorn/canvas.hpp): authoring API · Native path, layout, gradient, and composition input. · `slughorn/canvas.hpp`
- [SVG adapter](https://github.com/alphapixel/slughorn/blob/main/slughorn/nanosvg.hpp): import adapter · NanoSVG paths and gradients. · `slughorn/nanosvg.hpp`
- [FreeType outlines](https://github.com/alphapixel/slughorn/blob/main/slughorn/freetype.hpp): font adapter · `slughorn/freetype.hpp`
- [Color glyph layers](https://github.com/alphapixel/slughorn/blob/main/slughorn/emoji.hpp): font adapter · COLRv0/COLRv1 glyph composition. · `slughorn/emoji.hpp`
- [Drawing path adapters](https://github.com/alphapixel/slughorn/blob/main/slughorn/cairo.hpp): import adapters · Cairo, Skia, and Blend2D path ingestion. · `slughorn/cairo.hpp`

### Python Runtime

- [Python module](https://github.com/alphapixel/slughorn/blob/main/ext/python/slughorn.cpp): pybind11 bindings · Offline processing entry point. · `ext/python/slughorn.cpp`
- [Python binding units](https://github.com/alphapixel/slughorn/blob/main/ext/python/slughorn-core.cpp): binding surface · Exposes core, canvas, render, SVG, font, emoji, and tessellation APIs. · `ext/python/slughorn-core.cpp`
- [pybind11](https://github.com/alphapixel/slughorn/tree/main/ext/pybind11): vendored dependency · `ext/pybind11`

### Other components

- [CMake build](https://github.com/alphapixel/slughorn/blob/main/CMakeLists.txt): build · Builds the C++ library and optional integrations. · `CMakeLists.txt`
- **Native consumers**: host application · Own GPU resources, shaders, upload, and drawing.
- **Graphics frontends**: external renderer · OpenGL, Vulkan, WebGPU, Metal, DirectX, or scene-graph rendering.
- [CLI launchers](https://github.com/alphapixel/slughorn/blob/main/bin/slughorn): command-line tools · `bin/slughorn`

## Connections

- CMake build → Core implementation: builds
- Core model & API → Core implementation: implemented by
- Canvas authoring → Core model & API: authors shapes
- SVG adapter → Core model & API: imports paths
- FreeType outlines → Core model & API: imports outlines
- Color glyph layers → Core model & API: adds color layers
- Drawing path adapters → Core model & API: ingests paths
- Core implementation → Tessellation utilities: uses
- Core implementation → MSDF generation: generates distance fields
- Core implementation → Render descriptors: prepares atlas data
- Core model & API → Serialization: serializes model
- Native consumers → Core model & API: uses
- Render descriptors → Graphics frontends: uploaded and rendered by
- pybind11 → Python module: binds with
- Python module → Python binding units: loads
- Python binding units → Core model & API: exposes
- CLI launchers → Python module: launches processing