Text Rendering: Reported Text Height Change Proposal

[frank-weindel]

The following proposal aims to make the Reported Text Height, which is provided during the loaded event for Text Nodes, consistent between SDF and Canvas text renderers, closer to how HTML/CSS works, and solve some issues that have been reported around the current implementation:

• 165

• 157

The phases are divided as such to make it easier to grok the issues and their solutions. We could very well implement and release all of phases at once.

Phase 1: Make Reported Text Height dimension of text based purely on Line Height and number of lines rendered (plus offsetY)

• Reasoning
  • This is how browsers reports text dimensions for inline-block HTML div tags containing only text.
  • This will result in consistent Height reporting regardless of which characters are used on the last line of text.
• Prior to this phase, Reported Text Height was based on:
  • SDF: The actual Y axis extents of the rendered characters.
    • The problem with this is that the presence/absence of descenders (parts of glyphs that hang below the baseline such as in: jqpg) on the last line of text will affect the Reported Text Height. This is generally NOT desired when the Reported Text Height is used for vertically centering text or determining the Y position of the next node in a vertical layout.
  • Canvas (Currently): Line Height times number of lines
    • **Check if offsetY needs be added, otherwise no change needed
  • Canvas (Renderer PR #158): This behavior, copied from Lightning 2, uses the following formula to calculate the Reported Text Height
    • This formula is mostly based on lineHeight+numLines+offsetY, except for the last line it attempts to ensure the text will fit by adding additional, somewhat arbitrarily defined, pixels.

      const baselineOffset = textBaseline !== 'bottom' ? 0.5 * fontSize : 0;
      return (
      lineHeight * (numLines - 1) +
      baselineOffset +
      Math.max(lineHeight, fontSize) +
      (offsetY || 0)
      );

• If the Line Height is too small there's a chance for characters to bleed out of the reported text dimensions.
  • For Phase 1 the Default Line Height will remain the same as the Font Size. This is NOT always enough to guarantee rendered text will fit within the Reported Text Height. Phase 2 ensures that a Minimum Encapsulating Line Height is the Default Line Height.

Phase 2: Determine Default Line Height by Font Metrics

• Reasoning:
  • This change will ensure that users who do not explicitly set a Line Height are by default using a value that is enough to make sure the Reported Text Height encapsulates all characters appropriately.
• For each SDF/Canvas Web Font, metrics may be configured explicitly. These metrics are derived from the source font's themselves like ascender, descender and lineGap.
• Developers can use the msdf-generator tool to get the default font metrics for each font used in their application.
• For SDF Fonts, providing Font Metrics is REQUIRED.
  • The Lightning 3 msdf-generator tool must be used to generate SDF Fonts and will handle all this without any extra work required from the developer (unless the developer desires to modify the metrics)
• For Canvas Web Fonts, configuring the Font Metrics are highly RECOMMENDED to insure consistent text rendering across devices/browser.
• If an application relies on both the SDF and Canvas version of a font, for instance if the application has to run in both WebGL and Canvas2D Render Mode, it is extremely important that both the SDF/Canvas Web version of the font has the same Font Metrics configured in the font definitions. This ensures consistent layout between SDF and Canvas text renders.
• If Canvas Web Font Metrics are no provided, a fallback set will be derived from the browser. It is not recommended to rely on these values as it can lead to inconsistency between browsers. A warning will fire if this happens. The fallback logic is as follows (units are fractions of 1 EM):
  • Canvas (Fallback 1):
    • ascender: metrics.actualBoundingBoxAscent / fontSize
    • descender: -metrics.actualBoundingBoxDescent / fontSize
    • lineGap: 0.2
  • Canvas (Fallback 2):
    • ascender: 0.8
    • descender: 0.2
    • lineGap: 0.2
    • See also:
    • https://stackoverflow.com/a/45789011
    • https://developer.mozilla.org/en-US/docs/Web/API/TextMetrics/actualBoundingBoxAscent
• To do this properly, we will need to default the Line Height property of a Text Node to null (or undefined) and have that indicate to the CoreTextNode that the Line Height shall be set to the Default Line Height.
  • ~As ThreadX does not currently support null (or undefined) values natively for any type, this will require a change in ThreadX to support it.~
    • Completed in https://github.com/lightning-js/threadx/pull/5
• Prior to this phase, the Default Line Height for all Text Nodes was the Font Size (which is not a 100% reliable method due to the way fonts can differ in their metrics)

Phase 3: Make the Default Vertical Align text property value "middle"

• Reasoning:
  • To better match with how HTML/CSS handles line-by-line vertical alignment of text.
  • The functionality of the Vertical Align text property in Lightning 2/3 is NOT available for HTML/CSS text. The CSS vertical-align property has an entirely different functionality and there is really no equivalent property in CSS that does exactly what Lightning's Vertical Align text property does. In HTML/CSS, text is rendered in the way it would be if the Lightning Vertical Align property was set to "middle".
• The Vertical Align text property defines where text should be aligned vertically for each line within the defined Line Height.
• Prior to this phase, the Default Vertical Align value was "top".

[chiefcll]

👍

[suresh-gangumalla]

As per phase 2 proposal, With inter-Black MSDF type, "Wonka" text will have a line height of 48, and "Migration" text will have a line height of 56, based on the maximum character height in each word

If two texts have different line heights, how does the final rendered height become the same for a given font size?

[frank-weindel]

@suresh-gangumalla In Phase 2, the calculation of the Default Line Height is across all characters of the font, not just characters used in the text property of a text node. So both "Wonka" and "Migration" should result in the same Default Line Height since they both use the same font "Inter-Black".

[frank-weindel]

Updated the Phase 2 of the proposal to now rely on font metrics being provided explicitly by the developer (and extractable with the msdf-generator tool). This will have the added bonus of text between Canvas and SDF text renderers being able to be laid out consistently.