bevyengine / bevyengine/bevy

Update information about ShaderDef's to indicate how to use non-boolean types in code

Open
#13,393 0 comments 0 reactions 0 assignees View on GitHub
A-Rendering C-Docs D-Shaders D-Straightforward S-Ready-For-Implementation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.