SPB Git

Repository Public

layout-engine.md 20.0 KB

# Layout engine

DocLayout turns a DocumentModel into pages and draws them. This document covers typesetting, caching, tables, drawing and the geometry queries the editor uses. The flow of blocks into columns and pages has its own document: pagination.md. PDF output is in pdf.md.

Part Code (Packages/ORIXDocsKit/Sources/)
Font resolution DocLayout/Fonts.swift
Paragraph typesetting DocLayout/ParagraphLayout.swift
Layout result, cache, table layout types DocLayout/DocumentLayout.swift
Flow into pages DocLayout/Paginator.swift
Drawing DocLayout/PageRenderer.swift
Caret, selection, hit testing DocLayout/Geometry.swift
Equations DocMath/MathRenderer.swift
Tests Tests/DocLayoutTests/PaginationTests.swift (TypesettingTests, GeometryQueryTests, TableLayoutTests), PDFTests.swift, SmokeTests.swift

# Why Core Text and an own paginator

The decision and its evidence are in technology-evaluation.md, section 1. In short: NSTextLayoutManager (TextKit 2) has a single text container and viewport-based layout, so it cannot flow text through a sequence of pages with exact geometry for the whole document; TextKit 1 paginates through multiple containers but offers no footnote placement, repeated table header rows, keep rules or widow/orphan control. CTTypesetter returns one line at a time for a width the caller chooses, which is what a paginator needs, and the same drawing code can target the screen, a bitmap or a PDF context. The cost is that everything NSTextView gives for free must be written by hand (text-engine.md).

flowchart LR
    M[DocumentModel] --> N[Numbering]
    M --> PG[Paginator]
    N --> PG
    PG -->|"paragraph + environment"| LC[LayoutCache]
    LC -->|miss| PL[ParagraphLayout]
    PL --> FC[FontCache]
    PL --> MR[MathRenderer]
    LC --> PG
    PG --> DL["DocumentLayout: pages of fragments"]
    DL --> PR[PageRenderer]
    DL --> GQ["Geometry queries"]
    PR --> SC["Screen: EditorCanvasView"]
    PR --> BM["Bitmap: thumbnails, previews"]
    PR --> PDF["PDF context: PDFPublisher"]
    GQ --> SC

# Font resolution

FontCache.shared.font(family:size:weight:italic:smallCaps:) returns a CTFont and memoises it by those five values (lock-protected).

  • System designs by name. New York, SF Pro (also SF Pro Display, SF Pro Text, System), SF Pro Rounded and SF Mono are not font files; they map to NSFontDescriptor.SystemDesign .serif, .default, .rounded, .monospaced on NSFont.systemFont(ofSize:weight:).
  • Weights. The model's CSS-like weight (100–900; bold is 700) maps to an NSFont.Weight for system designs (nsWeight) and to a kCTFontWeightTrait value for other families (ctWeight); the bold symbolic trait is requested from 600 up.
  • Italic. Requested as a symbolic trait. A family that yields a font without the italic trait gets a synthetic slant (a copy with the matrix c = 0.2). System designs take the italic trait on the descriptor and get no synthetic fallback.
  • Small capitals. When smallCaps is set the font descriptor gets OpenType feature type 37, selector 1 (lowercase small capitals). Nothing is synthesised for fonts that lack the feature.
  • Superscript and subscript use the same family at 0.66 of the size (font(for:scale:)), with a baseline shift of +0.33 or −0.14 of the font size added in ParagraphLayout.
  • Missing families. The list of installed families is read once (CTFontManagerCopyAvailableFontFamilyNames, lower-cased). A family that is neither installed nor a system design is recorded in missingFamilies and replaced by Times New Roman. DocumentConverter.preflight(_:format:) reports the list as a "Missing fonts" warning before a PDF export. The set only grows during the life of the process.
  • No-break space correction. noBreakSpaceCorrection(_:) measures the difference between the advances of U+0020 and U+00A0 in a font. Some fonts (the code comment names Charter) give the no-break space a figure-wide advance, which shows as a visibly wide gap, for example in "Figure 3" or before French punctuation. ParagraphLayout adds the difference as kerning (or to the tracking value when the run already uses tracking, because the two do not add up on one character) on every U+00A0 of a run.

Per-glyph fallback for characters a font does not contain (CJK, emoji, symbols) is left to Core Text; the code sets no cascade list.

# Building the attributed string

