Explanation for the '2d shapes' example (#19211)

[Explanation](https://bevyengine.org/learn/contribute/helping-out/explaining-examples/)
for the 2d shapes example, taken from the original HackMD document and
edited a bit.

This example is a strange one, it's eye-catching mostly because it's the
first example (at time of writing) in the examples page. That being
said, the example does a decent amount of teaching utility to it: we can
explain the bevy math-shape to mesh pipeline, which illuminates a way of
transforming one form of data (abstract, mathematical shape
descriptions) into another (meshes) which may be novel or inspirational
to some users.

---------

Co-authored-by: theotherphil <phil.j.ellison@gmail.com>
This commit is contained in:
Fallible Things 2025-05-26 20:21:01 +01:00 committed by GitHub
parent 1674938c49
commit cedf8d357a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -1,4 +1,14 @@
//! Shows how to render simple primitive shapes with a single color.
//! Here we use shape primitives to build meshes in a 2D rendering context, making each mesh a certain color by giving that mesh's entity a material based off a [`Color`].
//!
//! Meshes are better known for their use in 3D rendering, but we can use them in a 2D context too. Without a third dimension, the meshes we're building are flat like paper on a table. These are still very useful for "vector-style" graphics, picking behavior, or as a foundation to build off of for where to apply a shader.
//!
//! A "shape definition" is not a mesh on its own. A circle can be defined with a radius, i.e. [`Circle::new(50.0)`][Circle::new], but rendering tends to happen with meshes built out of triangles. So we need to turn shape descriptions into meshes.
//!
//! Thankfully, we can add shape primitives directly to [`Assets<Mesh>`] because [`Mesh`] implements [`From`] for shape primitives and [`Assets<T>::add`] can be given any value that can be "turned into" `T`!
//!
//! We apply a material to the shape by first making a [`Color`] then calling [`Assets<ColorMaterial>::add`] with that color as its argument, which will create a material from that color through the same process [`Assets<Mesh>::add`] can take a shape primitive.
//!
//! Both the mesh and material need to be wrapped in their own "newtypes". The mesh and material are currently [`Handle<Mesh>`] and [`Handle<ColorMaterial>`] at the moment, which are not components. Handles are put behind "newtypes" to prevent ambiguity, as some entities might want to have handles to meshes (or images, or materials etc.) for different purposes! All we need to do to make them rendering-relevant components is wrap the mesh handle and the material handle in [`Mesh2d`] and [`MeshMaterial2d`] respectively.
//!
//! You can toggle wireframes with the space bar except on wasm. Wasm does not support
//! `POLYGON_MODE_LINE` on the gpu.