Class TextModeLayoutUtil

Shared utility for computing text mode grid layout from font size and available space. Used by both TextModeView (world-space) and UITextModeView (Canvas).

Inheritance
object
TextModeLayoutUtil
Inherited Members
Namespace: Scylla.TextMode
Assembly: ScyllaTextMode.dll
Syntax
public static class TextModeLayoutUtil

Methods

ComputeBaselineY(float, float, float, float, float, float)

Computes where the text baseline sits inside a cell, as a fraction of the cell height measured up from the cell's bottom edge. The shader positions every glyph from this value, so it decides how the space a line does not need is shared between the room above the tallest glyph and the room below the deepest descender.

Declaration
public static float ComputeBaselineY(float lineHeight, float descentLine, float ascentLine, float inkTop, float inkBottom, float lineHeightMultiplier)
Parameters
Type Name Description
float lineHeight

Font's line height in font units, from LineHeight.
float descentLine

Font's descent line in font units (negative), from DescentLine.
float ascentLine

Font's ascent line in font units, from AscentLine.
float inkTop

Highest point reached by ordinary glyphs, from InkTop.
float inkBottom

Lowest point reached by ordinary glyphs, from InkBottom.
float lineHeightMultiplier

Line height multiplier (1.0 = natural spacing).
Returns
Type Description
float

The baseline position as a fraction of the cell height, measured from the cell bottom.
Remarks

A font reserves more vertical room than its glyphs actually use. The Scylla default monospace font, for example, has a line height of 66 units spanning an ascent line at 51 and a descent line at -15, while the printable ASCII glyphs only reach 44 at the top and -10 at the bottom. The remaining 12 units are empty on every line, and that empty band is what a line height below 1.0 should consume first.

Each side is therefore given a share of the height change in proportion to the room it has spare, which means both sides run out of room at the same moment. Reducing the line height packs the lines closer together and leaves the glyphs untouched, until the cell becomes shorter than the ink itself at (inkTop - inkBottom) / lineHeight. For the default font that is roughly 0.82.

At the natural line height the result is -descentLine / lineHeight regardless of the ink measurements, so default rendering is unaffected.

ComputeCenteredOffset(float, float, float, float, int, int)

Computes where a grid of whole cells starts inside a larger area when it is centered, so the space the cells cannot fill is split evenly around it.

Declaration
public static Vector2 ComputeCenteredOffset(float availableWidth, float availableHeight, float cellWidth, float cellHeight, int columns, int rows)
Parameters
Type Name Description
float availableWidth

Width of the area.
float availableHeight

Height of the area.
float cellWidth

Width of one cell.
float cellHeight

Height of one cell.
int columns

Columns of the grid.
int rows

Rows of the grid.
Returns
Type Description
Vector2

The distance from the area's top-left corner to the grid's, never negative.

ComputeGridArea(TMP_FontAsset, float, float, float, int, int)

Computes the area a view needs to show exactly the given number of columns and rows with a font, so a view can be given a fixed grid by sizing its RectTransform (or, for a world space view, its view width and height) rather than its font size.

Declaration
public static Vector2 ComputeGridArea(TMP_FontAsset fontAsset, float fontSize, float lineHeightMultiplier, float charSpacingMultiplier, int columns, int rows)
Parameters
Type Name Description
TMP_FontAsset fontAsset

The font the view uses. Null falls back to the default cell aspect ratio.
float fontSize

Font size in the view's units: canvas pixels for a UI view, or font size divided by pixels per unit for a world space view.
float lineHeightMultiplier

The view's line height multiplier.
float charSpacingMultiplier

The view's character spacing multiplier.
int columns

Columns of the whole grid, including any cell border.
int rows

Rows of the whole grid, including any cell border.
Returns
Type Description
Vector2

The width and height of the area, in the same units as fontSize.
Remarks

The area is half a cell larger than the grid in each direction. The layout rounds the number of cells down, and the extra half cell keeps a rounding error from costing a whole column or row. The view centers the grid, so the slack shows as a quarter cell on each side.

ComputeLayout(float, float, float, float, float, float, float, float, out float, out float, out int, out int)

Computes grid layout dimensions from font size, font metrics, and available space. Both cell width and height use the same scale factor (fontSize / pointSize): cellWidth = advanceWidth * (fontSize / pointSize) * charSpacingMultiplier, cellHeight = lineHeight * (fontSize / pointSize) * lineHeightMultiplier. Using lineHeight for cell height means a cell at the natural line height holds the font's full ascent and descent. A multiplier below 1.0 makes the cell shorter than that, which is what ComputeBaselineY(float, float, float, float, float, float) and ComputeVerticalOverhang(float, float, float, float, float, float) exist to handle. Columns and rows are computed by dividing the available space by cell dimensions.