ParagraphLayout.init(_:env:) receives a paragraph and a ParagraphEnvironment (style sheet, layout options, width, list label and level, heading number, texts of text-like inline objects, exclusions, math typeface, colour override, language).

Invariant: one model character is one display character. The attributed string has exactly the UTF-16 length of the paragraph (precondition(text.length == length)), so a model offset is a Core Text string index and no mapping table exists. To keep it:

  • an inline object stays the single character U+FFFC and gets a CTRunDelegate that supplies its width, ascent and descent;
  • allCaps text is replaced by its uppercase form only when the UTF-16 length is unchanged (so "ß" is left alone rather than becoming "SS");
  • tracked deletions hidden by LayoutOptions.markup == .none keep their characters but each gets a zero-size delegate, so they take no room (TypesettingTests.trackedDeletionsAreHiddenWithoutMarkup);
  • the only exception is a hyphenated line (below).

Each run carries a RunInfo object under the private attribute key orix.run (resolved formatting, colour, revision, comment flag, box, underline and strikethrough). Underline and strikethrough are not Core Text attributes; the renderer draws them. With markup shown, an inserted run is coloured per author (ReviewColors.color(for:), a hash into six colours) and underlined, a deleted run is coloured and struck through.

# Inline boxes

InlineBox holds the metrics and what to draw:

Content Source Notes
.image, .shape Inline images and shapes Width and height from the object (bounding box of a rotated image); ascent = height, descent 0.
.equation(MathLayout) .equation Typeset by MathRenderer.layout at 1.1 × the run's font size.
.text(CTLine, rise:) Note marks, citations, cross-references, fields The displayed string comes from env.boxTexts in order of appearance; it is typeset as its own CTLine and behaves as one unbreakable box. Note marks are superscript.
.dropCap Drop capital See below.
.anchor Bookmarks, anchors of floating objects, hidden deleted text Zero size.

