[API Proposal]: Create and convenience APIs for System.Numerics types

[tannergooding]

Background and Motivation

Continuing along the general spirit of #94384 and the iterative efforts to improve the support of the original vector types exposed in 2014, there are a few additional convenience APIs that are missing.

Namely these are APIs that allow developers to interact with the data in a more meaningful way such as getting entire rows out of a matrix as a known accelerated type or creating a vector using a scalar value.

This finishes out the APIs that we're currently using internally for acceleration and should finally give us parity across the types.

API Proposal

namespace System.Numerics
{
    public partial struct Matrix3x2
    {
        public static Matrix3x2 Create(float value);
        public static Matrix3x2 Create(Vector2 x, Vector2 y, Vector2 z);

        public static Vector2 X { readonly get; set; }
        public static Vector2 Y { readonly get; set; }
        public static Vector2 Z { readonly get; set; }

        public Vector2 this[int row] { readonly get; set; }

        public Vector2 GetRow(int index);
        public Matrix3x2 WithRow(int index, Vector2 value);

        public float GetElement(int row, int column);
        public Matrix3x2 WithElement(int row, int column, float value);
    }

    public partial struct Matrix4x4
    {
        public static Matrix4x4 Create(float value);
        public static Matrix4x4 Create(Vector4 x, Vector4 y, Vector4 z, Vector4 w);

        public static Vector4 X { readonly get; set; }
        public static Vector4 Y { readonly get; set; }
        public static Vector4 Z { readonly get; set; }
        public static Vector4 W { readonly get; set; }

        public Vector4 this[int row] { readonly get; set; }

        public Vector4 GetRow(int index);
        public Matrix4x4 WithRow(int index, Vector4 value);

        public float GetElement(int row, int column);
        public Matrix4x4 WithElement(int row, int column, float value);
    }

    public partial struct Plane
    {
        public static Plane Create(Vector3 normal, float d);
        public static Plane Create(float x, float y, float z, float d);
    }

    public partial struct Quaternion
    {
        public static Quaternion Create(Vector3 vectorPart, float scalarPart);
        public static Quaternion Create(float x, float y, float z, float w);
    }

    public static partial class Vector
    {
        public static Vector2 AsVector2(Vector3 value);

        public static unsafe Vector<T> CreateScalar<T>(T value);
        public static Vector<T> CreateScalarUnsafe<T>(T value);
    }

    public partial struct Vector2
    {
        public static Vector2 CreateScalar(float x);
        public static Vector2 CreateScalarUnsafe(float x)
    }

    public partial struct Vector3
    {
        public static Vector3 CreateScalar(float x);
        public static Vector3 CreateScalarUnsafe(float x);
    }

    public partial struct Vector4
    {
        public static Vector4 CreateScalar(float x);
        public static Vector4 CreateScalarUnsafe(float x);
    }
}

namespace System.Runtime.Intrinsics
{
    public static partial class Vector128
    {
        public static Plane AsPlane(this Vector128<float> value);
        public static Quaternion AsQuaternion(this Vector128<float> value);

        public static Vector128<float> AsVector128(this Plane value);
        public static Vector128<float> AsVector128(this Quaternion value);
    }
}

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-numerics
See info in area-owners.md if you want to be subscribed.

[bartonjs]

Video

• We decided to be opinionated and remove the setters.
• GetRow(int index) => GetRow(int row)

namespace System.Numerics
{
    public partial struct Matrix3x2
    {
        public static Matrix3x2 Create(float value);
        public static Matrix3x2 Create(Vector2 x, Vector2 y, Vector2 z);

        public Vector2 X { readonly get; }
        public Vector2 Y { readonly get; }
        public Vector2 Z { readonly get; }

        public Vector2 this[int row] { readonly get; }

        public readonly Vector2 GetRow(int row);
        public readonly Matrix3x2 WithRow(int row, Vector2 value);

        public readonly float GetElement(int row, int column);
        public readonly Matrix3x2 WithElement(int row, int column, float value);
    }

    public partial struct Matrix4x4
    {
        public static Matrix4x4 Create(float value);
        public static Matrix4x4 Create(Vector4 x, Vector4 y, Vector4 z, Vector4 w);

        public Vector4 X { readonly get; }
        public Vector4 Y { readonly get; }
        public Vector4 Z { readonly get; }
        public Vector4 W { readonly get; }

        public Vector4 this[int row] { readonly get; }

        public readonly Vector4 GetRow(int row);
        public readonly Matrix4x4 WithRow(int row, Vector4 value);

        public readonly float GetElement(int row, int column);
        public readonly Matrix4x4 WithElement(int row, int column, float value);
    }

    public partial struct Plane
    {
        public static Plane Create(Vector3 normal, float d);
        public static Plane Create(float x, float y, float z, float d);
    }

    public partial struct Quaternion
    {
        public static Quaternion Create(Vector3 vectorPart, float scalarPart);
        public static Quaternion Create(float x, float y, float z, float w);
    }

    public static partial class Vector
    {
        public static Vector2 AsVector2(Vector3 value);

        public static unsafe Vector<T> CreateScalar<T>(T value);
        public static Vector<T> CreateScalarUnsafe<T>(T value);
    }

    public partial struct Vector2
    {
        public static Vector2 CreateScalar(float x);
        public static Vector2 CreateScalarUnsafe(float x)
    }

    public partial struct Vector3
    {
        public static Vector3 CreateScalar(float x);
        public static Vector3 CreateScalarUnsafe(float x);
    }

    public partial struct Vector4
    {
        public static Vector4 CreateScalar(float x);
        public static Vector4 CreateScalarUnsafe(float x);
    }
}

namespace System.Runtime.Intrinsics
{
    public static partial class Vector128
    {
        public static Plane AsPlane(this Vector128<float> value);
        public static Quaternion AsQuaternion(this Vector128<float> value);

        public static Vector128<float> AsVector128(this Plane value);
        public static Vector128<float> AsVector128(this Quaternion value);
    }
}