Text Rendering Notes - Revision history

Moini at 14:23, 16 February 2023

2023-02-16T14:23:57Z

← Older revision		Revision as of 14:23, 16 February 2023
Line 303:		Line 303:
	== Vertical Text, Down and Dirty ==		== Vertical Text, Down and Dirty ==

	~~Harbuzz~~ 4.1 introduces some changes to vertical text which need to be accounted for by Inkscape. This prompted a closer look at handling vertical text. This is quite complicated as it involves the interactions of four different libraries (HarfBuzz, Pango, Cairo, and FreeType) and two different programs (Inkscape and FontForge or whatever program is used to generate the font files).		Harfbuzz 4.1 introduces some changes to vertical text which need to be accounted for by Inkscape. This prompted a closer look at handling vertical text. This is quite complicated as it involves the interactions of four different libraries (HarfBuzz, Pango, Cairo, and FreeType) and two different programs (Inkscape and FontForge or whatever program is used to generate the font files).

	=== Fonts ===		=== Fonts ===

Tavmjong: /* Vertical Text, Down and Dirty */

2023-02-15T15:08:14Z

Vertical Text, Down and Dirty

← Older revision		Revision as of 15:08, 15 February 2023
Line 307:		Line 307:
	=== Fonts ===		=== Fonts ===

	The font file can be a TrueType or an OpenType font. The actual difference between the two is ~~very~~ murky and most software no longer tries to distinguish between the two. Both font formats contain a set of tables with the font data (glyph outlines, positioning information, etc.). These table definitions are shared between the formats; the difference being mostly which tables are typically found in which format. ~~The most important tables for vertical text are:~~		The font file can be a TrueType or an OpenType font. The actual difference between the two is murky and most software no longer tries to distinguish between the two. Both font formats contain a set of tables with the font data (glyph outlines, positioning information, etc.). These table definitions are shared between the formats; the difference being mostly which tables are typically found in which format. TrueType fonts have the glyph outline data in the 'glyf' (TrueType outline format) table while OpenType fonts usually use the 'CFF' (Compact Font Format, a.k.a. PostScript Type 1) table (but could also include the 'glyf' table).

			The most important tables for vertical text are:

			* CFF: Compact Font Format (PostScript Type 1) font data. Glyph outlines uses cubic Bezier curves.
			* glyf: TrueType outline font data. Glyph outlines use quadratic Bezier curves.
	* hhea and hmtx: Contain horizontal font metrics. Almost always present.		* hhea and hmtx: Contain horizontal font metrics. Almost always present.
	* vhea and vmtx: Contain vertical font metrics. Usually missing unless a font is designed with vertical text in mind. If present, vertical text will be laid out correctly.		* vhea and vmtx: Contain vertical font metrics. Usually missing unless a font is designed with vertical text in mind. If present, vertical text will be laid out correctly.
