bevy/crates/bevy_render/src/mesh/shape/regular_polygon.rs
JMS55 44424391fe
Unload render assets from RAM (#10520)
# Objective
- No point in keeping Meshes/Images in RAM once they're going to be sent
to the GPU, and kept in VRAM. This saves a _significant_ amount of
memory (several GBs) on scenes like bistro.
- References
  - https://github.com/bevyengine/bevy/pull/1782
  - https://github.com/bevyengine/bevy/pull/8624 

## Solution
- Augment RenderAsset with the capability to unload the underlying asset
after extracting to the render world.
- Mesh/Image now have a cpu_persistent_access field. If this field is
RenderAssetPersistencePolicy::Unload, the asset will be unloaded from
Assets<T>.
- A new AssetEvent is sent upon dropping the last strong handle for the
asset, which signals to the RenderAsset to remove the GPU version of the
asset.

---

## Changelog
- Added `AssetEvent::NoLongerUsed` and
`AssetEvent::is_no_longer_used()`. This event is sent when the last
strong handle of an asset is dropped.
- Rewrote the API for `RenderAsset` to allow for unloading the asset
data from the CPU.
- Added `RenderAssetPersistencePolicy`.
- Added `Mesh::cpu_persistent_access` for memory savings when the asset
is not needed except for on the GPU.
- Added `Image::cpu_persistent_access` for memory savings when the asset
is not needed except for on the GPU.
- Added `ImageLoaderSettings::cpu_persistent_access`.
- Added `ExrTextureLoaderSettings`.
- Added `HdrTextureLoaderSettings`.

## Migration Guide
- Asset loaders (GLTF, etc) now load meshes and textures without
`cpu_persistent_access`. These assets will be removed from
`Assets<Mesh>` and `Assets<Image>` once `RenderAssets<Mesh>` and
`RenderAssets<Image>` contain the GPU versions of these assets, in order
to reduce memory usage. If you require access to the asset data from the
CPU in future frames after the GLTF asset has been loaded, modify all
dependent `Mesh` and `Image` assets and set `cpu_persistent_access` to
`RenderAssetPersistencePolicy::Keep`.
- `Mesh` now requires a new `cpu_persistent_access` field. Set it to
`RenderAssetPersistencePolicy::Keep` to mimic the previous behavior.
- `Image` now requires a new `cpu_persistent_access` field. Set it to
`RenderAssetPersistencePolicy::Keep` to mimic the previous behavior.
- `MorphTargetImage::new()` now requires a new `cpu_persistent_access`
parameter. Set it to `RenderAssetPersistencePolicy::Keep` to mimic the
previous behavior.
- `DynamicTextureAtlasBuilder::add_texture()` now requires that the
`TextureAtlas` you pass has an `Image` with `cpu_persistent_access:
RenderAssetPersistencePolicy::Keep`. Ensure you construct the image
properly for the texture atlas.
- The `RenderAsset` trait has significantly changed, and requires
adapting your existing implementations.
  - The trait now requires `Clone`.
- The `ExtractedAsset` associated type has been removed (the type itself
is now extracted).
  - The signature of `prepare_asset()` is slightly different
- A new `persistence_policy()` method is now required (return
RenderAssetPersistencePolicy::Unload to match the previous behavior).
- Match on the new `NoLongerUsed` variant for exhaustive matches of
`AssetEvent`.
2024-01-03 03:31:04 +00:00

114 lines
3.0 KiB
Rust

use crate::{
mesh::{Indices, Mesh},
render_asset::RenderAssetPersistencePolicy,
};
use wgpu::PrimitiveTopology;
/// A regular polygon in the `XY` plane
#[derive(Debug, Copy, Clone)]
pub struct RegularPolygon {
/// Circumscribed radius in the `XY` plane.
///
/// In other words, the vertices of this polygon will all touch a circle of this radius.
pub radius: f32,
/// Number of sides.
pub sides: usize,
}
impl Default for RegularPolygon {
fn default() -> Self {
Self {
radius: 0.5,
sides: 6,
}
}
}
impl RegularPolygon {
/// Creates a regular polygon in the `XY` plane
pub fn new(radius: f32, sides: usize) -> Self {
Self { radius, sides }
}
}
impl From<RegularPolygon> for Mesh {
fn from(polygon: RegularPolygon) -> Self {
let RegularPolygon { radius, sides } = polygon;
debug_assert!(sides > 2, "RegularPolygon requires at least 3 sides.");
let mut positions = Vec::with_capacity(sides);
let mut normals = Vec::with_capacity(sides);
let mut uvs = Vec::with_capacity(sides);
let step = std::f32::consts::TAU / sides as f32;
for i in 0..sides {
let theta = std::f32::consts::FRAC_PI_2 - i as f32 * step;
let (sin, cos) = theta.sin_cos();
positions.push([cos * radius, sin * radius, 0.0]);
normals.push([0.0, 0.0, 1.0]);
uvs.push([0.5 * (cos + 1.0), 1.0 - 0.5 * (sin + 1.0)]);
}
let mut indices = Vec::with_capacity((sides - 2) * 3);
for i in 1..(sides as u32 - 1) {
// Vertices are generated in CW order above, hence the reversed indices here
// to emit triangle vertices in CCW order.
indices.extend_from_slice(&[0, i + 1, i]);
}
Mesh::new(
PrimitiveTopology::TriangleList,
RenderAssetPersistencePolicy::Unload,
)
.with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, positions)
.with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
.with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
.with_indices(Some(Indices::U32(indices)))
}
}
/// A circle in the `XY` plane
#[derive(Debug, Copy, Clone)]
pub struct Circle {
/// Inscribed radius in the `XY` plane.
pub radius: f32,
/// The number of vertices used.
pub vertices: usize,
}
impl Default for Circle {
fn default() -> Self {
Self {
radius: 0.5,
vertices: 64,
}
}
}
impl Circle {
/// Creates a circle in the `XY` plane
pub fn new(radius: f32) -> Self {
Self {
radius,
..Default::default()
}
}
}
impl From<Circle> for RegularPolygon {
fn from(circle: Circle) -> Self {
Self {
radius: circle.radius,
sides: circle.vertices,
}
}
}
impl From<Circle> for Mesh {
fn from(circle: Circle) -> Self {
Mesh::from(RegularPolygon::from(circle))
}
}