Improve 3.x compatibility with 2.x (or vice versa)

[mattleibow]

Description

Not sure we can do everything we want and have a perfect world, but we can make things a bit better.

There is a summary and diff here that you can read to learn more about the changes that we have: https://github.com/mono/SkiaSharp/blob/main/changelogs/SkiaSharp/3.0.0/SkiaSharp.humanreadable.md

Using this list and some community libraries, we have found ways to improve compatibility without much additional effort for you or the maintenance in general.

Implementation

This work is 2 parts:

• Add "hidden" APIs in 3.x that allow for upgrades where API usage is small or restricted to common things. Typically, the APIs that are used in most apps all have overloads, alternatives or other mechanisms that are better.
  • Add and remove the compatibility APIs #2789
• Add new APIs in 2.x so that people can use the new APIs today, and then they can upgrade to 3.x without any changes as they are using it already.
  • [release/2.x] Add some new overloads for better compat #2810

Changes

Here is a list of PRs that may or may not make it in but cover this area:

• [release/2.x] Add some new overloads for better compat #2810
• [release/2.x] Backport some new APIs from 3.0 to 2.x allowing smoother migration. #2756
• Add and remove the compatibility APIs #2789
• Clean up SKTextBlobBuilder and SKRunBuffer APIs #2775

Tools

I have also been working to make a tool that can be used to detect any cases where a breaking will occur, without having to update and hope everything is fine. In some cases, different overloads will resolve, hiding a potential break.

Tool: https://www.nuget.org/packages/api-tools
Docs: https://github.com/mattleibow/Mono.ApiTools.NuGetDiff/blob/main/docs/api-tools.md#compat-command

dotnet api-tools compat Svg.Skia/Svg.Skia.dll SkiaSharp/v3/SkiaSharp.dll

<?xml version="1.0" encoding="utf-8"?>
<assemblies>
  <assembly>
    <types>
      <type fullname="SkiaSharp.SKImageFilter/CropRect" />
      <type fullname="SkiaSharp.SKCropRectFlags" />
    </types>
    <members>
      <member fullname="System.Void SkiaSharp.SKImageFilter/CropRect::.ctor(SkiaSharp.SKRect,SkiaSharp.SKCropRectFlags)" />
      <member fullname="SkiaSharp.SKImageFilter SkiaSharp.SKImageFilter::CreateMerge(SkiaSharp.SKImageFilter[],SkiaSharp.SKImageFilter/CropRect)" />
      <member fullname="SkiaSharp.SKImageFilter SkiaSharp.SKImageFilter::CreatePaint(SkiaSharp.SKPaint,SkiaSharp.SKImageFilter/CropRect)" />
      <!-- several other items -->
      <member fullname="System.Void SkiaSharp.SKPath::Transform(SkiaSharp.SKMatrix)" />
      <member fullname="System.Void SkiaSharp.SKCanvas::SetMatrix(SkiaSharp.SKMatrix)" />
    </members>
  </assembly>
</assemblies>

For this result, we have done some things:

• We added overloads to the SKImageFilter type that allow for creating of filters without SKImageFilter.CropRect and instead use SKRect.
• We added a hidden API SKCanvas.SetMatrix that matches 2.x, but we cannot add it to the public API as it is ambiguous to VB and not what we want to use going forward.

[follesoe]

Fantastic effort on easing migration and adoption of v3!