initial pass at sorted-and-binned render phase items

[ChristopherBiscardi]

and resources, including rc non-mesh fixes.

fixes #1386

I picked URLs that would work today so review could be made, assuming they'd need to be changed either before or after merging.

[alice-i-cecile]

LGTM in terms of technical writing and clarity.

[alice-i-cecile]

On a technical note though, this new file should be in migration-guides, and you need to update the .toml file at the top of that folder to reflect the two removed and one added file :)

[ChristopherBiscardi]

I don't see any other entries in the toml file with combined/multiple PR urls so I left it as the original PR which introduced the Sorted/Binned. The other two PRs are the resource move and the non-mesh/hanabi fix

[BD103]

I'll take a look at this once I finish the migration guides. (10 more to go!)

[djeedai]

Looks like a good start, but I'm not sure this is enough to migrate code. The move to resources for example definitely requires seeing a before/after to understand how to transform one's code. Selecting the sorted or binned phase item was also the easy part; it's after to implement the binned one that problems start.

I think we need to explain:

• what's binning? why is it better than sorting and when can you use it or not?
• how do you come up with a bin key?
• how do you query the phase item container from the resource and the camera view entity?
• caveats of using non mesh (there's actually no binning!)

[djeedai]

"is potentially batchable" or is actually batched (binned)?

[ChristopherBiscardi]

"potentially batchable" is the wording used in the original PR, so I deferred to that - bevyengine/bevy#12453

[djeedai]

Link them all maybe? (sorry for the extra work 😅)

[ChristopherBiscardi]

Could do. I linked Shadow specifically because to someone less familiar it looks out of place next to things that are clearly 2d/3d forward/deferred/prepass related. The full list is already available at the "Examples of" links.

[alice-i-cecile]

I'm going to merge this as is to avoid unduly burdening @ChristopherBiscardi, whose help I really appreciate here. I agree that these are important things to explain @djeedai, but IMO these point to a failing of the underlying documentation, and don't belong in a migration guide.

[alice-i-cecile]

Looks like the name of the file doesn't match somehow; see the failed CI. I'll take a look later unless someone beats me to it.

[ChristopherBiscardi]

@alice-i-cecile merging the main branch into this branch caused the previously-removed file to be re-inserted into the toml file.

I re-removed it

[alice-i-cecile]

Thanks!

[ChristopherBiscardi]

also @djeedai fwiw the length and content of this was informed by the length and content of other migration guides. I agree with @alice-i-cecile and do consider the new binned functionality to not just be a migration (migration would be to sorted, which is where "the previous functionality lives") but also an adoption of new functionality, thus I would expect implementing binning to require reading binning docs which should explain how to implement it (which they do not today imo, similar to most lower level rendering unfortunately).

The new custom_phase_item example does show the larger context and is linked in the migration so I leaned on that existing for people who need larger context around an example. The example does show how to get view entities, etc.