Skip to content

Math proposal update #2598

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
otac0n wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Math proposal update #2598

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
911e5ec
Updated Generic Math proposal.
otac0n Jul 1, 2026
64cd756
Smal adjustment.
otac0n Jul 1, 2026
7956352
Added extra utility methods and corrected matrix type.
otac0n Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 28 additions & 19 deletions documentation/proposals/Proposal - Generic Math.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,15 +60,14 @@ For each vector struct, the following requirements **must** fulfill the followin
- A deconstruct method for detupling
- An implicit conversion from a value tuple of the same size.
- Define static CreateChecked, CreateSaturating, and CreateTruncating which converts other vector types to this type
- Try variants of these methods should also be defined which out the resulting vector and return a bool representing success or failure of the operation.

@Perksey Perksey Aug 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://learn.microsoft.com/en-us/dotnet/api/system.numerics.inumberbase-1.tryconvertfromchecked?view=net-10.0

@Exanite Exanite Aug 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got clarification on this during the coffee and code on Aug 15, 2026. This was because TryCreateFromSaturating and similar were thought to be not exposed, but if I'm understanding the problem right, these can actually be called by using a generic method.

Image

For example, I used this code to call TryConvertFromChecked:

private static bool TryConvertFromCheckedFromDouble<TTo, TFrom>(double value, [MaybeNullWhen(false)] out TTo result)
    where TTo : INumberBase<TTo>
    where TFrom : INumberBase<double>
{
    if (typeof(TTo) == typeof(double))
    {
        result = (TTo)(object)value;
        return true;
    }

    return TFrom.TryConvertToChecked(value, out result);
}

- Define Transform static methods which take a Matrix of higher dimensionality assuming 1 in for the final missing component and 0 for the rest (Vector 2 can use `Matrix2Xn`, `Matrix3Xn`, and `Matrix4Xn`) and return a vector containing the output (type should match the outer type e.g. `Vector2D.Transform(Matrix4X4)` returns `Vector2D`)
- Define `VectorND<T> * MatrixNXM` operators where N is the same for both Vector and Matrix, but M is any number
- These operators should function like Transform, but without needed assumptions
- Define TransformNormal static methods which take a Matrix of higher dimensionality assuming 0 in for all missing components (Vector 2 can use `Matrix2Xn`, `Matrix3Xn`, and `Matrix4Xn`) and return a vector containing the output (type should match the outer type e.g. `Vector2D.Transform(Matrix4X4)` returns `Vector2D`)
- For types implementing `IBinaryNumber<T>`
- `BitwiseAnd`, `BitwiseOr`, and `BitwiseXor` static methods defined between two vectors which returns a vector which has had these operators applied on a component-wise basis.
- `BitwiseAnd`, `BitwiseOr`, and `BitwiseXor` static methods operators defined between a vectors and a scalar value that matches the generic type which returns a vector which has had these operators applied on a component-wise basis with the scalar.
- `BitwiseNot` static method defined which negates the bits of the vector components. (BitwiseComplement?)
- `BitwiseAnd`, `BitwiseOr`, and `ExclusiveOr` static methods defined between two vectors which returns a vector which has had these operators applied on a component-wise basis.
- `BitwiseAnd`, `BitwiseOr`, and `ExclusiveOr` static methods operators defined between a vectors and a scalar value that matches the generic type which returns a vector which has had these operators applied on a component-wise basis with the scalar.
- `OnesComplement` static method defined which negates the bits of the vector components. (BitwiseComplement?)
- A Normalize extension method which divides all components by the length of the vector, when `T` implements `IRootFunctions<T>`
- A Reflect static method which takes a normal vector and reflects the vector over the normal
- The following static Vector properties which have the given value for all components
Expand Down Expand Up @@ -245,6 +244,9 @@ Matrix structs **must** fulfill the following requirements:
- Transform
- from a Quaternion
- CreateFromYawPitchRoll
- For Matrix4X4
- CreateFromAffine (For 3x2 and 3x3 matrices)
- CreateFromHomogenous
- For Matrix4X3 and Matrix4X4 include the following static functions
- CreateConstrainedBillboardLH
- CreateConstrainedBillboardRH
Expand Down Expand Up @@ -283,18 +285,13 @@ A Quaternion struct **must** be defined and match the following requirements:
- Define `+`, `-`, `*`, and `/` between two Quaternions
- Define `*` with `T` multiplying each component by the scalar value returning a new quaternion
- Define unary `~`
- A Dot function which takes another Quaternion and returns its the dotproduct between them
- A static implementation of this function **must** be available
- A static Dot function which takes another Quaternion and returns its the dotproduct between them
- A LengthSquared property which returns the dot product of the quaternion with itself
- A Length property which returns the Square Root of LengthSquared
- An Invert function inverts the Quaternion
- a static Inverse function **must** be available but it returns the inverse rather than affecting the original
- A Normalize function which normalizes the Quaternion
- A static implemenation of this function must be available but returns the normalized Quaternion rather than affecting the original
- A Concatenate function which takes another Quaternion and concatenates it with this quaternion
- A static implementation of this function **must** be available but it returns a new Quaternion rather than affecting the originals
- A Conjugate function which returns the conjugate of this quaternion
- A static implementation of this function **must** be available
- A static Invert function which inverts the Quaternion
- A static Normalize function which normalizes the Quaternion
- A static Concatenate function which takes two Quaternions and concatenates them
- A static Conjugate function which returns the conjugate of a quaternion
- A static CreateFromAxisAngle function which takes in a `Vector3D<T>` and an angle and returns a Quaternion representing that rotation
- A static CreateFromRotationMatrix function which takes either a Matrix3X3 or Matrix4X4 and returns a Quaternion representing that rotation
- A static CreateFromYawPitchRoll which takes either each components separately or in a `Vector3D<T>` and outputs a Quaternion representing that rotation
Expand All @@ -306,25 +303,27 @@ A Quaternion struct **must** be defined and match the following requirements:
# Geometric Types

