System.Numerics or Stride.Math

[Doprez]

I wanted to open a tracked discussion on using System.Numerics instead of Strides created types.

• I am curious if there were any reasons before as to not using numerics in the first place and if so what were they?
• what would need to change if we did a full conversion in our libraries
• what would/could break in user projects right now
• will there be a major performance impact and is there an easy way to quickly benchmark before doing this work?
• other

As far as I understand it the only breaking change would be that users would need to add an extra using statement to their existing projects for .NETs math libraries.

[Doprez]

Adding comments from Eideren that went over this already but they are getting lost in the discord.

So, we can either:
Deprecate our math type, replace their usage in source outside of Stride.Core.Mathematics with dotnet's System.Numerics' type. Add implicit conversion from our types to System.Numerics to reduce breaking changes. Create a new static type Stride.Mathematics for operations that are not covered by dotnet's numerics API.
Ref parameters, overriden virtual methods, compound assignment, etc. will still create some breaking changes
System.Numerics doesn't have equivalent to a lot of our types, like BoundingBox, ..Frustum, Ray, ... nor explicit types for other vector data types like half2-3, int2-3 ... This is going to be a bit confusing as now users would have to fetch vectors from dotnet's namespace and other datatypes from our math namespace.
We don't have full control over the type, meaning that implementing more operators and conversions is impossible for the former and fairly hard for the latter as long as dotnet doesn't support extensions for those function types.
Same as above but instead of relying on dotnet's we create a new one which wraps around dotnet's type internally.
Breaking changes isn't any better
No confusing namespace
We keep control over the whole type
More work on our part to create this one, cover the numerics api and keep up to date with changes dotnet might introduce
Keep our type, use dotnet's accelerated operations under the hood, break ref params anyway
Breaking changes are limited to ref params.
Larger breaking changes like below are harder to justify.
 
In #1 & #2 I think it would be a good idea to also adopt the way dotnet's System.Math is designed; Math.Round has overloads for int, float, double etc. under the same static type, instead of having Vector3.Round, Vector4.Round, etc. Also less confusing for operations that take different data types like RotationQuaternion(Quaternion rotation, out Matrix result) - should that be under Matrix or Quaternion ... and finally merging all of that with the not very well known MathUtil to help users discover helpers for angle conversions and such.

[Doprez]

Another comment from Ethereal to keep in mind

Regarding the math types, I think for Stride 4.2 we shouldn't do any major rewrite yet.
The .NET team has created many useful types and functions, but support for generic Vector2<T> where T can be float, double, Half, etc., is postponed to .NET 9 I believe. Those would be the more interesting targets to port the Stride math types to.
The Silk.NET team is also having a discussion right now about how to enhance their math library, with many interesting comments from Tanner Gooding. You can check [here](https://github.com/dotnet/Silk.NET/pull/1760#discussion_r1375156663).

referenced link.

[Doprez]

final thing I found that we should keep in mind is Silks ongoing work for 3.0. They are apparently dealing with this exact issue.
dotnet/Silk.NET#1727

[Perksey]

Yes it’s always been our intention for Silk.NET.Maths to be a “gap filler” and to always prefer System.Numerics where possible. By the sounds of this issue, Silk.NET.Maths as the same intentions as that of Stride.Mathematics discussed here.

[Kryptos-FR]

I am curious if there were any reasons before as to not using numerics in the first place and if so what were they?

Yes there was a big one. Those types just didn't exist when the engine was first being worked on. And after they were introduced they had at first slightly worse performance.

[ericwj]

With regard to what Eideren said, I think it would be beneficial in many places to replace some implementations in Stride.Math (method bodies) delegating as much as possible to usually well-optimized implementations in System.Numerics and review Stride.Math for opportunities to use intrinsics. For example converting RGBA to BGRA can be done in 2 instructions (BSWAP, ROL) or less (vectorized) and in some places what I remember it is done (or used to be done when I was working on a PR) in some 54.

One thing I recommend is marking the overloads with ref parameters obsolete. When I looked at it, it turns out they are often much slower and knowing how parameter passing works it is mostly pointless to pass a writable ref anyway. For parameters that fit a register or that might be broken into pieces and passed in more than one register, it might force them to stay on the stack.

By marking the obsoletions with some specific diagnostic ID, subsequently suppressing that warning in each project, people can go about their business without getting swamped with warnings while some issue tracks removing the suppression on a per-project basis, starting with the most specific projects and working backwards to the core Stride projects.

[Doprez]

Another discussion found thanks to Eideren that will need to be considered for matrices #291

[Doprez]

Another natural occurrence of system.Numerics ideas #2238 (comment)

I would wonder if FieldOffset could also be used as a conversion between the Stride Matrix and System.Numerics.Matrix4x4 to map between row major and column major mappings?

[JeroMiya]

For what it's worth, I'd like to provide some feedback, as this is something I'd really like to see implemented (using System.Numerics where possible). I feel it would be an overall benefit to the project in the long term. Of course, I'm not a game engine programmer, and I'm aware that there are limitations to System.Numerics, but overall I think the benefits outweigh the drawbacks.

Backwards compatibility:
Although I may currently be coming from the perspective of a new developer without a lot of legacy code to maintain, I feel confident that if I did, I would still consider backward compatibility a non-issue. The changes would likely be superficial.

The issue of not controlling the types, vs the custom types in the engine:
I would prefer using the System.Numerics types as-is, vs custom types that internally wrap the types. Being able to use those types in userland code is one of the main benefits to migrating to System.Numerics, so it would be a shame to lose that. Where necessary, my preference would be method overloads (this seems to mostly be the strategy of Silk.Net as far as I can tell), static utility methods, and if wrapping is absolutely necessary - then maybe hiding the wrapper classes as internal to the engine could be done. One benefit of method overloads vs wrapper classes is that we could, for example, support new types being added to System.Numerics while either continuing to support the old custom types or we could more gracefully deprecate them over a longer period.

Implicit Conversions:
My preference would be explicit conversions over implicit. Technically, an implicit conversion is valid if the conversion is lossless and one-to-one, but for game development I personally put "conversion has a performance impact" under the threshold moving the needle from implicit to explicit. And again, using method overloads instead of wrapper classes or custom types would make either implicit or explicit conversions less necessary for most code. That being said, I don't feel strongly on this and implicit conversions wouldn't be the worst thing.

Math types that don't currently exist in System.Numerics:
I'm ok with filling in the gaps with custom types where necessary. I think this is the Silk.Net strategy and it makes practical sense. But, for types like Vector3/Vector4/etc... that do have types in System.Numerics, my preference is to use those types directly (not wrapped in a custom type). The "different types from different namespaces" isn't a big issue. For my own projects, I use global using statements so I would only have to add one additional using statement in one file per csproj. Not a huge deal. And of course if System.Numerics adds the other types, we might be able to add method overloads to support them over time without breaking backward compatibility.

Consolidating math utils under one MathUtils static class:
I agree with this suggestion. Especially for new users, typing something like MathUtils. in the code editor and taking a look at the autocomplete list will help them find the static methods they need.

tannergooding's comment on public fields:
Hard agree here - public properties highly preferred over public fields. We're not Unity.