Skip to main content

sdf_text/
lib.rs

1//! `sdf-text` — a Rust port of lib3's `src/sdf-text/` module (signed-distance-
2//! field text rendered from real font outlines) plus its `src/sdf/edt.js`
3//! dependency.
4//!
5//! This is a `three-rs` addon, not a standalone text layout crate: steps 1–3
6//! of the port (font metrics and outlines, the raster + EDT + atlas, and
7//! layout — [`vector_font`], [`raster`], [`edt`], [`text_builder`]) are pure
8//! CPU code with no `three-rs` dependency, but [`BatchedText`] — steps 4–5 —
9//! depends on `three-rs` for the scene graph, the node material and the
10//! `R32Float` atlas texture: it is an `InstancedMesh` whose
11//! [`node()`](BatchedText::node) you add to a `three-rs` `Scene` like any
12//! other object, and which the `three-rs` renderer then draws.
13//!
14//! The port is graded against golden data dumped from the JavaScript; see
15//! `tests/golden/README.md` for the dump commands and `README.md` for the
16//! deviation and skip registers.
17//!
18//! Ladder position: steps 1–3 of the plan (font metrics and outlines, the
19//! raster + EDT + atlas, and layout) need no GPU and are graded against golden
20//! data. [`batched_text::BatchedText`] is steps 4–5: it depends on `three-rs`
21//! for the scene graph, the node material and the `R32Float` atlas texture, so
22//! `cargo test -p sdf-text` covers it only where the packing can be checked on
23//! the CPU; the pixel gates live in `three-rs`' own `tests/`.
24//!
25//! # Example
26//!
27//! Batching needs no font to compile against — an empty [`Text`] lays out to
28//! nothing — so this shows the shape without pulling in a font file. `no_run`
29//! only because [`BatchedText::node`] is meant to be added to a real scene,
30//! which this snippet does not build.
31//!
32//! ```no_run
33//! use sdf_text::{BatchedText, BatchedTextOptions, Text};
34//! use three_rs::Scene;
35//!
36//! let mut batch = BatchedText::new(64, 1024, BatchedTextOptions::default());
37//! let member_id = batch.add_text(Text::new());
38//! batch.sync();
39//!
40//! let mut scene = Scene::new();
41//! scene.add(batch.node());
42//! # let _ = member_id;
43//! ```
44//!
45//! # Member transforms
46//!
47//! A member's whole `matrix_world` reaches the GPU as its glyphs' instance
48//! matrix, so rotation and scale work as well as position — a label laid flat
49//! on a floor with `set_rotation( -PI / 2, 0, 0 )` on
50//! [`BatchedText::member_node`] renders flat. Members are not billboarded and
51//! are not position-only.
52//!
53//! # Frustum culling
54//!
55//! [`BatchedText::sync`] computes the batch's own bounding sphere over every
56//! glyph quad of every member, in the batch node's space, and stores it on the
57//! node — the way `BatchedMesh.computeBoundingSphere` does in three.js. The
58//! frustum cull reads that sphere in preference to the geometry's, so a batch
59//! node left at the origin with its members placed far away is culled on where
60//! its glyphs actually are, not on where its node is. Members added or moved
61//! after a `sync()` are only bounded by the next `sync()` (or by
62//! [`BatchedText::set_matrix_at`], which updates the sphere as it goes), which
63//! is the same contract as the attribute packing.
64
65#![warn(missing_docs)]
66pub(crate) mod batched_text;
67pub mod edt;
68pub(crate) mod error;
69pub mod raster;
70pub mod text;
71pub mod text_builder;
72pub mod vector_font;
73pub mod vector_font_atlas;
74
75pub use batched_text::{BatchedText, BatchedTextOptions, GLYPH_QUAD_PAD};
76pub use edt::{compute_sdf, compute_sdf_default, edt_1d};
77pub use error::Error;
78pub use text::{OpacitySink, Text};
79pub use text_builder::{
80    empty_render_info, layout_text, layout_text_vector, Anchor, LaidOutGlyph, LayoutParams,
81    LineHeight, TextAlign, TextRenderInfo,
82};
83pub use vector_font::{BBox, PathCommand, VectorFont};
84pub use vector_font_atlas::{GlyphMetrics, VectorFontAtlas};
85
86/// The constant set used by lib3's *test* (`src/sdf/index.js`), which matches
87/// neither `FontAtlas` (128/64/8/16) nor `VectorFontAtlas` (256/64/—/32). The
88/// ported test layers 2–4 use these, so they are kept as their own namespace
89/// rather than being folded into either atlas.
90pub mod sdf_defaults {
91    /// Rasterised glyph size, px.
92    pub const GLYPH_SIZE: u32 = 64;
93    /// SDF tile size, px.
94    pub const SDF_SIZE: u32 = 32;
95    /// SDF padding within the tile, px.
96    pub const SDF_PADDING: u32 = 4;
97    /// Encoded distance span, px.
98    pub const MAX_DISTANCE: f64 = 8.0;
99    /// `computeSDF`'s coverage threshold, 0–255.
100    pub const ALPHA_THRESHOLD: u8 = 128;
101}