Declaration
public static void ComputeLayout(float fontSize, float advanceWidth, float pointSize, float lineHeight, float availableWidth, float availableHeight, float lineHeightMultiplier, float charSpacingMultiplier, out float cellWidth, out float cellHeight, out int columns, out int rows)
Parameters
Type Name Description
float fontSize

Font size in coordinate-system units (pixels for UI, world units for world-space after PPU conversion).
float advanceWidth

Font's monospace advance width from GlyphAtlasCache. Pass 0 to use default aspect ratio.
float pointSize

Font's SDF sampling point size from GlyphAtlasCache. Pass 0 to use default aspect ratio.
float lineHeight

Font's line height from GlyphAtlasCache. Pass 0 to use default ratio.
float availableWidth

Available width in coordinate-system units.
float availableHeight

Available height in coordinate-system units.
float lineHeightMultiplier

Line height multiplier applied to cell height (1.0 = natural spacing).
float charSpacingMultiplier

Character spacing multiplier applied to cell width (1.0 = natural spacing).
float cellWidth

Computed cell width.
float cellHeight

Computed cell height.
int columns

Computed number of columns.
int rows

Computed number of rows.

ComputeVerticalOverhang(float, float, float, float, float, float)

Computes how far glyphs reach past the top and bottom of their own cell, as a fraction of the cell height. Returns zero while they still fit, which is the normal case.

Declaration
public static float ComputeVerticalOverhang(float lineHeight, float descentLine, float ascentLine, float inkTop, float inkBottom, float lineHeightMultiplier)
Parameters
Type Name Description
float lineHeight

Font's line height in font units, from LineHeight.
float descentLine

Font's descent line in font units (negative), from DescentLine.
float ascentLine

Font's ascent line in font units, from AscentLine.
float inkTop

Highest point reached by ordinary glyphs, from InkTop.
float inkBottom

Lowest point reached by ordinary glyphs, from InkBottom.
float lineHeightMultiplier

Line height multiplier (1.0 = natural spacing).
Returns
Type Description
float

The overhang as a fraction of the cell height, or 0 when every glyph fits.
Remarks

Below the point where the cell becomes shorter than the ink, roughly a line height of 0.82 for the Scylla default font, glyphs have nowhere left to go and start to hang over into the rows above and below. The shader uses this value to decide whether to draw the overhanging parts of its vertical neighbors, so a positive result is what turns tight line spacing into overlapping text rather than clipped text. See ComputeBaselineY(float, float, float, float, float, float) for how the space is shared out.

Both edges give way at the same moment, so this reports whichever side hangs over further.

FitCellBorder(TextModeCellBorder, int, int)

Fits a cell border into a laid-out grid, so the content inside it keeps at least MIN_COLUMNS columns and MIN_ROWS rows.

Declaration
public static TextModeCellBorder FitCellBorder(TextModeCellBorder requested, int totalColumns, int totalRows)
Parameters
Type Name Description
TextModeCellBorder requested

The border asked for. Negative sides count as zero.
int totalColumns

Columns of the whole grid, border included.
int totalRows

Rows of the whole grid, border included.
Returns
Type Description
TextModeCellBorder

The requested border, or less when it does not fit. A side is taken from the wider of each opposite pair first, so what is left stays as even as possible.

TryComputeCellPixels(GlyphAtlasCache, float, float, out Vector4, out float)

Computes the two cell-geometry shader uniforms for a font and its spacing multipliers.

Declaration
public static bool TryComputeCellPixels(GlyphAtlasCache glyphCache, float lineHeightMultiplier, float charSpacingMultiplier, out Vector4 cellPixels, out float verticalOverhang)
Parameters
Type Name Description
GlyphAtlasCache glyphCache

The glyph cache holding the font metrics. May be null.
float lineHeightMultiplier

Line height multiplier applied to cell height.
float charSpacingMultiplier

Character spacing multiplier applied to cell width.
Vector4 cellPixels

The computed _CellPixels value.
float verticalOverhang

The computed _VerticalOverhang value.
Returns
Type Description
bool

True when the font supplied usable metrics and both values were written. False when there is nothing to compute from, in which case the uniforms should be left at whatever the material already holds.
Remarks

The components of cellPixels are the cell width and height in font metric units, the atlas SDF padding in texels, and the baseline position within the cell. The shader derives every glyph's position and size in the cell from those four values, and uses verticalOverhang to decide whether it also has to draw the parts of the rows above and below that hang into this one.