dd812b3e49
# Objective In the Render World, there are a number of collections that are derived from Main World entities and are used to drive rendering. The most notable are: - `VisibleEntities`, which is generated in the `check_visibility` system and contains visible entities for a view. - `ExtractedInstances`, which maps entity ids to asset ids. In the old model, these collections were trivially kept in sync -- any extracted phase item could look itself up because the render entity id was guaranteed to always match the corresponding main world id. After #15320, this became much more complicated, and was leading to a number of subtle bugs in the Render World. The main rendering systems, i.e. `queue_material_meshes` and `queue_material2d_meshes`, follow a similar pattern: ```rust for visible_entity in visible_entities.iter::<With<Mesh2d>>() { let Some(mesh_instance) = render_mesh_instances.get_mut(visible_entity) else { continue; }; // Look some more stuff up and specialize the pipeline... let bin_key = Opaque2dBinKey { pipeline: pipeline_id, draw_function: draw_opaque_2d, asset_id: mesh_instance.mesh_asset_id.into(), material_bind_group_id: material_2d.get_bind_group_id().0, }; opaque_phase.add( bin_key, *visible_entity, BinnedRenderPhaseType::mesh(mesh_instance.automatic_batching), ); } ``` In this case, `visible_entities` and `render_mesh_instances` are both collections that are created and keyed by Main World entity ids, and so this lookup happens to work by coincidence. However, there is a major unintentional bug here: namely, because `visible_entities` is a collection of Main World ids, the phase item being queued is created with a Main World id rather than its correct Render World id. This happens to not break mesh rendering because the render commands used for drawing meshes do not access the `ItemQuery` parameter, but demonstrates the confusion that is now possible: our UI phase items are correctly being queued with Render World ids while our meshes aren't. Additionally, this makes it very easy and error prone to use the wrong entity id to look up things like assets. For example, if instead we ignored visibility checks and queued our meshes via a query, we'd have to be extra careful to use `&MainEntity` instead of the natural `Entity`. ## Solution Make all collections that are derived from Main World data use `MainEntity` as their key, to ensure type safety and avoid accidentally looking up data with the wrong entity id: ```rust pub type MainEntityHashMap<V> = hashbrown::HashMap<MainEntity, V, EntityHash>; ``` Additionally, we make all `PhaseItem` be able to provide both their Main and Render World ids, to allow render phase implementors maximum flexibility as to what id should be used to look up data. You can think of this like tracking at the type level whether something in the Render World should use it's "primary key", i.e. entity id, or needs to use a foreign key, i.e. `MainEntity`. ## Testing ##### TODO: This will require extensive testing to make sure things didn't break! Additionally, some extraction logic has become more complicated and needs to be checked for regressions. ## Migration Guide With the advent of the retained render world, collections that contain references to `Entity` that are extracted into the render world have been changed to contain `MainEntity` in order to prevent errors where a render world entity id is used to look up an item by accident. Custom rendering code may need to be changed to query for `&MainEntity` in order to look up the correct item from such a collection. Additionally, users who implement their own extraction logic for collections of main world entity should strongly consider extracting into a different collection that uses `MainEntity` as a key. Additionally, render phases now require specifying both the `Entity` and `MainEntity` for a given `PhaseItem`. Custom render phases should ensure `MainEntity` is available when queuing a phase item.
215 lines
7.6 KiB
Rust
215 lines
7.6 KiB
Rust
#![expect(deprecated)]
|
|
|
|
use crate::{
|
|
CascadeShadowConfig, Cascades, DirectionalLight, Material, MeshMaterial3d, PointLight,
|
|
SpotLight, StandardMaterial,
|
|
};
|
|
use bevy_derive::{Deref, DerefMut};
|
|
use bevy_ecs::{
|
|
bundle::Bundle,
|
|
component::Component,
|
|
entity::{Entity, EntityHashMap},
|
|
reflect::ReflectComponent,
|
|
};
|
|
use bevy_reflect::{std_traits::ReflectDefault, Reflect};
|
|
use bevy_render::sync_world::MainEntity;
|
|
use bevy_render::{
|
|
mesh::Mesh3d,
|
|
primitives::{CascadesFrusta, CubemapFrusta, Frustum},
|
|
sync_world::SyncToRenderWorld,
|
|
view::{InheritedVisibility, ViewVisibility, Visibility},
|
|
};
|
|
use bevy_transform::components::{GlobalTransform, Transform};
|
|
|
|
/// A component bundle for PBR entities with a [`Mesh3d`] and a [`MeshMaterial3d<StandardMaterial>`].
|
|
#[deprecated(
|
|
since = "0.15.0",
|
|
note = "Use the `Mesh3d` and `MeshMaterial3d` components instead. Inserting them will now also insert the other components required by them automatically."
|
|
)]
|
|
pub type PbrBundle = MaterialMeshBundle<StandardMaterial>;
|
|
|
|
/// A component bundle for entities with a [`Mesh3d`] and a [`MeshMaterial3d`].
|
|
#[derive(Bundle, Clone)]
|
|
#[deprecated(
|
|
since = "0.15.0",
|
|
note = "Use the `Mesh3d` and `MeshMaterial3d` components instead. Inserting them will now also insert the other components required by them automatically."
|
|
)]
|
|
pub struct MaterialMeshBundle<M: Material> {
|
|
pub mesh: Mesh3d,
|
|
pub material: MeshMaterial3d<M>,
|
|
pub transform: Transform,
|
|
pub global_transform: GlobalTransform,
|
|
/// User indication of whether an entity is visible
|
|
pub visibility: Visibility,
|
|
/// Inherited visibility of an entity.
|
|
pub inherited_visibility: InheritedVisibility,
|
|
/// Algorithmically-computed indication of whether an entity is visible and should be extracted for rendering
|
|
pub view_visibility: ViewVisibility,
|
|
}
|
|
|
|
impl<M: Material> Default for MaterialMeshBundle<M> {
|
|
fn default() -> Self {
|
|
Self {
|
|
mesh: Default::default(),
|
|
material: Default::default(),
|
|
transform: Default::default(),
|
|
global_transform: Default::default(),
|
|
visibility: Default::default(),
|
|
inherited_visibility: Default::default(),
|
|
view_visibility: Default::default(),
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Collection of mesh entities visible for 3D lighting.
|
|
///
|
|
/// This component contains all mesh entities visible from the current light view.
|
|
/// The collection is updated automatically by [`crate::SimulationLightSystems`].
|
|
#[derive(Component, Clone, Debug, Default, Reflect, Deref, DerefMut)]
|
|
#[reflect(Component, Debug, Default)]
|
|
pub struct VisibleMeshEntities {
|
|
#[reflect(ignore)]
|
|
pub entities: Vec<Entity>,
|
|
}
|
|
|
|
#[derive(Component, Clone, Debug, Default, Reflect, Deref, DerefMut)]
|
|
#[reflect(Component, Debug, Default)]
|
|
pub struct RenderVisibleMeshEntities {
|
|
#[reflect(ignore)]
|
|
pub entities: Vec<(Entity, MainEntity)>,
|
|
}
|
|
|
|
#[derive(Component, Clone, Debug, Default, Reflect)]
|
|
#[reflect(Component, Debug, Default)]
|
|
pub struct CubemapVisibleEntities {
|
|
#[reflect(ignore)]
|
|
data: [VisibleMeshEntities; 6],
|
|
}
|
|
|
|
impl CubemapVisibleEntities {
|
|
pub fn get(&self, i: usize) -> &VisibleMeshEntities {
|
|
&self.data[i]
|
|
}
|
|
|
|
pub fn get_mut(&mut self, i: usize) -> &mut VisibleMeshEntities {
|
|
&mut self.data[i]
|
|
}
|
|
|
|
pub fn iter(&self) -> impl DoubleEndedIterator<Item = &VisibleMeshEntities> {
|
|
self.data.iter()
|
|
}
|
|
|
|
pub fn iter_mut(&mut self) -> impl DoubleEndedIterator<Item = &mut VisibleMeshEntities> {
|
|
self.data.iter_mut()
|
|
}
|
|
}
|
|
|
|
#[derive(Component, Clone, Debug, Default, Reflect)]
|
|
#[reflect(Component, Debug, Default)]
|
|
pub struct RenderCubemapVisibleEntities {
|
|
#[reflect(ignore)]
|
|
pub(crate) data: [RenderVisibleMeshEntities; 6],
|
|
}
|
|
|
|
impl RenderCubemapVisibleEntities {
|
|
pub fn get(&self, i: usize) -> &RenderVisibleMeshEntities {
|
|
&self.data[i]
|
|
}
|
|
|
|
pub fn get_mut(&mut self, i: usize) -> &mut RenderVisibleMeshEntities {
|
|
&mut self.data[i]
|
|
}
|
|
|
|
pub fn iter(&self) -> impl DoubleEndedIterator<Item = &RenderVisibleMeshEntities> {
|
|
self.data.iter()
|
|
}
|
|
|
|
pub fn iter_mut(&mut self) -> impl DoubleEndedIterator<Item = &mut RenderVisibleMeshEntities> {
|
|
self.data.iter_mut()
|
|
}
|
|
}
|
|
|
|
#[derive(Component, Clone, Debug, Default, Reflect)]
|
|
#[reflect(Component)]
|
|
pub struct CascadesVisibleEntities {
|
|
/// Map of view entity to the visible entities for each cascade frustum.
|
|
#[reflect(ignore)]
|
|
pub entities: EntityHashMap<Vec<VisibleMeshEntities>>,
|
|
}
|
|
|
|
#[derive(Component, Clone, Debug, Default, Reflect)]
|
|
#[reflect(Component)]
|
|
pub struct RenderCascadesVisibleEntities {
|
|
/// Map of view entity to the visible entities for each cascade frustum.
|
|
#[reflect(ignore)]
|
|
pub entities: EntityHashMap<Vec<RenderVisibleMeshEntities>>,
|
|
}
|
|
|
|
/// A component bundle for [`PointLight`] entities.
|
|
#[derive(Debug, Bundle, Default, Clone)]
|
|
#[deprecated(
|
|
since = "0.15.0",
|
|
note = "Use the `PointLight` component instead. Inserting it will now also insert the other components required by it automatically."
|
|
)]
|
|
pub struct PointLightBundle {
|
|
pub point_light: PointLight,
|
|
pub cubemap_visible_entities: CubemapVisibleEntities,
|
|
pub cubemap_frusta: CubemapFrusta,
|
|
pub transform: Transform,
|
|
pub global_transform: GlobalTransform,
|
|
/// Enables or disables the light
|
|
pub visibility: Visibility,
|
|
/// Inherited visibility of an entity.
|
|
pub inherited_visibility: InheritedVisibility,
|
|
/// Algorithmically-computed indication of whether an entity is visible and should be extracted for rendering
|
|
pub view_visibility: ViewVisibility,
|
|
/// Marker component that indicates that its entity needs to be synchronized to the render world
|
|
pub sync: SyncToRenderWorld,
|
|
}
|
|
|
|
/// A component bundle for spot light entities
|
|
#[derive(Debug, Bundle, Default, Clone)]
|
|
#[deprecated(
|
|
since = "0.15.0",
|
|
note = "Use the `SpotLight` component instead. Inserting it will now also insert the other components required by it automatically."
|
|
)]
|
|
pub struct SpotLightBundle {
|
|
pub spot_light: SpotLight,
|
|
pub visible_entities: VisibleMeshEntities,
|
|
pub frustum: Frustum,
|
|
pub transform: Transform,
|
|
pub global_transform: GlobalTransform,
|
|
/// Enables or disables the light
|
|
pub visibility: Visibility,
|
|
/// Inherited visibility of an entity.
|
|
pub inherited_visibility: InheritedVisibility,
|
|
/// Algorithmically-computed indication of whether an entity is visible and should be extracted for rendering
|
|
pub view_visibility: ViewVisibility,
|
|
/// Marker component that indicates that its entity needs to be synchronized to the render world
|
|
pub sync: SyncToRenderWorld,
|
|
}
|
|
|
|
/// A component bundle for [`DirectionalLight`] entities.
|
|
#[derive(Debug, Bundle, Default, Clone)]
|
|
#[deprecated(
|
|
since = "0.15.0",
|
|
note = "Use the `DirectionalLight` component instead. Inserting it will now also insert the other components required by it automatically."
|
|
)]
|
|
pub struct DirectionalLightBundle {
|
|
pub directional_light: DirectionalLight,
|
|
pub frusta: CascadesFrusta,
|
|
pub cascades: Cascades,
|
|
pub cascade_shadow_config: CascadeShadowConfig,
|
|
pub visible_entities: CascadesVisibleEntities,
|
|
pub transform: Transform,
|
|
pub global_transform: GlobalTransform,
|
|
/// Enables or disables the light
|
|
pub visibility: Visibility,
|
|
/// Inherited visibility of an entity.
|
|
pub inherited_visibility: InheritedVisibility,
|
|
/// Algorithmically-computed indication of whether an entity is visible and should be extracted for rendering
|
|
pub view_visibility: ViewVisibility,
|
|
/// Marker component that indicates that its entity needs to be synchronized to the render world
|
|
pub sync: SyncToRenderWorld,
|
|
}
|