godotengine / godotengine/godot-docs
Renderer & Shader Reference Improvements
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:**
Godot 4.5.1
**Issue description:**
## Summary
There are a few (simple) differences between the compatibility and forward+ renderer that I have encountered that are not documented. I also think the effect of DIFFUSE_LIGHT should be stated clearly somewhere, and adding an example light() shader to the tutorial section would be an improvement.
I think adding in these behaviours would be helpful for beginners.
I have not tested the mobile renderer.
## Details
### ALPHA
Setting `ALPHA = 0`. in the light() function does not do anything when in compatibility, but it works in forward+ with the same settings. [see MRP below]. I assume this is not a bug and really just a limitation of the compatibility renderer. If this is correct, perhaps it could be added to a section on [this page](https://docs.godotengine.org/en/stable/tutorials/rendering/renderers.html).
### DIFFUSE_LIGHT
Diffuse light cannot be negative in the light() function when in compatibility. That is, `DIFFUSE_LIGHT = vec3(0.0);` behaves the same as `DIFFUSE_LIGHT = vec3(-100.);`. I assume this is just how compatibility / OpenGL works. Perhaps this is documented somewhere, but I've searched the docs and can't find it. This is also in the MRP.
### ALBEDO & DIFFUSE_LIGHT calculation
In the docs, I cannot see a definition of what DIFFUSE_LIGHT actually is. I assume that the pixel color calculation is quite complicated, renderer dependent and probably not simple to write, but I think it would be instructive to state in the docs what the overall function is. Is it pixel_color = ALBEDO * DIFFUSE_LIGHT + [some function of specular]? Or something completely different? Even just a word definition of DIFFUSE_LIGHT in the spatial shader reference (beyond "Diffuse light result") would be good. When I was first learning shaders, I think something like this would've been extremely helpful, even if you can get a feel through experiment.
### light() function example
The tutorial shaders [here](https://docs.godotengine.org/en/stable/tutorials/shaders/your_first_shader/index.html) only walk through vertex() and fragment() functions. I think it would be instructive to provide a (simple) lighting shader, so that beginners can understand what specular, diffuse, etc mean, and what the limitations of the light() function are (e.g. which variables can / can't be modified). Of course, you can convert a standardmaterial to a shadermaterial to reverse engineer it yourself, but I think its a good idea to have a short section which can explain what's going on.
## Conclusion
I am somewhat new to rendering, so I accept that my suggestions might be naive, or perhaps I have misunderstood what the MRP is showing. Maybe I'm being blind and the things I've mentioned above are documented somewhere. I am more than happy to submit a PR with the changes I've outlined above; it would be great if someone can confirm whether they are sensible changes.
**URL to the documentation page (if already existing):**
I think the changes could be added to these pages
https://docs.godotengine.org/en/stable/tutorials/shaders/shader_reference/spatial_shader.html
https://docs.godotengine.org/en/stable/tutorials/rendering/renderers.html
https://docs.godotengine.org/en/stable/tutorials/shaders/your_first_shader/index.html
## MRP
https://github.com/BenBlueeeee/godot-renderer-differences
The attached zip is from commit https://github.com/BenBlueeeee/godot-renderer-differences/commit/5f52ab578cc767a9d1b72a37dbff5b15a3aee7b5
[renderer_differences_2026-02-02_14-03-27.zip](https://github.com/user-attachments/files/25015082/renderer_differences_2026-02-02_14-03-27.zip)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the spatial shader reference, renderer documentation, and first-shader tutorial pages named in the issue, then run the linked MRP to verify the reported differences. Confirm the intended behavior with the rendering documentation or maintainers before editing. Done means the confirmed renderer limitations, DIFFUSE_LIGHT behavior, and a light() tutorial example are documented in the appropriate pages.
Written by the indexing model from the issue text.
Assessment
- Domain
- computer-graphics, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100