Update information about ShaderDef's to indicate how to use non-boolean types in code
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 171
Description
## How can Bevy's documentation be improved?
Neither the documentation for [ShaderDefVal](https://docs.rs/bevy/latest/bevy/render/render_resource/enum.ShaderDefVal.html) nor for the [`shader_defs`](https://docs.rs/bevy/latest/bevy/render/prelude/struct.Shader.html#structfield.shader_defs) field on the Shader (or ComputeShaderPipelines) have any information about how the defined values get passed to your shader.
Users coming from a C background might assume that the behavior is like passing `-DFLAG=1` and would use it as a bare identifier:
```c
for(int i = 0 i < FLAG; ++i) {...}
```
But this results in naga compilation errors about unknown identifiers.
It actually appears that to use a value it must be with in a "preprocessor context" like a `#define`.
This is demonstrated fairly well in the `shader_defs` example, but this still doesn't help users know how to use a numerical value in their code.
I ended up finding the correct invocation by finding an [old issue](https://github.com/bevyengine/bevy/issues/9256).
I think that the documentation for `ShaderDefVal` should be updated with examples of how the values defined can be used in a shader. This should include information about some of the strange behavior like how the inserted value will not have a type suffix, so to make many equations work you need to suffix with `u` or `i` (sometimes it is helpful though to be able to use `f`).
It would also be useful for the `shader_defs` example to be updated to use a numerical `ShaderDefVal` to demonstrate their use.
Contributor guide
Research direction
Start with the ShaderDefVal and Shader shader_defs documentation linked in the issue, then inspect the shader_defs example. Document how numerical values are used in shader preprocessor contexts, including relevant type suffix behavior, and update the example to demonstrate a numerical ShaderDefVal.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation, game-dev
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100