Port SKMatrix math to managed C# to remove native interop (#2779)

[mattleibow]

Fixes #2779.

Problem

SKMatrix is a pure managed struct, but every math operation (Invert, Concat, MapPoint, MapVector, MapRect, MapRadius, MapPoints/MapVectors) round-tripped through the Skia C API. Each call paid the full P/Invoke transition cost — pinning, marshalling and a managed→native→managed hop — even though the underlying math is a handful of floating-point operations. For hot paths (mapping points, inverting/concatenating transforms in a render loop) this interop dominates the cost.

What this does

Reimplements the math in managed C#, faithfully mirroring Skia's SkMatrix algorithms so results are bit-for-bit identical to the native path. The implementation follows the exact C++ code Skia runs through the C shim (AsMatrix/MakeAll → proc-table dispatch), matching float-vs-double usage, operation order, type-mask computation, the ±0/Inf/NaN edge behaviour, and the skvx min/max/shuffle semantics.

The batch MapPoints/MapVectors paths use System.Numerics.Vector4 (two points per vector lane, mirroring Skia's skvx::float4 procs Trans_pts/Scale_pts/Affine_vpts), with a hardware Vector128.Shuffle swizzle on modern runtimes (net8+) and a portable Vector4 fallback on older TFMs (netstandard2.0, net4x, net6). The scale/translate batch procs unroll to four points per iteration (two float4) exactly like Skia's Scale_pts/Trans_pts so the multiplies pipeline. Perspective mapping stays scalar (as it is in Skia), and perspective MapRect still delegates to native (Skia uses a non-trivial path-clipping routine there).

No public API changes — only method bodies changed, plus one new private static readonly bool gate. ABI is unchanged: every public signature is byte-identical to main (verified by diff); the only public-line edits are expression-body ↔ block-body reformatting.

Correctness

Bit-exactness is the hard requirement (SkiaSharp must not change rendering output). New SKMatrixManagedTests call the Skia C API directly (SkiaApi.sk_matrix_*) and assert bit-equality against the managed result across ~230 matrices (static + 200 seeded-random), including:

• perspective, degenerate / non-invertible, collinear-row matrices
• -0, Inf, NaN, MaxValue, Epsilon members
• scale-by-infinity matrices that specifically exercise the sort_as_rect NaN semantics
• odd/small batch counts {0,1,2,3,5,6,8,10,11,12} to hit the SIMD pair loop, the unrolled 4-point loop and the scalar tail (incl. counts that combine the single-pair lead-in with the unrolled loop)
• in-place mapping (dst == src) for both points and vectors
• overlapping shifted spans (dst one element ahead of src in a shared buffer) for vectors, which pins the reverse-iteration order of the perspective path
• Inf/NaN points and rects

All 12 equivalence tests pass bit-exact, the 20 existing SKMatrixTests stay green, and 151 additional matrix-consuming tests (SKMatrix44, SKPath, SKCanvas, SKShader, SKRoundRect, SKRotationScaleMatrix) pass.

This was independently reviewed against the pinned Skia submodule sources (SkMatrix.cpp, SkRect.cpp, SkVx.h, SkFloatingPoint.h) and by two AI reviewers (GPT-5.5 and Opus 4.8). Two narrow native-parity gaps were found and fixed in this PR:

1. MapVector affine operand order — native single mapVector routes through the SIMD Affine_vpts proc (y' = y*scaleY + x*skewY), not mapPointAffine (y' = x*skewY + y*scaleY). The managed vector path and the affine batch tail now use the Affine_vpts order. Bit-identical for finite inputs; this only affects NaN-payload propagation but makes the "bit-for-bit identical" claim hold for the vector path too.
2. Perspective MapVectors iteration direction — native walks the perspective case back-to-front; the managed path now does the same, so overlapping shifted spans match native for all inputs (previously only the dst == src in-place case matched). Covered by a new test that is proven to fail with forward iteration.

Platform note: x86 .NET Framework (x87 FPU)

The managed math is bit-for-bit identical to native Skia on every runtime that rounds each floating-point operation to single precision: x64 .NET Framework, and all .NET Core / .NET 5+ on x64 / x86 / ARM64. Those use SSE2 / NEON scalar math, exactly like native Skia's compiled C++, and the equivalence tests assert strict bit-for-bit equality there.

The one exception is x86 .NET Framework, whose legacy JIT targets the x87 FPU. x87 evaluates float expressions with 80-bit intermediates and only rounds to float32 on store — behaviour explicitly permitted by ECMA-334 §8.3.7: "Floating-point operations may be performed with higher precision than the result type of the operation." In cancellation-prone paths (e.g. x*skewY + y*scaleY where the result nearly cancels) that widening amplifies sub-ULP product-rounding differences into thousands of ULP, and 0*∞-style inputs diverge categorically (native SSE yields NaN, x87's wider range yields a finite value). No numeric tolerance can bridge that without effectively disabling the test and shipping different rendering output on that one runtime.

So on x86 .NET Framework only, the diverging public methods (TryInvert/IsInvertible, Concat/PreConcat/PostConcat/Concat(ref), MapPoint, MapVector, MapPoints, MapVectors, MapRect, MapRadius) keep routing through the original native C API, so output stays byte-for-byte identical to previous releases. The routing is a single static readonly bool UseNativeMath (detected once via RuntimeInformation) — a predictable, always-false branch on every modern runtime, so the managed fast path and its benchmark wins are unaffected. The equivalence tests therefore assert strict bit-equality on all platforms.

Benchmarks

Before/after harness added (SKMatrixBenchmark, SKMatrixMapBatchBenchmark): the *_Native methods call the Skia C API directly (the old code path), the *_Managed methods use the new math. Apple M3 Pro, .NET 10, default job. All ops allocate zero in both before and after.

Scalar / single-value ops

Interop dominated the old cost, so removing it is a clear, reproducible win:

Operation	Native	Managed	Speedup
Invert	24.1 ns	8.5 ns	2.8×
Concat	16.6 ns	10.3 ns	1.6×
MapPoint	7.4 ns	~0 ns¹	interop eliminated
MapPoint (perspective)	9.3 ns	0.3 ns	24×
MapVector	13.7 ns	1.7 ns	8×
MapRadius	24.6 ns	8.8 ns	2.8×
MapRect (affine)	17.2 ns	9.4 ns	1.8×
MapRect (scale)	14.8 ns	5.1 ns	2.9×
MapRect (translate)	14.1 ns	5.2 ns	2.7×

¹ The scalar single-point ops are now cheap enough that the JIT folds the constant-input benchmark away; the point is that the P/Invoke transition is gone.

Batch ops vs item count

The array-taking ops are parameterised by count — 4 (low), 64 (medium), 1,024 (cache-resident) and 1,000,000 (very high) — to show how the managed SIMD path scales against Skia's native procs (affine → Affine_vpts, scale → Scale_pts, translate → Trans_pts). Ratio = managed / native (< 1.0 = managed faster):

Count	MapPoints (affine)	MapPoints (scale)	MapPoints (translate)	MapVectors (affine)
4	9.8→3.0 ns · 0.31×	10.2→3.7 ns · 0.36×	8.8→3.0 ns · 0.35×	10.6→3.9 ns · 0.36×
64	21.7→13.9 ns · 0.64×	17.8→14.0 ns · 0.78×	16.4→8.5 ns · 0.52×	21.4→14.3 ns · 0.67×
1,024	211→200 ns · 0.95×	180→141 ns · 0.68×	117→174 ns · 1.48ײ	215→210 ns · 0.98×
1,000,000	200→202 µs · 1.01×	163→163 µs · 1.00×	144→141 µs · 0.98×	204→207 µs · 1.01×

Takeaway: the managed advantage is largest at small counts and converges to parity as the array grows — exactly as expected, since the removed cost is a fixed per-call P/Invoke transition amortised over more elements. At 1,000,000 points the work is memory-bandwidth bound and the two paths are identical (0.98–1.01×).

² The 1,024-point arrays are 8 KB and stay L1-resident, so absolute times are tens-to-low-hundreds of ns and dominated by CPU frequency scaling on this laptop. The native baseline for the same op swings run-to-run (e.g. translate@1024 native measured 117 ns isolated vs 187 ns in the full sweep → managed ratio 1.48× vs 0.75× for identical code; scale@1024 swung the other way, 0.68× vs 1.46×). This size is a noisy transition point and is effectively on par either way.

Future improvements (out of scope here)

On every modern runtime the single remaining interop call in SKMatrix is perspective MapRect (SKMatrix.cs, the hasPerspective branch); everything else is fully managed. (On x86 .NET Framework, all of the ported math additionally routes back to native — see the platform note above.) Tracked follow-ups:

• Perspective MapRect (the last interop) — tracked in [perf] Port perspective SKMatrix.MapRect to managed (remove last SKMatrix native interop) #4249. For a perspective matrix, mapping the four corners and taking their bounds is not correct: the transform can push corners onto or behind the w = 0 plane, and edges crossing that plane must be clipped. Skia builds a path from the rect and runs SkPathBuilder::transform → SkPathPriv::PerspectiveClip → SkHalfPlane + SkEdgeClipper::ClipPath (a full edge-clipping engine). A faithful port pulls in hundreds of lines of path-clipping infrastructure to remove one P/Invoke on the rare perspective path, so it stays native for now.
• System.Numerics bridges (additive API) — tracked in Add System.Numerics bridges: SKMatrix↔Matrix3x2, SKColorF↔Vector4, and related #4250. SKPoint↔Vector2, SKPoint3↔Vector3 and SKMatrix44↔Matrix4x4 already exist; the useful gaps are SKMatrix↔Matrix3x2 (the 2×3 affine equivalent; explicit SKMatrix→Matrix3x2 drops perspective, implicit the other way) and SKColorF↔Vector4 (layout is already identical R,G,B,A). Purely additive, so ABI-safe, but expands public surface and needs API-review sign-off. (SKRect↔Vector4, Plane, Vector<T> were considered and recommended against.)
• Wider SIMD for huge batches — the batch procs use Vector4 (two points per 128-bit lane). On x64 with AVX, Vector256 could pack four points per lane. Measured on ARM64/NEON it is a non-starter: Vector256 is emulated and ran 5.7–6.5× slower, while ILP-unrolling (4/8 points per iteration) gave no gain because large arrays are memory-bandwidth bound (the 1,000,000-point cases are already at parity above). Any benefit is x64-only, would need an Avx-gated second bit-exact path, and is unverified on the dev hardware — so it is deliberately not done.
• Related upstream runtime issue for Vector4 swizzle codegen (affects the affine SwapXY): Add Matrix3x3 dotnet/runtime#16226.

Deliberate non-goal — FMA: the managed math intentionally does not use fused multiply-add (MathF.FusedMultiplyAdd / Vector* FMA). FMA rounds a*b + c once instead of twice, so it would diverge from Skia's separate multiply/add and break the bit-exactness guarantee (the equivalence tests confirm the native build does not contract these either). The scale/affine inner loops should not be "optimised" with FMA.

(Note: SKMatrix44 is already fully managed — backed by System.Numerics.Matrix4x4 with no interop — so it needs no similar work.)

Independent confirmation — permanent tracking suite (CI, Linux)

The regression-tracking benchmarks added for this port (MatrixMapPointsBenchmark
single-op methods + the new MatrixOpsBenchmark, in SkiaSharp.Benchmarks.Tracking)
now measure this change on CI hardware. Comparing this branch's source build (managed)
against the nightly package (native), averaged over repeated Linux runs:

Op (4096 individual calls)	native → managed	Δ
MapVector	180 → 28 µs	−84%
MapPoint	76 → 16 µs	−78%
MapRadius	229 → 79 µs	−65%
MapRect	193 → 79 µs	−59%
Concat (pre+post)	229 → 102 µs	−56%
Invert	143 → 119 µs	−16% (smaller op, noisier)
MapPoints (batch — one native call)	2.9 → 2.6 µs	−9%

This independently reproduces the laptop micro-benchmarks above: removing the per-call
P/Invoke is a large win when it is paid per element (the single-op loops), and collapses
to parity for the batch overload that already made a single native call — the MapPoints
batch barely moves (−9%), exactly as the amortisation argument predicts.

Caveat: the tracking dashboard compares two separate CI runner VMs, so it carries a
~±25% run-to-run noise floor; these large effects clear it comfortably, but sub-25%
deltas on µs-scale benchmarks are within the noise and should be read from the
in-process A/B numbers above (that is why Invert, the smallest op, is the least stable).

---

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[github-actions]

📦 Try the packages from this PR

Warning

Do not run these scripts without first reviewing the code in this PR.

Step 1 — Download the packages

bash / macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.sh | bash -s -- 4241

PowerShell / Windows:

iex "& { $(irm https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.ps1) } 4241"

Step 2 — Add the local NuGet source

dotnet nuget add source ~/.skiasharp/hives/pr-4241/packages --name skiasharp-pr-4241

More options

Option	Description
--successful-only / -SuccessfulOnly	Only use successful builds
--force / -Force	Overwrite previously downloaded packages
--list / -List	List available artifacts without downloading
--build-id ID / -BuildId ID	Download from a specific build

Or download manually from Azure Pipelines — look for the nuget artifact on the build for this PR.

Remove the source when you're done:

dotnet nuget remove source skiasharp-pr-4241

[github-actions]

📖 Documentation Preview

The documentation for this PR has been deployed and is available at:

🔗 View Staging Site
🔗 View Staging Docs
🔗 View Staging Gallery (Blazor)
🔗 View Staging Gallery (Uno Platform)
🔗 View Staging SkiaFiddle

This preview will be updated automatically when you push new commits to this PR.

---

This comment is automatically updated by the documentation staging workflow.

[Copilot]

Pull request overview

This PR ports SKMatrix math operations from native Skia C API calls to a managed C# implementation to eliminate P/Invoke overhead on hot paths, while preserving native behavior (including a runtime gate that keeps x86 .NET Framework on the native path to avoid x87 precision divergences). It also adds parity tests and benchmarks to validate/measure the change.

Changes:

• Replaced native interop in SKMatrix operations (invert/concat/map/map-batch/map-radius/map-rect fast paths) with managed implementations intended to be bit-for-bit identical to Skia.
• Added SKMatrixManagedTests that compare managed results against direct calls into SkiaApi.sk_matrix_* across a broad corpus, including aliasing/overlap cases.
• Added BenchmarkDotNet benchmarks to compare old (direct native C API) vs new (managed) paths for scalar and batch operations.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
tests/Tests/SkiaSharp/SKMatrixManagedTests.cs	Adds native-vs-managed equivalence tests for SKMatrix math, including edge cases and aliasing/overlap scenarios.
binding/SkiaSharp/SKMatrix.cs	Implements managed SKMatrix math + runtime UseNativeMath gate; replaces prior per-call native interop for most operations.
benchmarks/SkiaSharp.Benchmarks/Benchmarks/SKMatrixBenchmark.cs	Adds before/after benchmarks comparing direct C API calls (“Native”) to the new managed path (“Managed”).

[mattleibow]

Stale — already addressed at the current PR head. NativeTryInvert now initializes the local before the call: var result = SKMatrix.Identity;, which is exactly the fix suggested here, so there is no uninitialized-stack read. (The managed TryInvert also explicitly sets inverse = Identity on the non-invertible path, matching the native shim.)

[mattleibow]

By design — not a defect. BitEqual enforces an exact bit match for every finite result and a NaN-for-NaN match for non-finite ones, deliberately ignoring NaN sign/payload. The native and managed paths legitimately reach NaN via different routes and can differ only in those payload/sign bits (e.g. MapRect of a rotation over an infinite rect: native 0x7FC00000 vs managed 0xFFC00000 — same quiet NaN, opposite sign). Skia never inspects NaN payloads, so comparing them would fail the suite on a provably insignificant difference while adding no real coverage. The bit-for-bit guarantee that matters — all finite outputs — is fully enforced.

[mattleibow]

Stale — the current comment is accurate and already says this. It reads: "…leaves its out matrix as the identity it was default-constructed with … (A default-constructed SKMatrix in C# is all-zero, so set it explicitly.)" It refers to the native C++ SkMatrix default-ctor (which is identity) and explicitly notes the C# default is all-zero, which is why the code assigns Identity. No misleading claim remains.

[mattleibow]

Stale — resolved in commit 024893a ("Use unaligned Vector4 access in SKMatrix batch procs"). MapTranslateBatch now reads/writes via Unsafe.ReadUnaligned<Vector4> / Unsafe.WriteUnaligned; there is no raw *(Vector4*) dereference left, so the alignment/UB concern no longer applies.

[mattleibow]

Stale — same fix (commit 024893a). MapScaleBatch now uses Unsafe.ReadUnaligned<Vector4> / Unsafe.WriteUnaligned for all vector reads and writes; no aligned *(Vector4*) cast remains.

[mattleibow]

Stale — same fix (commit 024893a). MapAffineBatch now uses var v = Unsafe.ReadUnaligned<Vector4>(s + o); and Unsafe.WriteUnaligned(...); no aligned *(Vector4*) dereference remains.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[mattleibow]

The code is correct — this is at most a wording nit in the summary comment, not a behavioral issue. The scalar tails are bit-identical to native because they preserve native operand order, not because of commutativity: the affine tail computes (x*sx + y*kx) + tx / (y*sy + x*ky) + ty, matching Skia's Affine_vpts trailing-element lane (and the inline comment directly above that line already states this correctly). Fair point that "IEEE addition is commutative" is imprecise justification in the top-of-proc comment; it could read "the scalar tail preserves native operand order" instead. No code change needed.