[Merged by Bors] - shader examples wording coherence #4810
Conversation
|
it might be a good opportunity to tackle all examples descriptions and not only "shader" ones, but I'll await feedbacks before doing so. |
alice-i-cecile
added
A-Rendering
| `animate_shader` | [`shader/animate_shader.rs`](./shader/animate_shader.rs) | A shader that uses dynamic data like the time since startup. | ||
| `compute_shader_game_of_life` | [`shader/compute_shader_game_of_life.rs`](./shader/compute_shader_game_of_life.rs) | A compute shader that simulates Conway's Game of Life. | ||
| `custom_vertex_attribute` | [`shader/custom_vertex_attribute.rs`](./shader/custom_vertex_attribute.rs) | A shader that reads a mesh's custom vertex attribute. | ||
| `shader_defs` | [`shader/shader_defs.rs`](./shader/shader_defs.rs) | A shader that uses "shaders defs" (a bevy tool to selectively toggle parts of a shader). |
There was a problem hiding this comment.
| `shader_defs` | [`shader/shader_defs.rs`](./shader/shader_defs.rs) | A shader that uses "shaders defs" (a bevy tool to selectively toggle parts of a shader). | |
| `shader_defs` | [`shader/shader_defs.rs`](./shader/shader_defs.rs) | A shader that uses "shaders defs" to selectively toggle parts of a shader. |
This isn't a Bevy-specific concept and we can phrase this more directly.
There was a problem hiding this comment.
a quick search for "shaders def" gave me very little information on internet, I also remembered bevy having a custom shader preprocessor https://bevyengine.org/news/bevy-0-6/#shader-preprocessor.
While the concept is not from bevy, isn't the implementation specific to bevy ? Even though probably very similar to other implementations, it might surprise readers if not all features are similar ?
I'd love to be wrong here, if there's a specification to "shader_defs", maybe this would benefit giving a link to a reference to that shader_def concept (or link to a shader preprocessor documentation ?)
There was a problem hiding this comment.
Hmm, apparently you're right. I think we should really strive to have a useful introduction both here and in the docs.
There was a problem hiding this comment.
Yes, the way we do it in bevy is specific to bevy. Wgsl doesn't support that natively.
|
@bevyengine/rendering-team, can I get a pithy explanation of what a "shader def" is exactly, so we can improve the descriptions of these examples? |
|
I should note this discussion: https://discord.com/channels/691052431525675048/743559241461399582/977244773410832384 ; if "first line" in example docs should be the same as or imported to the example readme, we might lose this change PR, so I should update the examples "first line" docs too. |
Yes please! |
A ‘shader def’ is a definition used by a shader. The term ‘definition’ comes from preprocessor languages where source code is processed to apply preprocessor definitions before it is passed to a compiler. In bevy, the currently-supported definitions allow pieces of shader code to be included or not based on whether the shader defs are supplied when the shader code is being preprocessed. This allows you to do things like: #ifdef SUPPORTS_FEATURE_A
Code for when feature A is supported.
#else
Code for when feature A is not supported.
#endifThen, in this example, if in rust code you detect that your mesh has some particular vertex attributes or the GPU supports a particular feature, and that is feature ‘A’ then you provide We also use preprocessor directives for handling shader imports - saying ‘insert the code from this other shader file here.’ We will add more functionality as it is needed. I expect another one that will come soon is being able to replace a definition with a value. So in the shader code there may be |
|
Thanks @superdump ; we might want to add that kind of description into https://docs.rs/bevy/latest/bevy/render/render_resource/struct.VertexState.html ? and link to there from the example ? |
# Objective I noticed different examples descriptions were not using the same structure:  This results in sentences that a reader has to read differently each time, which might result in information being hard to find, especially foreign language users. Original discord discussion: https://discord.com/channels/691052431525675048/976846499889705020 ## Solution - Use less different words, similar structure and being straight to the point. --- ## Changelog - Examples descriptions more accessible.
bors
bot
changed the title
# Objective I noticed different examples descriptions were not using the same structure:  This results in sentences that a reader has to read differently each time, which might result in information being hard to find, especially foreign language users. Original discord discussion: https://discord.com/channels/691052431525675048/976846499889705020 ## Solution - Use less different words, similar structure and being straight to the point. --- ## Changelog - Examples descriptions more accessible.
# Objective I noticed different examples descriptions were not using the same structure:  This results in sentences that a reader has to read differently each time, which might result in information being hard to find, especially foreign language users. Original discord discussion: https://discord.com/channels/691052431525675048/976846499889705020 ## Solution - Use less different words, similar structure and being straight to the point. --- ## Changelog - Examples descriptions more accessible.
Objective
I noticed different examples descriptions were not using the same structure:
This results in sentences that a reader has to read differently each time, which might result in information being hard to find, especially foreign language users.
Original discord discussion: https://discord.com/channels/691052431525675048/976846499889705020
Solution
Changelog