Skip to content

A repeating gradient background paints as tiles on iOS, so a resize draws nothing - #9

Merged
janicduplessis merged 5 commits into
mainfrom
@janic/pattern-gradients
Nov 15, 2026
Merged

janicduplessis merged 5 commits into
mainfrom
@janic/pattern-gradients

Conversation

@janicduplessis

@janicduplessis janicduplessis commented Nov 15, 2026 •

Copy link
Copy Markdown

Description

On iOS a repeating-linear-gradient background makes its node draw the whole box in draw(_:) (gradientDraws → boxDrawn). Because the view uses contentMode = .redraw, that full-size bitmap is drawn again at every new size. During an interactive drag, UIKit resizes a sheet with detents on every frame. A sheet whose page has two diagonal repeating-linear-gradient textures therefore re-rasterizes a full-screen texture every frame, and the drag runs at 20 to 30 fps on an iPhone. #3 made each repaint cheaper, but every frame still repaints.

Solution

When every background layer is a repeating linear gradient whose period is the same at every box size, the gradients paint as tile cells on sublayers. The node then keeps no bitmap, so a resize draws nothing.

  • Period (GradientTile.swift, shared). Gradient.period(dark:) reads one period out of the kernel's resolved stops. A gradient with any percentage stop is refused outright: CSS fix-up can clamp a percentage to an earlier length stop at one size and not at another. For the rest, it resolves at two box sizes and accepts the gradient only when the period, its offset from the start corner and the direction agree. to <corner> fails that check and keeps the drawn path. The period is read from the gradient's source for the view's appearance (its dark-scheme source where it has one) and with the view's tint where a stop names AccentColor; a tint change draws the tiles again.
  • Placement. Tiles are placed from the device pixel of the corner where the CSS gradient line starts. When the box changes size by whole pixels, the tiles move with that corner and each tile's picture stays the same. A size that moves the corner by a fraction of a pixel changes every phase and redraws the pictures that frame. The sheet dragged on the simulator was sized in whole pixels, and no picture was redrawn during the drag (NodeLayer.display stayed under 0.1 ms per frame). I have not verified this on a device.
  • Seams. At 45° no tile is a whole number of periods in pixels. Each cell's picture is therefore keyed by how far its phase is from the corner tile's, less whole periods, rounded to 1/32 device pixel. Cells with the same key share one CGImage, and the corner tile and every tile at its phase are drawn exactly. There is no seam or drift at any angle. Tiles are about 256 px, the size closest to whole periods up to 512. On a phone-sized box at 1x to 3x that comes to at most 70 tiles and 5 distinct pictures per gradient, and 1 for an axis-aligned grid.
  • Painting. Each picture is drawn by Gradient.paintAxial, the same code Gradient.paint uses for the whole box. That code was split out of paint with no change in behaviour.
  • Fallback (GradientTilesIOS.swift). Tiles are used only for a border-box clip, a non-fixed attachment, no surface, and a box that nothing else makes draw. When something else does make it draw (a dashed border, a paragraph without a raster), the tile layer is removed and draw(_:) paints the gradient as before.

macOS is unchanged. Two cases still draw: linear-light interpolation and mixed layers (a repeating gradient together with a plain one).

Relayout is not the bottleneck. With tiles, a dragged textured sheet costs the same as an untextured one, about 4 ms per frame. Most of that is the relayout that each new sheet size triggers through publish(), so this PR leaves publish() as it is.

Measurements

These numbers come from an iOS 27.0 simulator (iPhone 18 Pro, 3x) running a development build on a Mac heavily loaded by other jobs. The sheet has detents medium large. A real touch drags it 300 pt up and back over about 2 s. Each figure is a one-second window during the drag, measured with a temporary run-loop probe from each main-thread wake to its next sleep. The before and after runs used the same build, with tiling switched off for "before". The probe is not part of this PR.

Sheet page UI updates/s during drag main-thread ms per update of which NodeLayer.display
two diagonal hatches, before 7 to 13 67 to 144 58 to 127
two diagonal hatches, after 54 to 60 3.9 to 6.1 0.05 to 0.09
axis-aligned 14 px grid, before 46 to 53 11 to 16 8 to 10
axis-aligned 14 px grid, after 58 to 61 4.2 to 5.8 0.05 to 0.06
no texture 50 to 61 4.1 to 5.2 0.03

On the simulator the texture looks the same with tiles as with the drawn path, at rest and in the middle of a drag (full-resolution screenshots). A recording of the detent snap animations shows the texture covering the sheet in every frame.

