Skip to content

Instantly share code, notes, and snippets.

@skarllot

skarllot/guide.md

Created July 4, 2026 22:05
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save skarllot/9b736fff064e0f5b6cba9df67bd385b5 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save skarllot/9b736fff064e0f5b6cba9df67bd385b5 to your computer and use it in GitHub Desktop.
Download ZIP
SkiaSharp v4 Migration Instructions
Raw
guide.md

SkiaSharp v4 Migration Instructions

Prepared: July 1, 2026

This guide summarizes the practical migration work for moving a project from SkiaSharp 3.x to the SkiaSharp 4.x line. It is based on the official SkiaSharp release notes, API diff, GitHub release notes, and related pull request notes.

Version Scope

  • Stable target: SkiaSharp 4.148.0, the first stable v4 release.
  • Preview rollup: SkiaSharp 4.147.0 was preview-only and rolled into 4.148.0.
  • Newer preview/RC note: SkiaSharp 4.150.0 was preview/RC as of July 1, 2026 and includes one additional breaking change: removal of deprecated .NET Interactive / Polyglot Notebooks support.

Recommended posture: upgrade first to 4.148.0 unless you explicitly need a 4.150.0 preview capability.

Migration Checklist

  1. Inventory all SkiaSharp packages in the solution:

    • SkiaSharp
    • SkiaSharp.NativeAssets.*
    • SkiaSharp.Views.*
    • SkiaSharp.HarfBuzz
    • Any platform-specific SkiaSharp packages

  2. Choose the target line:

    • Use 4.148.0 for stable v4.
    • Use 4.150.0 preview/RC only if preview risk is acceptable.

  3. Upgrade related SkiaSharp packages together so managed assemblies and native assets stay aligned.

  4. Build the solution and treat compiler errors from obsolete APIs as the migration work queue.

  5. Replace old SKPaint text/font APIs with SKFont.

  6. Replace SKFilterQuality usage with SKSamplingOptions overloads.

  7. Move obsolete path construction/output APIs to SKPathBuilder where required.

  8. Check platform-specific risk:

    • WebAssembly workloads using pre-.NET 8 Emscripten native builds need attention.
    • Projects using SkiaSharp in Polyglot Notebooks need attention if testing 4.150.0.

  9. Run rendering regression tests before release:

    • Image snapshots
    • Text rendering and font fallback
    • Scaling/filtering output
    • PDF/export flows
    • Platform-specific views

Breaking Changes and Required Actions

Area What Breaks Migration Action Source
Pre-v4 obsolete APIs Legacy v3-era APIs that previously compiled with warnings can now fail compilation or be absent from the reference assembly. Treat compiler errors as the migration queue. Replace each obsolete member with the API named in its obsolete message or the API diff. SkiaSharp 4.148.0 release notes
SKPaint text and font state Old text/font members on SKPaint, paint-only DrawText / DrawTextOnPath overloads, and related members were promoted to hard errors. Create and pass SKFont explicitly. Pass text alignment explicitly where required. PR #4068
Filtering quality Several SKFilterQuality-consuming overloads across bitmap/image/shader/pixmap paths are no longer the preferred public surface. Use SKSamplingOptions overloads and choose sampling behavior intentionally. 4.148.0 API diff; PR #4068
Path mutation and path outputs Many SKPath mutation methods and some output parameters are obsolete in favor of SKPathBuilder. Construct paths with SKPathBuilder, then call Snapshot() or Detach() when an SKPath is needed. 4.148.0 API diff
Vulkan YCbCr structures GRVkImageInfo.YcbcrConversionInfo now uses GRVkYcbcrConversionInfo; equality members were removed from the older GrVkYcbcrConversionInfo surface. Update type names, property usage, and equality/hash-code assumptions around these structs. 4.148.0 API diff
WebAssembly native assets Pre-.NET 8 Emscripten native builds were dropped. Move WASM workloads to .NET 8+ compatible Emscripten/native asset paths before upgrading. 4.147.0 / 4.148.0 release notes
.NET Interactive support Deprecated Polyglot Notebooks support was removed in the 4.150.0 preview/RC line. Use an alternate display/export approach, or stay on 4.148.0 until migrated. 4.150.0 release notes

Step-by-Step Migration Procedure

1. Create a Controlled Upgrade Branch

Before updating packages, capture a baseline:

  • Current SkiaSharp package versions
  • Current target frameworks and platforms
  • Current rendering snapshots or golden images
  • Current build/test status
  • Known rendering differences that already exist

This prevents v4 migration issues from being mixed with unrelated regressions.

2. Upgrade Packages Together

Update SkiaSharp packages as a group. Avoid mixing 3.x managed packages with 4.x native assets or companion packages.

Recommended stable target:

<PackageReference Include="SkiaSharp" Version="4.148.0" />

Apply the same v4 line to related packages such as native assets, views packages, and HarfBuzz integration packages.

3. Resolve Compile Errors First

Most v4 migration work is intentionally surfaced by compile-time failures from obsolete API promotion.

