Add Rectangular Area Light Source

[CookieBadger]

This PR adds a rectangular area light source, implemented via Linearly Transformed Cosines (LTC) with textures. It makes use of a Lookup-Table added in the form of two .dds files, and adds some fields to the LightData struct in the light storage, and adds a new atlas for area light textures.

• Closes Add an AreaLight3D node to render real-time light coming out from a rectangle in 3D space godot-proposals#11450.
• Closes Add support for textured rectangular area lights using the decal atlas and a new PrefilteredTexture resource godot-proposals#13214

• Integrate lights in VolumetricFog
• Integrate lights in LightMaps
• Integrate lights in VoxelGI
• Implement texturing the light quad

Here's a list of steps on how to improve the feature in the future:

• Integrate material effects (those that are possible), such as anisotropy (https://github.com/AakashKT/LTC-Anisotropic/tree/main), Sub-surface scattering, rim light, clearcoat, toon shading, etc.
• Integrate light source in SDFGI (SDFGI is a complex system, ideally somebody who is familiar with it can integrate area lights)
• Integrate in Vertex Shading (if there's a demand)

Here's how shadows can be improved:

• Add shadows in Compatibility renderer (requires adding paraboloid or alternative shadow mapping to the GLES3 shader).
• Improve accuracy of paraboloid rendering in Forward renderers (currently area lights use the optimized version that was implemented for omni lights, but a more accurate represenation might better prevent leaks)

I believe we can also expand on and improve the feature in future PR, and have more nuanced discussions about e.g. the material subsystem.

One known issue is that specular light can leak through to a face that faces away from the area when viewing at a steep angle and a low roughness value. This is a literal edge case, and fixing it would likely require additional horizon clipping, so maybe we can live with the leak for now. It is present in the source LTC implementation, and the implementation in Unity, and I didn't notice until very recently.

The main sources for this technique are https://eheitzresearch.wordpress.com/415-2/ and https://blog.selfshadow.com/publications/s2016-advances/
In theory, it can be extended to arbitrary polygons, disks, and lines, to serve as the light surface (https://eheitzresearch.wordpress.com/757-2/), but I would worry about adding those in the future.

In the process of making this PR I investigated different techniques for lighting and shading. I investigated a Monte-Carlo sampling approach, and a most-representative point sampling approach, but both were outperformed by LTC, and contemporary research of non-raytraced dynamic area lights still seems to also focus around LTC.
I also investigated shadow sampling with many shadow maps on a new atlas, and adaptive sampling techniques, but those proved to be unusable due to the added implementation complexity. I figured the most suitable shadow technique was using 4 shadow maps per light and directional sampling with PCF to obtain a smooth result, but the shape of the penumbra was strangely warped, and the performance was not good. If you are curious, you may check it out at https://github.com/CookieBadger/godot/tree/area-light-quadriscopic-shadows. Another way to shadow area lights would of course be ray tracing (https://eheitzresearch.wordpress.com/705-2/), but I'm not aware of any developments of the engine in that direction. So, I decided to just integrate PCSS shadows for area lights, which are not physically accurate, but can look decent.

You can find a writeup and builds with several example scenes at https://github.com/CookieBadger/master-thesis-artifacts, but those already outdated as they are based on Godot 4.3. You'll also find a Thesis.pdf there, which is my Master's Thesis about this topic.

Any help with improving and maintaing this feature will be greatly appreciated.

[Calinou]

Also, CI seems to fail due to some GDExtension stuff that I am unfamiliar with, I'd appreciate a pointer to the fix.

The failures are because you reordered some enums around (specifically the Light3D PARAM_* enum), which breaks compatibility with existing projects. Make sure you only add new values at the end; never move existing values or remove them.

[Calinou]

Tested locally, it works as expected. This is a great start 🙂

Testing project: test_pr_108219.zip

Some feedback:

• Area width and height should use a single area Vector2 property instead of two separate float properties. While doing so, make sure to use PROPERTY_HINT_LINK for the property so you can adjust the width proportionally to the current height (and vice versa). You can clamp the value to positive numbers in the set_area() setter (this ensures it also affects script-based usage).
• Gizmo behavior and icons look good to me.
• I've only tested this in Forward+, as Mobile will print a lot of errors and not render anything. On Compatibility, area lights are not supported but rendering works correctly otherwise.
  • There should be a node configuration warning on AreaLight3D when in Compatibility, similar to the Decal node's existing node configuration warning.
• Like with lights that use a dual paraboloid shadow mode, meshes need to be subdivided enough (relative to the size of the area light) for shadows to look correct:

area_shadow_subdivided.mp4

This is most noticeable on shadows with a low blur value:

area_shadow_subdivided_no_blur.mp4

• Light/shadow distance fade works correctly.
• Volumetric fog doesn't take area lights into account yet.
• Hard positional shadow quality looks the same as Soft Very Low. Ideally, Hard should disable shadow blurring entirely like it does with other light types to maximize performance on low-end GPUs.
• High and Ultra soft shadow qualities can be very expensive with lights that have a high blur value (even 1.0 is quite blurry out of the box), so beware. Consider using TAA or FSR2 to get temporal smoothing (and keep shadow filter quality at its default Low), which will give you smoother shadows without an increased performance cost.
• Shadow opacity will behave differently to other light types, as the shadow won't fade in an uniform manner across the whole light. This may be desired behavior, but it might be worth documenting to avoid surprises:

area_shadow_opacity.mp4

• When you move some shadow casters, they can sometimes be in a position where they will self-shadow. This is most noticeable at low blur values (below 0.3 in the test project). Reloading the scene or restarting the project does not fix the self-shadowing, so this does not appear to be an issue related to shadow updates sometimes not occurring when they should.

https://github.com/user-attachments/assets/131dee5c-c6c1-40d0-bcfc-2d8e68a7dbc

The issue will occur even if you're moving another shadow caster:

area_shadow_self_moving_other_shadow_caster.mp4

• Specular contribution is set to 0.5 by default, which leads to area lights not having specular contributions as strong as omni and spot lights:

It's more in line with other light types when set to 1.0, so I suggest changing the default to that:

[LiveTrower]

I believe that, for now, to provide some level of mobile support and compatibility, area lights will only be usable through lightmap baking. I don't think anyone has the time to research and implement real-time area lights with acceptable performance, especially on mobile devices.

[CookieBadger]

@Calinou do you have any further details about the self-shadow bug? I was unable to reproduce it on my machine with your project.

[Calinou]

@Calinou do you have any further details about the self-shadow bug? I was unable to reproduce it on my machine with your project.

I've just tested the PR and can't reproduce the issue anymore, so I guess it's fixed now.

[CookieBadger]

@LiveTrower I would see no reason, why area lights shouldn't work on mobile, or in compatibility. In fact, they should work now (just need to fix up the shadows in compat).

[LiveTrower]

@CookieBadger I was talking about performance because when it comes to mobile rendering and compatibility, it's a very sensitive subject. That's why many advanced features found in Forward+ rendering are left out of these renders.

You'll probably need to make a highly optimized version for these renders and prove with extensive testing that it's feasible on mobiles that support Vulkan or OpenGL, as well as on very old PC hardware that only runs Godot in compatibility mode because it lacks Vulkan or DirectX 12.

I'm not an expert, and I won't have the final say, so it would be better if @clayjohn gave you his opinion since he knows more about this.

[Calinou]

I expect area lights will perform somewhat OK on Mobile and Compatibility with shadows disabled, but I would avoid enabling shadows for them (but this applies to all light types in general when working with mobile/low-end platforms). PCSS-style variable penumbra shadows don't work in Mobile and Compatibility anyway, so the Light3D Size property will only affect the size of the specular lobe and the light's diffuse appearance anyway.

Last time I checked, there are some remnants of PCSS-style shadows in the Mobile renderer, but these were meant to be removed due to performance concerns: #55882

[CookieBadger]

@Calinou I agree, lighting computations are just mildly more complex than for point lights. They require two texture lookups, but the textures are constant, so should not be an issue even in Compatibility. Shadows in Compatibility don't work anyways since there is no dual paraboloid shadow pass, so I disabled them now. For the mobile renderer, shadows do work, but as you say, variable penumbra doesn't. Would you rather note that in documentation, or disable shadows entirely there?

[Calinou]

For the mobile renderer, shadows do work, but as you say, variable penumbra doesn't. Would you rather note that in documentation, or disable shadows entirely there?

I think you can keep shadows there, just document it in the class reference.

[CookieBadger]

Also, I rebased, and need help with failing tests, as well as with Re-SPIRV (#113561 (comment))

[fire]

Did you try ERROR: /root: The caller thread can't call the function propagate_notification() on this node. Use call_deferred() or call_deferred_thread_group() instead.
at: propagate_notification (./scene/main/node.cpp:2597)?

[CookieBadger]

I implemented textures, by adding a new area_light_atlas to the TextureStorage, next to the decal atlas basically.
EDIT: textures are not supported in the compatibility renderer.

[jcostello]

Im getting this error

ERROR: Failed parse:
WARNING: 0:494: '' : all default precisions are highp; use precision statements to quiet warning, e.g.:
         "precision mediump int; precision highp float;" 
ERROR: 0:2377: '=' :  cannot convert from ' global highp float' to ' temp float16_t'
ERROR: 0:2377: '' : missing #endif 
ERROR: 0:2377: '' : compilation terminated 
ERROR: 3 compilation errors.  No code generated.



   at: compile_stages (servers/rendering/renderer_rd/shader_rd.cpp:1001)
ERROR: Condition "variant_stages.is_empty()" is true.
   at: _compile_variant (servers/rendering/renderer_rd/shader_rd.cpp:306)
ERROR: Failed parse:
WARNING: 0:494: '' : all default precisions are highp; use precision statements to quiet warning, e.g.:
         "precision mediump int; precision highp float;" 
ERROR: 0:2377: '=' :  cannot convert from ' global highp float' to ' temp float16_t'
ERROR: 0:2377: '' : missing #endif 
ERROR: 0:2377: '' : compilation terminated 
ERROR: 3 compilation errors.  No code generated.

[jcostello]

And in other projects

SPIR-V Parsing error. Result 3803 is not valid.
SPIR-V Parsing error. Result 3790 is not valid.
SPIR-V Parsing error. Result 3773 is not valid.
SPIR-V Parsing error. Result 3786 is not valid.

WARNING: "usage" is not supported in add_property_info().
     at: _add_property_info_bind (core/config/project_settings.cpp:1347)
WARNING: "usage" is not supported in add_property_info().
     at: _add_property_info_bind (core/config/project_settings.cpp:1347)
ERROR: /root: The caller thread can't call the function `propagate_notification()` on this node. Use `call_deferred()` or `call_deferred_thread_group()` instead.
   at: propagate_notification (scene/main/node.cpp:2597)