Add custom projection mode to Camera3D, make Camera3D store its CameraMatrix and expose CameraMatrix to user code

[Astrono2]

Describe the project you are working on

I'm working on a portal plugin.

Describe the problem or limitation you are having in your project

I need to use oblique frustum projection to allow for the portals' cameras to clip content that's behind the portal plane. Which is currently impossible in Godot.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The enhancement would be to add a new projection mode, PROJECTION_CUSTOM to the Camera class, which would allow the developer to directly set the matrix to be used for projection. For my specific case, that would allow me to use oblique frustum projection. It would also address any other projection that any developer could want to use. And it would probably allow for some weird distortion effects as well.
Also, if a new projection is added with a CameraMatrix exposed to the user, it would make sense to migrate the entire Camera class and camera rendering to work with a CameraMatrix object belonging to each Camera instead of calculating the matrices from the Cameras' parameters.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

I think this can be done in a few steps:

1. Make CameraMatrix or other 4x4 matrix type available to user code
   1. Register CameraMatrix so that it is accessible to user code
   2. Add CameraMatrix to the documentation
2. Change the Camera class to allow for custom matrices
   1. Add a CameraMatrix object to the Camera class (could be named projection_matrix)
   2. Add updating the matrix when a parameter is changed (fov, near, far, etc.) by modifying the appropriate item in the matrix
   3. Add updating the matrix when the projection mode is changed by using the already existing methods in the CameraMatrix struct
   4. Add PROJECTION_CUSTOM to the Projection enum
   5. Add the CameraMatrix to the Camera's properties
3. Replace steps like this one in the rendering process with getting the camera's projection matrix.
4. Add necessary methods to either Camera3D or CameraMatrix to replace the functionality that calculating the matrix when necessary provided (e.g. setting the aspect ratio). So that the matrix doesn't have to be completely remade
5. Update Camera3D and possibly RenderingServer documentation
6. XR wizardry I cannot comprehend.

Here's a little mockup:

If this enhancement will not be used often, can it be worked around with a few lines of script?

Most definitely not

Is there a reason why this should be core and not an add-on in the asset library?

It requires considerable (although not very invasive) changes to two core classes and the rendering system.

[Calinou]

• Related to Add angled/oblique near and far camera planes #501
  and Allow for setting the X and Y FOV/frustrum sizes independently, and/or modifying the view transform #1250.

[lyuma]

Related to godotengine/godot#7499

My understanding is this feature is used for creating oblique frustums (mirrors / portals). Would a more limited feature like PROJECTION_OBLIQUE be sufficient to cover your proposed usecases?

[SaracenOne]

Yes, our specific use-case for this is creating portals/mirrors, particularly in VR. I would add also that the ability to seperate the view and clipping frustum seperately would likely go further in allowing optimisation, because we could limit the clipping plane to the confines of the portal.

[io12]

I was also working on a portal plugin and needed this (in addition to other things, like stencil buffering).

[elvisish]

I was also working on a portal plugin and needed this (in addition to other things, like stencil buffering).

It's one of the few things I've missed about switching to godot, having full access to the camera projection matrix. This portal plugin looks like it could be amazing if it could be completed with oblique frustum projection being available.

[Astrono2]

Related to godotengine/godot#7499

My understanding is this feature is used for creating oblique frustums (mirrors / portals). Would a more limited feature like PROJECTION_OBLIQUE be sufficient to cover your proposed usecases?

That's also the only use case I know, but in general I think having access to a Camera's matrix is a better solution. Specially since the changes I propose would also simplify adding new projection modes in the future. At the moment, the VisualServerScene::render_camera function scales with the amount of projection modes, as well as many of the functions in Camera.

CameraMatrix cm;

if (mode == PROJECTION_ORTHOGONAL) {
	cm.set_orthogonal(size, viewport_size.aspect(), p_z_depth, far, keep_aspect == KEEP_WIDTH);
} else {
	cm.set_perspective(fov, viewport_size.aspect(), p_z_depth, far, keep_aspect == KEEP_WIDTH);
}

This appears 3 times in camera.cpp. Storing the Camera's matrix in a variable would make the code a lot simpler.

[winston-yallow]

Exposing the possibility to set the matrix directly would be really nice in my opinion. It will also allow for more artistic effects like morphing between two matrices (even if not perspective/mathematically correct during morph you can achieve quite some interesting effects).

[wareya]

I want this to make it easier to fake 2d-style isometric and orthographic perspectives using 3d assets. Right now I need to stretch the world in bizarre ways to get the same effect, and it loses me a lot of control.

[Astrono2]

I left this hanging for a long time due to school. So I just edited to comply with not touching the Variant class and to update it for Godot 4, and I'll start working on it now!

[Calinou]

I left this hanging for a long time due to school. So I just edited to comply with not touching the Variant class and to update it for Godot 4, and I'll start working on it now!

Bump 🙂 Have you made progress so far?