Skip to content

[shaping] reuse the break attributes of a paragraph across line wrappings - #304

Merged
benoitkugler merged 4 commits into
go-text:mainfrom
cogentcore:wrap-segmented
Nov 10, 2026
Merged

benoitkugler merged 4 commits into
go-text:mainfrom
cogentcore:wrap-segmented

Conversation

@rcoreilly

Copy link
Copy Markdown
Contributor

LineWrapper.Prepare and WrapParagraph run Segmenter.Init on the paragraph every time, which computes the UAX #14 line breaks and UAX #29 grapheme and word breaks of every rune. These attributes depend only on the text. A GUI layout usually wraps the same paragraph several times, though: once to an estimated width and once to the allocated one, and again whenever the window width changes. In Cogent Core, finding the break attributes was about half the cost of wrapping a paragraph that had already been shaped. On the web build it also took about as much time as the rest of the wrapper.

This PR adds LineWrapper.PrepareSegmented(config, seg, runs). It takes a segmenter.Segmenter that has already been initialized with the paragraph, so a caller can keep the segmenter next to its shaped runs and reuse it for every wrapping. Prepare is now seg.Init(paragraph) followed by PrepareSegmented, so it behaves exactly as before. The wrapper only reads the segmenter. The segmenter must not be initialized again until the next Prepare, PrepareSegmented or WrapParagraph, as the doc comment says.

To support this, the segmenter package now documents something that was already true: iterators never modify a Segmenter, so any number of them can be created from one initialized Segmenter. An iterator and the slices it returns stay valid until the segmenter is initialized again. A new Segmenter.Len returns the number of runes of the paragraph, which the wrapper needs and previously took from the paragraph argument.

A third commit fixes the same kind of waste inside WrapParagraphF. It initialized the segmenter once to look for mandatory breaks before taking the single-run fast path, and then a second time in Prepare. It now reuses the first one.

Tests:

  • TestPrepareSegmented wraps three texts with a fresh Prepare each time and with one segmenter shared by all the wrappings, and checks that the lines are identical. The texts are Latin, Latin with \n\n, \r\n and U+2028 mandatory breaks, and Arabic RTL. Each is cut into 1 and 7 runs and wrapped with 8 configs (break policies, no trailing whitespace trim, truncation after 1-3 lines with and without truncator and TextContinues) at 66 widths from 0 to 1495, either constant or alternating between two widths line by line. A mutation check confirms the test fails when the segmenter is given a different text.
  • TestWrapParagraphSegmentedInit checks that WrapParagraph gives the same lines and truncation as Prepare plus WrapNextLine, covering both the fast path and wrapping.
  • TestIteratorsReuse (segmenter) creates line, grapheme and word iterators repeatedly, interleaved and from four goroutines, and checks they all give the same segments. It passes under -race.

Benchmarks:

BenchmarkWrappingWidths (new) wraps a paragraph cut into 10 runs to widths 150, 300 and 600:

case Prepare PrepareSegmented
100 runes Latin 16.8 µs 5.6 µs -67%
1000 runes Latin 156 µs 51 µs -67%
100 runes Arabic 18.3 µs 7.3 µs -60%
1000 runes Arabic 162 µs 56 µs -66%

The existing BenchmarkWrapping (WrapParagraph, main vs this branch, n=6) is 25-37% faster for 100 and 1000 runes, for example 1000 runes Latin in 1 part goes from 94.7 µs to 59.7 µs. For 10 runes in 10 parts it is 25-29% faster. The geomean over all cases is -29%. The 10-rune single-run cases take the fast path, which does the same work as before, and are unchanged (519 vs 519 ns in an interleaved rerun). Allocations are unchanged.

go test ./..., go vet ./... and staticcheck v0.8.0 (as in CI, with Go 1.26) pass. The shaping, segmenter and fontscan tests also pass with Go 1.22.12.

🤖 Generated with Claude Code

rcoreilly and others added 3 commits October 21, 2026 17:22
Iterators never modify the Segmenter, so any number of them can be
created from one initialized Segmenter, which lets callers keep the
break attributes of a text and segment it again without recomputing
them. Len returns the number of runes the Segmenter was initialized
with.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Prepare computes the UAX go-text#14 and go-text#29 break attributes of the whole
paragraph every time, although they only depend on the text. A layout
typically wraps the same paragraph several times, to an estimated width
and then the allocated one, and again whenever the width changes.

PrepareSegmented takes a segmenter.Segmenter already initialized with
the paragraph, which the caller can keep with its shaped runs. Prepare
is now Init followed by PrepareSegmented, so it behaves as before.

BenchmarkWrappingWidths wraps a paragraph to three widths: 3x faster
with PrepareSegmented for 100 and 1000 runes of Latin and Arabic text.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
WrapParagraphF initialized the segmenter twice with the same paragraph:
once to look for mandatory breaks before taking the single run fast
path, and again in Prepare. The wrapping now reuses the first one.

BenchmarkWrapping: 25-37% faster for 100 and 1000 runes (geomean of
all cases -29%).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

@whereswaldon whereswaldon left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for this optimization. It certainly has a large impact if you can afford to keep the segmenter around. My only concerns are minor documentation fixes.

Comment thread shaping/wrapping_test.go Resolved
Comment thread segmenter/segmenter.go Resolved
@whereswaldon

Copy link
Copy Markdown
Member

@benoitkugler @andydotxyz Can a second maintainer review this? I think it's ready.

@benoitkugler benoitkugler left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That looks good to me, nice optimization !

@benoitkugler

Copy link
Copy Markdown
Contributor

@whereswaldon not sure whether squash or rebase is the best strategy here.

@whereswaldon

Copy link
Copy Markdown
Member

I prefer rebase since the commits are logically distinct

@benoitkugler
benoitkugler merged commit bafa873 into go-text:main Nov 10, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants