Skip to content

Commit 20bfc52

Browse files
committed
Document EMJC bitmap compression not being supported in Using fonts
- Document which system fonts are used on Android when using aliases. - Mention font metrics varying across platforms when using system fonts. - Fix notice about which platforms support system fonts.
1 parent 2eba49b commit 20bfc52

File tree

1 file changed

+35
-15
lines changed

1 file changed

+35
-15
lines changed

tutorials/ui/gui_using_fonts.rst

Lines changed: 35 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -297,13 +297,18 @@ The downsides of MSDF font rendering are:
297297
`Google Fonts <https://fonts.google.com>`__, try downloading the font from the
298298
font author's official website instead.
299299

300+
.. _doc_using_fonts_emoji:
301+
300302
Using emoji
301303
^^^^^^^^^^^
302304

303305
Godot has limited support for emoji fonts:
304306

305307
- CBDT/CBLC (embedded PNGs) and SVG emoji fonts are supported.
306308
- COLR/CPAL emoji fonts (custom vector format) are **not** supported.
309+
- EMJC bitmap image compression (used by iOS' system emoji font) is **not** supported.
310+
This means that to support emoji on iOS, you must use a custom font that
311+
uses SVG or PNG bitmap compression instead.
307312

308313
For Godot to be able to display emoji, the font used (or one of its
309314
:ref:`fallbacks <doc_using_fonts_font_fallbacks>`) needs to include them.
@@ -326,7 +331,6 @@ you get the expected result:
326331

327332
Correct appearance after adding an emoji font to the label
328333

329-
330334
To use a regular font alongside emoji, it's recommended to specify a
331335
:ref:`fallback font <doc_using_fonts_font_fallbacks>` that points to the
332336
emoji font in the regular font's advanced import options. If you wish to use
@@ -644,7 +648,7 @@ System fonts
644648

645649
.. warning::
646650

647-
Loading system fonts is only supported on Windows, macOS and Linux.
651+
Loading system fonts is only supported on Windows, macOS, Linux, Android and iOS.
648652

649653
System fonts are a different type of resource compared to imported fonts. They
650654
are never actually imported into the project, but are loaded at run-time. This
@@ -656,6 +660,11 @@ has 2 benefits:
656660
issues that would occur if proprietary system fonts were distributed alongside
657661
the project.
658662

663+
The engine automatically uses system fonts as fallback fonts, which makes it
664+
possible to display CJK characters and emoji without having to load a custom
665+
font. There are some restrictions that apply though, as mentioned in the
666+
:ref:`Using emoji <doc_using_fonts_emoji>` section.
667+
659668
Create a SystemFont resource in the location where you desire to use the system font:
660669

661670
.. figure:: img/using_fonts_system_font_create.webp
@@ -672,19 +681,25 @@ You can either specify one or more font names explicitly (such as ``Arial``), or
672681
specify the name of a font *alias* that maps to a "standard" default font for
673682
the system:
674683

675-
+----------------+-----------------+----------------+-------------------------+
676-
| Font alias | Windows | macOS/iOS | Linux |
677-
+================+=================+================+=========================+
678-
| ``sans-serif`` | Arial | Helvetica | *Handled by fontconfig* |
679-
+----------------+-----------------+----------------+-------------------------+
680-
| ``serif`` | Times New Roman | Times | *Handled by fontconfig* |
681-
+----------------+-----------------+----------------+-------------------------+
682-
| ``monospace`` | Courier New | Courier | *Handled by fontconfig* |
683-
+----------------+-----------------+----------------+-------------------------+
684-
| ``cursive`` | Comic Sans MS | Apple Chancery | *Handled by fontconfig* |
685-
+----------------+-----------------+----------------+-------------------------+
686-
| ``fantasy`` | Gabriola | Papyrus | *Handled by fontconfig* |
687-
+----------------+-----------------+----------------+-------------------------+
684+
.. Android font information sourced from <https://android.googlesource.com/platform/frameworks/base/+/master/data/fonts/fonts.xml>
685+
686+
+----------------+-----------------+----------------+-------------------------+-------------------------+
687+
| Font alias | Windows | macOS/iOS | Linux | Android |
688+
+================+=================+================+=========================+=========================+
689+
| ``sans-serif`` | Arial | Helvetica | *Handled by fontconfig* | Roboto / Noto Sans |
690+
+----------------+-----------------+----------------+-------------------------+-------------------------+
691+
| ``serif`` | Times New Roman | Times | *Handled by fontconfig* | Noto Serif |
692+
+----------------+-----------------+----------------+-------------------------+-------------------------+
693+
| ``monospace`` | Courier New | Courier | *Handled by fontconfig* | Droid Sans Mono |
694+
+----------------+-----------------+----------------+-------------------------+-------------------------+
695+
| ``cursive`` | Comic Sans MS | Apple Chancery | *Handled by fontconfig* | Dancing Script |
696+
+----------------+-----------------+----------------+-------------------------+-------------------------+
697+
| ``fantasy`` | Gabriola | Papyrus | *Handled by fontconfig* | Droid Sans Mono |
698+
+----------------+-----------------+----------------+-------------------------+-------------------------+
699+
700+
On Android, Roboto is used for Latin/Cyrillic text and Noto Sans is used for
701+
other languages' glyphs such as CJK. On third-party Android distributions, the
702+
exact font selection may differ.
688703

689704
If specifying more than one font, the first font that is found on the system
690705
will be used (from top to bottom). Font names and aliases are case-insensitive
@@ -693,6 +708,11 @@ on all platforms.
693708
Like for font variations, you can save the SystemFont arrangement to a resource
694709
file to reuse it in other places.
695710

711+
Remember that different system fonts have different metrics, which means that
712+
text that can fit within a rectangle on one platform may not be doing so on
713+
another platform. Always reserve some additional space during development so
714+
that labels can extend further if needed.
715+
696716
.. note::
697717

698718
Unlike Windows and macOS/iOS, the set of default fonts shipped on Linux

0 commit comments

Comments
 (0)