2D shapes and meshes
Draw circles, polygons and your own 2D meshes with Mesh2d and ColorMaterial, colour them, texture them, and write custom 2D materials.
On this page
Sprites draw images. For flat geometry, such as circles, polygons, rings or a custom outline, use a 2D mesh. A 2D mesh entity has two components:
| Component | What it holds |
|---|---|
Mesh2d(Handle<Mesh>) | The shape, as a mesh asset. |
MeshMaterial2d(Handle<M>) | How to colour it, as a material asset. ColorMaterial is the built-in one. |
Meshes and materials are assets: you add them to Assets<Mesh> and Assets<ColorMaterial> once and reuse the handles on as many entities as you like.
Draw a shape#
Shape primitives such as Circle convert into meshes, and colours convert into ColorMaterials, so add accepts them directly:
use neo::prelude::*;
fn setup(
mut commands: Commands,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<ColorMaterial>>,
) {
commands.spawn(Camera2d);
commands.spawn((
Mesh2d(meshes.add(Circle::new(50.0))),
MeshMaterial2d(materials.add(Color::srgb(0.9, 0.3, 0.2))),
Transform::from_xyz(-120.0, 0.0, 0.0),
));
commands.spawn((
Mesh2d(meshes.add(RegularPolygon::new(50.0, 6))),
MeshMaterial2d(materials.add(Color::srgb(0.2, 0.6, 0.9))),
Transform::from_xyz(120.0, 0.0, 0.0),
));
}2D primitives#
| Primitive | Constructor |
|---|---|
| Circle | Circle::new(radius) |
| Ellipse | Ellipse::new(half_width, half_height) |
| Annulus (a ring) | Annulus::new(inner_radius, outer_radius) |
| Circular sector and segment | CircularSector::new(radius, half_angle), CircularSegment::new(radius, half_angle) |
| Rectangle | Rectangle::new(width, height) |
| Rhombus | Rhombus::new(horizontal_diagonal, vertical_diagonal) |
| Regular polygon | RegularPolygon::new(circumradius, sides) |
| Triangle | Triangle2d::new(a, b, c) |
| Capsule | Capsule2d::new(radius, length) |
| Line segment and polyline | Segment2d::new(a, b), Polyline2d::new(points) |
Most shapes can also be drawn as an outline of a given thickness with .to_ring(thickness), for example Circle::new(50.0).to_ring(5.0). Ring::new(outer, inner) makes a ring from any two shapes.
The same primitives are used for maths and collision tests; see Math.
ColorMaterial#
| Field | What it does |
|---|---|
color | The fill colour, multiplied with the texture and any vertex colours. |
texture | Option<Handle<Image>>: an image mapped over the mesh's UVs. |
uv_transform | An Affine2 applied to the UVs: scale it to repeat a texture, or rotate and shift it. |
alpha_mode | AlphaMode2d::Opaque, Mask(threshold) or Blend. A material made from a colour is Opaque unless the colour's alpha is below 1.0. |
materials.add(image_handle) makes a white material with that texture.
Build your own mesh#
A Mesh is a list of vertex attributes plus, usually, indices. You can start from a primitive and add attributes, or build one from scratch:
let mut mesh = Mesh::from(Rectangle::default());
// one colour per corner, mixed across the face
mesh.insert_attribute(
Mesh::ATTRIBUTE_COLOR,
vec![
LinearRgba::RED.to_f32_array(),
LinearRgba::GREEN.to_f32_array(),
LinearRgba::BLUE.to_f32_array(),
LinearRgba::WHITE.to_f32_array(),
],
);
commands.spawn((
Mesh2d(meshes.add(mesh)),
MeshMaterial2d(materials.add(ColorMaterial::default())),
Transform::default().with_scale(Vec3::splat(128.0)),
));Meshes in general, including building one vertex by vertex, are covered in Meshes.
Custom 2D materials#
For effects ColorMaterial can't do, write a material: a struct that derives Asset, TypePath and AsBindGroup, implements Material2d and points at a shader. Register it with Material2dPlugin.
use neo::{
prelude::*,
reflect::TypePath,
render::render_resource::AsBindGroup,
shader::ShaderRef,
sprite_render::{AlphaMode2d, Material2d, Material2dPlugin},
};
#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
struct CustomMaterial {
#[uniform(0)]
color: LinearRgba,
#[texture(1)]
#[sampler(2)]
color_texture: Option<Handle<Image>>,
}
impl Material2d for CustomMaterial {
fn fragment_shader() -> ShaderRef {
"shaders/custom_material_2d.wesl".into()
}
fn alpha_mode(&self) -> AlphaMode2d {
AlphaMode2d::Mask(0.5)
}
}
// in main: app.add_plugins(Material2dPlugin::<CustomMaterial>::default());Spawn it like any material: MeshMaterial2d(custom_materials.add(CustomMaterial { .. })). Writing shaders is covered in Custom materials and shaders.
To change how sprites themselves are shaded, use SpriteMaterialPlugin with a MaterialExtension2d; the sprite_material example shows a dissolve effect.
Wireframes#
Wireframe2dPlugin (in neo::sprite_render) draws mesh edges, which helps when you're building meshes. It needs line polygon mode on the GPU, which WebGL 2 doesn't have, so it doesn't work in the browser.
Examples#
| Example | What it shows |
|---|---|
mesh2d | One rectangle mesh. |
2d_shapes | Every 2D primitive, filled and as rings. Needs --features neo_feathers for its toggles. |
mesh2d_vertex_color_texture | Vertex colours and a texture together. |
mesh2d_repeated_texture | uv_transform with a repeating sampler. |
mesh2d_arcs | UV mapping on sectors and segments. |
mesh2d_manual | A mesh drawn with lower-level renderer APIs. |
shader_material_2d | A custom Material2d. |
Run one from the engine core's workspace: cargo run --example mesh2d.