Add example for pixel-perfect grid snapping in 2D (#8112)

# Objective

Provide an example of how to achieve pixel-perfect "grid snapping" in 2D
via rendering to a texture. This is a common use case in retro pixel art
game development.

## Solution

Render sprites to a canvas via a Camera, then use another (scaled up)
Camera to render the resulting canvas to the screen. This example is
based on the `3d/render_to_texture.rs` example. Furthermore, this
example demonstrates mixing retro-style graphics with high-resolution
graphics, as well as pixel-snapped rendering of a
`MaterialMesh2dBundle`.
This commit is contained in:
Nurzhan Sakén 2023-12-26 21:15:50 +04:00 committed by GitHub
parent ac58a5fe57
commit 8067e46049
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 180 additions and 56 deletions

View file

@ -489,13 +489,12 @@ category = "2D Rendering"
wasm = true wasm = true
[[example]] [[example]]
name = "pixel_perfect" name = "pixel_grid_snap"
path = "examples/2d/pixel_perfect.rs" path = "examples/2d/pixel_grid_snap.rs"
doc-scrape-examples = true
[package.metadata.example.pixel_perfect] [package.metadata.example.pixel_grid_snap]
name = "Pixel Perfect" name = "Pixel Grid Snapping"
description = "Demonstrates pixel perfect in 2d" description = "Shows how to create graphics that snap to the pixel grid by rendering to a texture in 2D"
category = "2D Rendering" category = "2D Rendering"
wasm = true wasm = true

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.9 KiB

After

Width:  |  Height:  |  Size: 560 B

Binary file not shown.

Before

Width:  |  Height:  |  Size: 182 B

After

Width:  |  Height:  |  Size: 3.2 KiB

View file

@ -0,0 +1,174 @@
//! Shows how to create graphics that snap to the pixel grid by rendering to a texture in 2D
use bevy::{
prelude::*,
render::{
camera::RenderTarget,
render_resource::{
Extent3d, TextureDescriptor, TextureDimension, TextureFormat, TextureUsages,
},
view::RenderLayers,
},
sprite::MaterialMesh2dBundle,
window::WindowResized,
};
/// In-game resolution width.
const RES_WIDTH: u32 = 160;
/// In-game resolution height.
const RES_HEIGHT: u32 = 90;
/// Default render layers for pixel-perfect rendering.
/// You can skip adding this component, as this is the default.
const PIXEL_PERFECT_LAYERS: RenderLayers = RenderLayers::layer(0);
/// Render layers for high-resolution rendering.
const HIGH_RES_LAYERS: RenderLayers = RenderLayers::layer(1);
fn main() {
App::new()
.add_plugins(DefaultPlugins.set(ImagePlugin::default_nearest()))
.insert_resource(Msaa::Off)
.add_systems(Startup, (setup_camera, setup_sprite, setup_mesh))
.add_systems(Update, (rotate, fit_canvas))
.run();
}
/// Low-resolution texture that contains the pixel-perfect world.
/// Canvas itself is rendered to the high-resolution world.
#[derive(Component)]
struct Canvas;
/// Camera that renders the pixel-perfect world to the [`Canvas`].
#[derive(Component)]
struct InGameCamera;
/// Camera that renders the [`Canvas`] (and other graphics on [`HIGH_RES_LAYERS`]) to the screen.
#[derive(Component)]
struct OuterCamera;
#[derive(Component)]
struct Rotate;
fn setup_sprite(mut commands: Commands, asset_server: Res<AssetServer>) {
// the sample sprite that will be rendered to the pixel-perfect canvas
commands.spawn((
SpriteBundle {
texture: asset_server.load("pixel/bevy_pixel_dark.png"),
transform: Transform::from_xyz(-40., 20., 2.),
..default()
},
Rotate,
PIXEL_PERFECT_LAYERS,
));
// the sample sprite that will be rendered to the high-res "outer world"
commands.spawn((
SpriteBundle {
texture: asset_server.load("pixel/bevy_pixel_light.png"),
transform: Transform::from_xyz(-40., -20., 2.),
..default()
},
Rotate,
HIGH_RES_LAYERS,
));
}
/// Spawns a capsule mesh on the pixel-perfect layer.
fn setup_mesh(
mut commands: Commands,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<ColorMaterial>>,
) {
commands.spawn((
MaterialMesh2dBundle {
mesh: meshes.add(Mesh::from(shape::Capsule::default())).into(),
transform: Transform::from_xyz(40., 0., 2.).with_scale(Vec3::splat(32.)),
material: materials.add(ColorMaterial::from(Color::BLACK)),
..default()
},
Rotate,
PIXEL_PERFECT_LAYERS,
));
}
fn setup_camera(mut commands: Commands, mut images: ResMut<Assets<Image>>) {
let canvas_size = Extent3d {
width: RES_WIDTH,
height: RES_HEIGHT,
..default()
};
// this Image serves as a canvas representing the low-resolution game screen
let mut canvas = Image {
texture_descriptor: TextureDescriptor {
label: None,
size: canvas_size,
dimension: TextureDimension::D2,
format: TextureFormat::Bgra8UnormSrgb,
mip_level_count: 1,
sample_count: 1,
usage: TextureUsages::TEXTURE_BINDING
| TextureUsages::COPY_DST
| TextureUsages::RENDER_ATTACHMENT,
view_formats: &[],
},
..default()
};
// fill image.data with zeroes
canvas.resize(canvas_size);
let image_handle = images.add(canvas);
// this camera renders whatever is on `PIXEL_PERFECT_LAYERS` to the canvas
commands.spawn((
Camera2dBundle {
camera: Camera {
// render before the "main pass" camera
order: -1,
target: RenderTarget::Image(image_handle.clone()),
..default()
},
..default()
},
InGameCamera,
PIXEL_PERFECT_LAYERS,
));
// spawn the canvas
commands.spawn((
SpriteBundle {
texture: image_handle,
..default()
},
Canvas,
HIGH_RES_LAYERS,
));
// the "outer" camera renders whatever is on `HIGH_RES_LAYERS` to the screen.
// here, the canvas and one of the sample sprites will be rendered by this camera
commands.spawn((Camera2dBundle::default(), OuterCamera, HIGH_RES_LAYERS));
}
/// Rotates entities to demonstrate grid snapping.
fn rotate(time: Res<Time>, mut transforms: Query<&mut Transform, With<Rotate>>) {
for mut transform in &mut transforms {
let dt = time.delta_seconds();
transform.rotate_z(dt);
}
}
/// Scales camera projection to fit the window (integer multiples only).
fn fit_canvas(
mut resize_events: EventReader<WindowResized>,
mut projections: Query<&mut OrthographicProjection, With<OuterCamera>>,
) {
for event in resize_events.read() {
let h_scale = event.width / RES_WIDTH as f32;
let v_scale = event.height / RES_HEIGHT as f32;
let mut projection = projections.single_mut();
projection.scale = 1. / h_scale.min(v_scale).round();
}
}

View file

@ -1,49 +0,0 @@
//! Renders a 2D scene containing pixelated bevy logo in a pixel perfect style
use bevy::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins.set(
// This sets image filtering to nearest
// This is done to prevent textures with low resolution (e.g. pixel art) from being blurred
// by linear filtering.
ImagePlugin::default_nearest(),
))
.add_systems(Startup, setup)
.add_systems(Update, sprite_movement)
.run();
}
#[derive(Component)]
enum Direction {
Left,
Right,
}
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
commands.spawn(Camera2dBundle::default());
commands.spawn((
SpriteBundle {
texture: asset_server.load("pixel/bevy_pixel_dark.png"),
transform: Transform::from_xyz(100., 0., 0.),
..default()
},
Direction::Right,
));
}
fn sprite_movement(time: Res<Time>, mut sprite_position: Query<(&mut Direction, &mut Transform)>) {
for (mut logo, mut transform) in &mut sprite_position {
match *logo {
Direction::Right => transform.translation.x += 30. * time.delta_seconds(),
Direction::Left => transform.translation.x -= 30. * time.delta_seconds(),
}
if transform.translation.x > 200. {
*logo = Direction::Left;
} else if transform.translation.x < -200. {
*logo = Direction::Right;
}
}
}

