[animation] start values read from `presentation()` are for Core Animation's time, not the clock's time the animations begin at

[honghaoz]

Observation

Split from item 3 of #95. When retarget(keyPath:to:) can't fold the in-flight animations, it replaces them with an animation that starts from presentation(), and the replacement begins at AnimationClock's time for the turn. The two times differ.

In a probe where 30 ms passed between the turn's first clock read and a non-animated DropShadowLayer.update, the shadowOpacity replacement began at the clock's time but started 30.3 ms further along the interrupted animation: 0.3698 instead of 0.3092, for a fade from 0 to 1 over 0.5 s. In a normal turn the gap was 0.2 ms. The shadow radius, which the retarget folds at the clock's time, matched to six decimals either way.

AnimationClock documents that "the in-flight animations evaluated in a turn are evaluated at the time the new ones begin". The fold follows that. A start value read from presentation() doesn't.

Analysis

Core Animation evaluates presentation layers at one time per transaction: the time of the transaction's first presentation read, of any layer. Later reads return that time until the transaction commits, and model changes don't refresh them. Probed on macOS 26: two reads 30 ms apart returned the same object, another layer read 30 ms later showed the first read's time, and a model change or adding and removing an animation didn't refresh it. Only a commit, from CATransaction.flush() or a run loop turn, did. iOS wasn't probed.

So a start value read from presentation() is for whenever the transaction first read a presentation layer, while the animation it starts begins at whenever the turn first read the clock. In a long turn, such as a render pass over many items, the two can be milliseconds apart in either order, and the new animation starts that far along or behind the motion it interrupts.

The framework starts animations from presentation() in 12 places:

• retarget(keyPath:to:), for the animations it can't fold: of opacity and shadowOpacity, which the render server clamps, non-additive ones, and ones of values other than numbers, sizes, and points, such as colors.
• animate(key:keyPath:timing:from:to:model:updateAnimation:), for the unresolved from value of a delayed non-additive animation.
• DropShadowLayer and InnerShadowLayer: shadowColor and shadowOpacity.
• ModifierNode: backgroundColor, borderColor, shadowColor, shadowOpacity, and shadowPath.
• ColorNode: backgroundColor.

Performance

Measured in a release build on macOS (M4 Max), with 200 hosted layers, each with a non-additive shadowOpacity animation and a frame animation in flight, median of 40 rounds:

• A layer's first presentation read in a transaction costs about 2.7 µs, 3.0 µs through KVC, and keeps 14 allocations, 1,076 bytes, alive until the commit. Later reads of the same layer in the transaction return the same object.
• Computing the same opacity from the layer's animations at the clock's time costs about 1.1 µs including fetching the animations, and 0.33 µs with them already at hand, as retarget has them. It matches the presentation value to within 7e-6.
• The saving only happens where a layer's presentation reads in the turn go away entirely. A layer whose color animates in the same update still builds its presentation copy for the color, and computing its opacity would then add to that.

These paths run when an update starts or retargets animations, not every frame, so the saving counts when one turn updates many layers, such as a theme change over a long list.

Options

1. Compute numbers at the clock's time. Evaluate opacities from the in-flight animations at the clock's time, as interruptedOpacityState() already does for opacity, and keep presentation() for colors and paths. This fixes numbers and saves the presentation copy where only numbers change, but a color and an opacity retargeted together would then start at different times.
2. Also compute colors and paths. Interpolate them the way Core Animation does. This fixes all 12 places and removes the presentation reads from these paths, but it needs interpolation that matches Core Animation's, including the color space colors interpolate in, or the start would differ from what's on screen.
3. Align the two clocks. Have the clock's first read in a turn also fix Core Animation's presentation time, since one presentation read fixes it for the whole transaction, so every presentation() read in the turn is for the clock's time. This fixes all 12 places with a small change, without the performance gain. Unverified: whether a read of any layer fixes it, as an unhosted layer's presentation() is nil. A CATransaction.flush() mid-turn commits and lets the next read fix a new time while the clock keeps its own. A presentation read before the clock's first read in a turn fixes the time before the clock can.

To do

1. Add a test that exposes the offset: a hosted layer with an animation in flight, the clock read, a stall, then a replacement that should start from the value at the clock's time.
2. Choose an option, or combine 1 and 3.
3. Measure a render pass that updates the colors and opacities of many layers before and after, since the costs above are per-layer micro-benchmarks.

