Vulkan perspective projection matrices or more flexible perspective matrix functions

[BalintCsala]

For a personal project I needed a set of vulkan-specific projection matrices, meaning:

• NDC depth range is [0,1]
• +Y points down in clip space

I implemented these into a fork of glam and thought you might be interested in a PR for them? I have tests and stuff ready for it.

Alternatively I've seen discussions about a more general solution (#569), which I would be willing to tackle if there's a need for it, just need some pointers on what the preferred implementation would look like.

What I'm thinking is that a perspective projection matrix is basically the result of the following "decisions":

• Is the input (view) coordinate system left or right handed?
• In the input (view) coordinate system does Z or Y point up?
• In the resulting (clip) coordinate system does Y point up or down?
• What is the range of depth in NDC? Usually this is either [0,1] or [-1,1], but it could technically be anything.
• Plus the classic parameters: znear, zfar, aspect ratio, fov_y

I think the simplest and probably most user-friendly approach to go at this is something like

enum Handedness { Left, Right };
enum UpDirection { Y, Z };
enum ClipPosY {Up, Down};

fn perspective(handedness: Handedness, up: UpDirection, clip_pos_y: ClipPosY, ndc_y_front: f32, ndc_y_back: f32, z_near: f32, z_far: f32, aspect: f32, fov_y_radians: f32) -> Mat4 {
    let handedness_component: Mat4 = match(handedness) { ... };
    let up_component: Mat4 = match(up) { ... };
    let clip_pos_y_component: Mat4 = match (clip_pos_y) { ... };
    let depth_scale_component: Mat4 = ...;
    let base_perspective: Mat4 = ...;
    return handedness_component * up_component * ...;
}

which generates the perspective matrix from smaller components, each influencing how a view space position would get mapped to clip space. Second step after this would be to hope this mess can get untangled by the compiler into something that doesn't need runtime matrix multiplications.

My personal opinion is that the purposefully specific perspective_lh, perspective_rh, perspective_rh_gl, etc. functions are nice to have, since most people probably don't want to fuss with exact projection parametrizations too much, but if a more general solution emerges, they could use that as the implementation backend.

[bitshifter]

Hi there.

Yes providing a more general solution is something I'd like to do for glam. Interface wise I haven't worked out exactly how it should look, but behind the scenes it could be a method that can generate the correct matrix for the input parameters that you describe.

What I'm thinking is:

• Possibly a module or type called projection - it should be able to generate perspective and orthogonal projection matrices. This module or type would implement the common projection methods, e.g. perspective, othographic, perspective_infinite, perspective_infinite_reverse
• I'd be inclined to create types for each common permutation rather than making users specify things like Handedness, Up, Clip etc but the implementation could do that. Ultraviolet names methods based on the convention of the graphics API, e.g. GL, DX, VK, WGPU. Not necessarily tied to that but it is at least familiar to people.
• Ideally a glam users could use the projection module or type that matches their use case and not have the ones they don't care about in their project. For example engines like bevy re-export glam, it would make sense to only export the projection methods that match bevy's renderer.
• I would be inclined to deprecate and remove perspective and orthographic methods from matrix types because I don't like they cluttering up matrix but I'd try and gauge how glam users felt about that first. Both methods could exist.

Not suggesting that you do all of this, but if you have some code that does some of the implementation it would help progress things.

Dealing with different graphics APIs and projection matrices is not something I regularly do so any help is appreciated.

[BalintCsala]

I could see this implemented the following way:

• A trait called something like ProjectionComponentProvider

• Handedness, Up, ClipUp, Type are all superset traits of ProjectionComponentProvider

• Projection is a struct that takes Handedness, Up, etc. as generic arguments (struct Projection<H: Handedness, U: Up ...)
• Single fn matrix on Projection to get the respective matrix
• impl From for DMat4, Mat4, etc. that calls matrix() for convenience
• alias different parametrizations of Projection as WebGPUPerspective, VulkanOrthographic, etc.

What do you think?

I would be inclined to deprecate and remove perspective and orthographic methods from matrix types because I don't like they cluttering up matrix but I'd try and gauge how glam users felt about that first. Both methods could exist.

Yeah considering how many larger libraries are downstream to glam (e.g. Bevy), this could cause a bit of a turmoil, but maybe deprecating and removing later could help with moving people over.

Not suggesting that you do all of this, but if you have some code that does some of the implementation it would help progress things.

