godotengine / godotengine/godot-docs
LightmapGI output resolution behavior could be better explained
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:**
4.7.stable
**System information:**
Godot v4.7.stable - Windows 11 (build 22631) - Multi-window, 3 monitors - OpenGL 3 (Compatibility) - NVIDIA GeForce RTX 4070 SUPER (NVIDIA; 32.0.16.1074) - AMD Ryzen 9 5900XT 16-Core Processor (32 threads) - 31.92 GiB memory - WASAPI (48000 Hz, Stereo/mono)
**Issue description:**
Intuitively, the max_texture_size property in LightmapGI node controls the output resolution for the baked lightmap .exr file. In practice, it is a hard-limit, but depending on circumstances your output file will be the smallest resolution possible in common sizes (1024^2, 2048^2, 4096^2, etc). Currently, the only way to know what your output file resolution will actually be, is to bake and check the result afterwards. This means a user will naturally generate larger lightmaps incidentally as their scene grows, potentially crashing their editor when they surpass the resources they have available during lightmap bake.
The default LightmapGI settings, and the documentation, tell the developer to leave max_texture_size at a value of 16384. The potential output file size of the .EXR file at that resolution is enormous (>300mb) and impractical. I would wager that the average user system isn't even capable of baking it without crashing (I wasn't able to, I've attached my hardware), so I think that a smaller, safe default value would be a good change. An 8096^2 texture on-disk can use close to 100mb--reasonable in the right scene, but maybe a lot to ask of an unsuspecting user. I think we can improve the documentation comments for these properties to better describe what's happening, and I'd be happy to help write it. The existing warning dialog that instructs the user to increase their resolution or decrease their texel size is already good at directing the user in a situation where the max_texture_size isn't enough for the scene.
After enabling Supersampling and starting a lightmap bake, this max_texture_size limit is also enforced during the supersampling step, which wants to multiply your texel size to render a high resolution image, then downsample it to the desired output resolution. This effectively prevents supersampling when the max_texture_size is equal to the output size required by the lightmap contents. If the user wants to target a specific output resolution, and use supersampling, they have to do it by juggling three different properties: supersampling factor, texel scale, and max texture size.
It would be much more intuitive to let the user pick a desired output resolution, then automatically adjust the texel_scale to fit everything neatly inside the available UV space during the bake. Or it might be possible to calculate it when the property changes in the inspector, to keep from breaking version compatability. But short of that, I think adding some additional documentation would help clarify how this behaves.
**URL to the documentation page (if already existing):**
[https://docs.godotengine.org/en/4.7/classes/class_lightmapgi.html](https://docs.godotengine.org/en/4.7/classes/class_lightmapgi.html)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the LightmapGI documentation page linked in the issue and review the descriptions of max_texture_size, supersampling, and texel_scale. Update the documentation comments to explain the effective output-resolution limit, supersampling interaction, and potentially large default, then verify that the page clearly describes how these settings affect baking.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- godot
- Domain
- documentation, game-dev
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100