Add a custom render phase example

[IceSentry]

Objective

• It's currently very hard for beginners and advanced users to get a full understanding of a complete render phase.

Solution

• Implement a full custom render phase
• The render phase in the example is intended to show a custom stencil phase that renders the stencil in red directly on the screen

---

Showcase

Notes

More docs to explain what is going on is still needed but the example works and can already help some people.

We might want to consider using a batched phase and cold specialization in the future, but the example is already complex enough as it is.

[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.

[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.

[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.

[tychedelia]

This is a great start. I think it would be cool if this did something more notable like an outline. I don't have many specific comments, other than I think it would be nice if we had a way to demonstrate a custom draw command here, but it's difficult for me to think what that would be. The only other thing is that we should demonstrate the cold specialization and retained bin pattern once those are settled, but this is also an issue with our other existing examples and out of scope here. This is going to be sooo helpful to share I think and we can def iterate more, tysm for doing this.

[IceSentry]

Yeah, an outline would be cool, but it would require a lot more code and the example is already really long.

It's for the same reason I used a sorted phase and didn't use cold specialization. It made the code even more complicated.

IIRC we already have an example showing a custom draw command. If not, we could set the shader color from a uniform that is bound in a custom command. Shouldn't be too hard to add to this example.

[ChristopherBiscardi]

I've run the example on an m1 mac and previously used this example (plus a custom post_process) to implement outlines.

I think the outlines are probably more than this PR should sustain, I like that it stops at rendering to the view as that's a concrete jumping-off point for anyone who wants to get started.

The example shows off a lot of useful concepts already. The only real downside I see is that adding hdr to the camera will break it due to the color attachment format (maybe worth changing in a future PR).

[ChristopherBiscardi]

The miri CI failure was a github network request issue, so I've moved it to ready-for-final since all other ci is passing and it now has two reviews.

[tychedelia]

It's for the same reason I used a sorted phase and didn't use cold specialization. It made the code even more complicated.

Okay I'm convinced, it's definitely better to start small.

IIRC we already have an example showing a custom draw command.

It's the custom phase item example which this one kinda overlaps with. I don't think we need to make this an everything example, just interacting with some of the more complex retained rendering stuff we've added recently is on my radar as conspicuously missing from our examples atm. This is covering a huge gap though so let's def just start here!

[cBournhonesque]

I tried to google it but could only find some vague definitions; what is a 'stencil' in this context?
I'm not sure what i'm looking for when looking at the red cube

[IceSentry]

It refers to essentially drawing the shape of the mesh. It's a bit of graphics programming terminology, but it's useful when you want to mask out something or want to create outlines. It's not really the purpose of the example though. It was just to have something a bit more concrete since it's most likely the most common use case for a custom phase.

[cBournhonesque]

What does the batching do in this case?

[IceSentry]

That's part of the future docs improvements I want to do, but the docs on the trait explain what is going on a bit more and I didn't want to just copy paste the doc, but maybe I should.

[cBournhonesque]

Super helpful example!
As a rendering noob, most of it made sense to me (the only thing I didn't understand is the batching logic and how it's used)