Add sprite and mesh alteration examples

[richchurcher]

Objective

Add examples for manipulating sprites and meshes by either mutating the handle or direct manipulation of the asset, as described in #15056.

Closes #3130.

(The previous PR suffered a Git-tastrophe, and was unceremoniously closed, sry! 😅 )

[github-actions]

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[alice-i-cecile]

Perfect: this demonstrates the point really nicely.

[janhohenheim]

Good idea! The alter_mesh example could mayyyybe be turned into procedural_mesh, as that is what most people using this API will probably end up doing. Not sure, your choice.
The rest of the comments are just about how to make the examples a bit easier to understand for outsiders. Comments are mostly valid for both examples.
Good job with the examples, they're pretty nicely written!

[JMS55]

I'm surprised not to see any usage of RenderAssetUsages here.

[richchurcher]

I'm surprised not to see any usage of RenderAssetUsages here.

I'm sorry, you might need to ELI5 here... how should I best use this?

[richchurcher]

could mayyyybe be turned into procedural_mesh, as that is what most people using this API will probably end up doing.

Couldn't make a decision either way, so left it alone.

[JMS55]

I'm sorry, you might need to ELI5 here... how should I best use this?

Read the docs https://dev-docs.bevyengine.org/bevy/render/render_asset/struct.RenderAssetUsages.html, and then let me know if you have any questions.

I just realized the default is actually RenderAssetUsages::all() so that's why this example is fine, but I'd prefer if we could explicitly set that to all() and call out why it's necessary, as I very frequently see people make the mistake of using RENDER_WORLD only and then being confused why their asset does not exist.

[richchurcher]

@JMS55 Is this the kind of thing you had in mind? New territory for me, so feel free to provide more direction!

[janhohenheim]

@JMS55 will know better than me, but IME it is the other way around: usually you won't be mutating meshes at runtime, so it's best to set it to RENDER_WORLD only unless you have a good reason to set it to ALL. Although IIRC for footgun reasons, we left the default at ALL.

[richchurcher]

So JMS55 wrote:

but I'd prefer if we could explicitly set that to all() and call out why it's necessary, as I very frequently see people make the mistake of using RENDER_WORLD only and then being confused why their asset does not exist.

Perhaps if I make a point of only setting this to all for the asset whose mesh we're going to directly modify, and re-word the comment to say the default is "usually safe" unless you have more specific needs? I'll push that so you can have a read.

[janhohenheim]

The default is not usually safe, it is always safe, as the default is ALL. It's just twice as expensive than it needs to be for 99% of use cases, as nearly no one will be editing or inspecting meshes at runtime. Many people choose to use RENDER_WORLD instead of ALL for meshes, which is safe until you need to access the mesh on the CPU, which we do in this example.

[richchurcher]

I'm with you now. OK, so maybe the second one we explicitly set it to RENDER_WORLD and add a further comment there. Maybe also modify the sprite example.

[janhohenheim]

Looks great now, thanks :) The example are very readable, good job!

[janhohenheim]

Leaving it as waiting for author because of the render world thing

[richchurcher]

Thanks for being patient, I think I've arrived at a good place with the comments now!

[alice-i-cecile]

I'm going to merge this once CI is green :)

[richchurcher]

Argh internal imports again! One moment, caller.

[richchurcher]

@alice-i-cecile sorted

[janhohenheim]

Thanks for being patient

If this took a moment for you, that's a big indicator that our existing docs could be better in this regard. Happy to have an example showing and explaining the concept now :)
Fantastic work!