Provide "Left Handed" overloads of matrix create functions

[tannergooding]

Background and Motivation

Matrix4x4 currently exposes several Create functions that operate exclusively in the "right-handed" domain. In practice, various graphics opt to use a "left-handed" domain instead and similary numerics libraries (such as DirectX Math or GLM) typically provide overloads for both domains.

Additionally, we have had several issues where users have been confused about which domain the Matrix4x4 functions default to and have had prior requests for providing such functionality.

Proposed API

namespace System.Numerics;

public partial struct Matrix4x4
{
    public static Matrix4x4 CreateLookAtLH(Vector3 cameraPosition, Vector3 cameraTarget, Vector3 cameraUpVector);

    public static Matrix4x4 CreateLookTo(Vector3 cameraPosition, Vector3 cameraDirection, Vector3 cameraUpVector);
    public static Matrix4x4 CreateLookToLH(Vector3 cameraPosition, Vector3 cameraDirection, Vector3 cameraUpVector);

    public static Matrix4x4 CreateOrthographicLH(float width, float height, float zNearPlane, float zFarPlane);
    public static Matrix4x4 CreateOrthographicOffCenterLH(float left, float right, float bottom, float top, float zNearPlane, float zFarPlane);

    public static Matrix4x4 CreatePerspectiveLH(float width, float height, float nearPlaneDistance, float farPlaneDistance);
    public static Matrix4x4 CreatePerspectiveFieldOfViewLH(float fieldOfView, float aspectRatio, float nearPlaneDistance, float farPlaneDistance);
    public static Matrix4x4 CreatePerspectiveOffCenterLH(float left, float right, float bottom, float top, float nearPlaneDistance, float farPlaneDistance);
    
    public static Matrix4x4 CreateViewportLH(float x, float y, float width, float height, float minDepth, float maxDepth)
}

Additional Considerations

The documentation should be clearly updated to indicate the non-suffixed functions are "right-handed" and the new functions are "left-handed".

It may be desirable to spell out "LeftHanded", however the common case is abbreviating and within the context of Matrix4x4 it should be self-explanatory.

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[ghost]

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

Issue Details

---

null

Author:	tannergooding
Assignees:	-
Labels:	api-suggestion, area-System.Numerics
Milestone:	-

[bartonjs]

Video

We expanded "LH" to "LeftHanded", otherwise looks good as proposed.

namespace System.Numerics;

public partial struct Matrix4x4
{
    public static Matrix4x4 CreateLookAtLeftHanded(Vector3 cameraPosition, Vector3 cameraTarget, Vector3 cameraUpVector);

    public static Matrix4x4 CreateLookToLeftHanded(Vector3 cameraPosition, Vector3 cameraDirection, Vector3 cameraUpVector);

    public static Matrix4x4 CreateOrthographicLeftHanded(float width, float height, float zNearPlane, float zFarPlane);
    public static Matrix4x4 CreateOrthographicOffCenterLeftHanded(float left, float right, float bottom, float top, float zNearPlane, float zFarPlane);

    public static Matrix4x4 CreatePerspectiveLeftHanded(float width, float height, float nearPlaneDistance, float farPlaneDistance);
    public static Matrix4x4 CreatePerspectiveFieldOfViewLeftHanded(float fieldOfView, float aspectRatio, float nearPlaneDistance, float farPlaneDistance);
    public static Matrix4x4 CreatePerspectiveOffCenterLeftHanded(float left, float right, float bottom, float top, float nearPlaneDistance, float farPlaneDistance);
    
    public static Matrix4x4 CreateViewportLeftHanded(float x, float y, float width, float height, float minDepth, float maxDepth)
}

[DaZombieKiller]

Should this also include the rotation APIs?

namespace System.Numerics;

public partial struct Matrix4x4
{
+   public static Matrix4x4 CreateFromQuaternionLeftHanded(Quaternion quaternion);
+   public static Matrix4x4 CreateRotationXLeftHanded(float radians);
+   public static Matrix4x4 CreateRotationXLeftHanded(float radians, Vector3 centerPoint);
+   public static Matrix4x4 CreateRotationYLeftHanded(float radians);
+   public static Matrix4x4 CreateRotationYLeftHanded(float radians, Vector3 centerPoint);
+   public static Matrix4x4 CreateRotationZLeftHanded(float radians);
+   public static Matrix4x4 CreateRotationZLeftHanded(float radians, Vector3 centerPoint);
+   public static Matrix4x4 CreateFromYawPitchRollLeftHanded(float yaw, float pitch, float roll);
}

[tannergooding]

@DaZombieKiller You'd need to open a separate API proposal and cover how the logic would differ for these between LH and RH.

Notably neither DirectX Math nor GLM provide such functions, even with all the other LH vs RH APIs they do provide.