bevy_framebuffer/
lib.rs

1//! # Bevy FrameBuffer
2//! Bevy framebuffer rendering using `pixels` or `softbuffer`.
3//!
4//! ## Functionality
5//!
6//! `bevy` framebuffer rendering with the choice of either a `pixels` or `softbuffer`
7//!  pixel buffer backend. Just specify the backend as a feature, and access it with
8//! `NonSend` or `NonSendMut`.
9//!
10//! ### Example
11//!
12//! ```toml
13//! bevy = { version = "0.15.0", default-features = false }
14//! bevy_framebuffer = { version = "0.1.0", features = ["pixels"] }
15//! ```
16//!
17//! ```rust
18//! # #[cfg(all(feature = "pixels", feature = "schedule"))]
19//! # {
20//! # use bevy::prelude::*;
21//! # use bevy::a11y::AccessibilityPlugin;
22//! # use bevy::prelude::MinimalPlugins;
23//! # use bevy::window::WindowPlugin;
24//! # use bevy::winit::{WakeUp, WinitPlugin};
25//! # use bevy_framebuffer::FrameBufferPlugin;
26//! # use bevy_framebuffer::pixels_impl::*;
27//! # use bevy_framebuffer::schedule::RenderSchedule;
28//! # let mut app = App::new();
29//! // Add `DefaultPlugins` and either `PixelsPlugin` or `SoftbufferPlugin` to your project.
30//! app.add_plugins(
31//!     DefaultPlugins,
32//!     PixelsPlugin {
33//!         config: PixelsConfig {
34//!             width: 320,
35//!             height: 180,
36//!             ..Default::default()
37//!         },
38//! })
39//! // Add a render system.
40//! .add_systems(RenderSchedule, render_system);
41//!
42//! // Access the framebuffer in systems with `NonSend` or `NonSendMut`.
43//! pub fn render_system(buffer: NonSendMut<PixelsFrame>) {
44//!     buffer.render().unwrap();
45//! }
46//! # }
47//! ```
48//!
49//! This crate, by design, only adds `FrameBuffer<T>` (and the `PixelsFrame` and/or
50//! `SoftbufferFrame` aliases) as a resource and avoids adding any systems. This
51//! choice was made to highlight the divergent behaviour of both libraries
52//! (especially in relation to scaling/resizing) while also allowing the user a
53//! degree of flexibility in how events are handled, See [`examples`] for how one
54//! might implement basic systems.
55//!
56//! ## Backends
57//!
58//! This crate offers `pixels` and `softbuffer` as a framebuffer backend. **Neither**
59//! plugin is enabled by default and must be enabled explicitly. Note that the
60//! functionality of backends varies, and it is recommended to become familiar with
61//! your backend of choice.
62//!
63//! Feature | Description | Exposed Type
64//! ---|---|---
65//! `pixels` | Adds the [`pixels`] buffer as a backend. | [`pixels::Pixels`]
66//! `softbuffer` | Adds the [`softbuffer`] buffer as a backend. | [`softbuffer::Surface`]
67//!
68//! ## Schedules
69//!
70//! Two schedules are provided by `bevy_framebuffer`, `SurfaceSchedule` and `RenderSchedule`.
71//! Resizing/scaling operations should be run on the `SurfaceSchedule`, which runs *after*
72//! `PreUpdate`.  Rendering should be run on the `RenderSchedule` which runs *before* `Last`.
73//! These schedules are included with the default `schedule` feature, which can be
74//! disabled if needed.
75//!
76//! ## Examples
77//!
78//! Minimal examples are provided for both `softbuffer` and `pixels`, showing how one might
79//! approach scaling and rendering for the given backend. Note that resizing is handled
80//! differently for each example.
81//!
82//! ```bash
83//! # Run the `pixels` example.
84//! cargo run --example minimal_pixels --features="pixels"
85//! # Run the `softbuffer` example.
86//! cargo run --example minimal_softbuffer --features="softbuffer"
87//! ```
88//!
89//! ## Safety
90//!
91//! This crate uses `unsafe` to expose `raw_window_handler` implementations with
92//! the caveat that certain platforms do not support usage off of the main thread.
93//! As such, `bevy_framebuffer` enforces main thread access on **all** platforms,
94//! enforcing `FrameBuffer` as a `NonSend`/`NonSendMut` resource.
95//!
96//! ## Bevy compatability
97//!
98//! `bevy` | `pixels` | `softbuffer` | `bevy_framebuffer`
99//! ---|---|---|---
100//! 0.15 | 0.15 | 0.4 | 0.1 - 0.2
101pub mod framebuffer;
102pub mod plugin;
103
104pub use framebuffer::FrameBuffer;
105pub use plugin::*;
106
107#[cfg(feature = "schedule")]
108pub mod schedule;
109
110#[cfg(feature = "pixels")]
111pub use pixels;
112#[cfg(feature = "pixels")]
113pub mod pixels_impl;
114
115#[cfg(feature = "softbuffer")]
116pub use softbuffer;
117#[cfg(feature = "softbuffer")]
118pub mod softbuffer_impl;
bevy_framebuffer/lib.rs

bevy_framebuffer/
lib.rs