Test plan

  • macOS bun host/apple/build.mjs --test --only GradientTileTests,BorderParityMacTests,HiddenGradientIOSTests passes. The Chrome parity hatch case, which now tiles on iOS, stays at 0.00/255.
  • iOS --test --ios --only GradientTileTests,GradientTilesIOSTests,BorderParityIOSTests,HiddenGradientIOSTests: 12 test cases, none failed.
    • GradientTileTests checks that tiles composed as the layers place them match Gradient.image. It covers the hatch, the grid, an opaque 30° stripe and the Chrome parity page's hatch (whose stripe edges sit exactly on pixel centres), at 1x, 2x and 3x, at 100×70 and at two heights a whole number of pixels apart and not a whole number of periods. The worst mean difference is 0.12/255, the parity hatch is identical, and the test bounds are a mean under 0.5/255 and under 1% of pixels beyond 2/255. It also checks that shrinking by 1 to 300 pixels keeps the phase and needs no new picture, that a phone-sized box takes at most 120 tiles and 32 pictures, and that percentage stops (one clamped by an earlier length stop among them), to top right and a non-repeating gradient do not tile.
    • GradientTilesIOSTests checks that the textured node keeps no bitmap and that its render(in:) matches the drawn path before and after a whole-pixel resize, which reuses only existing pictures. It also checks that a dashed border makes the box draw its gradients.
  • Not run: --tvos --no-install. This machine's toolchain lacks aarch64-apple-tvos-sim. The new iOS file is also compiled for tvOS.
  • Not on a device: all numbers are from the simulator.

@janicduplessis
janicduplessis marked this pull request as ready for review November 15, 2026 03:33
…raws nothing

A repeating gradient made its node draw its whole box in draw(_:), and
contentMode .redraw drew that bitmap again at every size. A sheet with
detents is resized every frame of an interactive drag, so a sheet whose
page has two diagonal repeating-linear-gradient textures re-rasterized the
full-screen texture every frame.

When every background layer is a repeating linear gradient whose period
does not change with the box, the gradients now paint as tile cells on
sublayers and the node keeps no bitmap. Tiles start from the device pixel
of the corner the gradient line starts at, and each tile's picture is
keyed by its phase along the line, so a resize by whole pixels moves the
tiles and draws nothing. Tiles are drawn with the same code that draws
the whole box. Percentage stops, to-corner directions and boxes drawn for
another reason keep the drawn path.
CSS fix-up can clamp a percentage stop to an earlier length stop at both
of the sizes the period is checked at and leave it free at a larger box,
so the two-size check alone accepted a period that changes with the box.
A period a hair off a whole number of pixels kept a tile one period wide,
thousands of tile layers over a phone screen. Each tile carries its own
phase, so its size only decides how many tiles share a picture. The tvOS
build, which compiles the tiles too, also leaves a tiled gradient to them
in draw(_:).
…corner

The corner tile drew with the corner pixel's phase while its top left sits
a tile away, a few thousandths of a point off where its period is not a
whole number of pixels. That moved every stripe edge that falls on a pixel
centre, as the Chrome parity page's hatch does. Each picture is now keyed
by its phase's distance from the corner tile's, which draws exactly.
A gradient that interpolates differently in the dark scheme carries a
source of its own there, and one that names AccentColor resolves with the
view's tint. The period comes from the source for the appearance, and the
tiles are drawn again when the tint changes.
@janicduplessis
janicduplessis force-pushed the @janic/pattern-gradients branch from 97c68a5 to 2440dac Compare November 15, 2026 04:11
@janicduplessis
janicduplessis merged commit 48e5cf4 into main Nov 15, 2026
2 checks passed
ccheever added a commit to expo/exact that referenced this pull request Nov 15, 2026
…o a resize draws nothing

A background of repeating linear gradients made its box draw in
draw(_:), so every frame of a sheet's detent drag on iOS, or of a Mac
window's live resize, rasterized the whole texture again. Each gradient
is now a sublayer whose background is a Core Animation pattern: the
kernel resolves one period (Gradient::cycle, exact_gradient_cycle), its
cell is painted once, axis-aligned, and the render server tiles it.
The sublayer is turned to the gradient's angle and anchored where the
period starts, so the phase follows the view, and a resize only moves
the anchor. Other backgrounds, and a box that draws for another reason,
paint as before.

The turn is the layer's, not the pattern matrix's: on iOS, render(in:)
(captures, a filter's input) mirrors a pattern's y axis about the
layer's origin, which a cell that is constant along y does not show.

The issue's sheet on an iPhone 17 simulator (iOS 27): over four
detent drags, NodeLayer.display ran 30 times at 24 to 39 ms each, all
drawing, and now runs 54 times at 0.13 to 0.32 ms with nothing drawn.
Each period's cell rasterizes once in under 0.1 ms. On screen at 3x,
boxes at 0, 30, 45 (the hatch pair) and 90 degrees, a 45 degree black
and white stripe and a rounded "to top right" differ from Chrome by a
mean of 0.00, 1.32, 0.00, 0.00, 2.92 and 0.76 out of 255. The hatch
parity case passes on macOS and iOS.

Reading one period and placing it from where the gradient line starts
follows appandflow#9.

Fixes #661

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.

1 participant