View file

@ -102,7 +102,7 @@ Example | Description
[Mesh 2D](../examples/2d/mesh2d.rs) | Renders a 2d mesh [Mesh 2D](../examples/2d/mesh2d.rs) | Renders a 2d mesh
[Mesh 2D With Vertex Colors](../examples/2d/mesh2d_vertex_color_texture.rs) | Renders a 2d mesh with vertex color attributes [Mesh 2D With Vertex Colors](../examples/2d/mesh2d_vertex_color_texture.rs) | Renders a 2d mesh with vertex color attributes
[Move Sprite](../examples/2d/move_sprite.rs) | Changes the transform of a sprite [Move Sprite](../examples/2d/move_sprite.rs) | Changes the transform of a sprite
[Pixel Perfect](../examples/2d/pixel_perfect.rs) | Demonstrates pixel perfect in 2d [Pixel Grid Snapping](../examples/2d/pixel_grid_snap.rs) | Shows how to create graphics that snap to the pixel grid by rendering to a texture in 2D
[Sprite](../examples/2d/sprite.rs) | Renders a sprite [Sprite](../examples/2d/sprite.rs) | Renders a sprite
[Sprite Flipping](../examples/2d/sprite_flipping.rs) | Renders a sprite flipped along an axis [Sprite Flipping](../examples/2d/sprite_flipping.rs) | Renders a sprite flipped along an axis
[Sprite Sheet](../examples/2d/sprite_sheet.rs) | Renders an animated sprite [Sprite Sheet](../examples/2d/sprite_sheet.rs) | Renders an animated sprite