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.
This commit is contained in:
Hugo Locurcio
2023-06-07 12:55:04 +02:00
parent 2eba49b466
commit 20bfc52fd1

View File

@@ -297,6 +297,8 @@ The downsides of MSDF font rendering are:
`Google Fonts <https://fonts.google.com>`__, try downloading the font from the `Google Fonts <https://fonts.google.com>`__, try downloading the font from the
font author's official website instead. font author's official website instead.
.. _doc_using_fonts_emoji:
Using emoji Using emoji
^^^^^^^^^^^ ^^^^^^^^^^^
@@ -304,6 +306,9 @@ Godot has limited support for emoji fonts:
- CBDT/CBLC (embedded PNGs) and SVG emoji fonts are supported. - CBDT/CBLC (embedded PNGs) and SVG emoji fonts are supported.
- COLR/CPAL emoji fonts (custom vector format) are **not** supported. - COLR/CPAL emoji fonts (custom vector format) are **not** supported.
- EMJC bitmap image compression (used by iOS' system emoji font) is **not** supported.
This means that to support emoji on iOS, you must use a custom font that
uses SVG or PNG bitmap compression instead.
For Godot to be able to display emoji, the font used (or one of its For Godot to be able to display emoji, the font used (or one of its
:ref:`fallbacks <doc_using_fonts_font_fallbacks>`) needs to include them. :ref:`fallbacks <doc_using_fonts_font_fallbacks>`) needs to include them.
@@ -326,7 +331,6 @@ you get the expected result:
Correct appearance after adding an emoji font to the label Correct appearance after adding an emoji font to the label
To use a regular font alongside emoji, it's recommended to specify a To use a regular font alongside emoji, it's recommended to specify a
:ref:`fallback font <doc_using_fonts_font_fallbacks>` that points to the :ref:`fallback font <doc_using_fonts_font_fallbacks>` that points to the
emoji font in the regular font's advanced import options. If you wish to use emoji font in the regular font's advanced import options. If you wish to use
@@ -644,7 +648,7 @@ System fonts
.. warning:: .. warning::
Loading system fonts is only supported on Windows, macOS and Linux. Loading system fonts is only supported on Windows, macOS, Linux, Android and iOS.
System fonts are a different type of resource compared to imported fonts. They System fonts are a different type of resource compared to imported fonts. They
are never actually imported into the project, but are loaded at run-time. This are never actually imported into the project, but are loaded at run-time. This
@@ -656,6 +660,11 @@ has 2 benefits:
issues that would occur if proprietary system fonts were distributed alongside issues that would occur if proprietary system fonts were distributed alongside
the project. the project.
The engine automatically uses system fonts as fallback fonts, which makes it
possible to display CJK characters and emoji without having to load a custom
font. There are some restrictions that apply though, as mentioned in the
:ref:`Using emoji <doc_using_fonts_emoji>` section.
Create a SystemFont resource in the location where you desire to use the system font: Create a SystemFont resource in the location where you desire to use the system font:
.. figure:: img/using_fonts_system_font_create.webp .. 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
specify the name of a font *alias* that maps to a "standard" default font for specify the name of a font *alias* that maps to a "standard" default font for
the system: the system:
+----------------+-----------------+----------------+-------------------------+ .. Android font information sourced from <https://android.googlesource.com/platform/frameworks/base/+/master/data/fonts/fonts.xml>
| Font alias | Windows | macOS/iOS | Linux |
+================+=================+================+=========================+ +----------------+-----------------+----------------+-------------------------+-------------------------+
| ``sans-serif`` | Arial | Helvetica | *Handled by fontconfig* | | Font alias | Windows | macOS/iOS | Linux | Android |
+----------------+-----------------+----------------+-------------------------+ +================+=================+================+=========================+=========================+
| ``serif`` | Times New Roman | Times | *Handled by fontconfig* | | ``sans-serif`` | Arial | Helvetica | *Handled by fontconfig* | Roboto / Noto Sans |
+----------------+-----------------+----------------+-------------------------+ +----------------+-----------------+----------------+-------------------------+-------------------------+
| ``monospace`` | Courier New | Courier | *Handled by fontconfig* | | ``serif`` | Times New Roman | Times | *Handled by fontconfig* | Noto Serif |
+----------------+-----------------+----------------+-------------------------+ +----------------+-----------------+----------------+-------------------------+-------------------------+
| ``cursive`` | Comic Sans MS | Apple Chancery | *Handled by fontconfig* | | ``monospace`` | Courier New | Courier | *Handled by fontconfig* | Droid Sans Mono |
+----------------+-----------------+----------------+-------------------------+ +----------------+-----------------+----------------+-------------------------+-------------------------+
| ``fantasy`` | Gabriola | Papyrus | *Handled by fontconfig* | | ``cursive`` | Comic Sans MS | Apple Chancery | *Handled by fontconfig* | Dancing Script |
+----------------+-----------------+----------------+-------------------------+ +----------------+-----------------+----------------+-------------------------+-------------------------+
| ``fantasy`` | Gabriola | Papyrus | *Handled by fontconfig* | Droid Sans Mono |
+----------------+-----------------+----------------+-------------------------+-------------------------+
On Android, Roboto is used for Latin/Cyrillic text and Noto Sans is used for
other languages' glyphs such as CJK. On third-party Android distributions, the
exact font selection may differ.
If specifying more than one font, the first font that is found on the system If specifying more than one font, the first font that is found on the system
will be used (from top to bottom). Font names and aliases are case-insensitive will be used (from top to bottom). Font names and aliases are case-insensitive
@@ -693,6 +708,11 @@ on all platforms.
Like for font variations, you can save the SystemFont arrangement to a resource Like for font variations, you can save the SystemFont arrangement to a resource
file to reuse it in other places. file to reuse it in other places.
Remember that different system fonts have different metrics, which means that
text that can fit within a rectangle on one platform may not be doing so on
another platform. Always reserve some additional space during development so
that labels can extend further if needed.
.. note:: .. note::
Unlike Windows and macOS/iOS, the set of default fonts shipped on Linux Unlike Windows and macOS/iOS, the set of default fonts shipped on Linux