Crate bevy_mod_plotters

bevy_mod_plotters

A bevy game engine material to display the plotters BGRX texture format.

Motivation

The BGRX texture used by plotters is like a BGRA texture, but the plotters crate does not does not abstain from overwriting the ‘X’ byte, which for BGRA is the alpha channel, so one cannot rely on setting alpha once in the texture data but must assume it was changed after any render from plotters. This crate exists principally to avoid that alpha resetting problem and provide convenience methods.

Install

Install the crate.

cargo add bevy_mod_plotters

Usage

Add Plugin to App

use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(bevy_mod_plotters::PlottersPlugin)
        .run();
}

Create Image and Plot

use bevy_mod_plotters::prelude::*;
use plotters::prelude::*;
fn setup() -> Image {
    let mut image = Image::new_fill(
        Extent3d {
            width: 500,
            height: 500,
            depth_or_array_layers: 1,
        },
        TextureDimension::D2,
        &[0x00, 0x00, 0x00, 0x00],
        TextureFormat::Bgra8UnormSrgb,
        RenderAssetUsages::MAIN_WORLD | RenderAssetUsages::RENDER_WORLD,
    );
    
    {
        let root = try_as_backend(&mut image)
            .unwrap()
            .into_drawing_area();
        plot(&root)
            .unwrap();
    }
    image
}

fn plot<DB: DrawingBackend>(
    root: &DrawingArea<DB, Shift>,
) -> Result<(), DrawingAreaErrorKind<DB::ErrorType>> {

    let mut chart = ChartBuilder::on(&root)
        .caption("Hello, World!", ("sans-serif", 40).into_font())
        .build_cartesian_2d(-1.0..1.0, -1.0..1.0)?;

    let points = vec![(0.0, 0.0), (5.0, 5.0), (8.0, 7.0)];
    chart.draw_series(LineSeries::new(points, &RED))?;
    root.present()
}

Add Image as a PlotUiMaterial

fn add_image(
    In(image): In<Image>,
    mut commands: Commands,
    mut images: ResMut<Assets<Image>>,
    mut ui_materials: ResMut<Assets<PlotUiMaterial>>,
) {
    commands.spawn(Camera2dBundle::default());
    commands
        .spawn(NodeBundle {
            style: Style {
                width: Val::Percent(100.),
                height: Val::Percent(100.),
                justify_content: JustifyContent::Center,
                ..Default::default()
            },
            ..Default::default()
        })
        .with_children(|parent| {
            parent.spawn(MaterialNodeBundle {
                style: Style {
                    width: Val::Px(500.0),
                    height: Val::Px(500.0),
                    border: UiRect::all(Val::Px(20.0)),
                    ..default()
                },
                material: ui_materials.add(PlotUiMaterial {
                    color: LinearRgba::WHITE,
                    texture: images.add(image),
                }),
                ..default()
            });
        });
}

Examples

Run the “draw_graph” example like so:

cargo run --example draw_graph

This will show a red sphere with a light rotating around it and blue plane cut.

• draw_graph - Draw a plot of lines, hit ‘Space’ to update.
• anim_graph - Animate a sinusoidal wave.

TODO

Consider adding a plotters backend specifically for the BGRA8 formats that will not overwrite the alpha channel. A backend like that might be slightly slower for writing, but it would allow one to produce plots with a transparent background.

Compatibility

bevy_mod_plotters	bevy
0.1	0.14

License

This crate is licensed under the MIT License or the Apache License 2.0. The examples are licensed under the CC0 license.

Acknowlegments

• Thanks to Claire V. Hammond for the bevy_plotters_test repository.

Modules

prelude

prelude

Structs

PlotUiMaterial

The PlotUiMaterial renders a texture ignoring its alpha channel, so that it will be compatible with BGRXPixel format that plotters uses. Instead the alpha channel is taken from the given color field.

PlottersPlugin

A plugin to render BGRX images from plotters

Functions

try_as_backend

Convert an image into a plotters backend if possible.