bevy/docs/cargo_features.md
MichiRecRoom 94d40d206e
Replace the wgpu_trace feature with a field in bevy_render::settings::WgpuSettings (#14842)
# Objective
- Remove the `wgpu_trace` feature while still making it easy/possible to
record wgpu traces for debugging.
- Close #14725.
- Get a taste of the bevy codebase. :P

## Solution
This PR performs the above objective by removing the `wgpu_trace`
feature from all `Cargo.toml` files.

However, wgpu traces are still useful for debugging - but to record
them, you need to pass in a directory path to store the traces in. To
avoid forcing users into manually creating the renderer,
`bevy_render::settings::WgpuSettings` now has a `trace_path` field, so
that all of Bevy's automatic initialization can happen while still
allowing for tracing.

## Testing
- Did you test these changes? If so, how?
- I have tested these changes, but only via running `cargo run -p ci`. I
am hoping the Github Actions workflows will catch anything I missed.
- Are there any parts that need more testing?
  - I do not believe so.
- How can other people (reviewers) test your changes? Is there anything
specific they need to know?
- If you want to test these changes, I have updated the debugging guide
(`docs/debugging.md`) section on WGPU Tracing.
- If relevant, what platforms did you test these changes on, and are
there any important ones you can't test?
- I ran the above command on a Windows 10 64-bit (x64) machine, using
the `stable-x86_64-pc-windows-msvc` toolchain. I do not have anything
set up for other platforms or targets (though I can't imagine this needs
testing on other platforms).

---

## Migration Guide

1. The `bevy/wgpu_trace`, `bevy_render/wgpu_trace`, and
`bevy_internal/wgpu_trace` features no longer exist. Remove them from
your `Cargo.toml`, CI, tooling, and what-not.
2. Follow the instructions in the updated `docs/debugging.md` file in
the repository, under the WGPU Tracing section.

Because of the changes made, you can now generate traces to any path,
rather than the hardcoded `%WorkspaceRoot%/wgpu_trace` (where
`%WorkspaceRoot%` is... the root of your crate's workspace) folder.

(If WGPU hasn't restored tracing functionality...) Do note that WGPU has
not yet restored tracing functionality. However, once it does, the above
should be sufficient to generate new traces.

---------

Co-authored-by: TrialDragon <31419708+TrialDragon@users.noreply.github.com>
2024-08-25 14:16:11 +00:00

6.2 KiB

Cargo Features

Bevy exposes many features to customise the engine. Enabling them add functionalities but often come at the cost of longer compilation times and extra dependencies.

Default Features

The default feature set enables most of the expected features of a game engine, like rendering in both 2D and 3D, asset loading, audio and UI. To help reduce compilation time, consider disabling default features and enabling only those you need.

feature name description
android_shared_stdcxx Enable using a shared stdlib for cxx on Android
animation Enable animation support, and glTF animation loading
bevy_animation Provides animation functionality
bevy_asset Provides asset functionality
bevy_audio Provides audio functionality
bevy_color Provides shared color types and operations
bevy_core_pipeline Provides cameras and other basic render pipeline features
bevy_gilrs Adds gamepad support
bevy_gizmos Adds support for rendering gizmos
bevy_gltf glTF support
bevy_pbr Adds PBR rendering
bevy_picking Provides picking functionality
bevy_render Provides rendering functionality
bevy_scene Provides scene functionality
bevy_sprite Provides sprite functionality
bevy_state Enable built in global state machines
bevy_text Provides text functionality
bevy_ui A custom ECS-driven UI framework
bevy_winit winit window and input backend
default_font Include a default font, containing only ASCII characters, at the cost of a 20kB binary size increase
hdr HDR image format support
ktx2 KTX2 compressed texture support
multi_threaded Enables multithreaded parallelism in the engine. Disabling it forces all engine tasks to run on a single thread.
png PNG image format support
smaa_luts Include SMAA Look Up Tables KTX2 Files
sysinfo_plugin Enables system information diagnostic plugin
tonemapping_luts Include tonemapping Look Up Tables KTX2 files. If everything is pink, you need to enable this feature or change the Tonemapping method on your Camera2dBundle or Camera3dBundle.
vorbis OGG/VORBIS audio format support
webgl2 Enable some limitations to be able to use WebGL2. Please refer to the WebGL2 and WebGPU section of the examples README for more information on how to run Wasm builds with WebGPU.
x11 X11 display server support
zstd For KTX2 supercompression

Optional Features

feature name description
accesskit_unix Enable AccessKit on Unix backends (currently only works with experimental screen readers and forks.)
asset_processor Enables the built-in asset processor for processed assets.
async-io Use async-io's implementation of block_on instead of futures-lite's implementation. This is preferred if your application uses async-io.
basis-universal Basis Universal compressed texture support
bevy_ci_testing Enable systems that allow for automated testing on CI
bevy_debug_stepping Enable stepping-based debugging of Bevy systems
bevy_dev_tools Provides a collection of developer tools
bmp BMP image format support
dds DDS compressed texture support
debug_glam_assert Enable assertions in debug builds to check the validity of parameters passed to glam
detailed_trace Enable detailed trace event logging. These trace events are expensive even when off, thus they require compile time opt-in
dynamic_linking Force dynamic linking, which improves iterative compile times
embedded_watcher Enables watching in memory asset providers for Bevy Asset hot-reloading
exr EXR image format support
file_watcher Enables watching the filesystem for Bevy Asset hot-reloading
flac FLAC audio format support
glam_assert Enable assertions to check the validity of parameters passed to glam
ios_simulator Enable support for the ios_simulator by downgrading some rendering capabilities
jpeg JPEG image format support
meshlet Enables the meshlet renderer for dense high-poly scenes (experimental)
meshlet_processor Enables processing meshes into meshlet meshes for bevy_pbr
minimp3 MP3 audio format support (through minimp3)
mp3 MP3 audio format support
pbr_anisotropy_texture Enable support for anisotropy texture in the StandardMaterial, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs
pbr_multi_layer_material_textures Enable support for multi-layer material textures in the StandardMaterial, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs
pbr_transmission_textures Enable support for transmission-related textures in the StandardMaterial, at the risk of blowing past the global, per-shader texture limit on older/lower-end GPUs
pnm PNM image format support, includes pam, pbm, pgm and ppm
reflect_functions Enable function reflection
serialize Enable serialization support through serde
shader_format_glsl Enable support for shaders in GLSL
shader_format_spirv Enable support for shaders in SPIR-V
symphonia-aac AAC audio format support (through symphonia)
symphonia-all AAC, FLAC, MP3, MP4, OGG/VORBIS, and WAV audio formats support (through symphonia)
symphonia-flac FLAC audio format support (through symphonia)
symphonia-isomp4 MP4 audio format support (through symphonia)
symphonia-vorbis OGG/VORBIS audio format support (through symphonia)
symphonia-wav WAV audio format support (through symphonia)
tga TGA image format support
trace Tracing support
trace_chrome Tracing support, saving a file in Chrome Tracing format
trace_tracy Tracing support, exposing a port for Tracy
trace_tracy_memory Tracing support, with memory profiling, exposing a port for Tracy
track_change_detection Enables source location tracking for change detection, which can assist with debugging
wav WAV audio format support
wayland Wayland display server support
webgpu Enable support for WebGPU in Wasm. When enabled, this feature will override the webgl2 feature and you won't be able to run Wasm builds with WebGL2, only with WebGPU.
webp WebP image format support
zlib For KTX2 supercompression