Merge pull request #52719 from Calinou/doc-msdf-font-rendering

Improve documentation related to MSDF font rendering

3 files changed, 5 insertions, 3 deletions

diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml
index 4641bc52a4..501f89fa0d 100644
--- a/doc/classes/CanvasItem.xml
+++ b/doc/classes/CanvasItem.xml
@@ -115,7 +115,7 @@
 			<argument index="4" name="outline" type="float" default="0.0" />
 			<argument index="5" name="pixel_range" type="float" default="4.0" />
 			<description>
-				Draws a textured rectangle region of the multi-channel signed distance field texture at a given position, optionally modulated by a color.
+				Draws a textured rectangle region of the multi-channel signed distance field texture at a given position, optionally modulated by a color. See [method FontData.set_multichannel_signed_distance_field] for more information and caveats about MSDF font rendering.
 				If [code]outline[/code] is positive, each alpha channel value of pixel in region is set to maximum value of true distance in the [code]outline[/code] radius.
 				Value of the [code]pixel_range[/code] should the same that was used during distance field texture generation.
 			</description>
diff --git a/doc/classes/FontData.xml b/doc/classes/FontData.xml
index 72af7ca485..384d7c81f4 100644
--- a/doc/classes/FontData.xml
+++ b/doc/classes/FontData.xml
@@ -558,7 +558,8 @@
 			<return type="void" />
 			<argument index="0" name="msdf" type="bool" />
 			<description>
-				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. MSDF rendering allows displaying the font at any scaling factor without blurriness, and without incurring a CPU cost when the font size changes (since the font no longer needs to be rasterized on the CPU). 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] 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.
 			</description>
 		</method>
 		<method name="set_oversampling">
diff --git a/doc/classes/TextServer.xml b/doc/classes/TextServer.xml
index d7af2204cf..661c4f05ef 100644
--- a/doc/classes/TextServer.xml
+++ b/doc/classes/TextServer.xml
@@ -624,7 +624,8 @@
 			<argument index="0" name="font_rid" type="RID" />
 			<argument index="1" name="msdf" type="bool" />
 			<description>
-				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 generated from the dynamic font vector data. MSDF rendering allows displaying the font at any scaling factor without blurriness, and without incurring a CPU cost when the font size changes (since the font no longer needs to be rasterized on the CPU). 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] 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.
 			</description>
 		</method>
 		<method name="font_set_oversampling">