If you don't mind an implementation that's a user of glam instead of being integrated (mainly because it's easier to do so without the template stuff), I could whip something up. Won't be fully feature complete, but we can cross that bridge later.

[bitshifter]

If you don't mind an implementation that's a user of glam instead of being integrated (mainly because it's easier to do so without the template stuff), I could whip something up. Won't be fully feature complete, but we can cross that bridge later.

yep that's fine, would be good to see what it could look like. This should be an internal implementation detail so interface doesn't matter too much. Potentially existing methods could be migrated to use this more general implementation and a final public interface could come later.

[BalintCsala]

Okay, I'll get back to you sometime next week

[BalintCsala]

@bitshifter As discussed, here's a slightly jank example version for what I was imagining. It's nowhere near complete, but it should give you an idea for it.

How this works is basically:

• When constructing the projection matrix, assume a normalized setup: Left handed local coordinate system with +Y pointing up, depth range should be zero to one and clip space +Y is upwards
• If the assumption doesn't hold, the matrix components provided by the parameters help normalize it (e.g. if local up is +Z, the LocalUp COMPONENT will swap Y and Z and change the handedness

I ended up making perspective and orthographic functions on Projection, mainly because this makes it easier to ask for their parameters.

Some further discussion items could be:

• Should this use generic names (DepthRangeZeroToOne, DepthRangeNegOneToOne), or more "recognizable" ones (DepthRangeVulkan, DepthRangeOpenGL). The latter would be easier for end-users, but it would involve either really long and awkard names (DepthRangeVulkanWebGPUDirectX) or multiple copies of the same functionality. This same thing could be achieved with type aliases, which I think is preferable
• What combinations of parameters should be accepted, e.g. you probably don't want any combination of LeftHandedZUp cluttering the name space, since that's only really used by Unreal.
• Should the code choose "defaults", e.g. most people would probably want their WebGPU projection matrix to be a ProjectionWebGPURightHandedYUp, so that could be named ProjectionWebGPU

I didn't check if this actually compiles nicely, hopefully the matrix multiplications get constant evaluated

Also if you think of any extra parameters, let me know. One thing I thought about already is pre and post multiplication (in webgpu, vulkan and opengl people tend to write projection * view_pos, while in directx the convention is view_pos * projection)

Had to rename the file to txt as GitHub doesn't support uploading rs files.

lib.txt

[bitshifter]

Thanks for this!

I was wondering, could the generic parameters be const generic enums, but no, stable Rust can't do that :)

In your sample the DepthRange transform is currently unused, it would be good to include that to make sure the sequence of matrix transformations is correct.

Should this use generic names (DepthRangeZeroToOne, DepthRangeNegOneToOne), or more "recognizable" ones (DepthRangeVulkan, DepthRangeOpenGL). The latter would be easier for end-users, but it would involve either really long and awkard names (DepthRangeVulkanWebGPUDirectX) or multiple copies of the same functionality. This same thing could be achieved with type aliases, which I think is preferable

I think the generic names make sense here.

Should the code choose "defaults", e.g. most people would probably want their WebGPU projection matrix to be a ProjectionWebGPURightHandedYUp, so that could be named ProjectionWebGPU

Yeah I think that is the way to go, add aliases for the commonly used APIs and I guess people will have the tools available to create their own if they need to create anything exotic.

I didn't check if this actually compiles nicely, hopefully the matrix multiplications get constant evaluated

I don't think that they will. I'd have to not use glam types for the matrix multiplications, IIRC const traits aren't a thing yet so even if float ops can be const eval glams Op trait implementations can't be. The SIMD stuff also can't be const eval. It is worth thinking about how to make this efficient, but I think getting the interface and math right and some tests that give us confidence about correctness first is the way to go. The internals can be improved later.

One thing that could potentially be done differently is to make the traits define a transform method which transforms an input projection matrix and does nothing if no transform is required. That said, the worst case would still be 4 matrix multiplies which ideally I'd want to avoid in a final implementation.

Also if you think of any extra parameters, let me know. One thing I thought about already is pre and post multiplication (in webgpu, vulkan and opengl people tend to write projection * view_pos, while in directx the convention is view_pos * projection)

Glam is uses column vectors (versus DirectX math which uses row vectors) to multiplication order is always Projection * ViewPos.
https://github.com/bitshifter/glam-rs?tab=readme-ov-file#column-vectors

[BalintCsala]

I was wondering, could the generic parameters be const generic enums, but no, stable Rust can't do that :)

I considered that too and yeah, really annoying. Maybe in the future.

In your sample the DepthRange transform is currently unused, it would be good to include that to make sure the sequence of matrix transformations is correct.

I forgot that one. Tbh I'm not even confident that one works specifically, I'd have to grab a pen and paper to test. If it works, it should just go on the front of the multiplication chain.

I don't think that they will.

Actually, I just checked an example, and it seems like it does (at least for the f32 case, but potentially others as well). I created a main function where I generate a perspective projection matrix and I ran it on user input. The matrix ended up looking like this:

[[1, 0, 0, 0], [0, -1, 0, 0], [0, 0, 1.1111112, 1], [0, 0, -1.1111112, 0]]

And in the assembly there's a section like this:

.LCPI11_0:
	.long	0x3f800000
	.section	.rodata.cst16,"aM",@progbits,16
	.p2align	4, 0x0
.LCPI11_1:
	.long	0x00000000
	.long	0xbf800000
	.long	0x00000000
	.long	0x00000000
.LCPI11_2:
	.long	0x00000000
	.long	0x00000000
	.long	0x3f8e38e4
	.long	0x3f800000
.LCPI11_3:
	.long	0x00000000
	.long	0x00000000
	.long	0xbf8e38e4
	.long	0x00000000

Which if you convert to floats, you get

LCPI11_0: 1, (no clue where the 3 remaining zeroes are)
LCPI11_1: 0, -1, 0, 0,
LCPI11_2: 0, 0, 1.1111112, 1
LCPI11_3: 0, 0, -1.1111112, 0

Which is close enough I think. I'd assume this is true for DMat too, and even if the SIMD stuff stops that from constant evaluation, the path could be special cased where the matrix is calculated as a simple f32 Mat4 and converted to the simd variant right at the end.

I also did a test where the matrix inputs came from the user and even there it managed to do something, at least as far as I understood the code.

Glam is uses column vectors (versus DirectX math which uses row vectors) to multiplication order is always Projection * ViewPos.

Fair, forgot to consider that even if a solution was added for the projection matrix to act as a post multiplication matrix, there are no other matrices in the library to use it with.