Support SkiaSharp Blazor views on Server and Hybrid hosts (#1194)

[mattleibow]

Summary

Extends SkiaSharp.Views.Blazor so the same SKCanvasView / SKGLView that run in Blazor WebAssembly also work under Blazor Server, Blazor Hybrid (BlazorWebView), static SSR, and Interactive Auto — closing the long-standing ask in #1194. Existing WebAssembly consumers are unaffected (API and behaviour identical; all new API is additive).

The components detect their host at runtime (RendererInfo, .NET 9+) and pick one of two present strategies:

• Direct — WebAssembly draws natively in the browser (existing path, unchanged).
• Bridged — Server/Hybrid/Static render on the .NET side, then transfer the frame to the browser where a small JS module paints it into the same <canvas>.

Server and Hybrid both marshal through IJSRuntime (SignalR vs in-process WebView), so one code path covers both.

Verified end-to-end

The Blazor Server sample was driven in a real browser (Playwright): all three pages render identically to the WebAssembly sample — CPU (SKCanvasView), GPU (SKGLView SkSL shader on a WebGL-backed canvas), and Drawing (pointer/wheel input) — with the full MudBlazor chrome, painting at cssSize × DPR. 22 unit tests pass; the library builds for net6.0/net9.0/net10.0.

What's included

• Public API (additive): SKBlazorTransferFormat (Png/Jpeg/Put), SKBlazorOptions, AddSkiaSharpViewsBlazor(...), per-control TransferFormat/Quality. Configurable globally and per control, host defaults (Hybrid→Put, Server→Jpeg), orthogonal to the host so every path is testable from one host.
• Internals: host detection + format resolution, a pure/testable frame producer (PNG/JPEG/raw RGBA), the host-agnostic IJSObjectReference bridge interop, and a backpressured bridged renderer (matches WASM EnableRenderLoop/Invalidate, awaits the previous frame, suppresses byte-identical frames, yields each loop iteration).
• JavaScript: shared, pure-browser SKCanvasPresenter (Canvas2D + WebGL) and a thin host-agnostic SKHtmlCanvasBridge. The bridged path never imports the emscripten-coupled SKHtmlCanvas.js.
• SKGLView keeps a WebGL-backed canvas under a bridged host (CPU raster server-side, presented via texImage2D; real server GPU is a future extension).
• Tests: tests/SkiaSharp.Tests.Blazor (frame producer, host detection, DI).
• Sample: samples/Basic/BlazorServer — a 1:1 copy of the WebAssembly sample, Server-hosted (shared pages/layout/styles are byte-identical; only the host wiring differs).
• Docs: documentation/dev/blazor-server-hybrid-rendering.md — a normative, host-independent behaviour specification (WebAssembly + Server/Hybrid/Static/Auto) with a §14 conformance map, linked from AGENTS.md and the dev docs index.

Framework support

Server/Hybrid/Auto require .NET 9.0+ (uses the official RendererInfo API). net6.0/net8.0 remain WebAssembly-only and behaviourally unchanged.

Follow-ups

Tracked in #4367 — including partial (damage-based) frame transfer for the bridged path, a Blazor Hybrid sample + device test, the full test web-app pages + CI, native-asset packaging pack-verification, a static-SSR poster frame, folding the WASM paint onto the shared presenter, and API XML docs.

Closes #1194

Co-authored-by: Copilot App 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 -- 4363

PowerShell / Windows:

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

Step 2 — Add the local NuGet source

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

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-4363

[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.

[taublast]

Hey looks great!
Text below is suggestions on "what would be nice to have to consume this PR changes externally" (by DrawnUI and others..)

1. Add public CanvasSize on SKCanvasView/SKGLView — this PR silently breaks reflection-based consumers.
   The previous implementation kept a canvasSize field on the view; this PR moves it into the private renderer (BridgedRenderer.canvasSize). DrawnUI (and likely other frameworks) today read it via typeof(SKCanvasView).GetField("canvasSize", NonPublic) because no public accessor exists — after this PR that returns null and layouts get SKSize.Empty with no compile error. Since IRenderer already tracks size, exposing public SKSize CanvasSize => renderer?.CanvasSize ?? SKSize.Empty (add it to IRenderer next to Dpi) is cheap and removes the reflection incentive permanently.

2. Add a public size/DPI change notification on the views.
   BridgedRenderer.OnMetricsChanged receives size + DPR from JS but nothing reaches the component consumer; Dpi can only be polled. A retained-mode framework must re-measure/re-layout its tree exactly when metrics change. Ask: public event Action<SKSize, double>? MetricsChanged (or a protected virtual OnMetricsChanged) on both views, raised by all three renderers.

3. Expose renderer kind publicly — consumers must be able to detect bridged mode.
   In bridged mode SKGLView is CPU raster with a placeholder GRBackendRenderTarget (framebuffer 0) and no real GRContext. A framework that manages GPU caches/image textures must branch on this, and today the only signal is inference from side effects. Ask: make HostKind public and add public bool IsBridged (or RendererKind { DirectRaster, DirectGL, Bridged }) on the views. One enum + one property, no behavior change.

4. Expose GRContext on SKGLView (nullable).
   Same story as number 1: consumers currently reflect the private context field to share GPU resources (texture caches, cross-surface images). This PR restructures internals, so the reflection breaks. public GRContext? GRContext — null in bridged and pre-init — is the honest contract and pairs with number 3.

---

5. Make IRenderer public and renderer creation overridable: protected virtual IRenderer? CreateRenderer(HostKind hostKind).
   Rendering strategy selection is hardcoded in OnAfterRenderAsync. Frameworks with retained scenes know exactly when content is dirty and what changed; the paint-callback + full-frame byte-compare (lastFrame.AsSpan().SequenceEqual) is redundant work for them — for a loop over a 1080p canvas that is a repaint plus an ~8 MB memcmp per iteration even when the framework knows nothing changed. A ss wrap or replace the strategy (e.g. supplyframes from its own invalidation pipeline) without forking. If making IRenderer public is too much API surface for
   this PR, unsealing BridgedRenderer + making ut please don't ship the interface shape asinternal sealed forever.

6. Document (or fix) Invalidate() thread affinity.
   Invalidate() → _ = RenderLoopAsync() mutatesynchronization and walks straight into JSinterop. Frameworks drive invalidation from render loops/timers off the circuit dispatcher; calling this cross-thread
   is a data race today. Either document "must in the XML docs, or marshal internally(InvokeAsync) / use Interlocked on the flags. Cheap now, painful to diagnose later.

7. Make Dispose virtual (or the views implement IAsyncDisposable).
   public void Dispose() is non-virtual and fireAsync(). Subclasses must shadow with new,which breaks disposal through the base type reference. protected virtual disposal hook is the standard component
   pattern; async disposal would also stop the

8. Nice-to-have: poster frame at prerender/s
   Bridged presentation happens only after JS module init, so prerendered HTML shows an empty canvas. Optionally render
   the first frame server-side into an inline dnd so static SSR paints content immediately.Fine as a follow-up.