bevy_framebuffer 0.1.0

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

# 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`.

```rust
// Add either the plugins below, or `DefaultPlugins`.
app.add_plugins((
    MinimalPlugins,
    WindowPlugin::default(),
    AccessibilityPlugin,
    WinitPlugin::<WakeUp>::default(),
));
// Configure `FrameBufferPlugin` with either `PixelsConfig` or `SoftBufferConfig`,
// depending on the enabled feature.
app.add_plugins(FrameBufferPlugin {
    config: PixelsConfig {
        width: 320,
        height: 180,
        ..Default::default()
    },
})
// Add a render system.
.add_systems(RenderSchedule, render_system);

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

This crate, by design, only adds `FrameBuffer<T>` as a resource and avoids
adding systems (including a render system) beyond that. This choice was made
to leave allow the user a degree of flexibility in how rendering and window
events are handled by the user, especially in relation to the divergent default
behaviour of `pixels` and `softbuffer`. See [`examples`] for how one might
implement basic functionality.

## Backends

This crate offers `pixels` and `softbuffer` as a framebuffer backend. Note that
the functionality of backends varies, and it is recommended to become familiar
with your backend of choice. `bevy_framebuffer` requires exactly **one** of the
following features to be enabled:

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.

```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` | `bevy_framebuffer`
---|---
0.15 | 0.1.0

License: MIT OR Apache-2.0