From fcf54cabba28b45797093eca9d308868e543f92d Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Mon, 19 Dec 2022 17:15:44 +0100 Subject: [PATCH] Document MDSF font outlines may require `msdf_pixel_range` adjustments --- doc/classes/Button.xml | 1 + doc/classes/CheckBox.xml | 1 + doc/classes/CheckButton.xml | 1 + doc/classes/CodeEdit.xml | 1 + doc/classes/ColorPickerButton.xml | 1 + doc/classes/FontFile.xml | 14 ++++++++------ doc/classes/ItemList.xml | 1 + doc/classes/Label.xml | 1 + doc/classes/LineEdit.xml | 1 + doc/classes/LinkButton.xml | 1 + doc/classes/MenuBar.xml | 1 + doc/classes/MenuButton.xml | 1 + doc/classes/OptionButton.xml | 1 + doc/classes/PopupMenu.xml | 1 + doc/classes/ProgressBar.xml | 1 + doc/classes/RichTextLabel.xml | 1 + doc/classes/TabBar.xml | 1 + doc/classes/TabContainer.xml | 1 + doc/classes/TextEdit.xml | 1 + doc/classes/Tree.xml | 1 + 20 files changed, 27 insertions(+), 6 deletions(-) diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml index d2c9a7748636..961f3c495a77 100644 --- a/doc/classes/Button.xml +++ b/doc/classes/Button.xml @@ -118,6 +118,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. [Font] of the [Button]'s text. diff --git a/doc/classes/CheckBox.xml b/doc/classes/CheckBox.xml index 699e872e99b2..3ee18cf3514d 100644 --- a/doc/classes/CheckBox.xml +++ b/doc/classes/CheckBox.xml @@ -43,6 +43,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The [Font] to use for the [CheckBox] text. diff --git a/doc/classes/CheckButton.xml b/doc/classes/CheckButton.xml index dfbaa7cbee77..03578cafd015 100644 --- a/doc/classes/CheckButton.xml +++ b/doc/classes/CheckButton.xml @@ -43,6 +43,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The [Font] to use for the [CheckButton] text. diff --git a/doc/classes/CodeEdit.xml b/doc/classes/CodeEdit.xml index e7ef5fb289aa..c313e6c8756a 100644 --- a/doc/classes/CodeEdit.xml +++ b/doc/classes/CodeEdit.xml @@ -651,6 +651,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. Sets the default [Font]. diff --git a/doc/classes/ColorPickerButton.xml b/doc/classes/ColorPickerButton.xml index b7a0bdfb0c95..2a37cc162afb 100644 --- a/doc/classes/ColorPickerButton.xml +++ b/doc/classes/ColorPickerButton.xml @@ -79,6 +79,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. [Font] of the [ColorPickerButton]'s text. diff --git a/doc/classes/FontFile.xml b/doc/classes/FontFile.xml index 1019c271dcfe..69a762777421 100644 --- a/doc/classes/FontFile.xml +++ b/doc/classes/FontFile.xml @@ -570,7 +570,7 @@ Weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. - If set to [code]true[/code], auto-hinting is supported and preferred over font built-in hinting. Used by dynamic fonts only. + If set to [code]true[/code], auto-hinting is supported and preferred over font built-in hinting. Used by dynamic fonts only (MSDF fonts don't support hinting). If set to [code]true[/code], generate mipmaps for the font textures. @@ -579,25 +579,27 @@ Font hinting mode. Used by dynamic fonts only. - The width of the range around the shape between the minimum and maximum representable signed distance. + The width of the range around the shape between the minimum and maximum representable signed distance. If using font outlines, [member msdf_pixel_range] must be set to at least [i]twice[/i] the size of the largest font outline. The default [member msdf_pixel_range] value of [code]16[/code] allows outline sizes up to [code]8[/code] to look correct. - Source font size used to generate MSDF textures. + Source font size used to generate MSDF textures. Higher values allow for more precision, but are slower to render and require more memory. Only increase this value if you notice a visible lack of precision in glyph rendering. - If set to [code]true[/code], glyphs of all sizes are rendered using single multichannel signed distance field generated from the dynamic font vector data. + If set to [code]true[/code], glyphs of all sizes are rendered using single multichannel signed distance field (MSDF) generated from the dynamic font vector data. Since this approach does not rely on rasterizing the font every time its size changes, this allows for resizing the font in real-time without any performance penalty. Text will also not look grainy for [Control]s that are scaled down (or for [Label3D]s viewed from a long distance). As a downside, font hinting is not available with MSDF. The lack of font hinting may result in less crisp and less readable fonts at small sizes. + [b]Note:[/b] If using font outlines, [member msdf_pixel_range] must be set to at least [i]twice[/i] the size of the largest font outline. + [b]Note:[/b] MSDF font rendering does not render glyphs with overlapping shapes correctly. Overlapping shapes are not valid per the OpenType standard, but are still commonly found in many font files, especially those converted by Google Fonts. To avoid issues with overlapping glyphs, consider downloading the font file directly from the type foundry instead of relying on Google Fonts. Font OpenType feature set override. - Font oversampling factor, if set to [code]0.0[/code] global oversampling factor is used instead. Used by dynamic fonts only. + Font oversampling factor. If set to [code]0.0[/code], the global oversampling factor is used instead. Used by dynamic fonts only (MSDF fonts ignore oversampling). Font style name. - Font glyph subpixel positioning mode. Subpixel positioning provides shaper text and better kerning for smaller font sizes, at the cost of memory usage and font rasterization speed. Use [constant TextServer.SUBPIXEL_POSITIONING_AUTO] to automatically enable it based on the font size. + Font glyph subpixel positioning mode. Subpixel positioning provides shaper text and better kerning for smaller font sizes, at the cost of higher memory usage and lower font rasterization speed. Use [constant TextServer.SUBPIXEL_POSITIONING_AUTO] to automatically enable it based on the font size. diff --git a/doc/classes/ItemList.xml b/doc/classes/ItemList.xml index 844f260971e1..c485d26e0c76 100644 --- a/doc/classes/ItemList.xml +++ b/doc/classes/ItemList.xml @@ -459,6 +459,7 @@ The size of the item text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The vertical spacing between items. diff --git a/doc/classes/Label.xml b/doc/classes/Label.xml index cd87b4558f12..1a8cbf05846c 100644 --- a/doc/classes/Label.xml +++ b/doc/classes/Label.xml @@ -111,6 +111,7 @@ Text outline size. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The horizontal offset of the text's shadow. diff --git a/doc/classes/LineEdit.xml b/doc/classes/LineEdit.xml index e57cc68b3694..b8383aaed906 100644 --- a/doc/classes/LineEdit.xml +++ b/doc/classes/LineEdit.xml @@ -424,6 +424,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. Font used for the text. diff --git a/doc/classes/LinkButton.xml b/doc/classes/LinkButton.xml index 184ba1ba7a4e..b3938999f38c 100644 --- a/doc/classes/LinkButton.xml +++ b/doc/classes/LinkButton.xml @@ -76,6 +76,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The vertical space between the baseline of text and the underline. diff --git a/doc/classes/MenuBar.xml b/doc/classes/MenuBar.xml index e8505937ff42..79876e56a3ae 100644 --- a/doc/classes/MenuBar.xml +++ b/doc/classes/MenuBar.xml @@ -143,6 +143,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. [Font] of the menu item's text. diff --git a/doc/classes/MenuButton.xml b/doc/classes/MenuButton.xml index 4d5d5a011bd1..30611495707e 100644 --- a/doc/classes/MenuButton.xml +++ b/doc/classes/MenuButton.xml @@ -75,6 +75,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. [Font] of the [MenuButton]'s text. diff --git a/doc/classes/OptionButton.xml b/doc/classes/OptionButton.xml index e63e82264893..a58a6249ae79 100644 --- a/doc/classes/OptionButton.xml +++ b/doc/classes/OptionButton.xml @@ -259,6 +259,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. [Font] of the [OptionButton]'s text. diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index 6810b0e8e4a5..8dec4eaf86a5 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -584,6 +584,7 @@ The size of the item text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The size of the labeled separator text outline. diff --git a/doc/classes/ProgressBar.xml b/doc/classes/ProgressBar.xml index 510b8d5bd10b..9f89a4e4c3ad 100644 --- a/doc/classes/ProgressBar.xml +++ b/doc/classes/ProgressBar.xml @@ -42,6 +42,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. Font used to draw the fill percentage if [member show_percentage] is [code]true[/code]. diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index f587ababfece..e4bc2db104a1 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -656,6 +656,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The horizontal offset of the font's shadow. diff --git a/doc/classes/TabBar.xml b/doc/classes/TabBar.xml index 713c0166513f..8d56cbda13c9 100644 --- a/doc/classes/TabBar.xml +++ b/doc/classes/TabBar.xml @@ -319,6 +319,7 @@ The size of the tab text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The font used to draw tab names. diff --git a/doc/classes/TabContainer.xml b/doc/classes/TabContainer.xml index e2e7a0c37e4a..c744c9b43941 100644 --- a/doc/classes/TabContainer.xml +++ b/doc/classes/TabContainer.xml @@ -214,6 +214,7 @@ The size of the tab text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The space at the left or right edges of the tab bar, accordingly with the current [member tab_alignment]. diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index d4f5233438e4..1efd0f9326cd 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -1396,6 +1396,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. Sets the default [Font]. diff --git a/doc/classes/Tree.xml b/doc/classes/Tree.xml index 629c2714173c..584a2a2a7ba1 100644 --- a/doc/classes/Tree.xml +++ b/doc/classes/Tree.xml @@ -522,6 +522,7 @@ The size of the text outline. + [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. The space between the parent relationship lines for the selected [TreeItem] and the relationship lines to its siblings that are not selected.