0f1c75796b
# Objective `bevy_assets` has long been unapproachable for contributors and users. More and better documentation would help that. We're gradually moving towards globally denying missing docs (#3492)! However, writing all of the hundreds of missing doc strings in a single go will be miserable to review. ## Solution Remove the allow for missing docs temporarily, and then pick some easy missing doc warnings largely at random to tackle. Stop when the change set is starting to feel intimidating.
52 lines
2.5 KiB
Rust
52 lines
2.5 KiB
Rust
use bevy_reflect::{Reflect, ReflectDeserialize, ReflectSerialize};
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
bitflags::bitflags! {
|
|
/// Defines where the asset will be used.
|
|
///
|
|
/// If an asset is set to the `RENDER_WORLD` but not the `MAIN_WORLD`, the asset will be
|
|
/// unloaded from the asset server once it's been extracted and prepared in the render world.
|
|
///
|
|
/// Unloading the asset saves on memory, as for most cases it is no longer necessary to keep
|
|
/// it in RAM once it's been uploaded to the GPU's VRAM. However, this means you can no longer
|
|
/// access the asset from the CPU (via the `Assets<T>` resource) once unloaded (without re-loading it).
|
|
///
|
|
/// If you never need access to the asset from the CPU past the first frame it's loaded on,
|
|
/// or only need very infrequent access, then set this to `RENDER_WORLD`. Otherwise, set this to
|
|
/// `RENDER_WORLD | MAIN_WORLD`.
|
|
///
|
|
/// If you have an asset that doesn't actually need to end up in the render world, like an Image
|
|
/// that will be decoded into another Image asset, use `MAIN_WORLD` only.
|
|
///
|
|
/// ## Platform-specific
|
|
///
|
|
/// On Wasm, it is not possible for now to free reserved memory. To control memory usage, load assets
|
|
/// in sequence and unload one before loading the next. See this
|
|
/// [discussion about memory management](https://github.com/WebAssembly/design/issues/1397) for more
|
|
/// details.
|
|
#[repr(transparent)]
|
|
#[derive(Serialize, Deserialize, Hash, Clone, Copy, PartialEq, Eq, Debug, Reflect)]
|
|
#[reflect(opaque)]
|
|
#[reflect(Serialize, Deserialize, Hash, PartialEq, Debug)]
|
|
pub struct RenderAssetUsages: u8 {
|
|
/// The bit flag for the main world.
|
|
const MAIN_WORLD = 1 << 0;
|
|
/// The bit flag for the render world.
|
|
const RENDER_WORLD = 1 << 1;
|
|
}
|
|
}
|
|
|
|
impl Default for RenderAssetUsages {
|
|
/// Returns the default render asset usage flags:
|
|
/// `RenderAssetUsages::MAIN_WORLD | RenderAssetUsages::RENDER_WORLD`
|
|
///
|
|
/// This default configuration ensures the asset persists in the main world, even after being prepared for rendering.
|
|
///
|
|
/// If your asset does not change, consider using `RenderAssetUsages::RENDER_WORLD` exclusively. This will cause
|
|
/// the asset to be unloaded from the main world once it has been prepared for rendering. If the asset does not need
|
|
/// to reach the render world at all, use `RenderAssetUsages::MAIN_WORLD` exclusively.
|
|
fn default() -> Self {
|
|
RenderAssetUsages::MAIN_WORLD | RenderAssetUsages::RENDER_WORLD
|
|
}
|
|
}
|