Floating images and shapes are not in the line: the paragraph records a FloatBox (rectangle relative to the paragraph's top-left corner, from alignment and offsets) and leaves a zero-size anchor at the object's position.

# Line breaking

For each line the builder asks extent(at:height:first:) for the usable horizontal extent at the current y, then CTTypesetterSuggestLineBreakWithOffset for a break in that width, then CTTypesetterCreateLineWithOffset.

  • Indents. Left and right indents, and a first-line indent that may be negative (hanging). A list label or heading number changes the first-line start (below).
  • Exclusions. An Exclusion narrows lines between two y values from the left and/or right. They come from floats of earlier paragraphs (passed in by the paginator), from the paragraph's own floats (.square narrows on the side the float is on when its centre is in the outer 40 % of the column, otherwise the lines skip below it; .topAndBottom always skips; .behindText and .inFrontOfText exclude nothing), and from a drop cap. When fewer than 40 pt would remain, the line skips to the bottom of the exclusion. Test: floatingObjectsNarrowTheLinesBesideThem.
  • Drop caps. With dropCapLines ≥ 2 (capped at 6), on a paragraph that is not a list item and starts with a letter in an untracked text run, the first composed character gets a delegate box as wide as the enlarged glyph and an exclusion pushes the following lines aside. Test: dropCapNarrowsTheFollowingLines.
  • Justification. CTLineCreateJustifiedLine with factor 1.0, for every line except the last and those ending in a forced break. Test: justifiedLinesFillTheMeasureExceptTheLast.
  • Right-to-left. rightToLeft sets the base writing direction; a left-aligned right-to-left paragraph is aligned right. Test: rightToLeftParagraphsAlignRight.
  • Empty paragraphs and a paragraph ending in U+2028 get a zero-width line so the caret has a place.

# Hyphenation

Enabled per paragraph (hyphenate, off by default) when CFStringIsHyphenationAvailableForLocale holds for the language of the last run, else of the document. After Core Text suggests a break, the builder looks at the word that would start the next line: if the line ends with a space, contains no tab, and the word has at least five letters, it asks CFStringGetHyphenationLocationBeforeIndex for break points from the end of the word backwards and takes the first one for which the line plus a hyphen fits.

A hyphenated line is typeset separately: a new CTLine is created from the substring plus "-". Its string indexes start at 0, so LayoutLine.indexBase holds the offset to add to obtain model offsets (xPosition(for:) and offset(atX:) apply it). Test: hyphenationBreaksLongWordsOnlyWhenEnabled (lines still cover every character exactly once).

# Tabs and leaders

Tab stops (left, centre, right) become CTTextTabs measured from the column's left edge, with a default interval of 36 pt; a decimal tab is a right tab whose column terminators are "." and ",". Header and footer paragraphs without explicit tabs get a centre tab at half the width and a right tab at the full width. Leaders are not part of the line: PageRenderer.drawLeaders fills the gap of each tab character with dots, dashes or a rule.

# Line height

For each line, natural = ascent + descent + leading from CTLineGetTypographicBounds (the paragraph font's metrics when the line is empty), and fontLine is the same sum for the font of the last run:

LineSpacing Line height
.multiple(k) natural + (k − 1) × min(natural, fontLine) — a tall inline object does not multiply the extra spacing
.exact(v) v
.atLeast(v) max(v, natural)

The baseline is placed so that ascent + descent is centred in the line box. Test: lineSpacingModes.

# List labels and heading numbers

Labels are never in the text; Numbering computes them. A list label is a separate CTLine (LabelBox) drawn hanging at indent − hanging of the ListLevel, and the text starts at the level's indent (or after the label if it is wider). A heading number is drawn at the first-line start and the text follows after a gap of 0.55 × the font size. Labels use the size and colour of the first run and the paragraph style's weight. Test: listLabelsHangInTheIndent.

# The layout cache

LayoutCache (DocumentLayout.swift) avoids typesetting a paragraph again when nothing it depends on changed.

  • Key. Entries are stored per paragraph id, up to three per id (a paragraph can legitimately have several layouts: different column widths, with and without neighbouring floats). An entry matches when the Paragraph value is equal and width, list label, list level, heading number, box texts, exclusions, header/footer flag, colour override, layout options and math typeface are all equal.
  • Style sheet. beginPass(styles:) empties the cache when the StyleSheet differs from the one of the previous pass: any style edit is a full relayout.
  • Generations. Each pagination pass increments a generation and stamps the entries it uses; every eighth generation endPass() drops entries not used in the last eight, which removes layouts of deleted paragraphs.
  • Headers and footers. The same header paragraph appears on every page with different field values (page number, running head). With three slots per id it would be typeset again on almost every page of every pass, so these layouts live in a second dictionary keyed by paragraph id, box texts and width: one layout per distinct content.
  • hits and misses are public counters. removeAll() is called when a document is reloaded.

The cache has no lock: one cache serves one document on one thread at a time. Table layouts (TableLayout) are recomputed on every pass; only their cell paragraphs are cached.

# Tables

Pass.tableLayout(_:width:) produces a TableLayout:

  • Scaling. A table wider than its column (by more than 0.5 pt) has all its column widths scaled by the same factor and is reported in DocumentLayout.overflowingTableIDs. Test: aTableWiderThanTheColumnIsScaledAndReported.
  • Cells. A cell covers colSpan grid columns; its paragraphs are typeset at the cell width minus the style's padding, in the header text colour for header rows of a style that defines one.
  • Row heights. The tallest unmerged cell content plus padding, at least minHeight, never under 14 pt.
  • Vertical merges. A restart cell's rowSpan counts the continue cells below it in the same grid column; if its content is taller than the rows it covers, the last of those rows grows. Test: mergedCellsCoverTheirGrid.
  • headerRows is the number of leading rows with isHeader.

Splitting across pages is done by the paginator (pagination.md).

# Equations

MathRenderer.layout(latex:fontSize:display:color:typeface:) typesets LaTeX with SwiftMath and caches the result (up to 4,000 entries, keyed by typeface, size, style, colour and source). The MathLayout wraps the NSImage returned by SwiftMath's MathImage.asImage(), which on macOS is created with a drawing handler, so drawing it replays glyph drawing into the destination context. The math typeface is chosen from the document's default font family (MathTypeface.matching(textFamily:)). A formula that does not parse is shown as its source in red monospaced text and carries an error (invalidEquationShowsItsSourceInsteadOfVanishing). Drawing is serialised by a lock.

# The page renderer

PageRenderer.draw(page:in:) draws into a context whose origin is the page's top-left corner with y pointing down. The same code serves the canvas, thumbnails and previews (PDFPublisher.bitmap), printing and PDF.

Drawing order:

  1. page background (PageSetup.background), else white paper when drawsPaper is on (off for PDF);
  2. watermark (not on blank parity pages), page border;
  3. floats with .behindText;
  4. tables: cell shading (cell, header or banded rows), then borders — cell overrides, else the table style's outer and inner lines; the Academic style adds its three rules;
  5. text fragments, in placement order (below);
  6. the other floats;
  7. footnote separator rules, column rules;
  8. break markers, unless forPrint.

For a text fragment: paragraph shading and borders span the fragment; the list label or heading number is drawn with the first line; then each line is drawn run by run (drawLine): highlight or comment tint behind the run, the link hook, the inline box if any, the glyphs with CTRunDraw, then underline and strikethrough from the font's metrics (trailing white space excluded). Leaders are drawn last.

Screen-only decorations, all skipped when LayoutOptions.forPrint is set: the change bar in the margin beside lines that carry a tracked change, the comment tint, break markers (a dashed rule with a label supplied through MarkerLabels, or a rule alone for continuous section breaks). Focus mode dims every body paragraph but one (focusParagraphID).

RenderHooks lets a client observe drawing without the renderer knowing about PDF: link(rect, target) for every run with a link, and begin(role) / end() around text fragments (paragraph, heading level, list item, note), figures (images, shapes, equations, with alternative text) and tables. pdf.md describes how they are used.

Images are decoded once per asset (ImageStore, an NSCache limited to 512 MB of decoded pixels); a PDF asset is drawn as vector content (its first page); crop and rotation are applied at draw time; a missing or unreadable asset draws a labelled placeholder.

# Geometry queries

Geometry.swift extends DocumentLayout; an index from (story, path) to fragments (fragments(story:path:)) backs all of them.

Query Result
locate(story:position:upstream:preferredPage:) The page, fragment and line that display a position. upstream prefers the previous line at a line boundary; preferredPage selects the page for headers and footers, which repeat.
caret(…) A 1.5 pt wide rectangle of the line's height. On an atomic block: the marker's or the generated block's leading edge.
selectionRects(story:start:end:blocks:preferredPage:) One rectangle per line covered; a small extension where the selection continues past a paragraph end; whole rectangles for break markers and generated blocks. Test: selectionRectanglesCoverEveryLineOfTheRange.
cellRect(block:row:cell:), columnBoundary(page:point:tolerance:), floatHit(page:point:) Table cell rectangle, column edge under the pointer, topmost floating object.
hitTest(page:point:restrictTo:) Markers first; inside a table the cell under the point; otherwise the nearest fragment (vertical distance weighted four times the horizontal one), its line at the point's y, and LayoutLine.offset(atX:). Reports upstream affinity at the end of a wrapped line and onAtomicBlock for generated content. Tests: hitTestRoundTripsCaretPositions, hitTestingFindsTheCellUnderThePoint.
lineRange(…) Model range of the visual line (Home/End), excluding a trailing forced break. Test: homeAndEndUseTheVisualLine.
verticalMove(story:from:goalX:down:…) The position on the adjacent visual line nearest to goalX, across fragments and pages. In a table: first within the cell, then to the cell of the next or previous row nearest to goalX, then out of the table; entering a table picks the cell under the caret. Test: verticalMovementKeepsTheColumnAndCrossesPages.

# Limits

  • Inline boxes are unbreakable. A citation, cross-reference, field value or note mark is one box; a long citation cannot wrap, and an inline image or equation wider than the line overflows it.
  • First-fit line breaking. Breaks are those suggested by Core Text line by line; there is no paragraph-level optimisation. Hyphenation only considers the first word of the next line, only after a space, and uses one language per paragraph.
  • Leaders: one leader style per paragraph — the first tab stop that has a leader decides for all tabs (drawLeaders) — and none on hyphenated lines.
  • Small capitals and bold depend on what the font offers; only italic is synthesised.
  • Bidirectional selections are approximated (text-engine.md).
  • Rows do not split across pages, and nothing keeps the rows of a vertical merge together (pagination.md).
  • Paragraph continuation beside a float: see pagination.md.
  • Concurrency. FontCache and MathRenderer are lock-protected and ImageStore is safe to share, but LayoutCache is not thread-safe. Fonts.swift reads the installed-family list once because, as its comment records, asking the font registry per family from many threads is slow and can stall. For the same reason the layout tests are run serially (swift test --no-parallel, see testing.md); batch processing bounds its concurrency (WorkflowRunner.runBatch(_:inputs:maxConcurrent:progress:) in DocAutomation, four files at a time by default).
  • Measured costs are in performance.md.
Files main
Menu

Theme