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::{
#     prelude::*,
#     render::{
#         render_asset::RenderAssetUsages,
#         render_resource::{Extent3d, TextureDimension, TextureFormat},
#         texture::Image,
#     },
# };
# use plotters::coord::Shift;
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

# use bevy::{
#     prelude::*,
#     color::palettes::basic,
#     pbr::ExtendedMaterial,
# };
# use bevy_mod_plotters::*;
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

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.