bevy_framebuffer 0.3.1

Bevy framebuffer rendering using the `pixels` and `softbuffer` backends.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# bevy_framebuffer

## Bevy FrameBuffer
Bevy framebuffer rendering using `pixels` or `softbuffer`.

### Functionality

`bevy` framebuffer rendering with the choice of either a `pixels` or `softbuffer`
 pixel buffer backend. Just specify the backend as a feature, and access it with
`NonSend` or `NonSendMut`.

#### Example

```toml
bevy = { version = "0.16.0", default-features = false }
# Enable the `pixels` or `softbuffer` feature.
bevy_framebuffer = { version = "0.3.0", features = ["pixels"] }
```

```rust
let mut app = App::new();
// Add `DefaultPlugins` and either `PixelsPlugin` or `SoftbufferPlugin` to your project.
app.add_plugins(
    DefaultPlugins,
    PixelsPlugin {
        config: PixelsConfig {
            width: 320,
            height: 180,
            ..Default::default()
        },
})
// Add a render system.
.add_systems(RenderSchedule, render_system);

// Access the `PixelsFrame` or `SoftBufferFrame` in systems with `NonSend` or `NonSendMut`.
pub fn render_system(buffer: NonSendMut<PixelsFrame>) {
    buffer.render().unwrap();
}
```

This crate, by design, only adds `FrameBuffer<T>` (and the `PixelsFrame` and/or
`SoftbufferFrame` aliases) as a resource and avoids adding any systems. This
choice was made to highlight the divergent behaviour of both libraries
(especially in relation to scaling/resizing) while also allowing the user a
degree of flexibility in how events are handled, See [`examples`] for how one
might implement basic systems.

### Backends

This crate offers `pixels` and `softbuffer` as a framebuffer backend. **Neither**
plugin is enabled by default and must be enabled explicitly. Note that the
functionality of backends varies, and it is recommended to become familiar with
your backend of choice.

Feature | Description | Exposed Type
---|---|---
`pixels` | Adds the [`pixels`] buffer as a backend. | [`pixels::Pixels`]
`softbuffer` | Adds the [`softbuffer`] buffer as a backend. | [`softbuffer::Surface`]

### Schedules

Two schedules are provided by `bevy_framebuffer`, `SurfaceSchedule` and `RenderSchedule`.
Resizing/scaling operations should be run on the `SurfaceSchedule`, which runs *after*
`PreUpdate`.  Rendering should be run on the `RenderSchedule` which runs *before* `Last`.
These schedules are included with the default `schedule` feature, which can be
disabled if needed.

### Examples

Minimal examples are provided for both `softbuffer` and `pixels`, showing how one might
approach scaling and rendering for the given backend. Note that resizing is handled
differently for each example.

```bash
# Run the `pixels` example.
cargo run --example minimal_pixels --features="pixels"
# Run the `softbuffer` example.
cargo run --example minimal_softbuffer --features="softbuffer"
```

### Safety

This crate uses `unsafe` to expose `raw_window_handler` implementations with
the caveat that certain platforms do not support usage off of the main thread.
As such, `bevy_framebuffer` enforces main thread access on **all** platforms,
enforcing `FrameBuffer` as a `NonSend`/`NonSendMut` resource.

### Bevy compatability

`bevy` | `pixels` | `softbuffer` | `bevy_framebuffer`
---|---|---|---
0.16 | 0.15 | 0.4 | 0.3
0.15 | 0.15 | 0.4 | 0.2

License: MIT OR Apache-2.0