godotengine / godotengine/godot-docs
Sampling hint_depth_texture in a shader disables SSR
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
On the [Screen-reading shaders docs](https://docs.godotengine.org/en/stable/tutorials/shaders/screen-reading_shaders.html) page there's the following warning:
> In 3D, materials that use hint_screen_texture are considered transparent themselves and will not appear in the resulting screen texture of other materials. If you plan to instance a scene that uses a material with hint_screen_texture, you will need to use a BackBufferCopy node.
It seems this also applies to `hint_depth_texture`. I assume this is just a doc oversight and not currently a fixable issue. But this and various other notes throughout the docs are actually referring to such materials not *appering* in reflections. It's not clear that this also means materials that sample these textures will also be considered transparent themselves, the same as when accessing ALPHA.
Some other pages that could use clarity on this:
* https://docs.godotengine.org/en/stable/tutorials/shaders/shader_reference/shading_language.html
* https://docs.godotengine.org/en/stable/tutorials/3d/environment_and_post_processing.html#screen-space-reflections-ssr
* https://docs.godotengine.org/en/stable/tutorials/shaders/shader_reference/spatial_shader.html
* https://docs.godotengine.org/en/latest/tutorials/shaders/advanced_postprocessing.html
Minimal shader repro
```
shader_type spatial;
uniform sampler2D depth_tex : hint_depth_texture;
void fragment() {
ALBEDO = vec3(0.2);
METALLIC = 1.0;
ROUGHNESS = 0.0;
// uncommenting the following line makes SSR disappear
// texture(depth_tex, SCREEN_UV);
}
```
**Godot version details:**
4.7.2.rc build from git 8df813a09b71d5c08656d038a24df9bb92bdad9f Forward+ on macbook m5 pro. macos tahoe 26.5.2. Both metal and vulkan backends
`scons platform=macos arch=arm64 generate_bundle=yes production=yes debug_symbols=yes`
Contributor guide
No contributing guide indexed for this repository
Research direction
Review the Screen-reading shaders, Shading language, Screen-space reflections (SSR), Spatial shader, and Advanced post-processing documentation pages listed in the issue. Use the minimal shader repro to confirm the documented behavior, then make the relevant warnings explain the effect of sampling hint_depth_texture and hint_screen_texture on transparency, reflections, and SSR; done means the affected pages are consistent and unambiguous.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- godot
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 64/100