Do not tune rendering behavior while the project still fails to compile. First, replace obsolete API usage until the build is clean.

4. Migrate Text Rendering to SKFont

In v3-era code, some font and text state may live on SKPaint. In v4, treat these responsibilities separately:

  • SKPaint: color, stroke, fill, antialiasing, shader, blend mode, drawing style
  • SKFont: typeface, text size, glyphs, metrics, font-specific text behavior

Common refactoring patterns:

Old Pattern v4 Direction
paint.TextSize = 16 var font = new SKFont(typeface, 16);
paint.Typeface = typeface Pass typeface to SKFont or create/clone a font with the desired typeface.
paint.FakeBoldText = true font.Embolden = true; prefer a real bold SKTypeface when available.
paint.StrokeWidth = 2 Keep this on SKPaint; stroke width is drawing style, not font state.
canvas.DrawText(text, x, y, paint) Use an overload that accepts SKFont and, where required, SKTextAlign.
typeface.CountGlyphs(...) or typeface.ContainsGlyphs(...) Use SKFont directly for glyph-related checks.

Example direction:

using var paint = new SKPaint
{
    Color = SKColors.Black,
    IsAntialias = true,
    Style = SKPaintStyle.Stroke,
    StrokeWidth = 2
};

using var font = new SKFont(typeface, 16)
{
    Embolden = true
};

canvas.DrawText("Hello", 20, 40, SKTextAlign.Left, font, paint);

Property split rule:

  • Move font/text-shaping state to SKFont: text size, typeface, glyph metrics, and synthetic emboldening via SKFont.Embolden.
  • Keep draw appearance on SKPaint: color, stroke/fill style, StrokeWidth, shaders, blend mode, and antialiasing.

5. Replace SKFilterQuality with SKSamplingOptions

If code used SKFilterQuality or paint.FilterQuality, migrate to overloads that take SKSamplingOptions.

Recommended approach:

  1. Identify each scaled bitmap/image/shader/pixmap draw path.
  2. Decide whether the old behavior should map to nearest, linear, or higher-quality sampling.
  3. Use the overload accepting SKSamplingOptions.
  4. Verify output with golden images, especially for scaled images and thumbnails.

6. Move Path Construction to SKPathBuilder

For code that mutates SKPath directly, migrate toward SKPathBuilder.

General pattern:

using var builder = new SKPathBuilder();

builder.MoveTo(10, 10);
builder.LineTo(100, 10);
builder.LineTo(100, 100);
builder.Close();

using var path = builder.Detach();
canvas.DrawPath(path, paint);

Use Snapshot() if you need a path while keeping the builder available for further edits. Use Detach() when ownership should move to the resulting SKPath.

7. Review Vulkan-Specific Code

If your project uses Vulkan interop, check usages of:

  • GRVkImageInfo
  • GrVkYcbcrConversionInfo
  • GRVkYcbcrConversionInfo
  • Equality comparisons or hash code usage around YCbCr conversion info

The 4.148 API diff shows type and member changes in this area.

8. Review WebAssembly Targets

If your project targets WebAssembly, confirm the runtime/native asset path is compatible with .NET 8+ Emscripten expectations.

SkiaSharp v4 dropped pre-.NET 8 Emscripten native builds, so older WASM build assumptions may no longer hold.

9. Handle .NET Interactive Only If Using 4.150 Preview/RC

The 4.150.0 preview/RC line removes deprecated .NET Interactive / Polyglot Notebooks support.

If your notebooks relied on the SkiaSharp Polyglot Notebooks extension, migrate to an alternate display or export approach before adopting that line.

Verification Plan

Run the smallest test set that proves the migration, then broaden to platform smoke tests.

Required Build Checks

  • Restore packages from a clean cache or CI environment.
  • Build all target frameworks.
  • Build all platform-specific heads.
  • Confirm no remaining references to removed/obsolete APIs.

Rendering Checks

  • Compare golden images for representative draw paths.
  • Test scaled images and thumbnails after SKSamplingOptions migration.
  • Test text rendering, font fallback, glyph coverage, and line layout.
  • Test paths created through SKPathBuilder.
  • Test image export, PDF export, and any server-side rendering jobs.

Platform Checks

Run platform smoke tests for every surface your project ships:

  • MAUI
  • Android
  • iOS/macOS/Mac Catalyst
  • WinUI
  • WPF
  • Windows Forms
  • Tizen
  • WebAssembly
  • Server-side Linux containers

Rollout Recommendations

  1. Merge the package update and compile-error fixes as one focused migration branch.
  2. Keep rendering behavior changes separate where possible.
  3. Review golden-image differences manually before approving them.
  4. Release behind normal application rollout gates.
  5. Watch crash logs for native asset/version mismatch errors after deployment.

Known Uncertainty

SkiaSharp's v4 documentation is currently spread across release notes, GitHub release notes, pull requests, and generated API diffs rather than one consolidated official migration guide. This document consolidates the official notes into an implementation checklist, but project-specific compile errors remain the most reliable source of exact member-level migration work.

Sources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment