SDF text rendering

---

---

🎯 Recommended outlineSize Range for SDF Rendering (Axmol Engine)

Use Case	Suggested Maximum Range	Notes
UI text rendering	0.5 – 2.0	Safe under Axmol defaults; ideal for buttons, labels, and high-DPI interfaces
Headings or large fonts	2.0 – 3.0 (requires tuning)	Approaches precision limits; ensure SDF texture resolution is sufficient
Special effects (e.g. glow, stroke, shadow)	3.0 – 6.0 (requires spread override)	Requires modifying engine defaults; may impact performance
Experimental or extreme effects	>6.0 (not recommended)	Exceeds safe range; likely to cause distortion or shader artifacts

---

⚠️ Key Considerations

• Engine default spread: Axmol defines spread = 6.0 in FontFreeType.cpp.
  Combined with shader-side scale = 1.5, the CPU-side safe outlineSize is:

However, due to edge falloff and precision loss, the recommended safe range is ≤2.0.

• To support thicker outlines:

• Increase spread in FontFreeType.cpp (e.g. to 12.0 – 16.0)

• Synchronize the same value in label_distanceOutline.glsl (uniform float spread)

• Recalculate safe outlineSize as spread / scale

• SDF texture resolution: Larger outlines require higher-resolution distance fields to avoid blur or aliasing.

• Font size: Applying large outlines to small fonts can overwhelm glyphs and reduce legibility.

• Performance impact: Bigger outlines increase fragment shader workload, especially with dense text rendering.

• Font spacing compatibility: Fonts with tight horizontal spacing may suffer from character overlap when using thicker outlines.
  Use the following API to increase spacing:

label->setAdditionalKerning(float spacing);

✅ Practical Tips

• Start with outlineSize = 1.0 and gradually increase based on visual clarity and performance.
• Use debug mode to visualize SDF distance fields and validate outline boundaries.
• Maintain a mapping table between FreeType spread and safe outlineSize ranges:

FreeType spread	Shader scale	Safe outlineSize (CPU)
6	1.5	≤2.0
12	1.5	≤4.0
16	1.5	≤5.3