Storage space or time waste

Oct 13, 2025 by wbrum.org 77 views

Extended TinySDF Text Rendering: A Proposal for Improved Performance and Robustness

Motivation

In the style specification for MapLibre, the root glyphs property points to a series of server-side glyph PBFs. While this property is technically optional, it is required if any symbol layer has a text-field property. However, the glyph PBF format has several limitations that hinder its adoption and usage. In this article, we will explore the limitations of the glyph PBF format and propose a solution to extend the existing TinySDF path for local text rendering to cover every codepoint, not just ideographic code blocks.

Limitations of Glyph PBF Format

The glyph PBF format has several limitations that make it less desirable for text rendering:

Special tooling required: Glyph PBFs require special tooling instead of the more widespread tooling for custom fonts available on each platform.
Bandwidth waste: Downloading glyph PBFs wastes bandwidth when the surrounding webpage or application already has to download the same fonts in a different format.
Storage space or time waste: Downloading offline maps requires downloading all possible glyph PBFs or scanning all downloaded tiles for text-fields to determine which glyph PBFs to download.
No guarantee of text rendering: If the specified glyph PBFs don’t load for some reason, the user is unable to see the text at all.
Inordinately more glyph PBFs required: Expanding text rendering support beyond the Basic Multilingual Plane would require a webmaster to generate and host inordinately more glyph PBFs.
Assumed one-to-one correspondence between Unicode codepoints and font glyphs: An assumed one-to-one correspondence between Unicode codepoints and font glyphs does not hold in writing systems that require contextual text shaping or ligatures.
Platform-specific limitations: Some specialized clients lack a viable path to supporting custom fonts in MapLibre stylesheets.

Proposed Change

To address these limitations, we propose leaving glyphs unset when the stylesheet contains a text layer. In this case, the client would be responsible for rendering the text however it can. The client would interpret text-font as a fallback list of font names, which can be influenced by application-specific configuration options external to the stylesheet.

For its part, MapLibre would extend the existing TinySDF path for local text rendering to cover every codepoint, not just ideographic code blocks. The text-font values would be fed into TinySDF to influence font selection; the details differ by platform.

API Modifications

glyphs would no longer be required under any circumstance, not even when a symbol layer has a text-field property. In the absence of glyphs, the text-font property would be interpreted as a fallback list of font names, instead of a concatenated fontstack name.

Migration Plan and Compatibility

Existing styles can continue to specify glyphs as before. To benefit from improved performance, robustness, and (in the future) language support, a style author can omit the glyphs property. They would need to ensure that any text-font property names fonts that exist in the current environment, such as system fonts. Custom fonts would require additional setup depending on the platform.

Alternatives

There are several alternatives to this proposal, including:

Protocol: Implementing a protocol that produces individual glyphs locally on the fly, similar to this proposal.
Root font definitions: Introducing a new root property to register TrueType files and map them to codepoint ranges.
Positioned glyph font: Implementing a positioned glyph font architecture that reuses the existing server-rendered font pipeline.

However, these alternatives have several limitations and drawbacks, including:

Platform-specific limitations: Some alternatives are platform-specific and may not work on all platforms.
Special software required: Some alternatives require special software to generate both the glyph PBFs and vector tiles.
Tight coupling between glyph PBFs and vector tiles: Some alternatives force a tight coupling between glyph PBFs and vector tiles, which may not be desirable.

Proof of Concept

A proof of concept implementation of this proposal is available in the 1ec5/maplibre-gl-js#1 branch. This implementation demonstrates using a custom variable font in an otherwise standard MapLibre map, something that would be infeasible in the current font architecture or any of the alternative proposals.

Conclusion

In conclusion, the glyph PBF format has several limitations that make it less desirable for text rendering. To address these limitations, we propose extending the existing TinySDF path for local text rendering to cover every codepoint, not just ideographic code blocks. This proposal has several advantages, including improved performance, robustness, and (in the future) language support. We believe that this proposal is a step in the right direction and look forward to implementing it in the future.

Future Work

Future work on this proposal includes:

Implementing extended TinySDF: Implementing extended TinySDF in stages, starting with GL JS.
Porting to other platforms: Porting extended TinySDF to other platforms, including MapLibre Native on Android and iOS.
Testing and validation: Testing and validating extended TinySDF to ensure that it works as expected on all platforms.

We believe that this proposal has the potential to improve the performance, robustness, and language support of MapLibre, and we look forward to implementing it in the future.
Extended TinySDF Text Rendering: A Q&A Article

Q: What is the current state of text rendering in MapLibre?

A: Currently, MapLibre uses a glyph PBF format for text rendering, which has several limitations, including special tooling required, bandwidth waste, storage space or time waste, no guarantee of text rendering, inordinately more glyph PBFs required, assumed one-to-one correspondence between Unicode codepoints and font glyphs, and platform-specific limitations.

Q: What is the proposed solution to address these limitations?

A: The proposed solution is to extend the existing TinySDF path for local text rendering to cover every codepoint, not just ideographic code blocks. This would allow MapLibre to render text using a fallback list of font names, which can be influenced by application-specific configuration options external to the stylesheet.

Q: How would this proposal affect existing styles?

A: Existing styles can continue to specify glyphs as before. To benefit from improved performance, robustness, and (in the future) language support, a style author can omit the glyphs property. They would need to ensure that any text-font property names fonts that exist in the current environment, such as system fonts. Custom fonts would require additional setup depending on the platform.

Q: What are the advantages of this proposal?

A: The advantages of this proposal include improved performance, robustness, and (in the future) language support. By extending the existing TinySDF path for local text rendering, MapLibre can render text using a fallback list of font names, which can be influenced by application-specific configuration options external to the stylesheet.

Q: What are the alternatives to this proposal?

A: There are several alternatives to this proposal, including:

Protocol: Implementing a protocol that produces individual glyphs locally on the fly, similar to this proposal.
Root font definitions: Introducing a new root property to register TrueType files and map them to codepoint ranges.
Positioned glyph font: Implementing a positioned glyph font architecture that reuses the existing server-rendered font pipeline.

Q: What are the limitations and drawbacks of these alternatives?

A: The limitations and drawbacks of these alternatives include:

Platform-specific limitations: Some alternatives are platform-specific and may not work on all platforms.
Special software required: Some alternatives require special software to generate both the glyph PBFs and vector tiles.
Tight coupling between glyph PBFs and vector tiles: Some alternatives force a tight coupling between glyph PBFs and vector tiles, which may not be desirable.

Q: What is the current status of this proposal?

A: The current status of this proposal is that it has been proposed and is being considered for implementation. A proof of concept implementation of this proposal is available in the 1ec5/maplibre-gl-js#1 branch.

Q: What is the timeline for implementing this proposal?

A: The timeline for implementing this proposal is not yet determined. However, it is expected to be implemented in stages, starting with GL JS, and then ported to other platforms, including MapLibre Native on Android and iOS.

Q: How can I get involved in the implementation of this proposal?

A: If you are interested in getting involved in the implementation of this proposal, you can:

Join the MapLibre community: Join the MapLibre community to stay up-to-date on the latest developments and to contribute to the implementation of this proposal.
Contribute to the code: Contribute to the code by submitting pull requests or participating in code reviews.
Provide feedback: Provide feedback on the proposal and the implementation to help shape the final product.

We hope this Q&A article has provided you with a better understanding of the proposed solution to address the limitations of the glyph PBF format in MapLibre. If you have any further questions or would like to get involved in the implementation of this proposal, please don't hesitate to reach out.