Line 320:		Line 324:
	=== FreeType ===		=== FreeType ===

	We use FreeType to extract out font data that we need inside Inkscape including the glyph outlines (needed, for example, when stroking a glyph). HarfBuzz and Pango also use FreeType, although their reliance on FreeType is slowly being removed.		We use FreeType to extract out font data that we need inside Inkscape including the glyph outlines (needed, for example, when stroking a glyph). HarfBuzz and Pango also use FreeType, although their reliance on FreeType is slowly being removed. When a font is missing vertical metrics, FreeType will return glyph paths that center the glyph vertical inside the (em-box?) region.

	=== HarfBuzz ===		=== HarfBuzz ===

	HarfBuzz is responsible for "shaping" a string of characters, that is converting a string of characters into an array of glyphs with positions that can be used to render a section of text. It takes a string of Unicode characters and a font file as input. Until very recently, it had no rendering support.		HarfBuzz is responsible for "shaping" a string of characters, that is converting a string of characters into an array of glyphs with positions that can be used to render a section of text. It takes a string of Unicode characters and a font file as input. Until very recently, it had no rendering support. How the glyphs are positioned for vertical text depends on a variety of factors TO BE DETERMINED. It will also substitute vertical variants of glyphs if available (for example, Japanese punctuation differs between horizontal and vertical text https://en.wikipedia.org/wiki/Japanese_punctuation).

	=== Pango ===		=== Pango ===

Tavmjong: /* Vertical Text, Down and Dirty */

2023-02-15T14:01:43Z

Vertical Text, Down and Dirty

← Older revision		Revision as of 14:01, 15 February 2023
Line 317:		Line 317:
	** etc.		** etc.
	* BASE: Alphabetic, mathematical, CJK, etc. baseline data.		* BASE: Alphabetic, mathematical, CJK, etc. baseline data.

			=== FreeType ===

			We use FreeType to extract out font data that we need inside Inkscape including the glyph outlines (needed, for example, when stroking a glyph). HarfBuzz and Pango also use FreeType, although their reliance on FreeType is slowly being removed.

	=== HarfBuzz ===		=== HarfBuzz ===

Tavmjong: /* Vertical Text, Down and Dirty */

2023-02-15T13:58:33Z

Vertical Text, Down and Dirty

← Older revision		Revision as of 13:58, 15 February 2023
Line 305:		Line 305:
	Harbuzz 4.1 introduces some changes to vertical text which need to be accounted for by Inkscape. This prompted a closer look at handling vertical text. This is quite complicated as it involves the interactions of four different libraries (HarfBuzz, Pango, Cairo, and FreeType) and two different programs (Inkscape and FontForge or whatever program is used to generate the font files).		Harbuzz 4.1 introduces some changes to vertical text which need to be accounted for by Inkscape. This prompted a closer look at handling vertical text. This is quite complicated as it involves the interactions of four different libraries (HarfBuzz, Pango, Cairo, and FreeType) and two different programs (Inkscape and FontForge or whatever program is used to generate the font files).

	* The font file can be a TrueType or an OpenType font. The actual difference between the two is very murky and most software no longer tries to distinguish between the two. Both font formats contain a set of tables with the font data (glyph outlines, positioning information, etc.). These table definitions are shared between the formats; the difference being mostly which tables are typically found in which format. The most important tables for vertical text are:		=== Fonts ===

			The font file can be a TrueType or an OpenType font. The actual difference between the two is very murky and most software no longer tries to distinguish between the two. Both font formats contain a set of tables with the font data (glyph outlines, positioning information, etc.). These table definitions are shared between the formats; the difference being mostly which tables are typically found in which format. The most important tables for vertical text are:

			* hhea and hmtx: Contain horizontal font metrics. Almost always present.
			* vhea and vmtx: Contain vertical font metrics. Usually missing unless a font is designed with vertical text in mind. If present, vertical text will be laid out correctly.
			* GDEF, GPOS, GSUB: These tables contain information on which glyphs should be used and how they should be positioned.
			** How marks should be placed relative to a base glyph.
			** Substitutions of ligatures.
			** Substitution of special vertical text forms.
			** etc.
			* BASE: Alphabetic, mathematical, CJK, etc. baseline data.

			=== HarfBuzz ===

			HarfBuzz is responsible for "shaping" a string of characters, that is converting a string of characters into an array of glyphs with positions that can be used to render a section of text. It takes a string of Unicode characters and a font file as input. Until very recently, it had no rendering support.

			=== Pango ===

			Pango is a higher level text layout program. Recent versions rely on HarfBuzz for shaping. Pango handles things like font substitution (finding the best matching font when the original font is not available) and embedding left-to-right text inside right-to-left text.

			=== Cairo ===

			We use Cairo to actually render the glyphs using information from Pango for where the glyphs are to be placed.

			=== Inkscape ===

			We apply some corrections to the output of Pango for vertical text, things like how the text is aligned to a reference point, fixing the advance to one em-box when vertical metrics are not available, and shifting the glyphs to ensure even spacing between glyph baselines.

	== Terminology ==		== Terminology ==

Tavmjong at 13:41, 15 February 2023

2023-02-15T13:41:06Z

← Older revision		Revision as of 13:41, 15 February 2023
Line 300:		Line 300:

	Inkscape uses the ''slant'' for ''Italic'' fonts to match the text cursor to the text slope. The slant is stored the ''hhea'' and ''vhea'' OpenType tables. FreeType can access these tables; Pango and HarfBuzz cannot. The ''post'' table also has an ''italicAngle'' value, accessible by FreeType.		Inkscape uses the ''slant'' for ''Italic'' fonts to match the text cursor to the text slope. The slant is stored the ''hhea'' and ''vhea'' OpenType tables. FreeType can access these tables; Pango and HarfBuzz cannot. The ''post'' table also has an ''italicAngle'' value, accessible by FreeType.

			== Vertical Text, Down and Dirty ==

			Harbuzz 4.1 introduces some changes to vertical text which need to be accounted for by Inkscape. This prompted a closer look at handling vertical text. This is quite complicated as it involves the interactions of four different libraries (HarfBuzz, Pango, Cairo, and FreeType) and two different programs (Inkscape and FontForge or whatever program is used to generate the font files).

			* The font file can be a TrueType or an OpenType font. The actual difference between the two is very murky and most software no longer tries to distinguish between the two. Both font formats contain a set of tables with the font data (glyph outlines, positioning information, etc.). These table definitions are shared between the formats; the difference being mostly which tables are typically found in which format. The most important tables for vertical text are:


	== Terminology ==		== Terminology ==
Line 318:		Line 325:
	</dl>		</dl>

	~~== Future Section ==~~
	== Future Section ==		== Future Section ==

	</div> <!-- Width -->		</div> <!-- Width -->

Tavmjong: /* Vertical Text */

2021-04-06T15:19:24Z

Vertical Text

← Older revision		Revision as of 15:19, 6 April 2021
Line 191:		Line 191:
	====Vertical Text====		====Vertical Text====

	Vertical text is the Achilles' heel of text rendering! PangoLayout and pango-view show rendering errors for fonts without vertical metrics and for fonts with vertical metrics when used with accents (Pango 1.48.2).		Vertical text is the Achilles' heel of text rendering! PangoLayout and pango-view show rendering errors for fonts without vertical metrics and for fonts with vertical metrics when used with accents (Pango 1.48.1 through 1.48.3).

	* PangoLayout and pango-view create a Cairo font with the FC_VERTICAL_LAYOUT true (Pango 1.48.2 and earlier). This causes Cairo to shift glyphs down and to the left. Recent versions of Pango use HarfBuzz for shaping which uses horizontal metrics and thus should not set FC_VERTICAL_LAYOUT to true. A "fix" merged for 1.48.2 attempts to undo the shift but this fails for fonts without vertical metrics.		* PangoLayout and pango-view create a Cairo font with the FC_VERTICAL_LAYOUT true (Pango 1.48.3 and earlier). This causes Cairo to shift glyphs down and to the left. Recent versions of Pango use HarfBuzz for shaping which uses horizontal metrics and thus should not set FC_VERTICAL_LAYOUT to true. A "fix" merged for 1.48.1 attempts to undo the shift but this fails for fonts without vertical metrics. A better fix (by moi) was merged in time for 1.48.4.
	* FreeType has a flag FT_LOAD_VERTICAL_LAYOUT for FT_Load_Glyph(). This should not be used if FT_HAS_VERTICAL is not true according to the documentation. (And shouldn't be used with HarfBuzz shaping.)		* FreeType has a flag FT_LOAD_VERTICAL_LAYOUT for FT_Load_Glyph(). This should not be used if FT_HAS_VERTICAL is not true according to the documentation. (And shouldn't be used with HarfBuzz shaping.)
	* Pango logical_rect and hb_font_extents use "Win Ascent" and "Win Descent" values (FontForge OS/2 Metrics Tab), which can be greater than em-size height. OS/2 will clip rendering to this region. Super-confusing! Don't use Pango logical_rect!		* Pango logical_rect and hb_font_extents use "Win Ascent" and "Win Descent" values (FontForge OS/2 Metrics Tab), which can be greater than em-size height. OS/2 will clip rendering to this region. Super-confusing! Don't use Pango logical_rect!

Tavmjong: /* Ascent and Descent */

2021-04-03T09:22:14Z

Ascent and Descent

← Older revision		Revision as of 09:22, 3 April 2021
Line 277:		Line 277:
	CSS dictates that one should use the OS/2 ''sTypoAscender'' and ''sTypeDescender'' values if available, falling back to the HHEA ''Ascent'' and ''Descent'' values if missing. See https://www.w3.org/TR/CSS2/visudet.html#sTypoAscender. See also the <b>The Webfont Strategy (2019)</b> section of https://glyphsapp.com/learn/vertical-metrics.		CSS dictates that one should use the OS/2 ''sTypoAscender'' and ''sTypeDescender'' values if available, falling back to the HHEA ''Ascent'' and ''Descent'' values if missing. See https://www.w3.org/TR/CSS2/visudet.html#sTypoAscender. See also the <b>The Webfont Strategy (2019)</b> section of https://glyphsapp.com/learn/vertical-metrics.

	Fonts can request that the ''Typo'' values be given preference, but popular fonts like ''DejaVu Sans'' do not set the request flag. Pango::FontMetrics::get_ascent() and get_descent(), and hb_font_get_extents_for_direction() return the ''HHEA'' numbers if the flag is not set. To ensure that we use the ''Typo'' values we must resort to using FreeType to read the 'OS/2' table (with fallback to the HHEA table).		Fonts can request that the ''Typo'' values be given preference, but popular fonts like ''DejaVu Sans'' do not set the request flag. Pango::FontMetrics::get_ascent() and get_descent(), and hb_font_get_extents_for_direction() return the ''HHEA'' numbers if the flag is not set (see <code>hb-ot-metrics.cc, _hb_ot_metrics_get_position_common()</code>). To ensure that we use the ''Typo'' values we must resort to using FreeType to read the 'OS/2' table (with fallback to the HHEA table). If vertical metrics are requested, they are read from the ''VHEA'' table (which is unlikely to exist for most fonts).

			Note that in Pango, the ''logical_rect'' 'y' is the negative of the ascender value and the 'height' is the ascender - the descender (where the descender is negative). The width is the glyph advance. (See <code>pangofc-font.c</code>).

	=== x-height ===		=== x-height ===

Tavmjong: /* Itemization */

2021-03-30T09:43:20Z

Itemization

← Older revision		Revision as of 09:43, 30 March 2021
Line 78:		Line 78:

	<span style="font-size:100px;color:blue">m<span style="color:red">̃</span></span> vs. <span style="font-size:100px;color:blue">m<span style="color:red">̃</span></span> (View in Firefox.)		<span style="font-size:100px;color:blue">m<span style="color:red">̃</span></span> vs. <span style="font-size:100px;color:blue">m<span style="color:red">̃</span></span> (View in Firefox.)

			When Pango itemizes text for Pango::Layout, it uses only attributes that should affect itemization:

			* Language
			* Font family, style, weight, variant, stretch, size, scale, gravity, gravity hint, fallback
			* Letter spacing
			* Baseline shift

			Before shaping, it adds back:

			* Allow breaks
			* Insert hyphens
			* OpenType font features
			* Show (how to render invisible characters)

			The text is finally rendered with all attributes which adds back:

			* Foreground color, alpha
			* Background color, alpha
			* Underline, color
			* Strike through, color

	See pango_layout_check_lines() for how Pango::Layout does itemization (and line layout).		See pango_layout_check_lines() for how Pango::Layout does itemization (and line layout).

Tavmjong: /* Shaping */

2021-03-30T08:23:02Z

Shaping

← Older revision		Revision as of 08:23, 30 March 2021
Line 63:		Line 63:

	Our current code gets the PangoFontDescription from PangoItem.PangoAnalysis->PangoFont and uses it as an argument for our FontFactory::Face(). We save a copy of the PangoItem in our own PangoItemInfo structure before the PangoItem glist is destroyed. It is not clear if the PangoFont exists afterwards (PangoItem contains a PangoAnalysis but PangoAnalyis contains a pointer to PangoFont). FontFactory::Face() takes the PangoFontDescription, sets a fixed size, and uses it to search for an already existing ''font_instance'', if not found it calls ''pango_font_map_load_font()'' to get the PangoFont corresponding to the description and create a new ''font_instance'' for the face. The new instance calls InstallFace(PangoFont), if this fails it tries to load a generic ''sans-serif'' face. Once the ''font_instance'' is found or created, font_instance->InitTheFace() is called. InitTheFace() finds the underlying FreeType font and reads various OpenType tables. InitTheFace() is called from a variety of functions. It's functionality probably should be handled during constructing a ''font_instance''.		Our current code gets the PangoFontDescription from PangoItem.PangoAnalysis->PangoFont and uses it as an argument for our FontFactory::Face(). We save a copy of the PangoItem in our own PangoItemInfo structure before the PangoItem glist is destroyed. It is not clear if the PangoFont exists afterwards (PangoItem contains a PangoAnalysis but PangoAnalyis contains a pointer to PangoFont). FontFactory::Face() takes the PangoFontDescription, sets a fixed size, and uses it to search for an already existing ''font_instance'', if not found it calls ''pango_font_map_load_font()'' to get the PangoFont corresponding to the description and create a new ''font_instance'' for the face. The new instance calls InstallFace(PangoFont), if this fails it tries to load a generic ''sans-serif'' face. Once the ''font_instance'' is found or created, font_instance->InitTheFace() is called. InitTheFace() finds the underlying FreeType font and reads various OpenType tables. InitTheFace() is called from a variety of functions. It's functionality probably should be handled during constructing a ''font_instance''.


			== Itemization ==

			Taking a text and breaking it into blocks that have the same properties.

			Breaking text into blocks is a two step process:
			# Break text into blocks based on SVG requirements. For example, any new positioning attribute creates a new block that must be shaped independently of previous characters. We must do this ourselves.
			# Break text into blocks based on language, direction, etc. requirements. This is handle by Pango.

			Proper shaping often requires knowledge of the characters before and after the text being shaped. For example, a user might want to change the color of a character in the middle of an Arabic word. Arabic uses different glyphs depending on if the character is at the beginning, in the middle, or at the end of a word. If the character is shaped out of context, the start form of the glyph will always be used. By putting it in context (using <code>pango_shape_full()</code>), the correct glyph will be chosen. (This was fixed for 1.1.)

			Inkscape currently (1.1) shapes each SVG text node independently. (For example, in <text>AA<tspan>BB<tspan/>CC</text>, there are three text nodes, one for 'AA', one for 'BB', and one for 'CC'.) With <code>pango_shape_full()</code> this seems to handle correctly glyph selection for Arabic text. But there are situations where this does not work. For example, if one wanted to change the color of a ''mark'' (accent), the ''mark'' would not be properly placed over the base character:

			<span style="font-size:100px;color:blue">m<span style="color:red">̃</span></span> vs. <span style="font-size:100px;color:blue">m<span style="color:red">̃</span></span> (View in Firefox.)

			See pango_layout_check_lines() for how Pango::Layout does itemization (and line layout).

	== Shaping ==		== Shaping ==

Tavmjong: /* Clusters */

2021-03-23T08:21:08Z

Clusters

← Older revision		Revision as of 08:21, 23 March 2021
Line 197:		Line 197:
	In Firefox, the marks in the word "Arabic" (in Arabic) are shown in color. (Chrome only supports changing the base character color [example, the purple character] with marks colored the same as the base.) This recoloring is highly font and language dependent. The markup tries to color the two stacked marks above differently but this fails in Firefox with the font ''Estedad-VF'' as they are rendered by one glyph.		In Firefox, the marks in the word "Arabic" (in Arabic) are shown in color. (Chrome only supports changing the base character color [example, the purple character] with marks colored the same as the base.) This recoloring is highly font and language dependent. The markup tries to color the two stacked marks above differently but this fails in Firefox with the font ''Estedad-VF'' as they are rendered by one glyph.

	In the following, the circle in the Japanese word "パン" should be red but as fonts include the pre-composed glyph 'パ' it is rendered as one glyph. The same thing happens with 'a' and 'tilde'; it does not happen with an 'x' and 'tilde' as that combination is not a Unicode character (there is unlikely to be a pre-composed glyph for it). One can sometimes block the use of a pre-composed glyph by inserting a "zero-width non-joiner" Unicode character between the a base character and a mark as done with the 'e' and 'tilde' (this has undesirable side affects when tried with the Arabic text above as it also breaks the proper shaping ~~with between~~ the base characters on either side).		In the following, the circle in the Japanese word "パン" should be red but as fonts include the pre-composed glyph 'パ' it is rendered as one glyph. The same thing happens with 'a' and 'tilde'; it does not happen with an 'x' and 'tilde' as that combination is not a Unicode character (there is unlikely to be a pre-composed glyph for it). One can sometimes block the use of a pre-composed glyph by inserting a "zero-width non-joiner" Unicode character between the a base character and a mark as done with the 'e' and 'tilde' (this has undesirable side affects when tried with the Arabic text above as it also breaks the proper shaping of the base characters on either side).

	<p style="font-size:100px">ハ<span style="color:red">゚</span>ン a<span style="color:red">̃</span>x<span style="color:blue">̃</span>e&zwnj;<span style="color:red">̃</p>		<p style="font-size:100px">ハ<span style="color:red">゚</span>ン a<span style="color:red">̃</span>x<span style="color:blue">̃</span>e&zwnj;<span style="color:red">̃</p>