[release/2.x] Backport some new APIs from 3.0 to 2.x allowing smoother migration.

[maxkatz6]

Description of Change

With these changes Avalonia should be able to work with both 2.x and 3.0 referenced (need to double check once nightly builds are there).

API Changes

Added:

• SKCanvas.SetMatrix(in SKMatrix);
• SKPath.Transform(in SKMatrix, SKPath destination);
• SKImageFilter methods without SKImageFilter and SKImageFilter.CropRect overloads

Behavioral Changes

None.

Required skia PR

None.

PR Checklist

• [ ] Has tests (if omitted, state reason in description)
• [ ] Rebased on top of main at time of PR
• [ ] Merged related skia PRs
• [x] Changes adhere to coding standard
• [ ] Updated documentation

[maxkatz6]

@mattleibow I went through breaking changes page, and these changes were the low hanging fruits of what can be backported from 3.0 to 2.x. Which is also enough for Avalonia to run both versions.

Initially I also planned to backport some new SKRuntimeEffect methods (which we don't need), but it feels a bit intrusive, as I am not sure what to pass as isOpaque parameter.

I also didn't want to mark obsolete any old APIs that are going to be removed in 3.0.

And I am not sure what to do about SKFilterQuality. Looks like 3.0 still handles SKFilterQuality well everywhere, except SKPaint and DrawImage I guess I could do:

• Backport SKSamplingOptions to 2.88 (only managed part)
• Add SKCanvas.DrawImage method that accepts SKSamplingOptions and maps it back to SKPaint.SKFilterQuality (ABI compatible with 3.0)
• Add SKBitmap.Scale/Resize methods that also accept SKSamplingOptions (Optional, as 3.0 still has working SKFilterQuality methods).

And that would be enough? Without changing 3.0.

[workgroupengineering]

What do you think if instead of adding members to existing classes you added them as extension methods in a class called CompatibilyExtensions?

[maxkatz6]

@workgroupengineering this extension method would have to be added to 3.0 as well. So, it can be binary compatible. Imo, it would add more unwanted API surface to maintain.

[maxkatz6]

@mattleibow update the PR, removed "in" overloads that will break VB. Current PR changes will already help with some migration, though not ideal.

[mattleibow]

Ok. Afk right now but will look tonight or tomorrow. I also think I may have some idea of how to do something quite nice for compat. It is an idea still, but it is coming together nicely.

[mattleibow]

This was idea and my testing of prototypes seemed to work nicely.

https://github.com/mono/SkiaSharp/pull/2789

[maxkatz6]

@mattleibow I like your idea. Closing this PR then.

[maxkatz6]

Although, wait, that kind of API changes of this PR cannot be added to 3.0, as it already has these methods :D

Unless we add back overloads with SKImageFilter and SKImageFilter.CropRect: https://github.com/mono/SkiaSharp/blob/v2.88.7/binding/Binding/SKImageFilter.cs#L101

Imo, for these methods specifically, it would be simpler to get this PR to 2.88 with overloads without optional parameters, keeping common API.

[mattleibow]

Ah yeah. Both. We can backport anything too ugly to do - such as croprect. I'm working on making 2.x shippable again.

[mattleibow]

I did some looking around and I had to also remove the default args from the existing ones. https://github.com/mono/SkiaSharp/pull/2810

For example, if there is this:

public static SKImageFilter CreatePaint(SKPaint paint, SKImageFilter.CropRect cropRect = null)

And we just add:

public static SKImageFilter CreatePaint (SKPaint paint)

People that are using it like this:

SKImageFilter.CreatePaint(mypaint);

Will now get an ambiguous overload as both match. So I removed the = null value so if you are not specifying a crop rect, then you are going to use the new overload. If you are, well you have specified a value.

[mattleibow]

Thanks for this PR. I am going to close this one as I think I got all the APIs from 3.x in my PR and a few more things: https://github.com/mono/SkiaSharp/pull/2810