Implement Matrix.CreateRotation with center point.

[rabbitism]

What does the pull request do?

Add new overload for Matrix.CreateRotation(double radians, Point center).
This is a valid and commonly used transformation in SVG see: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform#rotate
Also part of Systme.Numeric api.

Notice: whether to use Point or Vector is not finalized yet, pending on team descision.

What is the current behavior?

What is the updated/expected behavior with this PR?

How was the solution implemented (if it's not obvious)?

Checklist

• Added unit tests (if possible)?
• Added XML documentation to any related classes?
• Consider submitting a PR to https://github.com/AvaloniaUI/avalonia-docs with user documentation

Breaking changes

Obsoletions / Deprecations

Fixed issues

Closes #17307

[avaloniaui-bot]

You can test this PR using the following package version. 11.3.999-cibuild0053637-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

[robloo]

Please double check Radians vs. Degrees for API uniformity. Higher levels usually use degrees. It is very important we keep APIs consistent in terms of units.

[rabbitism]

I think the other rotation api uses radians.

[robloo]

@rabbitism All our shape API uses degrees. API in WPF almost always uses degrees.

https://learn.microsoft.com/en-us/dotnet/api/system.windows.media.rotatetransform.-ctor?view=windowsdesktop-9.0#system-windows-media-rotatetransform-ctor(system-double-system-double-system-double)

I don't know the Matrix API off the top of my head but we need to 1) Use degrees or 2) Use radians if that is what WPF does in this case.

This is something that has to be very carefully reviewed in API because both degree and radian are double. So it's a very dangerous silently breaking changing if ever it needs to be fixed.

[rabbitism]

@rabbitism All our shape API uses degrees. API in WPF almost always uses degrees.

https://learn.microsoft.com/en-us/dotnet/api/system.windows.media.rotatetransform.-ctor?view=windowsdesktop-9.0#system-windows-media-rotatetransform-ctor(system-double-system-double-system-double)

I don't know the Matrix API off the top of my head but we need to 1) Use degrees or 2) Use radians if that is what WPF does in this case.

This is something that has to be very carefully reviewed in API because both degree and radian are double. So it's a very dangerous silently breaking changing if ever it needs to be fixed.

I don't see any reason this API should use a different unit with the other.

Avalonia/src/Avalonia.Base/Matrix.cs

Lines 210 to 215 in f4633e2

	public static Matrix CreateRotation(double radians)
	{
	double cos = Math.Cos(radians);
	double sin = Math.Sin(radians);
	return new Matrix(cos, sin, -sin, cos, 0, 0);
	}

[robloo]

Well, seems we are already different from WPF...

https://learn.microsoft.com/en-us/dotnet/api/system.windows.media.matrix.rotateat?view=windowsdesktop-9.0#system-windows-media-matrix-rotateat(system-double-system-double-system-double)

I wonder if this was intentional or an oversight. I guess the one benefit is radians makes the math easier. Still, we really shouldn't have both degrees and radians in the APIs. The convention has always been degrees as well. If we wanted to switch to radians it should have been done everywhere.

But it is worse to have different units in the same class. So now we are stuck.

API review is extremely important.

There should NOT be a public degrees to radians conversion method on this class either.

[maxkatz6]

Matrix APIs in .NET BCL and SkiaSharp use radians
https://learn.microsoft.com/en-us/dotnet/api/system.numerics.matrix4x4.createrotationx?view=net-9.0#system-numerics-matrix4x4-createrotationx(system-single)

[maxkatz6]

There should NOT be a public degrees to radians conversion method on this class either.

This method is 10 years old... Shouldn't be there indeed.

[robloo]

@maxkatz6 OK, if they already use radians in the BCL I won't argue. My point was WPF seems to be different using degrees. Perhaps Microsoft changed their thinking for .NET after WPF was initially released.

I guess the distinction is:

Low-level functionality uses Radians for mathematical reasons.

High-level API (XAML/Shapes) uses degrees for compatibility and simplicity (degrees are easier for people to visualize).