Select relevant 3D lights per mesh on GLES3 and Mobile renderers #107234

jon1solution · 2025-06-06T21:13:58Z

This PR changes the behavior of the RendererSceneCull::_scene_cull function to select the most relevant 3D lights per mesh in the Compatibility and Mobile renderers. It is a fix for Issue 107070.

Previously, if the scene had many more lights in range than could be rendered per-mesh (so > 8 for Mobile, or > Max Lights per Object for Compatibility), Godot would simply pick the first N lights and assign them to the mesh. Even increasing the limits (on Compatibility) failed to illuminate the scene as you would expect. I am sure most users who need complex 3D lighting can use the Forward+ renderer, but I am hoping to get a decent approximation running on the more limited renderers (I ran into the issue trying to fake GI in a procedural building with lots of lights).

Here is the behavior of 4.4.1 in a scene with 256 meshes and 256 omni-lights. For testing purposes, the range of each light was extended so that all meshes were in range of all lights. The result looked the same on both Mobile and Compatibility (with limits set to 256 lights per scene, 8 per-mesh to match Mobile):

With the code modifications in this PR, it now looks like this:

The original code ran through each mesh, and then each light relative to each mesh. The new code follows the same pattern but now assigns a score to each light, relative to each mesh, factoring in the distance from the light's AABB center to the mesh's AABB center, the light range, and the light energy.

The code then keeps track of the top N lights, by keeping the top N scores in a SortArray, which uses a heap internally to keep the scores sorted enough to find the worst score directly (it is always in slot [0]). If a new light is found to score better than the worst in the collection, slot 0 is replaced with the new light and the heap is updated.

In theory this is the fastest way to run through all M lights while keeping the top N, however many spatial hashing schemes could accelerate this by not having to run through all M lights for every mesh. So there is room to optimize further if this turns out to be too slow for extreme cases, however 256 3D lights in a scene might be excessive for mobile and web targets. [8^)

Removed pair_light_instances which took an intermediate collection of culled lights. Added in clear_light_instances to remove all paired lights from the mesh, and it returns how many lights max per mesh can be paired. Added pair_light_instance which pairs a specific light with a specific index into the pairing array. Inside RendererSceneCull::_scene_cull I keep the top N lights per mesh. The current implementation is not the fastest, I still need to move to a heap to efficiently keep the best lights, and SortArray seems to have the functionality I need.

SortArray uses a heap internally, which is the best option. On my system, worst test case is 256 omnilights with 256 meshes with 64 lights/mesh, and that takes 8.9us per mesh just to compute the distance score for the lights, with an additional 5.1us per mesh to keep the top 64.

Updating comments.

Takes Max Renderable Lights into account. The function clear_light_instances now also reports total_max_lights. Tried processing from cull_result.lights instead of geom->lights, but they are being built up over the life of the function, so the list is incomplete when I need it. (Also the function can be called from multiple threads)

Removed the code I was using for testing and profiling. Changed how clear_light_instances returns the per-mesh and total light count.

Ran clang-format on my files. Reverted useless change to .gitignore.

Calinou · 2025-06-11T00:05:14Z

Here is the behavior of 4.4.1 in a scene with 256 meshes and 256 omni-lights.

Can you upload this test project somewhere? This will make it easier to test the PR.

servers/rendering/renderer_scene_cull.cpp

Calinou

Tested locally with the MRP from #107070, it works as expected. (It doesn't have as many meshes/lights as shown on the screenshots, but it still shows that the situation compared to master is improved by rendering small lights on top of all the meshes.)

Code looks good to me.

jon1solution · 2025-06-11T01:00:22Z

Thank you for the feedback! I forgot to mention, in the original MRP, if you change the Grid Size export var up to 16, you should have the 256 meshes and lights test case displayed.

mrjustaguy · 2025-06-11T12:09:23Z

This probably also resolves #102230

Co-authored-by: Hugo Locurcio <hugo.locurcio@hugo.pro>

jon1solution added 6 commits June 6, 2025 10:40

Updating comments.

2fc9875

Updating comments.

Cleaned out test code.

688f075

Removed the code I was using for testing and profiling. Changed how clear_light_instances returns the per-mesh and total light count.

Ran clang-format.

361c498

Ran clang-format on my files. Reverted useless change to .gitignore.

jon1solution requested a review from a team as a code owner June 6, 2025 21:13

Calinou added bug topic:rendering topic:3d cherrypick:4.4 Considered for cherry-picking into a future 4.4.x release labels Jun 6, 2025

Calinou added this to the 4.5 milestone Jun 6, 2025