Skip to main content

Crate sdf_text

Crate sdf_text 

Source
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.rasterizeGlyph in 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 neither FontAtlas (128/64/8/16) nor VectorFontAtlas (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 Text member — a port of lib3’s src/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 f32 SDF atlas built from real font outlines — a port of lib3’s src/sdf-text/VectorFontAtlas.js (steps 4–10 of the plan’s §1.3).

Structs§

BatchedText
The instanced draw for a batch of Text members — a port of lib3’s BatchedText. See the module doc for the shape of the instance data and where it deliberately diverges from the JS.
BatchedTextOptions
The options object of new BatchedText( maxTextCount, maxGlyphCount, _baseMaterial, options ), vector mode only — FontAtlas is in the skip register, so options.font != null is assumed and _vectorMode is always true.

Enums§

Error
Everything the public API of sdf-text can 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.