Expand description
sdf-text — a Rust port of lib3’s src/sdf-text/ module (signed-distance-
field text rendered from real font outlines) plus its src/sdf/edt.js
dependency.
This is a three-rs addon, not a standalone text layout crate: steps 1–3
of the port (font metrics and outlines, the raster + EDT + atlas, and
layout — vector_font, raster, edt, text_builder) are pure
CPU code with no three-rs dependency, but BatchedText — steps 4–5 —
depends on three-rs for the scene graph, the node material and the
R32Float atlas texture: it is an InstancedMesh whose
node() you add to a three-rs Scene like any
other object, and which the three-rs renderer then draws.
The port is graded against golden data dumped from the JavaScript; see
tests/golden/README.md for the dump commands and README.md for the
deviation and skip registers.
Ladder position: steps 1–3 of the plan (font metrics and outlines, the
raster + EDT + atlas, and layout) need no GPU and are graded against golden
data. batched_text::BatchedText is steps 4–5: it depends on three-rs
for the scene graph, the node material and the R32Float atlas texture, so
cargo test -p sdf-text covers it only where the packing can be checked on
the CPU; the pixel gates live in three-rs’ own tests/.
§Example
Batching needs no font to compile against — an empty Text lays out to
nothing — so this shows the shape without pulling in a font file. no_run
only because BatchedText::node is meant to be added to a real scene,
which this snippet does not build.
use sdf_text::{BatchedText, BatchedTextOptions, Text};
use three_rs::Scene;
let mut batch = BatchedText::new(64, 1024, BatchedTextOptions::default());
let member_id = batch.add_text(Text::new());
batch.sync();
let mut scene = Scene::new();
scene.add(batch.node());§Member transforms
A member’s whole matrix_world reaches the GPU as its glyphs’ instance
matrix, so rotation and scale work as well as position — a label laid flat
on a floor with set_rotation( -PI / 2, 0, 0 ) on
BatchedText::member_node renders flat. Members are not billboarded and
are not position-only.
§Frustum culling
BatchedText::sync computes the batch’s own bounding sphere over every
glyph quad of every member, in the batch node’s space, and stores it on the
node — the way BatchedMesh.computeBoundingSphere does in three.js. The
frustum cull reads that sphere in preference to the geometry’s, so a batch
node left at the origin with its members placed far away is culled on where
its glyphs actually are, not on where its node is. Members added or moved
after a sync() are only bounded by the next sync() (or by
BatchedText::set_matrix_at, which updates the sphere as it goes), which
is the same contract as the attribute packing.
Re-exports§
pub use edt::compute_sdf;pub use edt::compute_sdf_default;pub use edt::edt_1d;pub use text::OpacitySink;pub use text::Text;pub use text_builder::empty_render_info;pub use text_builder::layout_text;pub use text_builder::layout_text_vector;pub use text_builder::Anchor;pub use text_builder::LaidOutGlyph;pub use text_builder::LayoutParams;pub use text_builder::LineHeight;pub use text_builder::TextAlign;pub use text_builder::TextRenderInfo;pub use vector_font::BBox;pub use vector_font::PathCommand;pub use vector_font::VectorFont;pub use vector_font_atlas::GlyphMetrics;pub use vector_font_atlas::VectorFontAtlas;
Modules§
- edt
- Exact Euclidean distance transform — a port of lib3’s
src/sdf/edt.js(Felzenszwalb & Huttenlocher, the lower-envelope-of-parabolas 1-D pass run over columns then rows). Not 8SSEDT, not a Chebyshev approximation. - raster
- The 256 px coverage rasteriser — steps 2–6 of
VectorFontAtlas.rasterizeGlyphin the port plan: map the outline into the raster with an affine, fill it white with the nonzero winding rule and anti-aliasing, and read the alpha plane back. - sdf_
defaults - The constant set used by lib3’s test (
src/sdf/index.js), which matches neitherFontAtlas(128/64/8/16) norVectorFontAtlas(256/64/—/32). The ported test layers 2–4 use these, so they are kept as their own namespace rather than being folded into either atlas. - text
- The
Textmember — a port of lib3’ssrc/sdf-text/Text.js. - text_
builder - Synchronous text layout — a port of lib3’s
src/sdf-text/TextBuilder.js. - vector_
font - Parsed font with real typographic metrics and kerning — a port of lib3’s
src/sdf-text/VectorFont.js, which itself is a thin layer over opentype.js. - vector_
font_ atlas - Single-channel
f32SDF atlas built from real font outlines — a port of lib3’ssrc/sdf-text/VectorFontAtlas.js(steps 4–10 of the plan’s §1.3).
Structs§
- Batched
Text - The instanced draw for a batch of
Textmembers — a port of lib3’sBatchedText. See the module doc for the shape of the instance data and where it deliberately diverges from the JS. - Batched
Text Options - The
optionsobject ofnew BatchedText( maxTextCount, maxGlyphCount, _baseMaterial, options ), vector mode only —FontAtlasis in the skip register, sooptions.font != nullis assumed and_vectorModeis always true.
Enums§
- Error
- Everything the public API of
sdf-textcan fail with.
Constants§
- GLYPH_
QUAD_ PAD BatchedText.js:23— the fraction of each glyph’s ink size that the quad and the sampled sub-rect are both grown by, so the outline/AA halo around the ink is not clipped at the ink bbox while the mapping stays ink↔ink.