bevy/Cargo.toml

1927 lines
49 KiB
TOML
Raw Normal View History

2019-11-13 03:36:02 +00:00
[package]
name = "bevy"
version = "0.11.0-dev"
edition = "2021"
categories = ["game-engines", "graphics", "gui", "rendering"]
2020-08-10 00:24:27 +00:00
description = "A refreshingly simple data-driven game engine and app framework"
exclude = ["assets/", "tools/", ".github/", "crates/", "examples/wasm/assets/"]
2020-08-10 00:24:27 +00:00
homepage = "https://bevyengine.org"
keywords = ["game", "engine", "gamedev", "graphics", "bevy"]
Relicense Bevy under the dual MIT or Apache-2.0 license (#2509) This relicenses Bevy under the dual MIT or Apache-2.0 license. For rationale, see #2373. * Changes the LICENSE file to describe the dual license. Moved the MIT license to docs/LICENSE-MIT. Added the Apache-2.0 license to docs/LICENSE-APACHE. I opted for this approach over dumping both license files at the root (the more common approach) for a number of reasons: * Github links to the "first" license file (LICENSE-APACHE) in its license links (you can see this in the wgpu and rust-analyzer repos). People clicking these links might erroneously think that the apache license is the only option. Rust and Amethyst both use COPYRIGHT or COPYING files to solve this problem, but this creates more file noise (if you do everything at the root) and the naming feels way less intuitive. * People have a reflex to look for a LICENSE file. By providing a single license file at the root, we make it easy for them to understand our licensing approach. * I like keeping the root clean and noise free * There is precedent for putting the apache and mit license text in sub folders (amethyst) * Removed the `Copyright (c) 2020 Carter Anderson` copyright notice from the MIT license. I don't care about this attribution, it might make license compliance more difficult in some cases, and it didn't properly attribute other contributors. We shoudn't replace it with something like "Copyright (c) 2021 Bevy Contributors" because "Bevy Contributors" is not a legal entity. Instead, we just won't include the copyright line (which has precedent ... Rust also uses this approach). * Updates crates to use the new "MIT OR Apache-2.0" license value * Removes the old legion-transform license file from bevy_transform. bevy_transform has been its own, fully custom implementation for a long time and that license no longer applies. * Added a License section to the main readme * Updated our Bevy Plugin licensing guidelines. As a follow-up we should update the website to properly describe the new license. Closes #2373
2021-07-23 21:11:51 +00:00
license = "MIT OR Apache-2.0"
readme = "README.md"
repository = "https://github.com/bevyengine/bevy"
rust-version = "1.67.0"
[workspace]
exclude = [
"benches",
"crates/bevy_ecs_compile_fail_tests",
"crates/bevy_reflect_compile_fail_tests",
]
members = [
"crates/*",
"examples/mobile",
"tools/ci",
"tools/build-templated-pages",
"tools/build-wasm-example",
"errors",
]
2019-11-13 03:36:02 +00:00
2020-03-11 05:20:49 +00:00
[features]
default = [
"animation",
"bevy_asset",
"bevy_audio",
"bevy_gilrs",
"bevy_scene",
"bevy_winit",
"bevy_core_pipeline",
"bevy_pbr",
"bevy_gltf",
"bevy_render",
"bevy_sprite",
"bevy_text",
"bevy_ui",
"png",
"hdr",
"ktx2",
"zstd",
"vorbis",
"x11",
"filesystem_watcher",
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
"bevy_gizmos",
"android_shared_stdcxx",
Revamp Bloom (#6677) ![image](https://user-images.githubusercontent.com/47158642/220197588-25e11022-02e4-45f3-b2e5-392c4ce7a025.png) Huge credit to @StarLederer, who did almost all of the work on this. We're just reusing this PR to keep everything in one place. # Objective 1. Make bloom more physically based. 1. Improve artistic control. 1. Allow to use bloom as screen blur. 1. Fix #6634. 1. Address #6655 (although the author makes incorrect conclusions). ## Solution 1. Set the default threshold to 0. 2. Lerp between bloom textures when `composite_mode: BloomCompositeMode::EnergyConserving`. 1. Use [a parametric function](https://starlederer.github.io/bloom) to control blend levels for each bloom texture. In the future this can be controlled per-pixel for things like lens dirt. 3. Implement BloomCompositeMode::Additive` for situations where the old school look is desired. ## Changelog * Bloom now looks different. * Added `BloomSettings:lf_boost`, `BloomSettings:lf_boost_curvature`, `BloomSettings::high_pass_frequency` and `BloomSettings::composite_mode`. * `BloomSettings::scale` removed. * `BloomSettings::knee` renamed to `BloomPrefilterSettings::softness`. * `BloomSettings::threshold` renamed to `BloomPrefilterSettings::threshold`. * The bloom example has been renamed to bloom_3d and improved. A bloom_2d example was added. ## Migration Guide * Refactor mentions of `BloomSettings::knee` and `BloomSettings::threshold` as `BloomSettings::prefilter_settings` where knee is now `softness`. * If defined without `..default()` add `..default()` to definitions of `BloomSettings` instances or manually define missing fields. * Adapt to Bloom looking visually different (if needed). Co-authored-by: Herman Lederer <germans.lederers@gmail.com>
2023-03-04 12:05:26 +00:00
"tonemapping_luts",
]
# Force dynamic linking, which improves iterative compile times
dynamic_linking = ["bevy_dylib", "bevy_internal/dynamic_linking"]
# Provides animation functionality
bevy_animation = ["bevy_internal/bevy_animation"]
# Provides asset functionality
bevy_asset = ["bevy_internal/bevy_asset"]
# Provides audio functionality
bevy_audio = ["bevy_internal/bevy_audio"]
# Provides cameras and other basic render pipeline features
bevy_core_pipeline = ["bevy_internal/bevy_core_pipeline", "bevy_asset", "bevy_render"]
# Plugin for dynamic loading (using [libloading](https://crates.io/crates/libloading))
bevy_dynamic_plugin = ["bevy_internal/bevy_dynamic_plugin"]
# Adds gamepad support
bevy_gilrs = ["bevy_internal/bevy_gilrs"]
# [glTF](https://www.khronos.org/gltf/) support
bevy_gltf = ["bevy_internal/bevy_gltf", "bevy_asset", "bevy_scene", "bevy_pbr"]
# Adds PBR rendering
bevy_pbr = ["bevy_internal/bevy_pbr", "bevy_asset", "bevy_render", "bevy_core_pipeline"]
# Provides rendering functionality
bevy_render = ["bevy_internal/bevy_render"]
# Provides scene functionality
bevy_scene = ["bevy_internal/bevy_scene", "bevy_asset"]
# Provides sprite functionality
bevy_sprite = ["bevy_internal/bevy_sprite", "bevy_render", "bevy_core_pipeline"]
# Provides text functionality
bevy_text = ["bevy_internal/bevy_text"]
# A custom ECS-driven UI framework
bevy_ui = ["bevy_internal/bevy_ui", "bevy_core_pipeline", "bevy_text", "bevy_sprite"]
# winit window and input backend
bevy_winit = ["bevy_internal/bevy_winit"]
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
# Adds support for rendering gizmos
bevy_gizmos = ["bevy_internal/bevy_gizmos"]
# Tracing support, saving a file in Chrome Tracing format
trace_chrome = ["trace", "bevy_internal/trace_chrome"]
# Tracing support, exposing a port for Tracy
trace_tracy = ["trace", "bevy_internal/trace_tracy"]
# Tracing support
trace = ["bevy_internal/trace"]
# Save a trace of all wgpu calls
wgpu_trace = ["bevy_internal/wgpu_trace"]
# EXR image format support
exr = ["bevy_internal/exr"]
# HDR image format support
hdr = ["bevy_internal/hdr"]
# PNG image format support
png = ["bevy_internal/png"]
# TGA image format support
tga = ["bevy_internal/tga"]
# JPEG image format support
jpeg = ["bevy_internal/jpeg"]
# BMP image format support
bmp = ["bevy_internal/bmp"]
# Basis Universal compressed texture support
basis-universal = ["bevy_internal/basis-universal"]
# DDS compressed texture support
dds = ["bevy_internal/dds"]
# KTX2 compressed texture support
ktx2 = ["bevy_internal/ktx2"]
# For KTX2 supercompression
zlib = ["bevy_internal/zlib"]
# For KTX2 supercompression
zstd = ["bevy_internal/zstd"]
# FLAC audio format support
flac = ["bevy_internal/flac"]
# MP3 audio format support
mp3 = ["bevy_internal/mp3"]
# OGG/VORBIS audio format support
vorbis = ["bevy_internal/vorbis"]
# WAV audio format support
wav = ["bevy_internal/wav"]
# MP3 audio format support (through minimp3)
minimp3 = ["bevy_internal/minimp3"]
# AAC audio format support (through symphonia)
symphonia-aac = ["bevy_internal/symphonia-aac"]
# AAC, FLAC, MP3, MP4, OGG/VORBIS, and WAV audio formats support (through symphonia)
symphonia-all = ["bevy_internal/symphonia-all"]
# FLAC audio format support (through symphonia)
symphonia-flac = ["bevy_internal/symphonia-flac"]
# MP4 audio format support (through symphonia)
symphonia-isomp4 = ["bevy_internal/symphonia-isomp4"]
# OGG/VORBIS audio format support (through symphonia)
symphonia-vorbis = ["bevy_internal/symphonia-vorbis"]
# WAV audio format support (through symphonia)
symphonia-wav = ["bevy_internal/symphonia-wav"]
# Enable watching file system for asset hot reload
filesystem_watcher = ["bevy_internal/filesystem_watcher"]
# Enable serialization support through serde
serialize = ["bevy_internal/serialize"]
# Wayland display server support
wayland = ["bevy_internal/wayland"]
# X11 display server support
x11 = ["bevy_internal/x11"]
2020-05-06 01:44:32 +00:00
# Enable rendering of font glyphs using subpixel accuracy
subpixel_glyph_atlas = ["bevy_internal/subpixel_glyph_atlas"]
# Enable systems that allow for automated testing on CI
bevy_ci_testing = ["bevy_internal/bevy_ci_testing"]
# Enable the "debug asset server" for hot reloading internal assets
debug_asset_server = ["bevy_internal/debug_asset_server"]
# Enable animation support, and glTF animation loading
animation = ["bevy_internal/animation", "bevy_animation"]
# Enable using a shared stdlib for cxx on Android
android_shared_stdcxx = ["bevy_internal/android_shared_stdcxx"]
# Enable detailed trace event logging. These trace events are expensive even when off, thus they require compile time opt-in
Introduce detailed_trace macro, use in TrackedRenderPass (#7639) Profiles show that in extremely hot loops, like the draw loops in the renderer, invoking the trace! macro has noticeable overhead, even if the trace log level is not enabled. Solve this by introduce a 'wrapper' detailed_trace macro around trace, that wraps the trace! log statement in a trivially false if statement unless a cargo feature is enabled # Objective - Eliminate significant overhead observed with trace-level logging in render hot loops, even when trace log level is not enabled. - This is an alternative solution to the one proposed in #7223 ## Solution - Introduce a wrapper around the `trace!` macro called `detailed_trace!`. This macro wraps the `trace!` macro with an if statement that is conditional on a new cargo feature, `detailed_trace`. When the feature is not enabled (the default), then the if statement is trivially false and should be optimized away at compile time. - Convert the observed hot occurrences of trace logging in `TrackedRenderPass` with this new macro. Testing the results of ``` cargo run --profile stress-test --features bevy/trace_tracy --example many_cubes -- spheres ``` ![image](https://user-images.githubusercontent.com/1222141/218298552-38551717-b062-4c64-afdc-a60267ac984d.png) shows significant improvement of the `main_opaque_pass_3d` of the renderer, a median time decrease from 6.0ms to 3.5ms. --- ## Changelog - For performance reasons, some detailed renderer trace logs now require the use of cargo feature `detailed_trace` in addition to setting the log level to `TRACE` in order to be shown. ## Migration Guide - Some detailed bevy trace events now require the use of the cargo feature `detailed_trace` in addition to enabling `TRACE` level logging to view. Should you wish to see these logs, please compile your code with the bevy feature `detailed_trace`. Currently, the only logs that are affected are the renderer logs pertaining to `TrackedRenderPass` functions
2023-02-13 18:20:27 +00:00
detailed_trace = ["bevy_internal/detailed_trace"]
# Include tonemapping Look Up Tables KTX2 files
tonemapping_luts = ["bevy_internal/tonemapping_luts"]
# Enable AccessKit on Unix backends (currently only works with experimental screen readers and forks.)
accesskit_unix = ["bevy_internal/accesskit_unix"]
2019-11-13 03:36:02 +00:00
[dependencies]
bevy_dylib = { path = "crates/bevy_dylib", version = "0.11.0-dev", default-features = false, optional = true }
bevy_internal = { path = "crates/bevy_internal", version = "0.11.0-dev", default-features = false }
2020-04-06 03:19:02 +00:00
[target.'cfg(target_arch = "wasm32")'.dependencies]
bevy_internal = { path = "crates/bevy_internal", version = "0.11.0-dev", default-features = false, features = [
Reduce power usage with configurable event loop (#3974) # Objective - Reduce power usage for games when not focused. - Reduce power usage to ~0 when a desktop application is minimized (opt-in). - Reduce power usage when focused, only updating on a `winit` event, or the user sends a redraw request. (opt-in) https://user-images.githubusercontent.com/2632925/156904387-ec47d7de-7f06-4c6f-8aaf-1e952c1153a2.mp4 Note resource usage in the Task Manager in the above video. ## Solution - Added a type `UpdateMode` that allows users to specify how the winit event loop is updated, without exposing winit types. - Added two fields to `WinitConfig`, both with the `UpdateMode` type. One configures how the application updates when focused, and the other configures how the application behaves when it is not focused. Users can modify this resource manually to set the type of event loop control flow they want. - For convenience, two functions were added to `WinitConfig`, that provide reasonable presets: `game()` (default) and `desktop_app()`. - The `game()` preset, which is used by default, is unchanged from current behavior with one exception: when the app is out of focus the app updates at a minimum of 10fps, or every time a winit event is received. This has a huge positive impact on power use and responsiveness on my machine, which will otherwise continue running the app at many hundreds of fps when out of focus or minimized. - The `desktop_app()` preset is fully reactive, only updating when user input (winit event) is supplied or a `RedrawRequest` event is sent. When the app is out of focus, it only updates on `Window` events - i.e. any winit event that directly interacts with the window. What this means in practice is that the app uses *zero* resources when minimized or not interacted with, but still updates fluidly when the app is out of focus and the user mouses over the application. - Added a `RedrawRequest` event so users can force an update even if there are no events. This is useful in an application when you want to, say, run an animation even when the user isn't providing input. - Added an example `low_power` to demonstrate these changes ## Usage Configuring the event loop: ```rs use bevy::winit::{WinitConfig}; // ... .insert_resource(WinitConfig::desktop_app()) // preset // or .insert_resource(WinitConfig::game()) // preset // or .insert_resource(WinitConfig{ .. }) // manual ``` Requesting a redraw: ```rs use bevy::window::RequestRedraw; // ... fn request_redraw(mut event: EventWriter<RequestRedraw>) { event.send(RequestRedraw); } ``` ## Other details - Because we have a single event loop for multiple windows, every time I've mentioned "focused" above, I more precisely mean, "if at least one bevy window is focused". - Due to a platform bug in winit (https://github.com/rust-windowing/winit/issues/1619), we can't simply use `Window::request_redraw()`. As a workaround, this PR will temporarily set the window mode to `Poll` when a redraw is requested. This is then reset to the user's `WinitConfig` setting on the next frame.
2022-03-07 23:32:05 +00:00
"webgl",
] }
2020-04-06 03:19:02 +00:00
[dev-dependencies]
anyhow = "1.0.4"
rand = "0.8.0"
ron = "0.8.0"
serde = { version = "1", features = ["derive"] }
bytemuck = "1.7"
# Needed to poll Task examples
futures-lite = "1.11.3"
crossbeam-channel = "0.5.0"
2020-05-01 20:12:47 +00:00
[[example]]
name = "hello_world"
path = "examples/hello_world.rs"
[package.metadata.example.hello_world]
hidden = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# 2D Rendering
Revamp Bloom (#6677) ![image](https://user-images.githubusercontent.com/47158642/220197588-25e11022-02e4-45f3-b2e5-392c4ce7a025.png) Huge credit to @StarLederer, who did almost all of the work on this. We're just reusing this PR to keep everything in one place. # Objective 1. Make bloom more physically based. 1. Improve artistic control. 1. Allow to use bloom as screen blur. 1. Fix #6634. 1. Address #6655 (although the author makes incorrect conclusions). ## Solution 1. Set the default threshold to 0. 2. Lerp between bloom textures when `composite_mode: BloomCompositeMode::EnergyConserving`. 1. Use [a parametric function](https://starlederer.github.io/bloom) to control blend levels for each bloom texture. In the future this can be controlled per-pixel for things like lens dirt. 3. Implement BloomCompositeMode::Additive` for situations where the old school look is desired. ## Changelog * Bloom now looks different. * Added `BloomSettings:lf_boost`, `BloomSettings:lf_boost_curvature`, `BloomSettings::high_pass_frequency` and `BloomSettings::composite_mode`. * `BloomSettings::scale` removed. * `BloomSettings::knee` renamed to `BloomPrefilterSettings::softness`. * `BloomSettings::threshold` renamed to `BloomPrefilterSettings::threshold`. * The bloom example has been renamed to bloom_3d and improved. A bloom_2d example was added. ## Migration Guide * Refactor mentions of `BloomSettings::knee` and `BloomSettings::threshold` as `BloomSettings::prefilter_settings` where knee is now `softness`. * If defined without `..default()` add `..default()` to definitions of `BloomSettings` instances or manually define missing fields. * Adapt to Bloom looking visually different (if needed). Co-authored-by: Herman Lederer <germans.lederers@gmail.com>
2023-03-04 12:05:26 +00:00
[[example]]
name = "bloom_2d"
path = "examples/2d/bloom_2d.rs"
[package.metadata.example.bloom_2d]
name = "2D Bloom"
description = "Illustrates bloom post-processing in 2d"
category = "2D Rendering"
wasm = false
[[example]]
name = "move_sprite"
path = "examples/2d/move_sprite.rs"
[package.metadata.example.move_sprite]
name = "Move Sprite"
description = "Changes the transform of a sprite"
category = "2D Rendering"
wasm = true
[[example]]
name = "rotation"
path = "examples/2d/rotation.rs"
[package.metadata.example.rotation]
name = "2D Rotation"
description = "Demonstrates rotating entities in 2D with quaternions"
category = "2D Rendering"
wasm = true
[[example]]
name = "mesh2d"
path = "examples/2d/mesh2d.rs"
[package.metadata.example.mesh2d]
name = "Mesh 2D"
description = "Renders a 2d mesh"
category = "2D Rendering"
wasm = true
[[example]]
name = "mesh2d_manual"
path = "examples/2d/mesh2d_manual.rs"
[package.metadata.example.mesh2d_manual]
name = "Manual Mesh 2D"
description = "Renders a custom mesh \"manually\" with \"mid-level\" renderer apis"
category = "2D Rendering"
wasm = true
[[example]]
name = "mesh2d_vertex_color_texture"
path = "examples/2d/mesh2d_vertex_color_texture.rs"
[package.metadata.example.mesh2d_vertex_color_texture]
name = "Mesh 2D With Vertex Colors"
description = "Renders a 2d mesh with vertex color attributes"
category = "2D Rendering"
wasm = true
Add an example to draw a rectangle (#2957) # Objective Every time I come back to Bevy I face the same issue: how do I draw a rectangle again? How did that work? So I go to https://github.com/bevyengine/bevy/tree/main/examples in the hope of finding literally the simplest possible example that draws something on the screen without any dependency such as an image. I don't want to have to add some image first, I just quickly want to get something on the screen with `main.rs` alone so that I can continue building on from that point on. Such an example is particularly helpful for a quick start for smaller projects that don't even need any assets such as images (this is my case currently). Currently every single example of https://github.com/bevyengine/bevy/tree/main/examples#2d-rendering (which is the first section after hello world that beginners will look for for very minimalistic and quick examples) depends on at least an asset or is too complex. This PR solves this. It also serves as a great comparison for a beginner to realize what Bevy is really like and how different it is from what they may expect Bevy to be. For example for someone coming from [LÖVE](https://love2d.org/), they will have something like this in their head when they think of drawing a rectangle: ```lua function love.draw() love.graphics.setColor(0.25, 0.25, 0.75); love.graphics.rectangle("fill", 0, 0, 50, 50); end ``` This, of course, differs quite a lot from what you do in Bevy. I imagine there will be people that just want to see something as simple as this in comparison to have a better understanding for the amount of differences. ## Solution Add a dead simple example drawing a blue 50x50 rectangle in the center with no more and no less than needed.
2021-12-18 00:52:37 +00:00
[[example]]
name = "2d_shapes"
path = "examples/2d/2d_shapes.rs"
Add an example to draw a rectangle (#2957) # Objective Every time I come back to Bevy I face the same issue: how do I draw a rectangle again? How did that work? So I go to https://github.com/bevyengine/bevy/tree/main/examples in the hope of finding literally the simplest possible example that draws something on the screen without any dependency such as an image. I don't want to have to add some image first, I just quickly want to get something on the screen with `main.rs` alone so that I can continue building on from that point on. Such an example is particularly helpful for a quick start for smaller projects that don't even need any assets such as images (this is my case currently). Currently every single example of https://github.com/bevyengine/bevy/tree/main/examples#2d-rendering (which is the first section after hello world that beginners will look for for very minimalistic and quick examples) depends on at least an asset or is too complex. This PR solves this. It also serves as a great comparison for a beginner to realize what Bevy is really like and how different it is from what they may expect Bevy to be. For example for someone coming from [LÖVE](https://love2d.org/), they will have something like this in their head when they think of drawing a rectangle: ```lua function love.draw() love.graphics.setColor(0.25, 0.25, 0.75); love.graphics.rectangle("fill", 0, 0, 50, 50); end ``` This, of course, differs quite a lot from what you do in Bevy. I imagine there will be people that just want to see something as simple as this in comparison to have a better understanding for the amount of differences. ## Solution Add a dead simple example drawing a blue 50x50 rectangle in the center with no more and no less than needed.
2021-12-18 00:52:37 +00:00
[package.metadata.example.2d_shapes]
name = "2D Shapes"
description = "Renders a rectangle, circle, and hexagon"
category = "2D Rendering"
wasm = true
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
[[example]]
name = "2d_gizmos"
path = "examples/2d/2d_gizmos.rs"
[package.metadata.example.2d_gizmos]
name = "2D Gizmos"
description = "A scene showcasing 2D gizmos"
category = "2D Rendering"
wasm = true
2020-05-04 08:22:25 +00:00
[[example]]
name = "sprite"
path = "examples/2d/sprite.rs"
[package.metadata.example.sprite]
name = "Sprite"
description = "Renders a sprite"
category = "2D Rendering"
wasm = true
Add Sprite Flipping (#1407) OK, here's my attempt at sprite flipping. There are a couple of points that I need review/help on, but I think the UX is about ideal: ```rust .spawn(SpriteBundle { material: materials.add(texture_handle.into()), sprite: Sprite { // Flip the sprite along the x axis flip: SpriteFlip { x: true, y: false }, ..Default::default() }, ..Default::default() }); ``` Now for the issues. The big issue is that for some reason, when flipping the UVs on the sprite, there is a light "bleeding" or whatever you call it where the UV tries to sample past the texture boundry and ends up clipping. This is only noticed when resizing the window, though. You can see a screenshot below. ![image](https://user-images.githubusercontent.com/25393315/107098172-397aaa00-67d4-11eb-8e02-c90c820cd70e.png) I am quite baffled why the texture sampling is overrunning like it is and could use some guidance if anybody knows what might be wrong. The other issue, which I just worked around, is that I had to remove the `#[render_resources(from_self)]` annotation from the Spritesheet because the `SpriteFlip` render resource wasn't being picked up properly in the shader when using it. I'm not sure what the cause of that was, but by removing the annotation and re-organizing the shader inputs accordingly the problem was fixed. I'm not sure if this is the most efficient way to do this or if there is a better way, but I wanted to try it out if only for the learning experience. Let me know what you think!
2021-03-03 19:26:45 +00:00
[[example]]
name = "sprite_flipping"
path = "examples/2d/sprite_flipping.rs"
[package.metadata.example.sprite_flipping]
name = "Sprite Flipping"
description = "Renders a sprite flipped along an axis"
category = "2D Rendering"
wasm = true
[[example]]
name = "sprite_sheet"
path = "examples/2d/sprite_sheet.rs"
[package.metadata.example.sprite_sheet]
name = "Sprite Sheet"
description = "Renders an animated sprite"
category = "2D Rendering"
wasm = true
[[example]]
name = "text2d"
path = "examples/2d/text2d.rs"
[package.metadata.example.text2d]
name = "Text 2D"
description = "Generates text in 2D"
category = "2D Rendering"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "texture_atlas"
path = "examples/2d/texture_atlas.rs"
[package.metadata.example.texture_atlas]
name = "Texture Atlas"
description = "Generates a texture atlas (sprite sheet) from individual sprites"
category = "2D Rendering"
wasm = true
[[example]]
name = "transparency_2d"
path = "examples/2d/transparency_2d.rs"
[package.metadata.example.transparency_2d]
name = "Transparency in 2D"
description = "Demonstrates transparency in 2d"
category = "2D Rendering"
wasm = true
[[example]]
name = "pixel_perfect"
path = "examples/2d/pixel_perfect.rs"
[package.metadata.example.pixel_perfect]
name = "Pixel Perfect"
description = "Demonstrates pixel perfect in 2d"
category = "2D Rendering"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# 3D Rendering
[[example]]
name = "3d_scene"
path = "examples/3d/3d_scene.rs"
[package.metadata.example.3d_scene]
name = "3D Scene"
description = "Simple 3D scene with basic shapes and lighting"
category = "3D Rendering"
wasm = true
Camera Driven Viewports (#4898) # Objective Users should be able to render cameras to specific areas of a render target, which enables scenarios like split screen, minimaps, etc. Builds on the new Camera Driven Rendering added here: #4745 Fixes: #202 Alternative to #1389 and #3626 (which are incompatible with the new Camera Driven Rendering) ## Solution ![image](https://user-images.githubusercontent.com/2694663/171560044-f0694f67-0cd9-4598-83e2-a9658c4fed57.png) Cameras can now configure an optional "viewport", which defines a rectangle within their render target to draw to. If a `Viewport` is defined, the camera's `CameraProjection`, `View`, and visibility calculations will use the viewport configuration instead of the full render target. ```rust // This camera will render to the first half of the primary window (on the left side). commands.spawn_bundle(Camera3dBundle { camera: Camera { viewport: Some(Viewport { physical_position: UVec2::new(0, 0), physical_size: UVec2::new(window.physical_width() / 2, window.physical_height()), depth: 0.0..1.0, }), ..default() }, ..default() }); ``` To account for this, the `Camera` component has received a few adjustments: * `Camera` now has some new getter functions: * `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, `projection_matrix` * All computed camera values are now private and live on the `ComputedCameraValues` field (logical/physical width/height, the projection matrix). They are now exposed on `Camera` via getters/setters This wasn't _needed_ for viewports, but it was long overdue. --- ## Changelog ### Added * `Camera` components now have a `viewport` field, which can be set to draw to a portion of a render target instead of the full target. * `Camera` component has some new functions: `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, and `projection_matrix` * Added a new split_screen example illustrating how to render two cameras to the same scene ## Migration Guide `Camera::projection_matrix` is no longer a public field. Use the new `Camera::projection_matrix()` method instead: ```rust // Bevy 0.7 let projection = camera.projection_matrix; // Bevy 0.8 let projection = camera.projection_matrix(); ```
2022-06-05 00:27:49 +00:00
[[example]]
name = "3d_shapes"
path = "examples/3d/3d_shapes.rs"
Camera Driven Viewports (#4898) # Objective Users should be able to render cameras to specific areas of a render target, which enables scenarios like split screen, minimaps, etc. Builds on the new Camera Driven Rendering added here: #4745 Fixes: #202 Alternative to #1389 and #3626 (which are incompatible with the new Camera Driven Rendering) ## Solution ![image](https://user-images.githubusercontent.com/2694663/171560044-f0694f67-0cd9-4598-83e2-a9658c4fed57.png) Cameras can now configure an optional "viewport", which defines a rectangle within their render target to draw to. If a `Viewport` is defined, the camera's `CameraProjection`, `View`, and visibility calculations will use the viewport configuration instead of the full render target. ```rust // This camera will render to the first half of the primary window (on the left side). commands.spawn_bundle(Camera3dBundle { camera: Camera { viewport: Some(Viewport { physical_position: UVec2::new(0, 0), physical_size: UVec2::new(window.physical_width() / 2, window.physical_height()), depth: 0.0..1.0, }), ..default() }, ..default() }); ``` To account for this, the `Camera` component has received a few adjustments: * `Camera` now has some new getter functions: * `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, `projection_matrix` * All computed camera values are now private and live on the `ComputedCameraValues` field (logical/physical width/height, the projection matrix). They are now exposed on `Camera` via getters/setters This wasn't _needed_ for viewports, but it was long overdue. --- ## Changelog ### Added * `Camera` components now have a `viewport` field, which can be set to draw to a portion of a render target instead of the full target. * `Camera` component has some new functions: `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, and `projection_matrix` * Added a new split_screen example illustrating how to render two cameras to the same scene ## Migration Guide `Camera::projection_matrix` is no longer a public field. Use the new `Camera::projection_matrix()` method instead: ```rust // Bevy 0.7 let projection = camera.projection_matrix; // Bevy 0.8 let projection = camera.projection_matrix(); ```
2022-06-05 00:27:49 +00:00
[package.metadata.example.3d_shapes]
name = "3D Shapes"
description = "A scene showcasing the built-in 3D shapes"
category = "3D Rendering"
wasm = true
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
[[example]]
name = "3d_gizmos"
path = "examples/3d/3d_gizmos.rs"
[package.metadata.example.3d_gizmos]
name = "3D Gizmos"
description = "A scene showcasing 3D gizmos"
category = "3D Rendering"
wasm = true
Add Distance and Atmospheric Fog support (#6412) <img width="1392" alt="image" src="https://user-images.githubusercontent.com/418473/203873533-44c029af-13b7-4740-8ea3-af96bd5867c9.png"> <img width="1392" alt="image" src="https://user-images.githubusercontent.com/418473/203873549-36be7a23-b341-42a2-8a9f-ceea8ac7a2b8.png"> # Objective - Add support for the “classic” distance fog effect, as well as a more advanced atmospheric fog effect. ## Solution This PR: - Introduces a new `FogSettings` component that controls distance fog per-camera. - Adds support for three widely used “traditional” fog falloff modes: `Linear`, `Exponential` and `ExponentialSquared`, as well as a more advanced `Atmospheric` fog; - Adds support for directional light influence over fog color; - Extracts fog via `ExtractComponent`, then uses a prepare system that sets up a new dynamic uniform struct (`Fog`), similar to other mesh view types; - Renders fog in PBR material shader, as a final adjustment to the `output_color`, after PBR is computed (but before tone mapping); - Adds a new `StandardMaterial` flag to enable fog; (`fog_enabled`) - Adds convenience methods for easier artistic control when creating non-linear fog types; - Adds documentation around fog. --- ## Changelog ### Added - Added support for distance-based fog effects for PBR materials, controllable per-camera via the new `FogSettings` component; - Added `FogFalloff` enum for selecting between three widely used “traditional” fog falloff modes: `Linear`, `Exponential` and `ExponentialSquared`, as well as a more advanced `Atmospheric` fog;
2023-01-29 15:28:56 +00:00
[[example]]
name = "atmospheric_fog"
path = "examples/3d/atmospheric_fog.rs"
[package.metadata.example.atmospheric_fog]
name = "Atmospheric Fog"
description = "A scene showcasing the atmospheric fog effect"
category = "3D Rendering"
wasm = true
[[example]]
name = "fog"
path = "examples/3d/fog.rs"
[package.metadata.example.fog]
name = "Fog"
description = "A scene showcasing the distance fog effect"
category = "3D Rendering"
wasm = true
Standard Material Blend Modes (#6644) # Objective - This PR adds support for blend modes to the PBR `StandardMaterial`. <img width="1392" alt="Screenshot 2022-11-18 at 20 00 56" src="https://user-images.githubusercontent.com/418473/202820627-0636219a-a1e5-437a-b08b-b08c6856bf9c.png"> <img width="1392" alt="Screenshot 2022-11-18 at 20 01 01" src="https://user-images.githubusercontent.com/418473/202820615-c8d43301-9a57-49c4-bd21-4ae343c3e9ec.png"> ## Solution - The existing `AlphaMode` enum is extended, adding three more modes: `AlphaMode::Premultiplied`, `AlphaMode::Add` and `AlphaMode::Multiply`; - All new modes are rendered in the existing `Transparent3d` phase; - The existing mesh flags for alpha mode are reorganized for a more compact/efficient representation, and new values are added; - `MeshPipelineKey::TRANSPARENT_MAIN_PASS` is refactored into `MeshPipelineKey::BLEND_BITS`. - `AlphaMode::Opaque` and `AlphaMode::Mask(f32)` share a single opaque pipeline key: `MeshPipelineKey::BLEND_OPAQUE`; - `Blend`, `Premultiplied` and `Add` share a single premultiplied alpha pipeline key, `MeshPipelineKey::BLEND_PREMULTIPLIED_ALPHA`. In the shader, color values are premultiplied accordingly (or not) depending on the blend mode to produce the three different results after PBR/tone mapping/dithering; - `Multiply` uses its own independent pipeline key, `MeshPipelineKey::BLEND_MULTIPLY`; - Example and documentation are provided. --- ## Changelog ### Added - Added support for additive and multiplicative blend modes in the PBR `StandardMaterial`, via `AlphaMode::Add` and `AlphaMode::Multiply`; - Added support for premultiplied alpha in the PBR `StandardMaterial`, via `AlphaMode::Premultiplied`;
2023-01-21 21:46:53 +00:00
[[example]]
name = "blend_modes"
path = "examples/3d/blend_modes.rs"
[package.metadata.example.blend_modes]
name = "Blend Modes"
description = "Showcases different blend modes"
category = "3D Rendering"
wasm = true
2021-06-02 02:59:17 +00:00
[[example]]
name = "lighting"
path = "examples/3d/lighting.rs"
[package.metadata.example.lighting]
name = "Lighting"
description = "Illustrates various lighting options in a simple scene"
category = "3D Rendering"
wasm = true
[[example]]
name = "lines"
path = "examples/3d/lines.rs"
[package.metadata.example.lines]
name = "Lines"
description = "Create a custom material to draw 3d lines"
category = "3D Rendering"
wasm = true
Spotlights (#4715) # Objective add spotlight support ## Solution / Changelog - add spotlight angles (inner, outer) to ``PointLight`` struct. emitted light is linearly attenuated from 100% to 0% as angle tends from inner to outer. Direction is taken from the existing transform rotation. - add spotlight direction (vec3) and angles (f32,f32) to ``GpuPointLight`` struct (60 bytes -> 80 bytes) in ``pbr/render/lights.rs`` and ``mesh_view_bind_group.wgsl`` - reduce no-buffer-support max point light count to 204 due to above - use spotlight data to attenuate light in ``pbr.wgsl`` - do additional cluster culling on spotlights to minimise cost in ``assign_lights_to_clusters`` - changed one of the lights in the lighting demo to a spotlight - also added a ``spotlight`` demo - probably not justified but so reviewers can see it more easily ## notes increasing the size of the GpuPointLight struct on my machine reduces the FPS of ``many_lights -- sphere`` from ~150fps to 140fps. i thought this was a reasonable tradeoff, and felt better than handling spotlights separately which is possible but would mean introducing a new bind group, refactoring light-assignment code and adding new spotlight-specific code in pbr.wgsl. the FPS impact for smaller numbers of lights should be very small. the cluster culling strategy reintroduces the cluster aabb code which was recently removed... sorry. the aabb is used to get a cluster bounding sphere, which can then be tested fairly efficiently using the strategy described at the end of https://bartwronski.com/2017/04/13/cull-that-cone/. this works well with roughly cubic clusters (where the cluster z size is close to the same as x/y size), less well for other cases like single Z slice / tiled forward rendering. In the worst case we will end up just keeping the culling of the equivalent point light. Co-authored-by: François <mockersf@gmail.com>
2022-07-08 19:57:43 +00:00
[[example]]
name = "spotlight"
path = "examples/3d/spotlight.rs"
[package.metadata.example.spotlight]
name = "Spotlight"
description = "Illustrates spot lights"
category = "3D Rendering"
wasm = true
[[example]]
Revamp Bloom (#6677) ![image](https://user-images.githubusercontent.com/47158642/220197588-25e11022-02e4-45f3-b2e5-392c4ce7a025.png) Huge credit to @StarLederer, who did almost all of the work on this. We're just reusing this PR to keep everything in one place. # Objective 1. Make bloom more physically based. 1. Improve artistic control. 1. Allow to use bloom as screen blur. 1. Fix #6634. 1. Address #6655 (although the author makes incorrect conclusions). ## Solution 1. Set the default threshold to 0. 2. Lerp between bloom textures when `composite_mode: BloomCompositeMode::EnergyConserving`. 1. Use [a parametric function](https://starlederer.github.io/bloom) to control blend levels for each bloom texture. In the future this can be controlled per-pixel for things like lens dirt. 3. Implement BloomCompositeMode::Additive` for situations where the old school look is desired. ## Changelog * Bloom now looks different. * Added `BloomSettings:lf_boost`, `BloomSettings:lf_boost_curvature`, `BloomSettings::high_pass_frequency` and `BloomSettings::composite_mode`. * `BloomSettings::scale` removed. * `BloomSettings::knee` renamed to `BloomPrefilterSettings::softness`. * `BloomSettings::threshold` renamed to `BloomPrefilterSettings::threshold`. * The bloom example has been renamed to bloom_3d and improved. A bloom_2d example was added. ## Migration Guide * Refactor mentions of `BloomSettings::knee` and `BloomSettings::threshold` as `BloomSettings::prefilter_settings` where knee is now `softness`. * If defined without `..default()` add `..default()` to definitions of `BloomSettings` instances or manually define missing fields. * Adapt to Bloom looking visually different (if needed). Co-authored-by: Herman Lederer <germans.lederers@gmail.com>
2023-03-04 12:05:26 +00:00
name = "bloom_3d"
path = "examples/3d/bloom_3d.rs"
Revamp Bloom (#6677) ![image](https://user-images.githubusercontent.com/47158642/220197588-25e11022-02e4-45f3-b2e5-392c4ce7a025.png) Huge credit to @StarLederer, who did almost all of the work on this. We're just reusing this PR to keep everything in one place. # Objective 1. Make bloom more physically based. 1. Improve artistic control. 1. Allow to use bloom as screen blur. 1. Fix #6634. 1. Address #6655 (although the author makes incorrect conclusions). ## Solution 1. Set the default threshold to 0. 2. Lerp between bloom textures when `composite_mode: BloomCompositeMode::EnergyConserving`. 1. Use [a parametric function](https://starlederer.github.io/bloom) to control blend levels for each bloom texture. In the future this can be controlled per-pixel for things like lens dirt. 3. Implement BloomCompositeMode::Additive` for situations where the old school look is desired. ## Changelog * Bloom now looks different. * Added `BloomSettings:lf_boost`, `BloomSettings:lf_boost_curvature`, `BloomSettings::high_pass_frequency` and `BloomSettings::composite_mode`. * `BloomSettings::scale` removed. * `BloomSettings::knee` renamed to `BloomPrefilterSettings::softness`. * `BloomSettings::threshold` renamed to `BloomPrefilterSettings::threshold`. * The bloom example has been renamed to bloom_3d and improved. A bloom_2d example was added. ## Migration Guide * Refactor mentions of `BloomSettings::knee` and `BloomSettings::threshold` as `BloomSettings::prefilter_settings` where knee is now `softness`. * If defined without `..default()` add `..default()` to definitions of `BloomSettings` instances or manually define missing fields. * Adapt to Bloom looking visually different (if needed). Co-authored-by: Herman Lederer <germans.lederers@gmail.com>
2023-03-04 12:05:26 +00:00
[package.metadata.example.bloom_3d]
name = "3D Bloom"
description = "Illustrates bloom configuration using HDR and emissive materials"
category = "3D Rendering"
wasm = false
2020-05-01 20:12:47 +00:00
[[example]]
name = "load_gltf"
path = "examples/3d/load_gltf.rs"
2020-05-01 20:12:47 +00:00
[package.metadata.example.load_gltf]
name = "Load glTF"
description = "Loads and renders a glTF file as a scene"
category = "3D Rendering"
wasm = true
[[example]]
name = "tonemapping"
path = "examples/3d/tonemapping.rs"
required-features = ["ktx2", "zstd"]
[package.metadata.example.tonemapping]
name = "Tonemapping"
description = "Compares tonemapping options"
category = "3D Rendering"
wasm = true
[[example]]
name = "fxaa"
path = "examples/3d/fxaa.rs"
[package.metadata.example.fxaa]
name = "FXAA"
description = "Compares MSAA (Multi-Sample Anti-Aliasing) and FXAA (Fast Approximate Anti-Aliasing)"
category = "3D Rendering"
wasm = true
2020-07-30 01:15:15 +00:00
[[example]]
name = "msaa"
path = "examples/3d/msaa.rs"
[package.metadata.example.msaa]
name = "MSAA"
description = "Configures MSAA (Multi-Sample Anti-Aliasing) for smoother edges"
category = "3D Rendering"
wasm = true
[[example]]
name = "orthographic"
path = "examples/3d/orthographic.rs"
[package.metadata.example.orthographic]
name = "Orthographic View"
description = "Shows how to create a 3D orthographic view (for isometric-look in games or CAD applications)"
category = "3D Rendering"
wasm = true
2020-05-01 20:12:47 +00:00
[[example]]
name = "parenting"
path = "examples/3d/parenting.rs"
[package.metadata.example.parenting]
name = "Parenting"
description = "Demonstrates parent->child relationships and relative transformations"
category = "3D Rendering"
wasm = true
[[example]]
name = "pbr"
path = "examples/3d/pbr.rs"
[package.metadata.example.pbr]
name = "Physically Based Rendering"
description = "Demonstrates use of Physically Based Rendering (PBR) properties"
category = "3D Rendering"
wasm = true
[[example]]
name = "render_to_texture"
path = "examples/3d/render_to_texture.rs"
[package.metadata.example.render_to_texture]
name = "Render to Texture"
description = "Shows how to render to a texture, useful for mirrors, UI, or exporting images"
category = "3D Rendering"
wasm = true
bevy_pbr2: Add support for most of the StandardMaterial textures (#4) * bevy_pbr2: Add support for most of the StandardMaterial textures Normal maps are not included here as they require tangents in a vertex attribute. * bevy_pbr2: Ensure RenderCommandQueue is ready for PbrShaders init * texture_pipelined: Add a light to the scene so we can see stuff * WIP bevy_pbr2: back to front sorting hack * bevy_pbr2: Uniform control flow for texture sampling in pbr.frag From 'fintelia' on the Bevy Render Rework Round 2 discussion: "My understanding is that GPUs these days never use the "execute both branches and select the result" strategy. Rather, what they do is evaluate the branch condition on all threads of a warp, and jump over it if all of them evaluate to false. If even a single thread needs to execute the if statement body, however, then the remaining threads are paused until that is completed." * bevy_pbr2: Simplify texture and sampler names The StandardMaterial_ prefix is no longer needed * bevy_pbr2: Match default 'AmbientColor' of current bevy_pbr for now * bevy_pbr2: Convert from non-linear to linear sRGB for the color uniform * bevy_pbr2: Add pbr_pipelined example * Fix view vector in pbr frag to work in ortho * bevy_pbr2: Use a 90 degree y fov and light range projection for lights * bevy_pbr2: Add AmbientLight resource * bevy_pbr2: Convert PointLight color to linear sRGB for use in fragment shader * bevy_pbr2: pbr.frag: Rename PointLight.projection to view_projection The uniform contains the view_projection matrix so this was incorrect. * bevy_pbr2: PointLight is an OmniLight as it has a radius * bevy_pbr2: Factoring out duplicated code * bevy_pbr2: Implement RenderAsset for StandardMaterial * Remove unnecessary texture and sampler clones * fix comment formatting * remove redundant Buffer:from * Don't extract meshes when their material textures aren't ready * make missing textures in the queue step an error Co-authored-by: Aevyrie <aevyrie@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2021-06-27 23:10:23 +00:00
[[example]]
name = "shadow_biases"
path = "examples/3d/shadow_biases.rs"
Scale normal bias by texel size (#26) * 3d_scene_pipelined: Use a shallower directional light angle to provoke acne * cornell_box_pipelined: Remove bias tweaks * bevy_pbr2: Simplify shadow biases by moving them to linear depth * bevy_pbr2: Do not use DepthBiasState * bevy_pbr2: Do not use bilinear filtering for sampling depth textures * pbr.wgsl: Remove unnecessary comment * bevy_pbr2: Do manual shadow map depth comparisons for more flexibility * examples: Add shadow_biases_pipelined example This is useful for stress testing biases. * bevy_pbr2: Scale the point light normal bias by the shadow map texel size This allows the normal bias to be small close to the light source where the shadow map texel to screen texel ratio is high, but is appropriately large further away from the light source where the shadow map texel can easily cover multiple screen texels. * shadow_biases_pipelined: Add support for toggling directional / point light * shadow_biases_pipelined: Cleanup * bevy_pbr2: Scale the directional light normal bias by the shadow map texel size * shadow_biases_pipelined: Fit the orthographic projection around the scene * bevy_pbr2: Directional lights should have no shadows outside their projection Before this change, sampling a fragment position from outside the ndc volume would result in the return sample being clamped to the edge in x,y or possibly always casting a shadow for fragment positions past the orthographic projection's far plane. * bevy_pbr2: Fix the default directional light normal bias * Revert "bevy_pbr2: Do manual shadow map depth comparisons for more flexibility" This reverts commit 7df1bab38a42d8a33bc50ca583d4be37bd9c9f0d. * shadow_biases_pipelined: Adjust directional light normal bias in 0.1 increments * pbr.wgsl: Add a couple of clarifying comments * Revert "bevy_pbr2: Do not use bilinear filtering for sampling depth textures" This reverts commit f53baab0232ce218866a45cad6902b470f4cf2c4. * shadow_biases_pipelined: Print usage to terminal
2021-07-19 19:20:59 +00:00
[package.metadata.example.shadow_biases]
name = "Shadow Biases"
description = "Demonstrates how shadow biases affect shadows in a 3d scene"
category = "3D Rendering"
wasm = true
[[example]]
name = "shadow_caster_receiver"
path = "examples/3d/shadow_caster_receiver.rs"
2020-05-01 20:12:47 +00:00
[package.metadata.example.shadow_caster_receiver]
name = "Shadow Caster and Receiver"
description = "Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene"
category = "3D Rendering"
wasm = true
Support array / cubemap / cubemap array textures in KTX2 (#5325) # Objective - Fix / support KTX2 array / cubemap / cubemap array textures - Fixes #4495 . Supersedes #4514 . ## Solution - Add `Option<TextureViewDescriptor>` to `Image` to enable configuration of the `TextureViewDimension` of a texture. - This allows users to set `D2Array`, `D3`, `Cube`, `CubeArray` or whatever they need - Automatically configure this when loading KTX2 - Transcode all layers and faces instead of just one - Use the UASTC block size of 128 bits, and the number of blocks in x/y for a given mip level in order to determine the offset of the layer and face within the KTX2 mip level data - `wgpu` wants data ordered as layer 0 mip 0..n, layer 1 mip 0..n, etc. See https://docs.rs/wgpu/latest/wgpu/util/trait.DeviceExt.html#tymethod.create_texture_with_data - Reorder the data KTX2 mip X layer Y face Z to `wgpu` layer Y face Z mip X order - Add a `skybox` example to demonstrate / test loading cubemaps from PNG and KTX2, including ASTC 4x4, BC7, and ETC2 compression for support everywhere. Note that you need to enable the `ktx2,zstd` features to be able to load the compressed textures. --- ## Changelog - Fixed: KTX2 array / cubemap / cubemap array textures - Fixes: Validation failure for compressed textures stored in KTX2 where the width/height are not a multiple of the block dimensions. - Added: `Image` now has an `Option<TextureViewDescriptor>` field to enable configuration of the texture view. This is useful for configuring the `TextureViewDimension` when it is not just a plain 2D texture and the loader could/did not identify what it should be. Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-07-30 07:02:58 +00:00
[[example]]
name = "skybox"
path = "examples/3d/skybox.rs"
[package.metadata.example.skybox]
name = "Skybox"
description = "Load a cubemap texture onto a cube like a skybox and cycle through different compressed texture formats."
category = "3D Rendering"
wasm = false
[[example]]
name = "spherical_area_lights"
path = "examples/3d/spherical_area_lights.rs"
[package.metadata.example.spherical_area_lights]
name = "Spherical Area Lights"
description = "Demonstrates how point light radius values affect light behavior"
category = "3D Rendering"
wasm = true
Camera Driven Viewports (#4898) # Objective Users should be able to render cameras to specific areas of a render target, which enables scenarios like split screen, minimaps, etc. Builds on the new Camera Driven Rendering added here: #4745 Fixes: #202 Alternative to #1389 and #3626 (which are incompatible with the new Camera Driven Rendering) ## Solution ![image](https://user-images.githubusercontent.com/2694663/171560044-f0694f67-0cd9-4598-83e2-a9658c4fed57.png) Cameras can now configure an optional "viewport", which defines a rectangle within their render target to draw to. If a `Viewport` is defined, the camera's `CameraProjection`, `View`, and visibility calculations will use the viewport configuration instead of the full render target. ```rust // This camera will render to the first half of the primary window (on the left side). commands.spawn_bundle(Camera3dBundle { camera: Camera { viewport: Some(Viewport { physical_position: UVec2::new(0, 0), physical_size: UVec2::new(window.physical_width() / 2, window.physical_height()), depth: 0.0..1.0, }), ..default() }, ..default() }); ``` To account for this, the `Camera` component has received a few adjustments: * `Camera` now has some new getter functions: * `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, `projection_matrix` * All computed camera values are now private and live on the `ComputedCameraValues` field (logical/physical width/height, the projection matrix). They are now exposed on `Camera` via getters/setters This wasn't _needed_ for viewports, but it was long overdue. --- ## Changelog ### Added * `Camera` components now have a `viewport` field, which can be set to draw to a portion of a render target instead of the full target. * `Camera` component has some new functions: `logical_viewport_size`, `physical_viewport_size`, `logical_target_size`, `physical_target_size`, and `projection_matrix` * Added a new split_screen example illustrating how to render two cameras to the same scene ## Migration Guide `Camera::projection_matrix` is no longer a public field. Use the new `Camera::projection_matrix()` method instead: ```rust // Bevy 0.7 let projection = camera.projection_matrix; // Bevy 0.8 let projection = camera.projection_matrix(); ```
2022-06-05 00:27:49 +00:00
[[example]]
name = "split_screen"
path = "examples/3d/split_screen.rs"
[package.metadata.example.split_screen]
name = "Split Screen"
description = "Demonstrates how to render two cameras to the same window to accomplish \"split screen\""
category = "3D Rendering"
wasm = true
2020-05-01 20:12:47 +00:00
[[example]]
name = "texture"
path = "examples/3d/texture.rs"
[package.metadata.example.texture]
name = "Texture"
description = "Shows configuration of texture materials"
category = "3D Rendering"
wasm = true
[[example]]
name = "transparency_3d"
path = "examples/3d/transparency_3d.rs"
[package.metadata.example.transparency_3d]
name = "Transparency in 3D"
description = "Demonstrates transparency in 3d"
category = "3D Rendering"
wasm = true
[[example]]
name = "two_passes"
path = "examples/3d/two_passes.rs"
[package.metadata.example.two_passes]
name = "Two Passes"
description = "Renders two 3d passes to the same window from different perspectives"
category = "3D Rendering"
wasm = true
[[example]]
name = "update_gltf_scene"
path = "examples/3d/update_gltf_scene.rs"
[package.metadata.example.update_gltf_scene]
name = "Update glTF Scene"
description = "Update a scene from a glTF file, either by spawning the scene as a child of another entity, or by accessing the entities of the scene"
category = "3D Rendering"
wasm = true
[[example]]
name = "vertex_colors"
path = "examples/3d/vertex_colors.rs"
[package.metadata.example.vertex_colors]
name = "Vertex Colors"
description = "Shows the use of vertex colors"
category = "3D Rendering"
wasm = true
[[example]]
name = "wireframe"
path = "examples/3d/wireframe.rs"
[package.metadata.example.wireframe]
name = "Wireframe"
description = "Showcases wireframe rendering"
category = "3D Rendering"
wasm = true
[[example]]
name = "no_prepass"
path = "tests/3d/no_prepass.rs"
[package.metadata.example.no_prepass]
hidden = true
# Animation
[[example]]
name = "animated_fox"
path = "examples/animation/animated_fox.rs"
[package.metadata.example.animated_fox]
name = "Animated Fox"
description = "Plays an animation from a skinned glTF"
category = "Animation"
wasm = true
[[example]]
name = "animated_transform"
path = "examples/animation/animated_transform.rs"
[package.metadata.example.animated_transform]
name = "Animated Transform"
description = "Create and play an animation defined by code that operates on the `Transform` component"
category = "Animation"
wasm = true
[[example]]
name = "custom_skinned_mesh"
path = "examples/animation/custom_skinned_mesh.rs"
[package.metadata.example.custom_skinned_mesh]
name = "Custom Skinned Mesh"
description = "Skinned mesh example with mesh and joints data defined in code"
category = "Animation"
wasm = true
[[example]]
name = "gltf_skinned_mesh"
path = "examples/animation/gltf_skinned_mesh.rs"
[package.metadata.example.gltf_skinned_mesh]
name = "glTF Skinned Mesh"
description = "Skinned mesh example with mesh and joints data loaded from a glTF file"
category = "Animation"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Application
[[example]]
name = "custom_loop"
path = "examples/app/custom_loop.rs"
[package.metadata.example.custom_loop]
name = "Custom Loop"
description = "Demonstrates how to create a custom runner (to update an app manually)"
category = "Application"
wasm = false
[[example]]
name = "drag_and_drop"
path = "examples/app/drag_and_drop.rs"
[package.metadata.example.drag_and_drop]
name = "Drag and Drop"
description = "An example that shows how to handle drag and drop in an app"
category = "Application"
wasm = false
2020-05-01 20:12:47 +00:00
[[example]]
name = "empty"
path = "examples/app/empty.rs"
[package.metadata.example.empty]
name = "Empty"
description = "An empty application (does nothing)"
category = "Application"
wasm = false
2020-11-13 01:23:57 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "empty_defaults"
path = "examples/app/empty_defaults.rs"
2020-11-13 01:23:57 +00:00
[package.metadata.example.empty_defaults]
name = "Empty with Defaults"
description = "An empty application with default plugins"
category = "Application"
wasm = true
2020-05-01 20:12:47 +00:00
[[example]]
name = "headless"
path = "examples/app/headless.rs"
[package.metadata.example.headless]
name = "Headless"
description = "An application that runs without default plugins"
category = "Application"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "logs"
path = "examples/app/logs.rs"
[package.metadata.example.logs]
name = "Logs"
description = "Illustrate how to use generate log output"
category = "Application"
wasm = true
2020-05-03 08:30:10 +00:00
[[example]]
name = "plugin"
path = "examples/app/plugin.rs"
[package.metadata.example.plugin]
name = "Plugin"
description = "Demonstrates the creation and registration of a custom plugin"
category = "Application"
wasm = true
[[example]]
name = "plugin_group"
path = "examples/app/plugin_group.rs"
[package.metadata.example.plugin_group]
name = "Plugin Group"
description = "Demonstrates the creation and registration of a custom plugin group"
category = "Application"
wasm = true
[[example]]
name = "return_after_run"
path = "examples/app/return_after_run.rs"
[package.metadata.example.return_after_run]
name = "Return after Run"
description = "Show how to return to main after the Bevy app has exited"
category = "Application"
wasm = false
[[example]]
name = "thread_pool_resources"
path = "examples/app/thread_pool_resources.rs"
[package.metadata.example.thread_pool_resources]
name = "Thread Pool Resources"
description = "Creates and customizes the internal thread pool"
category = "Application"
wasm = false
[[example]]
name = "no_renderer"
path = "examples/app/no_renderer.rs"
[package.metadata.example.no_renderer]
name = "No Renderer"
description = "An application that runs with default plugins and displays an empty window, but without an actual renderer"
category = "Application"
wasm = false
[[example]]
name = "without_winit"
path = "examples/app/without_winit.rs"
[package.metadata.example.without_winit]
name = "Without Winit"
description = "Create an application without winit (runs single time, no event loop)"
category = "Application"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Assets
2020-05-17 03:18:30 +00:00
[[example]]
name = "asset_loading"
path = "examples/asset/asset_loading.rs"
[package.metadata.example.asset_loading]
name = "Asset Loading"
description = "Demonstrates various methods to load assets"
category = "Assets"
wasm = true
[[example]]
name = "custom_asset"
path = "examples/asset/custom_asset.rs"
[package.metadata.example.custom_asset]
name = "Custom Asset"
description = "Implements a custom asset loader"
category = "Assets"
wasm = true
[[example]]
name = "custom_asset_io"
path = "examples/asset/custom_asset_io.rs"
[package.metadata.example.custom_asset_io]
name = "Custom Asset IO"
description = "Implements a custom asset io loader"
category = "Assets"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "hot_asset_reloading"
path = "examples/asset/hot_asset_reloading.rs"
[package.metadata.example.hot_asset_reloading]
name = "Hot Reloading of Assets"
description = "Demonstrates automatic reloading of assets when modified on disk"
category = "Assets"
wasm = true
# Async Tasks
[[example]]
name = "async_compute"
path = "examples/async_tasks/async_compute.rs"
[package.metadata.example.async_compute]
name = "Async Compute"
description = "How to use `AsyncComputeTaskPool` to complete longer running tasks"
category = "Async Tasks"
wasm = false
[[example]]
name = "external_source_external_thread"
path = "examples/async_tasks/external_source_external_thread.rs"
[package.metadata.example.external_source_external_thread]
name = "External Source of Data on an External Thread"
description = "How to use an external thread to run an infinite task and communicate with a channel"
category = "Async Tasks"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Audio
[[example]]
name = "audio"
path = "examples/audio/audio.rs"
[package.metadata.example.audio]
name = "Audio"
description = "Shows how to load and play an audio file"
category = "Audio"
wasm = true
[[example]]
name = "audio_control"
path = "examples/audio/audio_control.rs"
[package.metadata.example.audio_control]
name = "Audio Control"
description = "Shows how to load and play an audio file, and control how it's played"
category = "Audio"
wasm = true
[[example]]
name = "decodable"
path = "examples/audio/decodable.rs"
[package.metadata.example.decodable]
name = "Decodable"
description = "Shows how to create and register a custom audio source by implementing the `Decodable` type."
category = "Audio"
wasm = true
[[example]]
name = "spatial_audio_2d"
path = "examples/audio/spatial_audio_2d.rs"
[package.metadata.example.spatial_audio_2d]
name = "Spatial Audio 2D"
description = "Shows how to play spatial audio, and moving the emitter in 2D"
category = "Audio"
wasm = true
[[example]]
name = "spatial_audio_3d"
path = "examples/audio/spatial_audio_3d.rs"
[package.metadata.example.spatial_audio_3d]
name = "Spatial Audio 3D"
description = "Shows how to play spatial audio, and moving the emitter in 3D"
category = "Audio"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Diagnostics
[[example]]
name = "log_diagnostics"
path = "examples/diagnostics/log_diagnostics.rs"
[package.metadata.example.log_diagnostics]
name = "Log Diagnostics"
description = "Add a plugin that logs diagnostics, like frames per second (FPS), to the console"
category = "Diagnostics"
wasm = true
2020-05-04 21:14:49 +00:00
[[example]]
name = "custom_diagnostic"
path = "examples/diagnostics/custom_diagnostic.rs"
[package.metadata.example.custom_diagnostic]
name = "Custom Diagnostic"
description = "Shows how to create a custom diagnostic"
category = "Diagnostics"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# ECS (Entity Component System)
2020-05-04 21:14:49 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "ecs_guide"
path = "examples/ecs/ecs_guide.rs"
2020-05-04 21:14:49 +00:00
[package.metadata.example.ecs_guide]
name = "ECS Guide"
description = "Full guide to Bevy's ECS"
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "apply_system_buffers"
path = "examples/ecs/apply_system_buffers.rs"
[package.metadata.example.apply_system_buffers]
name = "Apply System Buffers"
description = "Show how to use `apply_system_buffers` system"
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "component_change_detection"
path = "examples/ecs/component_change_detection.rs"
[package.metadata.example.component_change_detection]
name = "Component Change Detection"
description = "Change detection on components"
category = "ECS (Entity Component System)"
wasm = false
Implement `WorldQuery` derive macro (#2713) # Objective - Closes #786 - Closes #2252 - Closes #2588 This PR implements a derive macro that allows users to define their queries as structs with named fields. ## Example ```rust #[derive(WorldQuery)] #[world_query(derive(Debug))] struct NumQuery<'w, T: Component, P: Component> { entity: Entity, u: UNumQuery<'w>, generic: GenericQuery<'w, T, P>, } #[derive(WorldQuery)] #[world_query(derive(Debug))] struct UNumQuery<'w> { u_16: &'w u16, u_32_opt: Option<&'w u32>, } #[derive(WorldQuery)] #[world_query(derive(Debug))] struct GenericQuery<'w, T: Component, P: Component> { generic: (&'w T, &'w P), } #[derive(WorldQuery)] #[world_query(filter)] struct NumQueryFilter<T: Component, P: Component> { _u_16: With<u16>, _u_32: With<u32>, _or: Or<(With<i16>, Changed<u16>, Added<u32>)>, _generic_tuple: (With<T>, With<P>), _without: Without<Option<u16>>, _tp: PhantomData<(T, P)>, } fn print_nums_readonly(query: Query<NumQuery<u64, i64>, NumQueryFilter<u64, i64>>) { for num in query.iter() { println!("{:#?}", num); } } #[derive(WorldQuery)] #[world_query(mutable, derive(Debug))] struct MutNumQuery<'w, T: Component, P: Component> { i_16: &'w mut i16, i_32_opt: Option<&'w mut i32>, } fn print_nums(mut query: Query<MutNumQuery, NumQueryFilter<u64, i64>>) { for num in query.iter_mut() { println!("{:#?}", num); } } ``` ## TODOs: - [x] Add support for `&T` and `&mut T` - [x] Test - [x] Add support for optional types - [x] Test - [x] Add support for `Entity` - [x] Test - [x] Add support for nested `WorldQuery` - [x] Test - [x] Add support for tuples - [x] Test - [x] Add support for generics - [x] Test - [x] Add support for query filters - [x] Test - [x] Add support for `PhantomData` - [x] Test - [x] Refactor `read_world_query_field_type_info` - [x] Properly document `readonly` attribute for nested queries and the static assertions that guarantee safety - [x] Test that we never implement `ReadOnlyFetch` for types that need mutable access - [x] Test that we insert static assertions for nested `WorldQuery` that a user marked as readonly
2022-02-24 00:19:49 +00:00
[[example]]
name = "custom_query_param"
path = "examples/ecs/custom_query_param.rs"
[package.metadata.example.custom_query_param]
name = "Custom Query Parameters"
description = "Groups commonly used compound queries and query filters into a single type"
category = "ECS (Entity Component System)"
wasm = false
2020-05-01 20:12:47 +00:00
[[example]]
name = "event"
path = "examples/ecs/event.rs"
[package.metadata.example.event]
name = "Event"
description = "Illustrates event creation, activation, and reception"
category = "ECS (Entity Component System)"
wasm = false
2020-12-13 02:04:42 +00:00
[[example]]
name = "fixed_timestep"
path = "examples/ecs/fixed_timestep.rs"
[package.metadata.example.fixed_timestep]
name = "Fixed Timestep"
description = "Shows how to create systems that run every fixed timestep, rather than every tick"
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "generic_system"
path = "examples/ecs/generic_system.rs"
[package.metadata.example.generic_system]
name = "Generic System"
description = "Shows how to create systems that can be reused with different types"
category = "ECS (Entity Component System)"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "hierarchy"
path = "examples/ecs/hierarchy.rs"
[package.metadata.example.hierarchy]
name = "Hierarchy"
description = "Creates a hierarchy of parents and children entities"
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "iter_combinations"
path = "examples/ecs/iter_combinations.rs"
[package.metadata.example.iter_combinations]
name = "Iter Combinations"
description = "Shows how to iterate over combinations of query results"
category = "ECS (Entity Component System)"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "parallel_query"
path = "examples/ecs/parallel_query.rs"
[package.metadata.example.parallel_query]
name = "Parallel Query"
description = "Illustrates parallel queries with `ParallelIterator`"
category = "ECS (Entity Component System)"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "removal_detection"
path = "examples/ecs/removal_detection.rs"
[package.metadata.example.removal_detection]
name = "Removal Detection"
Migrate engine to Schedule v3 (#7267) Huge thanks to @maniwani, @devil-ira, @hymm, @cart, @superdump and @jakobhellermann for the help with this PR. # Objective - Followup #6587. - Minimal integration for the Stageless Scheduling RFC: https://github.com/bevyengine/rfcs/pull/45 ## Solution - [x] Remove old scheduling module - [x] Migrate new methods to no longer use extension methods - [x] Fix compiler errors - [x] Fix benchmarks - [x] Fix examples - [x] Fix docs - [x] Fix tests ## Changelog ### Added - a large number of methods on `App` to work with schedules ergonomically - the `CoreSchedule` enum - `App::add_extract_system` via the `RenderingAppExtension` trait extension method - the private `prepare_view_uniforms` system now has a public system set for scheduling purposes, called `ViewSet::PrepareUniforms` ### Removed - stages, and all code that mentions stages - states have been dramatically simplified, and no longer use a stack - `RunCriteriaLabel` - `AsSystemLabel` trait - `on_hierarchy_reports_enabled` run criteria (now just uses an ad hoc resource checking run condition) - systems in `RenderSet/Stage::Extract` no longer warn when they do not read data from the main world - `RunCriteriaLabel` - `transform_propagate_system_set`: this was a nonstandard pattern that didn't actually provide enough control. The systems are already `pub`: the docs have been updated to ensure that the third-party usage is clear. ### Changed - `System::default_labels` is now `System::default_system_sets`. - `App::add_default_labels` is now `App::add_default_sets` - `CoreStage` and `StartupStage` enums are now `CoreSet` and `StartupSet` - `App::add_system_set` was renamed to `App::add_systems` - The `StartupSchedule` label is now defined as part of the `CoreSchedules` enum - `.label(SystemLabel)` is now referred to as `.in_set(SystemSet)` - `SystemLabel` trait was replaced by `SystemSet` - `SystemTypeIdLabel<T>` was replaced by `SystemSetType<T>` - The `ReportHierarchyIssue` resource now has a public constructor (`new`), and implements `PartialEq` - Fixed time steps now use a schedule (`CoreSchedule::FixedTimeStep`) rather than a run criteria. - Adding rendering extraction systems now panics rather than silently failing if no subapp with the `RenderApp` label is found. - the `calculate_bounds` system, with the `CalculateBounds` label, is now in `CoreSet::Update`, rather than in `CoreSet::PostUpdate` before commands are applied. - `SceneSpawnerSystem` now runs under `CoreSet::Update`, rather than `CoreStage::PreUpdate.at_end()`. - `bevy_pbr::add_clusters` is no longer an exclusive system - the top level `bevy_ecs::schedule` module was replaced with `bevy_ecs::scheduling` - `tick_global_task_pools_on_main_thread` is no longer run as an exclusive system. Instead, it has been replaced by `tick_global_task_pools`, which uses a `NonSend` resource to force running on the main thread. ## Migration Guide - Calls to `.label(MyLabel)` should be replaced with `.in_set(MySet)` - Stages have been removed. Replace these with system sets, and then add command flushes using the `apply_system_buffers` exclusive system where needed. - The `CoreStage`, `StartupStage, `RenderStage` and `AssetStage` enums have been replaced with `CoreSet`, `StartupSet, `RenderSet` and `AssetSet`. The same scheduling guarantees have been preserved. - Systems are no longer added to `CoreSet::Update` by default. Add systems manually if this behavior is needed, although you should consider adding your game logic systems to `CoreSchedule::FixedTimestep` instead for more reliable framerate-independent behavior. - Similarly, startup systems are no longer part of `StartupSet::Startup` by default. In most cases, this won't matter to you. - For example, `add_system_to_stage(CoreStage::PostUpdate, my_system)` should be replaced with - `add_system(my_system.in_set(CoreSet::PostUpdate)` - When testing systems or otherwise running them in a headless fashion, simply construct and run a schedule using `Schedule::new()` and `World::run_schedule` rather than constructing stages - Run criteria have been renamed to run conditions. These can now be combined with each other and with states. - Looping run criteria and state stacks have been removed. Use an exclusive system that runs a schedule if you need this level of control over system control flow. - For app-level control flow over which schedules get run when (such as for rollback networking), create your own schedule and insert it under the `CoreSchedule::Outer` label. - Fixed timesteps are now evaluated in a schedule, rather than controlled via run criteria. The `run_fixed_timestep` system runs this schedule between `CoreSet::First` and `CoreSet::PreUpdate` by default. - Command flush points introduced by `AssetStage` have been removed. If you were relying on these, add them back manually. - Adding extract systems is now typically done directly on the main app. Make sure the `RenderingAppExtension` trait is in scope, then call `app.add_extract_system(my_system)`. - the `calculate_bounds` system, with the `CalculateBounds` label, is now in `CoreSet::Update`, rather than in `CoreSet::PostUpdate` before commands are applied. You may need to order your movement systems to occur before this system in order to avoid system order ambiguities in culling behavior. - the `RenderLabel` `AppLabel` was renamed to `RenderApp` for clarity - `App::add_state` now takes 0 arguments: the starting state is set based on the `Default` impl. - Instead of creating `SystemSet` containers for systems that run in stages, simply use `.on_enter::<State::Variant>()` or its `on_exit` or `on_update` siblings. - `SystemLabel` derives should be replaced with `SystemSet`. You will also need to add the `Debug`, `PartialEq`, `Eq`, and `Hash` traits to satisfy the new trait bounds. - `with_run_criteria` has been renamed to `run_if`. Run criteria have been renamed to run conditions for clarity, and should now simply return a bool. - States have been dramatically simplified: there is no longer a "state stack". To queue a transition to the next state, call `NextState::set` ## TODO - [x] remove dead methods on App and World - [x] add `App::add_system_to_schedule` and `App::add_systems_to_schedule` - [x] avoid adding the default system set at inappropriate times - [x] remove any accidental cycles in the default plugins schedule - [x] migrate benchmarks - [x] expose explicit labels for the built-in command flush points - [x] migrate engine code - [x] remove all mentions of stages from the docs - [x] verify docs for States - [x] fix uses of exclusive systems that use .end / .at_start / .before_commands - [x] migrate RenderStage and AssetStage - [x] migrate examples - [x] ensure that transform propagation is exported in a sufficiently public way (the systems are already pub) - [x] ensure that on_enter schedules are run at least once before the main app - [x] re-enable opt-in to execution order ambiguities - [x] revert change to `update_bounds` to ensure it runs in `PostUpdate` - [x] test all examples - [x] unbreak directional lights - [x] unbreak shadows (see 3d_scene, 3d_shape, lighting, transparaency_3d examples) - [x] game menu example shows loading screen and menu simultaneously - [x] display settings menu is a blank screen - [x] `without_winit` example panics - [x] ensure all tests pass - [x] SubApp doc test fails - [x] runs_spawn_local tasks fails - [x] [Fix panic_when_hierachy_cycle test hanging](https://github.com/alice-i-cecile/bevy/pull/120) ## Points of Difficulty and Controversy **Reviewers, please give feedback on these and look closely** 1. Default sets, from the RFC, have been removed. These added a tremendous amount of implicit complexity and result in hard to debug scheduling errors. They're going to be tackled in the form of "base sets" by @cart in a followup. 2. The outer schedule controls which schedule is run when `App::update` is called. 3. I implemented `Label for `Box<dyn Label>` for our label types. This enables us to store schedule labels in concrete form, and then later run them. I ran into the same set of problems when working with one-shot systems. We've previously investigated this pattern in depth, and it does not appear to lead to extra indirection with nested boxes. 4. `SubApp::update` simply runs the default schedule once. This sucks, but this whole API is incomplete and this was the minimal changeset. 5. `time_system` and `tick_global_task_pools_on_main_thread` no longer use exclusive systems to attempt to force scheduling order 6. Implemetnation strategy for fixed timesteps 7. `AssetStage` was migrated to `AssetSet` without reintroducing command flush points. These did not appear to be used, and it's nice to remove these bottlenecks. 8. Migration of `bevy_render/lib.rs` and pipelined rendering. The logic here is unusually tricky, as we have complex scheduling requirements. ## Future Work (ideally before 0.10) - Rename schedule_v3 module to schedule or scheduling - Add a derive macro to states, and likely a `EnumIter` trait of some form - Figure out what exactly to do with the "systems added should basically work by default" problem - Improve ergonomics for working with fixed timesteps and states - Polish FixedTime API to match Time - Rebase and merge #7415 - Resolve all internal ambiguities (blocked on better tools, especially #7442) - Add "base sets" to replace the removed default sets.
2023-02-06 02:04:50 +00:00
description = "Query for entities that had a specific component removed earlier in the current frame"
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "run_conditions"
path = "examples/ecs/run_conditions.rs"
[package.metadata.example.run_conditions]
name = "Run Conditions"
description = "Run systems only when one or multiple conditions are met"
category = "ECS (Entity Component System)"
wasm = false
2020-05-01 20:12:47 +00:00
[[example]]
name = "startup_system"
path = "examples/ecs/startup_system.rs"
[package.metadata.example.startup_system]
name = "Startup System"
description = "Demonstrates a startup system (one that runs once when the app starts up)"
category = "ECS (Entity Component System)"
wasm = false
2020-12-13 02:04:42 +00:00
[[example]]
name = "state"
path = "examples/ecs/state.rs"
[package.metadata.example.state]
name = "State"
description = "Illustrates how to use States to control transitioning from a Menu state to an InGame state"
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "system_piping"
path = "examples/ecs/system_piping.rs"
[package.metadata.example.system_piping]
name = "System Piping"
description = "Pipe the output of one system into a second, allowing you to handle any errors gracefully"
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "system_closure"
path = "examples/ecs/system_closure.rs"
[package.metadata.example.system_closure]
name = "System Closure"
description = "Show how to use closures as systems, and how to configure `Local` variables by capturing external state"
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "system_param"
path = "examples/ecs/system_param.rs"
[package.metadata.example.system_param]
name = "System Parameter"
description = "Illustrates creating custom system parameters with `SystemParam`"
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "timers"
path = "examples/ecs/timers.rs"
[package.metadata.example.timers]
name = "Timers"
description = "Illustrates ticking `Timer` resources inside systems and handling their state"
category = "ECS (Entity Component System)"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Games
[[example]]
name = "alien_cake_addict"
path = "examples/games/alien_cake_addict.rs"
[package.metadata.example.alien_cake_addict]
name = "Alien Cake Addict"
description = "Eat the cakes. Eat them all. An example 3D game"
category = "Games"
wasm = true
2020-06-27 04:40:09 +00:00
[[example]]
name = "breakout"
path = "examples/games/breakout.rs"
[package.metadata.example.breakout]
name = "Breakout"
description = "An implementation of the classic game \"Breakout\""
category = "Games"
wasm = true
[[example]]
name = "contributors"
path = "examples/games/contributors.rs"
2020-06-27 04:40:09 +00:00
[package.metadata.example.contributors]
name = "Contributors"
description = "Displays each contributor as a bouncy bevy-ball!"
category = "Games"
wasm = true
[[example]]
name = "game_menu"
path = "examples/games/game_menu.rs"
[package.metadata.example.game_menu]
name = "Game Menu"
description = "A simple game menu"
category = "Games"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Input
2020-05-01 20:12:47 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "char_input_events"
path = "examples/input/char_input_events.rs"
2020-05-01 20:12:47 +00:00
[package.metadata.example.char_input_events]
name = "Char Input Events"
description = "Prints out all chars as they are inputted"
category = "Input"
wasm = false
2020-05-01 20:12:47 +00:00
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "gamepad_input"
path = "examples/input/gamepad_input.rs"
[package.metadata.example.gamepad_input]
name = "Gamepad Input"
description = "Shows handling of gamepad input, connections, and disconnections"
category = "Input"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "gamepad_input_events"
path = "examples/input/gamepad_input_events.rs"
2020-06-05 06:49:36 +00:00
[package.metadata.example.gamepad_input_events]
name = "Gamepad Input Events"
description = "Iterates and prints gamepad input and connection events"
category = "Input"
wasm = false
2020-06-05 06:49:36 +00:00
[[example]]
name = "keyboard_input"
path = "examples/input/keyboard_input.rs"
[package.metadata.example.keyboard_input]
name = "Keyboard Input"
description = "Demonstrates handling a key press/release"
category = "Input"
wasm = false
[[example]]
name = "keyboard_modifiers"
path = "examples/input/keyboard_modifiers.rs"
[package.metadata.example.keyboard_modifiers]
name = "Keyboard Modifiers"
description = "Demonstrates using key modifiers (ctrl, shift)"
category = "Input"
wasm = false
2020-06-05 06:49:36 +00:00
[[example]]
name = "keyboard_input_events"
path = "examples/input/keyboard_input_events.rs"
2020-05-01 20:12:47 +00:00
[package.metadata.example.keyboard_input_events]
name = "Keyboard Input Events"
description = "Prints out all keyboard events"
category = "Input"
wasm = false
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "mouse_input"
path = "examples/input/mouse_input.rs"
[package.metadata.example.mouse_input]
name = "Mouse Input"
description = "Demonstrates handling a mouse button press/release"
category = "Input"
wasm = false
[[example]]
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
name = "mouse_input_events"
path = "examples/input/mouse_input_events.rs"
[package.metadata.example.mouse_input_events]
name = "Mouse Input Events"
description = "Prints out all mouse events (buttons, movement, etc.)"
category = "Input"
wasm = false
[[example]]
name = "mouse_grab"
path = "examples/input/mouse_grab.rs"
[package.metadata.example.mouse_grab]
name = "Mouse Grab"
description = "Demonstrates how to grab the mouse, locking the cursor to the app's screen"
category = "Input"
wasm = false
[[example]]
name = "touch_input"
path = "examples/input/touch_input.rs"
[package.metadata.example.touch_input]
name = "Touch Input"
description = "Displays touch presses, releases, and cancels"
category = "Input"
wasm = false
[[example]]
name = "touch_input_events"
path = "examples/input/touch_input_events.rs"
[package.metadata.example.touch_input_events]
name = "Touch Input Events"
description = "Prints out all touch inputs"
category = "Input"
wasm = false
[[example]]
name = "text_input"
path = "examples/input/text_input.rs"
[package.metadata.example.text_input]
name = "Text Input"
description = "Simple text input with IME support"
category = "Input"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Reflection
2020-05-01 20:12:47 +00:00
[[example]]
2020-11-28 00:39:59 +00:00
name = "reflection"
path = "examples/reflection/reflection.rs"
[package.metadata.example.reflection]
name = "Reflection"
description = "Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types"
category = "Reflection"
wasm = false
2020-11-28 00:39:59 +00:00
[[example]]
name = "generic_reflection"
path = "examples/reflection/generic_reflection.rs"
[package.metadata.example.generic_reflection]
name = "Generic Reflection"
description = "Registers concrete instances of generic types that may be used with reflection"
category = "Reflection"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "reflection_types"
path = "examples/reflection/reflection_types.rs"
[package.metadata.example.reflection_types]
name = "Reflection Types"
description = "Illustrates the various reflection types available"
category = "Reflection"
wasm = false
2020-11-28 00:39:59 +00:00
[[example]]
name = "trait_reflection"
path = "examples/reflection/trait_reflection.rs"
2020-05-01 20:12:47 +00:00
[package.metadata.example.trait_reflection]
name = "Trait Reflection"
description = "Allows reflection with trait objects"
category = "Reflection"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Scene
2020-05-22 06:58:11 +00:00
[[example]]
2020-11-28 00:39:59 +00:00
name = "scene"
path = "examples/scene/scene.rs"
2020-05-22 06:58:11 +00:00
[package.metadata.example.scene]
name = "Scene"
description = "Demonstrates loading from and saving scenes to files"
category = "Scene"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Shaders
[[package.metadata.example_category]]
name = "Shaders"
description = """
These examples demonstrate how to implement different shaders in user code.
A shader in its most common usage is a small program that is run by the GPU per-vertex in a mesh (a vertex shader) or per-affected-screen-fragment (a fragment shader.) The GPU executes these programs in a highly parallel way.
There are also compute shaders which are used for more general processing leveraging the GPU's parallelism.
"""
Mesh vertex buffer layouts (#3959) This PR makes a number of changes to how meshes and vertex attributes are handled, which the goal of enabling easy and flexible custom vertex attributes: * Reworks the `Mesh` type to use the newly added `VertexAttribute` internally * `VertexAttribute` defines the name, a unique `VertexAttributeId`, and a `VertexFormat` * `VertexAttributeId` is used to produce consistent sort orders for vertex buffer generation, replacing the more expensive and often surprising "name based sorting" * Meshes can be used to generate a `MeshVertexBufferLayout`, which defines the layout of the gpu buffer produced by the mesh. `MeshVertexBufferLayouts` can then be used to generate actual `VertexBufferLayouts` according to the requirements of a specific pipeline. This decoupling of "mesh layout" vs "pipeline vertex buffer layout" is what enables custom attributes. We don't need to standardize _mesh layouts_ or contort meshes to meet the needs of a specific pipeline. As long as the mesh has what the pipeline needs, it will work transparently. * Mesh-based pipelines now specialize on `&MeshVertexBufferLayout` via the new `SpecializedMeshPipeline` trait (which behaves like `SpecializedPipeline`, but adds `&MeshVertexBufferLayout`). The integrity of the pipeline cache is maintained because the `MeshVertexBufferLayout` is treated as part of the key (which is fully abstracted from implementers of the trait ... no need to add any additional info to the specialization key). * Hashing `MeshVertexBufferLayout` is too expensive to do for every entity, every frame. To make this scalable, I added a generalized "pre-hashing" solution to `bevy_utils`: `Hashed<T>` keys and `PreHashMap<K, V>` (which uses `Hashed<T>` internally) . Why didn't I just do the quick and dirty in-place "pre-compute hash and use that u64 as a key in a hashmap" that we've done in the past? Because its wrong! Hashes by themselves aren't enough because two different values can produce the same hash. Re-hashing a hash is even worse! I decided to build a generalized solution because this pattern has come up in the past and we've chosen to do the wrong thing. Now we can do the right thing! This did unfortunately require pulling in `hashbrown` and using that in `bevy_utils`, because avoiding re-hashes requires the `raw_entry_mut` api, which isn't stabilized yet (and may never be ... `entry_ref` has favor now, but also isn't available yet). If std's HashMap ever provides the tools we need, we can move back to that. Note that adding `hashbrown` doesn't increase our dependency count because it was already in our tree. I will probably break these changes out into their own PR. * Specializing on `MeshVertexBufferLayout` has one non-obvious behavior: it can produce identical pipelines for two different MeshVertexBufferLayouts. To optimize the number of active pipelines / reduce re-binds while drawing, I de-duplicate pipelines post-specialization using the final `VertexBufferLayout` as the key. For example, consider a pipeline that needs the layout `(position, normal)` and is specialized using two meshes: `(position, normal, uv)` and `(position, normal, other_vec2)`. If both of these meshes result in `(position, normal)` specializations, we can use the same pipeline! Now we do. Cool! To briefly illustrate, this is what the relevant section of `MeshPipeline`'s specialization code looks like now: ```rust impl SpecializedMeshPipeline for MeshPipeline { type Key = MeshPipelineKey; fn specialize( &self, key: Self::Key, layout: &MeshVertexBufferLayout, ) -> RenderPipelineDescriptor { let mut vertex_attributes = vec![ Mesh::ATTRIBUTE_POSITION.at_shader_location(0), Mesh::ATTRIBUTE_NORMAL.at_shader_location(1), Mesh::ATTRIBUTE_UV_0.at_shader_location(2), ]; let mut shader_defs = Vec::new(); if layout.contains(Mesh::ATTRIBUTE_TANGENT) { shader_defs.push(String::from("VERTEX_TANGENTS")); vertex_attributes.push(Mesh::ATTRIBUTE_TANGENT.at_shader_location(3)); } let vertex_buffer_layout = layout .get_layout(&vertex_attributes) .expect("Mesh is missing a vertex attribute"); ``` Notice that this is _much_ simpler than it was before. And now any mesh with any layout can be used with this pipeline, provided it has vertex postions, normals, and uvs. We even got to remove `HAS_TANGENTS` from MeshPipelineKey and `has_tangents` from `GpuMesh`, because that information is redundant with `MeshVertexBufferLayout`. This is still a draft because I still need to: * Add more docs * Experiment with adding error handling to mesh pipeline specialization (which would print errors at runtime when a mesh is missing a vertex attribute required by a pipeline). If it doesn't tank perf, we'll keep it. * Consider breaking out the PreHash / hashbrown changes into a separate PR. * Add an example illustrating this change * Verify that the "mesh-specialized pipeline de-duplication code" works properly Please dont yell at me for not doing these things yet :) Just trying to get this in peoples' hands asap. Alternative to #3120 Fixes #3030 Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-02-23 23:21:13 +00:00
[[example]]
name = "custom_vertex_attribute"
path = "examples/shader/custom_vertex_attribute.rs"
[package.metadata.example.custom_vertex_attribute]
name = "Custom Vertex Attribute"
description = "A shader that reads a mesh's custom vertex attribute"
category = "Shaders"
wasm = true
[[example]]
name = "post_processing"
path = "examples/shader/post_processing.rs"
[package.metadata.example.post_processing]
name = "Post Processing - Render To Texture"
description = "A custom post processing effect, using two cameras, with one reusing the render texture of the first one"
category = "Shaders"
wasm = true
[[example]]
name = "post_process_pass"
path = "examples/shader/post_process_pass.rs"
[package.metadata.example.post_process_pass]
name = "Post Processing - Custom Render Pass"
description = "A custom post processing effect, using a custom render pass that runs after the main pass"
category = "Shaders"
wasm = true
2020-05-01 20:12:47 +00:00
[[example]]
name = "shader_defs"
path = "examples/shader/shader_defs.rs"
[package.metadata.example.shader_defs]
name = "Shader Defs"
description = "A shader that uses \"shaders defs\" (a bevy tool to selectively toggle parts of a shader)"
category = "Shaders"
wasm = true
Modular Rendering (#2831) This changes how render logic is composed to make it much more modular. Previously, all extraction logic was centralized for a given "type" of rendered thing. For example, we extracted meshes into a vector of ExtractedMesh, which contained the mesh and material asset handles, the transform, etc. We looked up bindings for "drawn things" using their index in the `Vec<ExtractedMesh>`. This worked fine for built in rendering, but made it hard to reuse logic for "custom" rendering. It also prevented us from reusing things like "extracted transforms" across contexts. To make rendering more modular, I made a number of changes: * Entities now drive rendering: * We extract "render components" from "app components" and store them _on_ entities. No more centralized uber lists! We now have true "ECS-driven rendering" * To make this perform well, I implemented #2673 in upstream Bevy for fast batch insertions into specific entities. This was merged into the `pipelined-rendering` branch here: #2815 * Reworked the `Draw` abstraction: * Generic `PhaseItems`: each draw phase can define its own type of "rendered thing", which can define its own "sort key" * Ported the 2d, 3d, and shadow phases to the new PhaseItem impl (currently Transparent2d, Transparent3d, and Shadow PhaseItems) * `Draw` trait and and `DrawFunctions` are now generic on PhaseItem * Modular / Ergonomic `DrawFunctions` via `RenderCommands` * RenderCommand is a trait that runs an ECS query and produces one or more RenderPass calls. Types implementing this trait can be composed to create a final DrawFunction. For example the DrawPbr DrawFunction is created from the following DrawCommand tuple. Const generics are used to set specific bind group locations: ```rust pub type DrawPbr = ( SetPbrPipeline, SetMeshViewBindGroup<0>, SetStandardMaterialBindGroup<1>, SetTransformBindGroup<2>, DrawMesh, ); ``` * The new `custom_shader_pipelined` example illustrates how the commands above can be reused to create a custom draw function: ```rust type DrawCustom = ( SetCustomMaterialPipeline, SetMeshViewBindGroup<0>, SetTransformBindGroup<2>, DrawMesh, ); ``` * ExtractComponentPlugin and UniformComponentPlugin: * Simple, standardized ways to easily extract individual components and write them to GPU buffers * Ported PBR and Sprite rendering to the new primitives above. * Removed staging buffer from UniformVec in favor of direct Queue usage * Makes UniformVec much easier to use and more ergonomic. Completely removes the need for custom render graph nodes in these contexts (see the PbrNode and view Node removals and the much simpler call patterns in the relevant Prepare systems). * Added a many_cubes_pipelined example to benchmark baseline 3d rendering performance and ensure there were no major regressions during this port. Avoiding regressions was challenging given that the old approach of extracting into centralized vectors is basically the "optimal" approach. However thanks to a various ECS optimizations and render logic rephrasing, we pretty much break even on this benchmark! * Lifetimeless SystemParams: this will be a bit divisive, but as we continue to embrace "trait driven systems" (ex: ExtractComponentPlugin, UniformComponentPlugin, DrawCommand), the ergonomics of `(Query<'static, 'static, (&'static A, &'static B, &'static)>, Res<'static, C>)` were getting very hard to bear. As a compromise, I added "static type aliases" for the relevant SystemParams. The previous example can now be expressed like this: `(SQuery<(Read<A>, Read<B>)>, SRes<C>)`. If anyone has better ideas / conflicting opinions, please let me know! * RunSystem trait: a way to define Systems via a trait with a SystemParam associated type. This is used to implement the various plugins mentioned above. I also added SystemParamItem and QueryItem type aliases to make "trait stye" ecs interactions nicer on the eyes (and fingers). * RenderAsset retrying: ensures that render assets are only created when they are "ready" and allows us to create bind groups directly inside render assets (which significantly simplified the StandardMaterial code). I think ultimately we should swap this out on "asset dependency" events to wait for dependencies to load, but this will require significant asset system changes. * Updated some built in shaders to account for missing MeshUniform fields
2021-09-23 06:16:11 +00:00
[[example]]
name = "shader_material"
path = "examples/shader/shader_material.rs"
Pipeline Specialization, Shader Assets, and Shader Preprocessing (#3031) ## New Features This adds the following to the new renderer: * **Shader Assets** * Shaders are assets again! Users no longer need to call `include_str!` for their shaders * Shader hot-reloading * **Shader Defs / Shader Preprocessing** * Shaders now support `# ifdef NAME`, `# ifndef NAME`, and `# endif` preprocessor directives * **Bevy RenderPipelineDescriptor and RenderPipelineCache** * Bevy now provides its own `RenderPipelineDescriptor` and the wgpu version is now exported as `RawRenderPipelineDescriptor`. This allows users to define pipelines with `Handle<Shader>` instead of needing to manually compile and reference `ShaderModules`, enables passing in shader defs to configure the shader preprocessor, makes hot reloading possible (because the descriptor can be owned and used to create new pipelines when a shader changes), and opens the doors to pipeline specialization. * The `RenderPipelineCache` now handles compiling and re-compiling Bevy RenderPipelineDescriptors. It has internal PipelineLayout and ShaderModule caches. Users receive a `CachedPipelineId`, which can be used to look up the actual `&RenderPipeline` during rendering. * **Pipeline Specialization** * This enables defining per-entity-configurable pipelines that specialize on arbitrary custom keys. In practice this will involve specializing based on things like MSAA values, Shader Defs, Bind Group existence, and Vertex Layouts. * Adds a `SpecializedPipeline` trait and `SpecializedPipelines<MyPipeline>` resource. This is a simple layer that generates Bevy RenderPipelineDescriptors based on a custom key defined for the pipeline. * Specialized pipelines are also hot-reloadable. * This was the result of experimentation with two different approaches: 1. **"generic immediate mode multi-key hash pipeline specialization"** * breaks up the pipeline into multiple "identities" (the core pipeline definition, shader defs, mesh layout, bind group layout). each of these identities has its own key. looking up / compiling a specific version of a pipeline requires composing all of these keys together * the benefit of this approach is that it works for all pipelines / the pipeline is fully identified by the keys. the multiple keys allow pre-hashing parts of the pipeline identity where possible (ex: pre compute the mesh identity for all meshes) * the downside is that any per-entity data that informs the values of these keys could require expensive re-hashes. computing each key for each sprite tanked bevymark performance (sprites don't actually need this level of specialization yet ... but things like pbr and future sprite scenarios might). * this is the approach rafx used last time i checked 2. **"custom key specialization"** * Pipelines by default are not specialized * Pipelines that need specialization implement a SpecializedPipeline trait with a custom key associated type * This allows specialization keys to encode exactly the amount of information required (instead of needing to be a combined hash of the entire pipeline). Generally this should fit in a small number of bytes. Per-entity specialization barely registers anymore on things like bevymark. It also makes things like "shader defs" way cheaper to hash because we can use context specific bitflags instead of strings. * Despite the extra trait, it actually generally makes pipeline definitions + lookups simpler: managing multiple keys (and making the appropriate calls to manage these keys) was way more complicated. * I opted for custom key specialization. It performs better generally and in my opinion is better UX. Fortunately the way this is implemented also allows for custom caches as this all builds on a common abstraction: the RenderPipelineCache. The built in custom key trait is just a simple / pre-defined way to interact with the cache ## Callouts * The SpecializedPipeline trait makes it easy to inherit pipeline configuration in custom pipelines. The changes to `custom_shader_pipelined` and the new `shader_defs_pipelined` example illustrate how much simpler it is to define custom pipelines based on the PbrPipeline. * The shader preprocessor is currently pretty naive (it just uses regexes to process each line). Ultimately we might want to build a more custom parser for more performance + better error handling, but for now I'm happy to optimize for "easy to implement and understand". ## Next Steps * Port compute pipelines to the new system * Add more preprocessor directives (else, elif, import) * More flexible vertex attribute specialization / enable cheaply specializing on specific mesh vertex layouts
2021-10-28 19:07:47 +00:00
[package.metadata.example.shader_material]
name = "Material"
description = "A shader and a material that uses it"
category = "Shaders"
wasm = true
Add depth and normal prepass (#6284) # Objective - Add a configurable prepass - A depth prepass is useful for various shader effects and to reduce overdraw. It can be expansive depending on the scene so it's important to be able to disable it if you don't need any effects that uses it or don't suffer from excessive overdraw. - The goal is to eventually use it for things like TAA, Ambient Occlusion, SSR and various other techniques that can benefit from having a prepass. ## Solution The prepass node is inserted before the main pass. It runs for each `Camera3d` with a prepass component (`DepthPrepass`, `NormalPrepass`). The presence of one of those components is used to determine which textures are generated in the prepass. When any prepass is enabled, the depth buffer generated will be used by the main pass to reduce overdraw. The prepass runs for each `Material` created with the `MaterialPlugin::prepass_enabled` option set to `true`. You can overload the shader used by the prepass by using `Material::prepass_vertex_shader()` and/or `Material::prepass_fragment_shader()`. It will also use the `Material::specialize()` for more advanced use cases. It is enabled by default on all materials. The prepass works on opaque materials and materials using an alpha mask. Transparent materials are ignored. The `StandardMaterial` overloads the prepass fragment shader to support alpha mask and normal maps. --- ## Changelog - Add a new `PrepassNode` that runs before the main pass - Add a `PrepassPlugin` to extract/prepare/queue the necessary data - Add a `DepthPrepass` and `NormalPrepass` component to control which textures will be created by the prepass and available in later passes. - Add a new `prepass_enabled` flag to the `MaterialPlugin` that will control if a material uses the prepass or not. - Add a new `prepass_enabled` flag to the `PbrPlugin` to control if the StandardMaterial uses the prepass. Currently defaults to false. - Add `Material::prepass_vertex_shader()` and `Material::prepass_fragment_shader()` to control the prepass from the `Material` ## Notes In bevy's sample 3d scene, the performance is actually worse when enabling the prepass, but on more complex scenes the performance is generally better. I would like more testing on this, but @DGriffin91 has reported a very noticeable improvements in some scenes. The prepass is also used by @JMS55 for TAA and GTAO discord thread: <https://discord.com/channels/691052431525675048/1011624228627419187> This PR was built on top of the work of multiple people Co-Authored-By: @superdump Co-Authored-By: @robtfm Co-Authored-By: @JMS55 Co-authored-by: Charles <IceSentry@users.noreply.github.com> Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2023-01-19 22:11:13 +00:00
[[example]]
name = "shader_prepass"
path = "examples/shader/shader_prepass.rs"
[package.metadata.example.shader_prepass]
name = "Material Prepass"
description = "A shader that uses the various textures generated by the prepass"
Add depth and normal prepass (#6284) # Objective - Add a configurable prepass - A depth prepass is useful for various shader effects and to reduce overdraw. It can be expansive depending on the scene so it's important to be able to disable it if you don't need any effects that uses it or don't suffer from excessive overdraw. - The goal is to eventually use it for things like TAA, Ambient Occlusion, SSR and various other techniques that can benefit from having a prepass. ## Solution The prepass node is inserted before the main pass. It runs for each `Camera3d` with a prepass component (`DepthPrepass`, `NormalPrepass`). The presence of one of those components is used to determine which textures are generated in the prepass. When any prepass is enabled, the depth buffer generated will be used by the main pass to reduce overdraw. The prepass runs for each `Material` created with the `MaterialPlugin::prepass_enabled` option set to `true`. You can overload the shader used by the prepass by using `Material::prepass_vertex_shader()` and/or `Material::prepass_fragment_shader()`. It will also use the `Material::specialize()` for more advanced use cases. It is enabled by default on all materials. The prepass works on opaque materials and materials using an alpha mask. Transparent materials are ignored. The `StandardMaterial` overloads the prepass fragment shader to support alpha mask and normal maps. --- ## Changelog - Add a new `PrepassNode` that runs before the main pass - Add a `PrepassPlugin` to extract/prepare/queue the necessary data - Add a `DepthPrepass` and `NormalPrepass` component to control which textures will be created by the prepass and available in later passes. - Add a new `prepass_enabled` flag to the `MaterialPlugin` that will control if a material uses the prepass or not. - Add a new `prepass_enabled` flag to the `PbrPlugin` to control if the StandardMaterial uses the prepass. Currently defaults to false. - Add `Material::prepass_vertex_shader()` and `Material::prepass_fragment_shader()` to control the prepass from the `Material` ## Notes In bevy's sample 3d scene, the performance is actually worse when enabling the prepass, but on more complex scenes the performance is generally better. I would like more testing on this, but @DGriffin91 has reported a very noticeable improvements in some scenes. The prepass is also used by @JMS55 for TAA and GTAO discord thread: <https://discord.com/channels/691052431525675048/1011624228627419187> This PR was built on top of the work of multiple people Co-Authored-By: @superdump Co-Authored-By: @robtfm Co-Authored-By: @JMS55 Co-authored-by: Charles <IceSentry@users.noreply.github.com> Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
2023-01-19 22:11:13 +00:00
category = "Shaders"
wasm = false
[[example]]
name = "shader_material_screenspace_texture"
path = "examples/shader/shader_material_screenspace_texture.rs"
[package.metadata.example.shader_material_screenspace_texture]
name = "Material - Screenspace Texture"
description = "A shader that samples a texture with view-independent UV coordinates"
category = "Shaders"
wasm = true
[[example]]
name = "shader_material_glsl"
path = "examples/shader/shader_material_glsl.rs"
[package.metadata.example.shader_material_glsl]
name = "Material - GLSL"
description = "A shader that uses the GLSL shading language"
category = "Shaders"
wasm = true
[[example]]
name = "shader_instancing"
path = "examples/shader/shader_instancing.rs"
[package.metadata.example.shader_instancing]
name = "Instancing"
description = "A shader that renders a mesh multiple times in one draw call"
category = "Shaders"
wasm = true
[[example]]
name = "animate_shader"
path = "examples/shader/animate_shader.rs"
[package.metadata.example.animate_shader]
name = "Animated"
description = "A shader that uses dynamic data like the time since startup"
category = "Shaders"
wasm = true
[[example]]
name = "compute_shader_game_of_life"
path = "examples/shader/compute_shader_game_of_life.rs"
[package.metadata.example.compute_shader_game_of_life]
name = "Compute - Game of Life"
description = "A compute shader that simulates Conway's Game of Life"
category = "Shaders"
wasm = false
[[example]]
name = "array_texture"
path = "examples/shader/array_texture.rs"
[package.metadata.example.array_texture]
name = "Array Texture"
description = "A shader that shows how to reuse the core bevy PBR shading functionality in a custom material that obtains the base color from an array texture."
category = "Shaders"
wasm = true
[[example]]
name = "texture_binding_array"
path = "examples/shader/texture_binding_array.rs"
[package.metadata.example.texture_binding_array]
name = "Texture Binding Array (Bindless Textures)"
description = "A shader that shows how to bind and sample multiple textures as a binding array (a.k.a. bindless textures)."
category = "Shaders"
wasm = false
# Stress tests
[[package.metadata.example_category]]
name = "Stress Tests"
description = """
These examples are used to test the performance and stability of various parts of the engine in an isolated way.
Due to the focus on performance it's recommended to run the stress tests in release mode:
```sh
cargo run --release --example <example name>
```
"""
[[example]]
name = "bevymark"
path = "examples/stress_tests/bevymark.rs"
[package.metadata.example.bevymark]
name = "Bevymark"
description = "A heavy sprite rendering workload to benchmark your system with Bevy"
category = "Stress Tests"
wasm = true
[[example]]
name = "many_animated_sprites"
path = "examples/stress_tests/many_animated_sprites.rs"
[package.metadata.example.many_animated_sprites]
name = "Many Animated Sprites"
description = "Displays many animated sprites in a grid arrangement with slight offsets to their animation timers. Used for performance testing."
category = "Stress Tests"
wasm = true
[[example]]
name = "many_buttons"
path = "examples/stress_tests/many_buttons.rs"
[package.metadata.example.many_buttons]
name = "Many Buttons"
description = "Test rendering of many UI elements"
category = "Stress Tests"
wasm = true
[[example]]
name = "many_cubes"
path = "examples/stress_tests/many_cubes.rs"
[package.metadata.example.many_cubes]
name = "Many Cubes"
description = "Simple benchmark to test per-entity draw overhead. Run with the `sphere` argument to test frustum culling"
category = "Stress Tests"
wasm = true
Immediate Mode Line/Gizmo Drawing (#6529) # Objective Add a convenient immediate mode drawing API for visual debugging. Fixes #5619 Alternative to #1625 Partial alternative to #5734 Based off https://github.com/Toqozz/bevy_debug_lines with some changes: * Simultaneous support for 2D and 3D. * Methods for basic shapes; circles, spheres, rectangles, boxes, etc. * 2D methods. * Removed durations. Seemed niche, and can be handled by users. <details> <summary>Performance</summary> Stress tested using Bevy's recommended optimization settings for the dev profile with the following command. ```bash cargo run --example many_debug_lines \ --config "profile.dev.package.\"*\".opt-level=3" \ --config "profile.dev.opt-level=1" ``` I dipped to 65-70 FPS at 300,000 lines CPU: 3700x RAM Speed: 3200 Mhz GPU: 2070 super - probably not very relevant, mostly cpu/memory bound </details> <details> <summary>Fancy bloom screenshot</summary> ![Screenshot_20230207_155033](https://user-images.githubusercontent.com/29694403/217291980-f1e0500e-7a14-4131-8c96-eaaaf52596ae.png) </details> ## Changelog * Added `GizmoPlugin` * Added `Gizmos` system parameter for drawing lines and wireshapes. ### TODO - [ ] Update changelog - [x] Update performance numbers - [x] Add credit to PR description ### Future work - Cache rendering primitives instead of constructing them out of line segments each frame. - Support for drawing solid meshes - Interactions. (See [bevy_mod_gizmos](https://github.com/LiamGallagher737/bevy_mod_gizmos)) - Fancier line drawing. (See [bevy_polyline](https://github.com/ForesightMiningSoftwareCorporation/bevy_polyline)) - Support for `RenderLayers` - Display gizmos for a certain duration. Currently everything displays for one frame (ie. immediate mode) - Changing settings per drawn item like drawing on top or drawing to different `RenderLayers` Co-Authored By: @lassade <felipe.jorge.pereira@gmail.com> Co-Authored By: @The5-1 <agaku@hotmail.de> Co-Authored By: @Toqozz <toqoz@hotmail.com> Co-Authored By: @nicopap <nico@nicopap.ch> --------- Co-authored-by: Robert Swain <robert.swain@gmail.com> Co-authored-by: IceSentry <c.giguere42@gmail.com> Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-03-20 20:57:54 +00:00
[[example]]
name = "many_gizmos"
path = "examples/stress_tests/many_gizmos.rs"
[package.metadata.example.many_gizmos]
name = "Many Gizmos"
description = "Test rendering of many gizmos"
category = "Stress Tests"
wasm = true
[[example]]
name = "many_foxes"
path = "examples/stress_tests/many_foxes.rs"
[package.metadata.example.many_foxes]
name = "Many Foxes"
description = "Loads an animated fox model and spawns lots of them. Good for testing skinned mesh performance. Takes an unsigned integer argument for the number of foxes to spawn. Defaults to 1000"
category = "Stress Tests"
wasm = true
[[example]]
name = "many_glyphs"
path = "examples/stress_tests/many_glyphs.rs"
[package.metadata.example.many_glyphs]
name = "Many Glyphs"
description = "Simple benchmark to test text rendering."
category = "Stress Tests"
wasm = true
[[example]]
name = "many_lights"
path = "examples/stress_tests/many_lights.rs"
[package.metadata.example.many_lights]
name = "Many Lights"
description = "Simple benchmark to test rendering many point lights. Run with `WGPU_SETTINGS_PRIO=webgl2` to restrict to uniform buffers and max 256 lights"
category = "Stress Tests"
wasm = true
[[example]]
name = "many_sprites"
path = "examples/stress_tests/many_sprites.rs"
[package.metadata.example.many_sprites]
name = "Many Sprites"
description = "Displays many sprites in a grid arrangement! Used for performance testing. Use `--colored` to enable color tinted sprites."
category = "Stress Tests"
wasm = true
[[example]]
name = "transform_hierarchy"
path = "examples/stress_tests/transform_hierarchy.rs"
[package.metadata.example.transform_hierarchy]
name = "Transform Hierarchy"
description = "Various test cases for hierarchy and transform propagation performance"
category = "Stress Tests"
wasm = true
[[example]]
name = "text_pipeline"
path = "examples/stress_tests/text_pipeline.rs"
[package.metadata.example.text_pipeline]
name = "Text Pipeline"
description = "Text Pipeline benchmark"
category = "Stress Tests"
wasm = false
# Tools
[[example]]
name = "scene_viewer"
path = "examples/tools/scene_viewer/main.rs"
[package.metadata.example.scene_viewer]
name = "Scene Viewer"
description = "A simple way to view glTF models with Bevy. Just run `cargo run --release --example scene_viewer /path/to/model.gltf#Scene0`, replacing the path as appropriate. With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory"
category = "Tools"
wasm = true
[[example]]
name = "gamepad_viewer"
path = "examples/tools/gamepad_viewer.rs"
[package.metadata.example.gamepad_viewer]
name = "Gamepad Viewer"
description = "Shows a visualization of gamepad buttons, sticks, and triggers"
category = "Tools"
wasm = false
Reduce internal system order ambiguities, and add an example explaining them (#7383) # Objective - Bevy should not have any "internal" execution order ambiguities. These clutter the output of user-facing error reporting, and can result in nasty, nondetermistic, very difficult to solve bugs. - Verifying this currently involves repeated non-trivial manual work. ## Solution - [x] add an example to quickly check this - ~~[ ] ensure that this example panics if there are any unresolved ambiguities~~ - ~~[ ] run the example in CI :smiling_imp:~~ There's one tricky ambiguity left, between UI and animation. I don't have the tools to fix this without system set configuration, so the remaining work is going to be left to #7267 or another PR after that. ``` 2023-01-27T18:38:42.989405Z INFO bevy_ecs::schedule::ambiguity_detection: Execution order ambiguities detected, you might want to add an explicit dependency relation between some of these systems: * Parallel systems: -- "bevy_animation::animation_player" and "bevy_ui::flex::flex_node_system" conflicts: ["bevy_transform::components::transform::Transform"] ``` ## Changelog Resolved internal execution order ambiguities for: 1. Transform propagation (ignored, we need smarter filter checking). 2. Gamepad processing (fixed). 3. bevy_winit's window handling (fixed). 4. Cascaded shadow maps and perspectives (fixed). Also fixed a desynchronized state bug that could occur when the `Window` component is removed and then added to the same entity in a single frame.
2023-01-31 01:47:00 +00:00
[[example]]
name = "nondeterministic_system_order"
path = "examples/ecs/nondeterministic_system_order.rs"
[package.metadata.example.nondeterministic_system_order]
name = "Nondeterministic System Order"
description = "Systems run in paralell, but their order isn't always deteriministic. Here's how to detect and fix this."
category = "ECS (Entity Component System)"
wasm = false
[[example]]
name = "3d_rotation"
path = "examples/transforms/3d_rotation.rs"
[package.metadata.example.3d_rotation]
name = "3D Rotation"
description = "Illustrates how to (constantly) rotate an object around an axis"
category = "Transforms"
wasm = true
[[example]]
name = "scale"
path = "examples/transforms/scale.rs"
[package.metadata.example.scale]
name = "Scale"
description = "Illustrates how to scale an object in each direction"
category = "Transforms"
wasm = true
[[example]]
name = "transform"
path = "examples/transforms/transform.rs"
[package.metadata.example.transform]
name = "Transform"
description = "Shows multiple transformations of objects"
category = "Transforms"
wasm = true
[[example]]
name = "translation"
path = "examples/transforms/translation.rs"
[package.metadata.example.translation]
name = "Translation"
description = "Illustrates how to move an object along an axis"
category = "Transforms"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# UI (User Interface)
[[example]]
name = "button"
path = "examples/ui/button.rs"
[package.metadata.example.button]
name = "Button"
description = "Illustrates creating and updating a button"
category = "UI (User Interface)"
wasm = true
[[example]]
name = "window_fallthrough"
path = "examples/ui/window_fallthrough.rs"
[package.metadata.example.window_fallthrough]
name = "Window Fallthrough"
description = "Illustrates how to access `winit::window::Window`'s `hittest` functionality."
category = "UI (User Interface)"
wasm = false
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
[[example]]
name = "font_atlas_debug"
path = "examples/ui/font_atlas_debug.rs"
[package.metadata.example.font_atlas_debug]
name = "Font Atlas Debug"
description = "Illustrates how FontAtlases are populated (used to optimize text rendering internally)"
category = "UI (User Interface)"
wasm = true
[[example]]
name = "relative_cursor_position"
path = "examples/ui/relative_cursor_position.rs"
[package.metadata.example.relative_cursor_position]
name = "Relative Cursor Position"
description = "Showcases the RelativeCursorPosition component"
category = "UI (User Interface)"
wasm = true
2020-05-13 20:09:32 +00:00
[[example]]
name = "text"
path = "examples/ui/text.rs"
[package.metadata.example.text]
name = "Text"
description = "Illustrates creating and updating text"
category = "UI (User Interface)"
wasm = true
[[example]]
name = "text_debug"
path = "examples/ui/text_debug.rs"
[package.metadata.example.text_debug]
name = "Text Debug"
description = "An example for debugging text layout"
category = "UI (User Interface)"
wasm = true
[[example]]
name = "flex_layout"
path = "examples/ui/flex_layout.rs"
[package.metadata.example.flex_layout]
name = "Flex Layout"
description = "Demonstrates how the AlignItems and JustifyContent properties can be composed to layout nodes and position text"
category = "UI (User Interface)"
wasm = false
2020-05-01 20:12:47 +00:00
[[example]]
name = "transparency_ui"
path = "examples/ui/transparency_ui.rs"
[package.metadata.example.transparency_ui]
name = "Transparency UI"
description = "Demonstrates transparency for UI"
category = "UI (User Interface)"
wasm = true
Add z-index support with a predictable UI stack (#5877) # Objective Add consistent UI rendering and interaction where deep nodes inside two different hierarchies will never render on top of one-another by default and offer an escape hatch (z-index) for nodes to change their depth. ## The problem with current implementation The current implementation of UI rendering is broken in that regard, mainly because [it sets the Z value of the `Transform` component based on a "global Z" space](https://github.com/bevyengine/bevy/blob/main/crates/bevy_ui/src/update.rs#L43) shared by all nodes in the UI. This doesn't account for the fact that each node's final `GlobalTransform` value will be relative to its parent. This effectively makes the depth unpredictable when two deep trees are rendered on top of one-another. At the moment, it's also up to each part of the UI code to sort all of the UI nodes. The solution that's offered here does the full sorting of UI node entities once and offers the result through a resource so that all systems can use it. ## Solution ### New ZIndex component This adds a new optional `ZIndex` enum component for nodes which offers two mechanism: - `ZIndex::Local(i32)`: Overrides the depth of the node relative to its siblings. - `ZIndex::Global(i32)`: Overrides the depth of the node relative to the UI root. This basically allows any node in the tree to "escape" the parent and be ordered relative to the entire UI. Note that in the current implementation, omitting `ZIndex` on a node has the same result as adding `ZIndex::Local(0)`. Additionally, the "global" stacking context is essentially a way to add your node to the root stacking context, so using `ZIndex::Local(n)` on a root node (one without parent) will share that space with all nodes using `Index::Global(n)`. ### New UiStack resource This adds a new `UiStack` resource which is calculated from both hierarchy and `ZIndex` during UI update and contains a vector of all node entities in the UI, ordered by depth (from farthest from camera to closest). This is exposed publicly by the bevy_ui crate with the hope that it can be used for consistent ordering and to reduce the amount of sorting that needs to be done by UI systems (i.e. instead of sorting everything by `global_transform.z` in every system, this array can be iterated over). ### New z_index example This also adds a new z_index example that showcases the new `ZIndex` component. It's also a good general demo of the new UI stack system, because making this kind of UI was very broken with the old system (e.g. nodes would render on top of each other, not respecting hierarchy or insert order at all). ![image](https://user-images.githubusercontent.com/1060971/189015985-8ea8f989-0e9d-4601-a7e0-4a27a43a53f9.png) --- ## Changelog - Added the `ZIndex` component to bevy_ui. - Added the `UiStack` resource to bevy_ui, and added implementation in a new `stack.rs` module. - Removed the previous Z updating system from bevy_ui, because it was replaced with the above. - Changed bevy_ui rendering to use UiStack instead of z ordering. - Changed bevy_ui focus/interaction system to use UiStack instead of z ordering. - Added a new z_index example. ## ZIndex demo Here's a demo I wrote to test these features https://user-images.githubusercontent.com/1060971/188329295-d7beebd6-9aee-43ab-821e-d437df5dbe8a.mp4 Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-11-02 22:06:04 +00:00
[[example]]
name = "z_index"
path = "examples/ui/z_index.rs"
[package.metadata.example.z_index]
name = "UI Z-Index"
description = "Demonstrates how to control the relative depth (z-position) of UI elements"
category = "UI (User Interface)"
wasm = true
[[example]]
2020-05-01 20:12:47 +00:00
name = "ui"
path = "examples/ui/ui.rs"
[package.metadata.example.ui]
name = "UI"
description = "Illustrates various features of Bevy UI"
category = "UI (User Interface)"
wasm = true
[[example]]
name = "ui_scaling"
path = "examples/ui/ui_scaling.rs"
[package.metadata.example.ui_scaling]
name = "UI Scaling"
description = "Illustrates how to scale the UI"
category = "UI (User Interface)"
wasm = true
Cleanup of Markdown Files and add CI Checking (#1463) I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo. The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md Rules I didn't follow/fix: * MD024/no-duplicate-heading * Changelog: Here Heading will always repeat. * Examples Readme: Platform-specific documentation should be symmetrical. * MD025/single-title * MD026/no-trailing-punctuation * Caused by the ! in "Hello, World!". * MD033/no-inline-html * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much. * ~~MD036/no-emphasis-as-heading:~~ * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~ * ~~MD041/first-line-heading~~ * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~ --- I also sorted the Examples in the Readme and Cargo.toml in this order/Priority: * Topic/Folder * Introductionary Examples * Alphabetical Order The explanation for each case, where it isn't Alphabetical : * Diagnostics * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own. * ECS (Entity Component System) * ecs_guide: The guide should be read, before diving into other Features. * Reflection * reflection: Basic Explanation should be read, before more advanced Topics. * WASM Examples * hello_wasm: It's "Hello, World!".
2021-02-22 04:50:05 +00:00
# Window
2020-06-25 22:24:27 +00:00
[[example]]
name = "clear_color"
path = "examples/window/clear_color.rs"
[package.metadata.example.clear_color]
name = "Clear Color"
description = "Creates a solid color window"
category = "Window"
wasm = true
Reduce power usage with configurable event loop (#3974) # Objective - Reduce power usage for games when not focused. - Reduce power usage to ~0 when a desktop application is minimized (opt-in). - Reduce power usage when focused, only updating on a `winit` event, or the user sends a redraw request. (opt-in) https://user-images.githubusercontent.com/2632925/156904387-ec47d7de-7f06-4c6f-8aaf-1e952c1153a2.mp4 Note resource usage in the Task Manager in the above video. ## Solution - Added a type `UpdateMode` that allows users to specify how the winit event loop is updated, without exposing winit types. - Added two fields to `WinitConfig`, both with the `UpdateMode` type. One configures how the application updates when focused, and the other configures how the application behaves when it is not focused. Users can modify this resource manually to set the type of event loop control flow they want. - For convenience, two functions were added to `WinitConfig`, that provide reasonable presets: `game()` (default) and `desktop_app()`. - The `game()` preset, which is used by default, is unchanged from current behavior with one exception: when the app is out of focus the app updates at a minimum of 10fps, or every time a winit event is received. This has a huge positive impact on power use and responsiveness on my machine, which will otherwise continue running the app at many hundreds of fps when out of focus or minimized. - The `desktop_app()` preset is fully reactive, only updating when user input (winit event) is supplied or a `RedrawRequest` event is sent. When the app is out of focus, it only updates on `Window` events - i.e. any winit event that directly interacts with the window. What this means in practice is that the app uses *zero* resources when minimized or not interacted with, but still updates fluidly when the app is out of focus and the user mouses over the application. - Added a `RedrawRequest` event so users can force an update even if there are no events. This is useful in an application when you want to, say, run an animation even when the user isn't providing input. - Added an example `low_power` to demonstrate these changes ## Usage Configuring the event loop: ```rs use bevy::winit::{WinitConfig}; // ... .insert_resource(WinitConfig::desktop_app()) // preset // or .insert_resource(WinitConfig::game()) // preset // or .insert_resource(WinitConfig{ .. }) // manual ``` Requesting a redraw: ```rs use bevy::window::RequestRedraw; // ... fn request_redraw(mut event: EventWriter<RequestRedraw>) { event.send(RequestRedraw); } ``` ## Other details - Because we have a single event loop for multiple windows, every time I've mentioned "focused" above, I more precisely mean, "if at least one bevy window is focused". - Due to a platform bug in winit (https://github.com/rust-windowing/winit/issues/1619), we can't simply use `Window::request_redraw()`. As a workaround, this PR will temporarily set the window mode to `Poll` when a redraw is requested. This is then reset to the user's `WinitConfig` setting on the next frame.
2022-03-07 23:32:05 +00:00
[[example]]
name = "low_power"
path = "examples/window/low_power.rs"
[package.metadata.example.low_power]
name = "Low Power"
description = "Demonstrates settings to reduce power use for bevy applications"
category = "Window"
wasm = true
[[example]]
name = "multiple_windows"
path = "examples/window/multiple_windows.rs"
2020-06-25 22:24:27 +00:00
[package.metadata.example.multiple_windows]
name = "Multiple Windows"
description = "Demonstrates creating multiple windows, and rendering to them"
category = "Window"
wasm = false
[[example]]
name = "scale_factor_override"
path = "examples/window/scale_factor_override.rs"
[package.metadata.example.scale_factor_override]
name = "Scale Factor Override"
description = "Illustrates how to customize the default window settings"
category = "Window"
wasm = true
[[example]]
name = "transparent_window"
path = "examples/window/transparent_window.rs"
[package.metadata.example.transparent_window]
name = "Transparent Window"
description = "Illustrates making the window transparent and hiding the window decoration"
category = "Window"
wasm = false
[[example]]
name = "window_settings"
path = "examples/window/window_settings.rs"
[package.metadata.example.window_settings]
name = "Window Settings"
description = "Demonstrates customizing default window settings"
category = "Window"
wasm = true
Add an example to test small window sizes (#3597) # Objective We keep getting issues where things break at small window sizes, e.g #3368 (caused by #3153), #3596 ('caused' by #3545) ## Solution - Add a test that we can make small windows. Currently, this fails on my machine with some quite scary vulkan errors: ``` 2022-01-08T22:55:13.770261Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,60), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,56), minImageExtent = (225,56), maxImageExtent = (225,56). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) 2022-01-08T22:55:13.770808Z ERROR wgpu_hal::vulkan::instance: objects: (type: DEVICE, hndl: 0x1adbd410a60, name: ?) 2022-01-08T22:55:13.787403Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,56), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,52), minImageExtent = (225,52), maxImageExtent = (225,52). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) ``` etc. This might be a new issue here, although I'm surprised it's vulkan giving this error; wgpu should stop it if this is illegal.
2022-04-26 22:15:24 +00:00
[[example]]
name = "resizing"
path = "tests/window/resizing.rs"
[package.metadata.example.resizing]
hidden = true
Add an example to test small window sizes (#3597) # Objective We keep getting issues where things break at small window sizes, e.g #3368 (caused by #3153), #3596 ('caused' by #3545) ## Solution - Add a test that we can make small windows. Currently, this fails on my machine with some quite scary vulkan errors: ``` 2022-01-08T22:55:13.770261Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,60), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,56), minImageExtent = (225,56), maxImageExtent = (225,56). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) 2022-01-08T22:55:13.770808Z ERROR wgpu_hal::vulkan::instance: objects: (type: DEVICE, hndl: 0x1adbd410a60, name: ?) 2022-01-08T22:55:13.787403Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,56), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,52), minImageExtent = (225,52), maxImageExtent = (225,52). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) ``` etc. This might be a new issue here, although I'm surprised it's vulkan giving this error; wgpu should stop it if this is illegal.
2022-04-26 22:15:24 +00:00
[[example]]
name = "minimising"
path = "tests/window/minimising.rs"
[package.metadata.example.minimising]
hidden = true
Add an example to test small window sizes (#3597) # Objective We keep getting issues where things break at small window sizes, e.g #3368 (caused by #3153), #3596 ('caused' by #3545) ## Solution - Add a test that we can make small windows. Currently, this fails on my machine with some quite scary vulkan errors: ``` 2022-01-08T22:55:13.770261Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,60), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,56), minImageExtent = (225,56), maxImageExtent = (225,56). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) 2022-01-08T22:55:13.770808Z ERROR wgpu_hal::vulkan::instance: objects: (type: DEVICE, hndl: 0x1adbd410a60, name: ?) 2022-01-08T22:55:13.787403Z ERROR wgpu_hal::vulkan::instance: VALIDATION [VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 (0x7cd0911d)] Validation Error: [ VUID-VkSwapchainCreateInfoKHR-imageExtent-01274 ] Object 0: handle = 0x1adbd410a60, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x7cd0911d | vkCreateSwapchainKHR() called with imageExtent = (225,56), which is outside the bounds returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR(): currentExtent = (225,52), minImageExtent = (225,52), maxImageExtent = (225,52). The Vulkan spec states: imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface (https://vulkan.lunarg.com/doc/view/1.2.198.1/windows/1.2-extensions/vkspec.html#VUID-VkSwapchainCreateInfoKHR-imageExtent-01274) ``` etc. This might be a new issue here, although I'm surprised it's vulkan giving this error; wgpu should stop it if this is illegal.
2022-04-26 22:15:24 +00:00
[[example]]
name = "window_resizing"
path = "examples/window/window_resizing.rs"
[package.metadata.example.window_resizing]
name = "Window Resizing"
description = "Demonstrates resizing and responding to resizing a window"
category = "Window"
wasm = true
[profile.wasm-release]
inherits = "release"
opt-level = "z"
lto = "fat"
codegen-units = 1
[profile.stress-test]
inherits = "release"
lto = "fat"
panic = "abort"