[honghaoz]

Findings

Probed on macOS 26 and in the iOS simulator, with the same results on both.

The offset goes both ways. Through DropShadowLayer.update with a 30 ms stall, replacements start 31 to 35 ms ahead when the clock is read first, and 32 to 35 ms behind when an app reads an animating layer's presentation first, which shows as a jump back. It's the same for colors and opacities, and for animated and non-animated updates.

Only a presentation read of a layer with animations fixes Core Animation's time. A read of a layer without animations doesn't, even when its sublayers animate, and neither does a model change, an empty transaction, adding an animation, or convertTime. This rules out option 3: the clock's first read would need an animating layer to read, and it would still break on a mid-turn CATransaction.flush() and on an earlier presentation read.

Colors and paths can be computed exactly. Core Animation converts both colors to extended sRGB and interpolates component by component with straight alpha, for every color space tried: sRGB, Display P3, generic and extended gray, generic RGB, extended and linear sRGB. The presentation color is always in extended sRGB, and a lerp in extended sRGB matches it to 1e-7. Paths with the same segments interpolate point by point, as PathPoints assumes.

The performance premise doesn't hold for a render pass. Measured in a release build on macOS (M4 Max):

• A presentation read of a layer without committed animations costs about 170 ns and builds no copy, and one copy serves every read of a layer in a transaction.
• Computing a start value walks the layer's animations once per key path: about 0.56 µs for animationKeys() plus 0.09 µs per animation. A color outside sRGB, such as NSColor.black, needs a ColorSync conversion, about 4.3 µs and 19 allocations, unless cached.
• Per start value, computing is 1.6 to 3.3 times faster, with fewer allocations. But a row usually reads several properties, and the render pass is what counts.

A 300-row render pass, medians of 30 passes, three interleaved runs:

Scenario	presentation()	Computed
Non-animated change, colors in flight	12.4 to 12.9 ms	12.3 to 12.8 ms, 10% fewer allocations
Animated change, frames in flight	9.2 to 10.2 ms	10.1 to 10.4 ms
Animated change, nothing in flight	6.3 to 6.7 ms	6.9 to 7.0 ms
Animated change, colors in flight	8.3 to 9.3 ms	10.3 to 11.0 ms

The computed version reuses the animations retarget already collects, caches ColorSync conversions, and returns the from or to value as it is at progress 0 or 1. A naive version was 9% to 60% slower.

Fix

Option 2, for all 12 places. A start value is computed from the layer's model value and animations at the clock's time, and presentation() is only the fallback for animations that can't be evaluated, such as keyframe or repeating ones. This fixes the accuracy, also for layers that haven't been committed yet, and removes the second time source. It costs up to 1 to 9 µs per changed row on an animated update, during refreshes rather than per frame, and is on par or better for non-animated updates.

[honghaoz]

Final numbers, from #98. They replace the ones in my earlier comment.

A render pass over 300 rows whose background, border and shadow colors and shadow opacity change. Release build on macOS, median of 30 rounds, autorelease pool drains included:

Scenario	master	#98
Non-animated change, colors in flight	12.3–12.4 ms	11.8–12.2 ms, 12.5% fewer allocations
Animated change, frames in flight	8.1–8.4 ms	8.4–8.6 ms, 4.5% fewer allocations
Animated change, nothing in flight	6.8 ms	7.2–7.4 ms
Animated change, colors in flight	8.4–8.6 ms	9.9–10.1 ms, 7% fewer allocations

• Non-animated updates get slightly faster, with fewer allocations: the retarget computes its start values from the animations it already collected instead of building a presentation copy.
• An animated color or opacity change costs about 0.4 µs more when nothing else animates, and about 1.2 µs more with colors in flight. The computed start value has to include the animations added earlier in the same pass, which presentation() ignores, and Core Animation makes animationKeys and animation(forKey:) several times slower right after an animation is added to a layer. With only the start value reads switched back to presentation(), the branch matches master exactly, so the rest of the change costs nothing.

Since the earlier comment:

• The computed value also clamps cornerRadius at 0, like the render server, checked against the pixels CARenderer renders.
• Parity tests compare the computed values with presentation() on a paused timeline, on macOS and iOS.
• The animation walk reads Core Animation's keys without bridging them to Swift strings, through perform(_:) in a local autorelease pool. perform(_:) autoreleases the layer, so without the pool a released layer stayed alive until the run loop's pool drained.