The following Geometric Types are defined:
- Box
- Box2
- Box3
- Circle
- Plane
- Ray2
- Ray3
- Rectangle
- Rect2
- Rect3
Comment on lines +306 to +313

@Exanite Exanite Jul 1, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Box2
- Box3
- Circle
- Plane
- Ray2
- Ray3
- Rectangle
- Rect2
- Rect3
- Box2D
- Box3D
- Circle
- Plane
- Ray2D
- Ray3D
- Rect2D
- Rect3D

- Sphere

Each type **must** include the following:
- Intersect functions with both another instance of the type and a point
- GetDistanceToNearest(Point,Edge,etc) functions **must** be available for a given point
- Get(Signed)Distance(ToEdge,ToInterior) functions **must** be available for a given point when applicable
- For all but the rays and planes, GetInflated function that takes a point and returns the scaled object that is closest to the original and contains the given point
- Include Scale and Translation transformation functions
- For Box and Rectangle the following Vector properties **must** be defined
- For Box and Rectangle the following Vector properties **must** be defined via interface
- Min
- Max
- Center
- Size
- For Planes and Rays, Normalize functions
- For Planes and Rays, static Normalize functions
- For Planes include the following static functions
- CreateFromVerticies
- CreateFromPointNormal
Expand Down Expand Up @@ -375,3 +374,13 @@ Each type **must** include the following:
- We will remove instance extension methods and add them back later if we still want them.
- We visited Length/LengthSquared as properties instead of .NET
- Approved notwithstanding instance extension method and Atan2(Memberwise, Scalar) removal

## 19/04/2026

[Video](https://www.youtube.com/live/CUF52it-fSg?t=2160s)

- Decided we wouldn't have the extra matrix constructors.
- Deciede to keep one set of overloads: CreateFromAffineXZ

@Exanite Exanite Jul 1, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Deciede to keep one set of overloads: CreateFromAffineXZ
- Decided to keep one set of overloads: CreateFromAffineXZ

- Standardize on IBinaryNumber naming.
- Decided to use Box2D, Box3D, Rect2D, Rect3D and an interface for extents.
- Reconfirmed the naming of `VectorND` and `MatrixNXM`.