[API Proposal]: Matrix4x4.CreateViewport

[PavielKraskouski]

Background and motivation

Matrix4x4 currently provides a large number of methods for creating various transformation matrices. The figure below shows a geometric pipeline for transforming vertices from object coordinates to window coordinates. Unfortunately, Matrix4x4 does not provide a method for creating a matrix that transforms vertices from normalized device coordinates to window coordinates.

I propose to add a method for creating a viewport matrix, which is shown in the figure below. width and height specify viewport dimensions, x and y stand for coordinates of the upper left corner of the viewport, zmin and zmax define the minimum and maximum viewport depth.

API Proposal

namespace System.Numerics;

public struct Matrix4x4
{
    public static Matrix4x4 CreateViewport(float x, float y, float width, float height, float minDepth, float maxDepth)
    {
        Matrix4x4 result = Identity;
        
        result.M11 = width * 0.5f;
        result.M22 = -height * 0.5f;
        result.M33 = maxDepth - minDepth;
        result.M41 = x + result.M11;
        result.M42 = y - result.M21;
        result.M43 = minDepth;

        return result;
    }
}

API Usage

Matrix4x4 scaleMatrix = Matrix4x4.CreateScale(model.Scale);
Matrix4x4 rotationMatrix = Matrix4x4.CreateFromYawPitchRoll(model.Yaw, model.Pitch, model.Roll);
Matrix4x4 translationMatrix = Matrix4x4.CreateTranslation(model.Position);
Matrix4x4 modelMatrix = scaleMatrix * rotationMatrix * translationMatrix;
Matrix4x4 viewMatrix = Matrix4x4.CreateLookAt(camera.Position, camera.Target, camera.Up);
Matrix4x4 projectionMatrix = Matrix4x4.CreatePerspectiveFieldOfView(camera.Fov, camera.AspectRatio, camera.Near, camera.Far);
Matrix4x4 modelViewProjectionMatrix = modelMatrix * viewMatrix * projectionMatrix;
Matrix4x4 viewportMatrix = Matrix4x4.CreateViewport(0, 0, bitmap.PixelWidth, bitmap.PixelHeight, 0, 1);

Vector4[] windowVertices = new Vector4[model.Vertices.Length];
for (int i = 0; i < windowVertices.Length; i++)
{
    windowVertices[i] = Vector4.Transform(model.Vertices[i], modelViewProjectionMatrix);
    windowVertices[i] /= windowVertices[i].W;
    windowVertices[i] = Vector4.Transform(windowVertices[i], viewportMatrix);
}

DrawPoints(windowVertices);

Alternative Designs

No response

Risks

No response

[ghost]

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

Issue Details

---

Background and motivation

The Matrix4x4 class currently provides a large number of methods for creating various transformation matrices. The figure below shows a geometric pipeline for transforming vertices from object coordinates to window coordinates. Unfortunately, the Matrix4x4 class does not provide a method for creating a matrix that transforms vertices from normalized device coordinates to window coordinates.

I propose to add a method for creating a viewport matrix, which is shown in the figure below. width and height specify viewport dimensions, x and y stand for coordinates of the upper left corner of the viewport.

API Proposal

namespace System.Numerics;

public struct Matrix4x4
{
    public static Matrix4x4 CreateViewport(float x, float y, float width, float height)
    {
        Matrix4x4 result = Identity;
        
        result.M11 = width * 0.5f;
        result.M21 = -height * 0.5f;
        result.M41 = x + result.M11;
        result.M42 = y - result.M21;

        return result;
    }
}

API Usage

Matrix4x4 scaleMatrix = Matrix4x4.CreateScale(model.Scale);
Matrix4x4 rotationMatrix = Matrix4x4.CreateFromYawPitchRoll(model.Yaw, model.Pitch, model.Roll);
Matrix4x4 translationMatrix = Matrix4x4.CreateTranslation(model.Position);
Matrix4x4 modelMatrix = scaleMatrix * rotationMatrix * translationMatrix;
Matrix4x4 viewMatrix = Matrix4x4.CreateLookAt(camera.Position, camera.Target, camera.Up);
Matrix4x4 projectionMatrix = Matrix4x4.CreatePerspectiveFieldOfView(camera.Fov, camera.AspectRatio, camera.Near, camera.Far);
Matrix4x4 modelViewProjectionMatrix = modelMatrix * viewMatrix * projectionMatrix;
Matrix4x4 viewportMatrix = Matrix4x4.CreateViewport(0, 0, bitmap.PixelWidth, bitmap.PixelHeight);

Vector4[] windowVertices = new Vector4[model.Vertices.Length];
for (int i = 0; i < windowVertices.Length; i++)
{
    windowVertices[i] = Vector4.Transform(model.Vertices[i], modelViewProjectionMatrix);
    windowVertices[i] /= windowVertices[i].W;
    windowVertices[i] = Vector4.Transform(windowVertices[i], viewportMatrix);
}

DrawPoints(windowVertices);

Alternative Designs

No response

Risks

No response

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

[tannergooding]

Viewports are typically represented as distinct types and not directly as matrices. They likewise typically include a min/max depth in their representation and are not exclusively location + size.

I'd expect a more typical matrix created from a viewport would be (noting this matches yours for the "typical" minZ/maxZ values of 0 and 1, represetively):

w / 2          0              0              0
0             -h / 2          0              0
0              0              maxZ - minZ    0
x + (w / 2)    y + (h / 2)    minZ           1

That being said, exposing a "proper" viewport type is probably more than desirable and exposing some API that creates the corresponding matrix from the relevant 6 parameters is probably fine.

There are potentially some open issues/questions here, however. In particular, this is just one example of a valid "viewport" matrix and is one that (iirc) places 0, 0 at the upper left corner (y increases downwards). However, other setups may allow for a 0, 0 that starts in the lower left corner/etc (sometimes achieved by allowing negative heights, etc).

Much of that can be answered in the docs, but we may want to consider whether just "CreateViewport" is the correct name and what parameter validation, if any, should be done; etc.

[ghost]

This issue has been marked needs-author-action and may be missing some important information.

[tannergooding]

If you could update the API proposal to include the minDepth/maxDepth then I think we can move forward with the proposal.

[PavielKraskouski]

@tannergooding Updated.

[bartonjs]

Video

Looks good as proposed

namespace System.Numerics;

public partial struct Matrix4x4
{
    public static Matrix4x4 CreateViewport(float x, float y, float width, float height, float minDepth, float maxDepth);
}