Add surface, document, and platform view guides - #4566
Open
mattleibow wants to merge 21 commits into
Open
Conversation
Contributor
📦 Try the packages from this PRWarning 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 -- 4566PowerShell / Windows: iex "& { $(irm https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.ps1) } 4566"Step 2 — Add the local NuGet source dotnet nuget add source ~/.skiasharp/hives/pr-4566/packages --name skiasharp-pr-4566More options
Or download manually from Azure Pipelines — look for the Remove the source when you're done: dotnet nuget remove source skiasharp-pr-4566 |
Contributor
|
📖 Documentation Preview The documentation for this PR has been deployed and is available at: 🔗 View Staging Site This preview will be updated automatically when you push new commits to this PR. This comment is automatically updated by the documentation staging workflow. |
Contributor
📊 SkiaSharp benchmarks — PR #4566No ⭐ source-build ( |
Contributor
📦 Artifact size reportPackages from this PR (build Total Packages
+38 package(s) unchanged (< 50.0 KB). Per-file changes
|
| File | Size |
|---|---|
runtimes/win-arm64/native/libGLESv2.pdb |
64.5 MB → 64.4 MB (🟢 −112.0 KB) |
runtimes/win-x64/native/libGLESv2.pdb |
66.6 MB → 66.5 MB (🟢 −64.0 KB) |
runtimes/win-x86/native/libGLESv2.pdb |
67.2 MB → 67.2 MB (🟢 −32.0 KB) |
Informational only — this never blocks the PR. Native binaries are labelled by os/arch.
14 tasks
mattleibow
changed the title
mattleibow
changed the title
mattleibow
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new “Drawing destinations” guide hierarchy to the DocFX guides, grouping offscreen surfaces (raster/Ganesh/Graphite), document outputs (PDF/SVG/XPS), and platform view controls under one navigable section.
Changes:
- Updates the guides landing page and TOC to introduce the new “Drawing destinations” section.
- Adds raster and GPU surface guides (Ganesh + Graphite), including lifecycle, readback, and backend-specific setup pages.
- Adds document (PDF/SVG/XPS) and platform-view (MAUI/Android/Apple/Windows/Linux/Tizen/Uno/Blazor) guidance with ownership/finalization notes.
Reviewed changes
Copilot reviewed 27 out of 27 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| documentation/docfx/guides/TOC.yml | Adds the “Drawing destinations” node and sub-navigation for surfaces/documents/views. |
| documentation/docfx/guides/index.md | Repositions guides landing page to cover non-MAUI scenarios and links to destinations. |
| documentation/docfx/guides/surfaces/index.md | Top-level destination chooser and Ganesh vs Graphite comparison. |
| documentation/docfx/guides/surfaces/raster/index.md | Raster and raster-direct surface creation and synchronous readback guidance. |
| documentation/docfx/guides/surfaces/ganesh/index.md | Ganesh overview + shared offscreen/wrapping lifecycle and cleanup guidance. |
| documentation/docfx/guides/surfaces/ganesh/opengl.md | OpenGL Ganesh setup and framebuffer-wrapping example. |
| documentation/docfx/guides/surfaces/ganesh/vulkan.md | Vulkan Ganesh setup (raw + Silk.NET) and image description pointers. |
| documentation/docfx/guides/surfaces/ganesh/metal.md | Metal Ganesh backend-context setup and texture description pointers. |
| documentation/docfx/guides/surfaces/ganesh/direct3d.md | Direct3D Ganesh backend-context setup and resource description pointers. |
| documentation/docfx/guides/surfaces/graphite/index.md | Graphite overview, submission model, async readback helper, image-provider guidance, and options. |
| documentation/docfx/guides/surfaces/graphite/vulkan.md | Graphite Vulkan backend context setup + wrapped-image usage/release guidance. |
| documentation/docfx/guides/surfaces/graphite/metal.md | Graphite Metal setup, texture wrapping, and simulator caveats. |
| documentation/docfx/guides/surfaces/graphite/dawn.md | Graphite Dawn/WebGPU setup and non-blocking submission guidance for WASM. |
| documentation/docfx/guides/surfaces/graphite/migrate-from-ganesh.md | Ganesh→Graphite conceptual mapping and “before/after” lifecycle conversion. |
| documentation/docfx/guides/surfaces/documents/index.md | Document format chooser and lifecycle differences vs surfaces. |
| documentation/docfx/guides/surfaces/documents/pdf.md | PDF creation example, metadata notes, and abort/verify guidance. |
| documentation/docfx/guides/surfaces/documents/svg.md | SVG canvas creation/disposal lifecycle and verification guidance. |
| documentation/docfx/guides/surfaces/documents/xps.md | XPS creation example including COM lifetime and Windows availability checks. |
| documentation/docfx/guides/surfaces/views/index.md | View-family chooser and paint-callback rules (Ganesh vs raster, no Graphite views). |
| documentation/docfx/guides/surfaces/views/maui.md | MAUI handler registration + backend notes per target. |
| documentation/docfx/guides/surfaces/views/android.md | Native Android raster/GL controls and invalidation guidance. |
| documentation/docfx/guides/surfaces/views/apple.md | Apple raster/OpenGL/Metal control matrix and invalidation guidance. |
| documentation/docfx/guides/surfaces/views/windows.md | WPF/WinForms/WinUI control selection and per-framework invalidation notes. |
| documentation/docfx/guides/surfaces/views/linux.md | GTK3/GTK4 raster control guidance and lack of packaged GPU view. |
| documentation/docfx/guides/surfaces/views/tizen.md | ElmSharp vs NUI control-family differences and event-args caveat. |
| documentation/docfx/guides/surfaces/views/uno.md | Uno-specific GPU availability caveats and target-by-target behavior guidance. |
| documentation/docfx/guides/surfaces/views/blazor.md | Blazor WASM raster vs WebGL components, redraw control, and ownership notes. |
Add a new "GPU and Offscreen Surfaces" section to the docfx guides covering
how to create every kind of SKSurface, wired into TOC.yml and the guides
overview:
- raster-surfaces: SKSurface.Create(SKImageInfo) and raster-direct via
SKPixmap / pinned memory, plus Snapshot / ReadPixels.
- ganesh-surfaces: GRContext for OpenGL, Vulkan, Metal, and Direct3D;
offscreen Create(GRContext, budgeted, info); wrapping GRBackendRenderTarget
and GRBackendTexture; flush and synchronous readback.
- views-surfaces: catalog of the raster vs GPU view controls across
SkiaSharp.Views, .NET MAUI, Uno, and Blazor, noting Graphite is offscreen
only and not driven by any view yet.
- graphite-surfaces: the new SKGraphiteContext path — Create{Vulkan,Metal,Dawn},
recorder -> surface -> Snap -> InsertRecording -> Submit, backend-texture
wrapping, SKImage interop, and the asynchronous RequestReadPixels +
CheckAsyncWorkCompletion readback (with the non-yielding Dawn/WASM caveat).
- graphite-migration: maps existing Ganesh code onto the Graphite model.
Prose guides only (no API reference). All code samples verified against the
bindings and the working Graphite/Ganesh test renderers on this branch; all
xref links validated against the skiasharp xrefmap (new Graphite types, which
are not yet in the published xrefmap, use inline code).
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
- views: state plainly that the view controls are raster + Ganesh only and that onscreen Graphite views are not yet available (under active investigation), not impossible; add minimal GL and Metal paint snippets alongside the raster one. - graphite-surfaces: add a short "Drawing CPU images: the image provider" section — unlike Ganesh, Graphite does not auto-upload a non-Graphite SKImage, so drawing a CPU image without a provider silently drops the draw; document the CreateRecorder image-provider overload and SKGraphiteImageCache. - graphite-migration: lead with the two biggest behaviour changes (async readback and the image-provider difference) and the structural shift (explicit Recorder -> Snap -> InsertRecording -> Submit; per-thread recorder); add the image provider as an explicit migration step and watch-out. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
Point readers at the padding-aware CopyPlaneTo convenience alongside the manual row-by-row copy in the Graphite async-readback example. The manual loop stays, since it makes the row-padding gotcha explicit. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
Update the GPU/surface guides with new learnings from the Graphite feature branch, verified against the current dev/graphite-backend bindings and tests: - Add a Graphite backend->platform support matrix: Metal on Apple (incl. the Apple-Silicon iOS/tvOS Simulator), Vulkan on Linux/Android/Windows, Dawn on WASM. State explicitly there is no Direct3D Graphite backend (Windows Graphite = Vulkan); reflect this in the index comparison table and migration guide. - Switch Vulkan guidance from SharpVk to Silk.NET. Ganesh gains the typed GRSilkNetBackendContext (SkiaSharp.Vulkan.Silk.NET); SharpVk is noted as legacy/unmaintained and Windows/Linux-only. Graphite has no typed Vulkan wrapper — feed the binding-neutral SKGraphiteVkBackendContext raw .Handle values from Silk.NET (or raw libvulkan). Removes the now-deleted SKGraphiteSharpVkBackendContext from the docs. - Document the Vulkan surface gotcha: wrapping a VkImage as a Graphite surface requires ImageUsageFlags to include COLOR_ATTACHMENT (0x10) AND INPUT_ATTACHMENT (0x80) or SKSurface.Create returns null; sample-only images need only SAMPLED (typical renderable mask 0x97). - Document the parameterless SKGraphiteReleaseDelegate overloads on the Graphite wrap-backend-texture SKSurface.Create and SKImage.FromTexture paths. - Add an iOS Simulator note (Graphite Metal works despite the simulator MTLDevice under-reporting its GPU family) and a WASM Dawn bring-up note (a real WGPUInstance must parent the device/queue or CreateDawn deadlocks). Docs-only; code samples mirror the current Graphite/Ganesh renderers and the release/usage Vulkan tests on dev/graphite-backend. Links, anchors, TOC YAML, and xrefs re-validated (new types remain inline code, not xrefs). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
Expand the "Releasing a wrapped texture" section into a full, verified end-to-end example, and document the key subtlety: the SKGraphiteReleaseDelegate fires only after the wrapping surface/image is disposed AND pending GPU work has drained — so callers must pump Submit(Sync=true) + CheckAsyncWorkCompletion and call FreeGpuResources to force it. Includes creating a renderable Vulkan backend texture (ImageUsageFlags 0x97) and freeing it with DeleteBackendTexture. Notes that SKImage.FromTexture's release callback fires the same way and that sample-only images need only SAMPLED usage. All types/members mirror the shipping bindings (SKGraphiteVkTextureInfo, SKGraphiteTextureInfo.CreateVulkan, recorder.CreateBackendTexture/ DeleteBackendTexture, context.FreeGpuResources) and the passing release tests. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
The async read-back API changed on the feature branch: SKGraphiteAsyncReadResult was removed in favour of the backend-neutral SKImageReadPixelsResult, and the rescale enums are now SKImageRescaleGamma / SKImageRescaleMode (default Src / Nearest, was Src / RepeatedLinear). - Rewrite the graphite-surfaces "Reading pixels back" example to use the new result type and its ToArray()/ToBitmap()/CopyPlaneTo(span) helpers instead of the old IntPtr + manual Marshal.Copy row loop; note the result is IDisposable and callback-scoped. - Update the "Status and enums" list to the renamed neutral enums and add SKImageReadPixelsResult; correct the default rescale mode to Nearest. - Refresh the migration guide's read-back step to point at the new helpers. Verified against binding/SkiaSharp/SKImageReadPixelsResult.cs, the SKImageRescale* enums, and SKGraphiteContext.RequestReadPixels on the current base (dev/graphite-backend @ bd78469). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
…ll, iOS sim) Re-reviewed the Graphite guide against the current PR #3968 head (ed8d017) and its description, and folded in the details that were missing or now differ: - iOS Simulator: add the gradient-shader limitation. The simulator's Metal compiler cannot build some pipelines Graphite emits (notably gradient shaders), so recorder.Snap() returns null for that frame; the same content renders on macOS, real hardware, and with Ganesh/Metal. Keeps the existing supportsFamily under-reporting note. - Render loop: document that Snap() returns null on failure and null-check it in the example; point at the image provider for CPU-image draws. - GPU budget: note the no-options Create* factories use Skia's default budget (256 MB) via the -1 sentinel (a literal 0 disables budgeting), matching the sentinel fix in ed8d017; note MaxBudgetedBytes defaults to 256 MB. - Image provider: note SKGraphiteImageCache is an LRU cache (cap 256, keyed on unique id + mipmap), is IDisposable, and that FindOrCreate throws ArgumentNullException on null args (guard added in ed8d017). Verified against binding/SkiaSharp/Gpu/Graphite/*.cs and the generated structs at the current tip. Docs-only; links/anchors/TOC/xrefs re-validated. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
…imitation Add a "tracked in #4555" reference (and the compiler's actual "Compiler failed to build request" message) to the iOS-simulator Graphite/Metal gradient caveat, so readers who hit the null Snap() can follow the known issue. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
…n, skia.org refs Rebased onto main (Graphite PR #3968 is now merged) and added conceptual depth sourced from Skia's own docs, keeping every claim tied to the actual API: - Threading: correct the intro note to reflect Graphite's actual model — a single recorder is single-threaded, but (unlike a single-threaded Ganesh GRContext) Graphite is designed for parallel recording with one recorder per thread feeding a shared context; serialize InsertRecording/Submit. Align the migration guide's threading watch-out to match. - Add a "Pipeline compilation" section: Graphite compiles a GPU pipeline per unique draw/paint/blend/format combination on first use (cached after), so the first frame using a new combination costs more, and a driver that can't compile it makes Snap() return null — which is exactly the iOS-simulator gradient case. Note upstream Skia's pipeline precompilation exists but isn't surfaced in SkiaSharp yet. Cross-linked from the render loop and the iOS-simulator note. - Add authoritative skia.org "canvas creation" references to the raster, Ganesh, and Graphite Related Links. Docs-only; verified against the merged Graphite bindings on main (byte-identical to the reviewed ed8d017). Links/anchors/TOC/xrefs re-validated. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
Add a Microsoft Learn-inspired conceptual documentation route while preserving the API-reference workflow. Correct GPU surface selection, Graphite lifecycle, ownership, failure, and platform guidance, and document the CI orchestration boundary.\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>\nCopilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
Limit automated authoring to reviewable batches and require explicit managed/native evidence, deterministic exception coverage, and truthful deferred reporting before generated docs are proposed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
Move the API/conceptual documentation skill and contributor workflow changes to standalone PR #4674 so this PR contains only the GPU surface guides and navigation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
Align the wrapped-texture cleanup sample with the tested recorder path, make Vulkan resolver placeholders syntactically valid, correct async-readback attribution, align section ordering, and tighten the guide description. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
Group raster, Ganesh, and Graphite guidance under a surfaces section, split backend setup into directly navigable pages, and keep view-managed rendering separate. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
Document PDF, SVG, and XPS canvas workflows, including lifecycle, ownership, platform constraints, and verification. Link document output as a sibling to surfaces and view-managed rendering. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
Nest document and platform view guidance under the surfaces section. Split view guidance into source-backed integration pages for MAUI, native platforms, Uno, and Blazor. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
Clarify Graphite Metal device preflight, initialize Ganesh Vulkan extensions, correct raster pointer lifetime, and align navigation and examples. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
Focus the examples on the successful rendering flow while keeping failure behavior and production caveats in the surrounding prose. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
mattleibow
force-pushed
the
mattleibow-graphite-surface-docs
branch
from
August 6, 2026 13:20
04bee4b to
42dff4c
Compare
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ae60ac4-ac5a-466d-9a84-8a9e3a6c7c88
Contributor
Author
|
/merge-message |
Contributor
|
❌ Merge Message failed. Please review the logs for details. |
Contributor
Author
|
/merge-message |
Contributor
|
❌ Merge Message failed. Please review the logs for details. |
Contributor
|
https://mono.github.io/SkiaSharp/staging/4566/docs/guides/surfaces/graphite/index.html
Not necessarily. There aren't SkiaSharp views that use graphite yet, but you can definitely set up an onscreen render target similar to how you can use Ganesh with an onscreen render target without going through the SkiaSharp views.
I don't think it necessarily auto-flushes. I think you usually need an explicit Flush call.
I think maybe we should stick to WebGPU and not mention Dawn? We only support actual webgpu in the browser (not desktop webgpu), so it's not really Dawn.
This is equally true for Ganesh, no? So it's kind of unnecessary to mention.
I think we should just say explicitly that this won't work on wasm because it needs to yield at some point."native hosts" is a bit ambiguous. https://mono.github.io/SkiaSharp/staging/4566/docs/guides/surfaces/views/uno.html |
…parallelism Rework the Graphite guide so readers stop inferring that a single serialized submission queue makes Graphite pointless. All docs-only. graphite/index.md: - Fix the Ganesh contrast: both backends defer GPU work (neither is immediate-mode). Ganesh keeps deferred work in a stateful GRContext drained by Flush/Submit (may flush internally); Graphite exposes independent Recorder/Recording producers transferred to one Context thread. Drop the absolute "offscreen-only" framing (you can wrap an onscreen target yourself); keep "no SkiaSharp view drives Graphite yet". - Define SKGraphiteRecording accurately: an immutable package of prepared tasks, resource refs and callbacks — NOT a native command buffer. InsertRecording encodes those tasks into the Context's current command buffer on the Context thread (no GPU work yet); Submit sends the buffer to one backend queue. - Refine threading: Recorder/Context are single-owner, not permanently thread-affined; separate recorders may run on CPU workers with synchronized handoff; all Context ops serialized on one submission thread. - Add "What parallel recording actually means" with a Mermaid flowchart (parallel CPU recording -> serialized Context encoding -> one ordered backend queue -> massively parallel GPU), stating one queue is not one GPU thread and extra recorders don't create extra GPU queues. Add a cross-frame pipelining diagram (async Submit lets CPU record N+1 while GPU runs N) and a compositor-style example (explicitly not stock Uno/SkiaSharp controls) with partitioning caveats. - Fix the readback helper: bounded pump budget, handle a null result, check the Submit return value; keep the browser/Dawn rule (never block the event loop). graphite/migrate-from-ganesh.md: - Drop "Ganesh auto-flushes" as the core distinction; "packages pending Graphite tasks/resources" instead of "captures recorded commands"; note recording is CPU-parallel while InsertRecording/Submit are serialized; link to the overview diagram instead of duplicating it. Preserves metal.md's macOS Apple7-9/Mac2 vs iOS Apple2-6 family note and the "no stock Graphite view control" statement. Mermaid validated with mermaid-cli; docfx build succeeds with 0 errors. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bdcc8d8b-500e-41ae-bb71-5e336ac92b1d
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a single Drawing destinations guide hierarchy that helps readers choose where an
SKCanvascomes from:SKSurface;This organization keeps offscreen surfaces, document output, and onscreen controls together as drawing destinations while preserving their different ownership and finalization models. The files remain grouped under
guides/surfaces/, with backend and platform pages that let readers go directly to the API they use:The 25 conceptual articles cover setup, ownership, submission, readback, finalization, platform limitations, and result verification. The view guidance also calls out non-obvious implementation details such as Graphite being offscreen-only, .NET MAUI using Metal behind
SKGLViewon Mac Catalyst, the raster-backed Tizen NUISKGLSurfaceView, and Uno's target-specific GPU support.Related issues
Related to #3968 and #4555.
Required skia PR
None.
Areas affected
binding/)externals/skia/src/c,include/c)Changes
None — conceptual documentation only; no public API or observable runtime behavior changes.
Testing
dotnet docfx documentation/docfx/docfx.json: 0 errors. The 36 warnings are existing release-page link warnings and do not reference changed guides.Checklist
Changesabove lists all public API and behavioral changes (or "None.")mono/skiaPR linked above and bindings regenerated — N/A; no native change.