2022-07-18 23:27:30 +00:00
|
|
|
use bevy_ecs::prelude::Bundle;
|
|
|
|
|
use bevy_transform::prelude::{GlobalTransform, Transform};
|
|
|
|
|
|
Split `ComputedVisibility` into two components to allow for accurate change detection and speed up visibility propagation (#9497)
# Objective
Fix #8267.
Fixes half of #7840.
The `ComputedVisibility` component contains two flags: hierarchy
visibility, and view visibility (whether its visible to any cameras).
Due to the modular and open-ended way that view visibility is computed,
it triggers change detection every single frame, even when the value
does not change. Since hierarchy visibility is stored in the same
component as view visibility, this means that change detection for
inherited visibility is completely broken.
At the company I work for, this has become a real issue. We are using
change detection to only re-render scenes when necessary. The broken
state of change detection for computed visibility means that we have to
to rely on the non-inherited `Visibility` component for now. This is
workable in the early stages of our project, but since we will
inevitably want to use the hierarchy, we will have to either:
1. Roll our own solution for computed visibility.
2. Fix the issue for everyone.
## Solution
Split the `ComputedVisibility` component into two: `InheritedVisibilty`
and `ViewVisibility`.
This allows change detection to behave properly for
`InheritedVisibility`.
View visiblity is still erratic, although it is less useful to be able
to detect changes
for this flavor of visibility.
Overall, this actually simplifies the API. Since the visibility system
consists of
self-explaining components, it is much easier to document the behavior
and usage.
This approach is more modular and "ECS-like" -- one could
strip out the `ViewVisibility` component entirely if it's not needed,
and rely only on inherited visibility.
---
## Changelog
- `ComputedVisibility` has been removed in favor of:
`InheritedVisibility` and `ViewVisiblity`.
## Migration Guide
The `ComputedVisibilty` component has been split into
`InheritedVisiblity` and
`ViewVisibility`. Replace any usages of
`ComputedVisibility::is_visible_in_hierarchy`
with `InheritedVisibility::get`, and replace
`ComputedVisibility::is_visible_in_view`
with `ViewVisibility::get`.
```rust
// Before:
commands.spawn(VisibilityBundle {
visibility: Visibility::Inherited,
computed_visibility: ComputedVisibility::default(),
});
// After:
commands.spawn(VisibilityBundle {
visibility: Visibility::Inherited,
inherited_visibility: InheritedVisibility::default(),
view_visibility: ViewVisibility::default(),
});
```
```rust
// Before:
fn my_system(q: Query<&ComputedVisibilty>) {
for vis in &q {
if vis.is_visible_in_hierarchy() {
// After:
fn my_system(q: Query<&InheritedVisibility>) {
for inherited_visibility in &q {
if inherited_visibility.get() {
```
```rust
// Before:
fn my_system(q: Query<&ComputedVisibilty>) {
for vis in &q {
if vis.is_visible_in_view() {
// After:
fn my_system(q: Query<&ViewVisibility>) {
for view_visibility in &q {
if view_visibility.get() {
```
```rust
// Before:
fn my_system(mut q: Query<&mut ComputedVisibilty>) {
for vis in &mut q {
vis.set_visible_in_view();
// After:
fn my_system(mut q: Query<&mut ViewVisibility>) {
for view_visibility in &mut q {
view_visibility.set();
```
---------
Co-authored-by: Robert Swain <robert.swain@gmail.com>
2023-09-01 13:00:18 +00:00
|
|
|
use crate::view::{InheritedVisibility, ViewVisibility, Visibility};
|
2022-07-18 23:27:30 +00:00
|
|
|
|
Improve `SpatialBundle` docs (#9673)
# Objective
This PR aims to fix a handful of problems with the `SpatialBundle` docs:
The docs describe the role of the single components of the bundle,
overshadowing the purpose of `SpatialBundle` itself. Also, those items
may be added, removed or changed over time, as it happened with #9497,
requiring a higher maintenance effort, which will often result in
errors, as it happened.
## Solution
Just describe the role of `SpatialBundle` and of the transform and
visibility concepts, without mentioning the specific component types.
Since the bundle has public fields, the reader can easily click them and
read the documentation if they need to know more. I removed the mention
of numbers of components since they were four, now they are five, and
who knows how many they will be in the future. In this process, I
removed the bullet points, which are no longer needed, and were
contextually wrong in the first place, since they were meant to list the
components, but ended up describing use-cases and requirements for
hierarchies.
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-09-02 23:44:12 +00:00
|
|
|
/// A [`Bundle`] that allows the correct positional rendering of an entity.
|
2022-07-18 23:27:30 +00:00
|
|
|
///
|
Improve `SpatialBundle` docs (#9673)
# Objective
This PR aims to fix a handful of problems with the `SpatialBundle` docs:
The docs describe the role of the single components of the bundle,
overshadowing the purpose of `SpatialBundle` itself. Also, those items
may be added, removed or changed over time, as it happened with #9497,
requiring a higher maintenance effort, which will often result in
errors, as it happened.
## Solution
Just describe the role of `SpatialBundle` and of the transform and
visibility concepts, without mentioning the specific component types.
Since the bundle has public fields, the reader can easily click them and
read the documentation if they need to know more. I removed the mention
of numbers of components since they were four, now they are five, and
who knows how many they will be in the future. In this process, I
removed the bullet points, which are no longer needed, and were
contextually wrong in the first place, since they were meant to list the
components, but ended up describing use-cases and requirements for
hierarchies.
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
2023-09-02 23:44:12 +00:00
|
|
|
/// It consists of transform components,
|
|
|
|
|
/// controlling position, rotation and scale of the entity,
|
|
|
|
|
/// but also visibility components,
|
|
|
|
|
/// which determine whether the entity is visible or not.
|
|
|
|
|
///
|
|
|
|
|
/// Parent-child hierarchies of entities must contain
|
|
|
|
|
/// all the [`Component`]s in this `Bundle`
|
|
|
|
|
/// to be rendered correctly.
|
|
|
|
|
///
|
|
|
|
|
/// [`Component`]: bevy_ecs::component::Component
|
2022-07-18 23:27:30 +00:00
|
|
|
#[derive(Bundle, Debug, Default)]
|
|
|
|
|
pub struct SpatialBundle {
|
|
|
|
|
/// The visibility of the entity.
|
|
|
|
|
pub visibility: Visibility,
|
Split `ComputedVisibility` into two components to allow for accurate change detection and speed up visibility propagation (#9497)
# Objective
Fix #8267.
Fixes half of #7840.
The `ComputedVisibility` component contains two flags: hierarchy
visibility, and view visibility (whether its visible to any cameras).
Due to the modular and open-ended way that view visibility is computed,
it triggers change detection every single frame, even when the value
does not change. Since hierarchy visibility is stored in the same
component as view visibility, this means that change detection for
inherited visibility is completely broken.
At the company I work for, this has become a real issue. We are using
change detection to only re-render scenes when necessary. The broken
state of change detection for computed visibility means that we have to
to rely on the non-inherited `Visibility` component for now. This is
workable in the early stages of our project, but since we will
inevitably want to use the hierarchy, we will have to either:
1. Roll our own solution for computed visibility.
2. Fix the issue for everyone.
## Solution
Split the `ComputedVisibility` component into two: `InheritedVisibilty`
and `ViewVisibility`.
This allows change detection to behave properly for
`InheritedVisibility`.
View visiblity is still erratic, although it is less useful to be able
to detect changes
for this flavor of visibility.
Overall, this actually simplifies the API. Since the visibility system
consists of
self-explaining components, it is much easier to document the behavior
and usage.
This approach is more modular and "ECS-like" -- one could
strip out the `ViewVisibility` component entirely if it's not needed,
and rely only on inherited visibility.
---
## Changelog
- `ComputedVisibility` has been removed in favor of:
`InheritedVisibility` and `ViewVisiblity`.
## Migration Guide
The `ComputedVisibilty` component has been split into
`InheritedVisiblity` and
`ViewVisibility`. Replace any usages of
`ComputedVisibility::is_visible_in_hierarchy`
with `InheritedVisibility::get`, and replace
`ComputedVisibility::is_visible_in_view`
with `ViewVisibility::get`.
```rust
// Before:
commands.spawn(VisibilityBundle {
visibility: Visibility::Inherited,
computed_visibility: ComputedVisibility::default(),
});
// After:
commands.spawn(VisibilityBundle {
visibility: Visibility::Inherited,
inherited_visibility: InheritedVisibility::default(),
view_visibility: ViewVisibility::default(),
});
```
```rust
// Before:
fn my_system(q: Query<&ComputedVisibilty>) {
for vis in &q {
if vis.is_visible_in_hierarchy() {
// After:
fn my_system(q: Query<&InheritedVisibility>) {
for inherited_visibility in &q {
if inherited_visibility.get() {
```
```rust
// Before:
fn my_system(q: Query<&ComputedVisibilty>) {
for vis in &q {
if vis.is_visible_in_view() {
// After:
fn my_system(q: Query<&ViewVisibility>) {
for view_visibility in &q {
if view_visibility.get() {
```
```rust
// Before:
fn my_system(mut q: Query<&mut ComputedVisibilty>) {
for vis in &mut q {
vis.set_visible_in_view();
// After:
fn my_system(mut q: Query<&mut ViewVisibility>) {
for view_visibility in &mut q {
view_visibility.set();
```
---------
Co-authored-by: Robert Swain <robert.swain@gmail.com>
2023-09-01 13:00:18 +00:00
|
|
|
/// The inherited visibility of the entity.
|
|
|
|
|
pub inherited_visibility: InheritedVisibility,
|
|
|
|
|
/// The view visibility of the entity.
|
|
|
|
|
pub view_visibility: ViewVisibility,
|
2022-07-18 23:27:30 +00:00
|
|
|
/// The transform of the entity.
|
|
|
|
|
pub transform: Transform,
|
|
|
|
|
/// The global transform of the entity.
|
|
|
|
|
pub global_transform: GlobalTransform,
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
impl SpatialBundle {
|
|
|
|
|
/// Creates a new [`SpatialBundle`] from a [`Transform`].
|
|
|
|
|
///
|
|
|
|
|
/// This initializes [`GlobalTransform`] as identity, and visibility as visible
|
|
|
|
|
#[inline]
|
|
|
|
|
pub const fn from_transform(transform: Transform) -> Self {
|
|
|
|
|
SpatialBundle {
|
|
|
|
|
transform,
|
2022-12-25 00:39:29 +00:00
|
|
|
..Self::INHERITED_IDENTITY
|
2022-07-18 23:27:30 +00:00
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2022-08-30 22:10:24 +00:00
|
|
|
/// A visible [`SpatialBundle`], with no translation, rotation, and a scale of 1 on all axes.
|
2022-12-25 00:39:29 +00:00
|
|
|
pub const INHERITED_IDENTITY: Self = SpatialBundle {
|
|
|
|
|
visibility: Visibility::Inherited,
|
Split `ComputedVisibility` into two components to allow for accurate change detection and speed up visibility propagation (#9497)
# Objective
Fix #8267.
Fixes half of #7840.
The `ComputedVisibility` component contains two flags: hierarchy
visibility, and view visibility (whether its visible to any cameras).
Due to the modular and open-ended way that view visibility is computed,
it triggers change detection every single frame, even when the value
does not change. Since hierarchy visibility is stored in the same
component as view visibility, this means that change detection for
inherited visibility is completely broken.
At the company I work for, this has become a real issue. We are using
change detection to only re-render scenes when necessary. The broken
state of change detection for computed visibility means that we have to
to rely on the non-inherited `Visibility` component for now. This is
workable in the early stages of our project, but since we will
inevitably want to use the hierarchy, we will have to either:
1. Roll our own solution for computed visibility.
2. Fix the issue for everyone.
## Solution
Split the `ComputedVisibility` component into two: `InheritedVisibilty`
and `ViewVisibility`.
This allows change detection to behave properly for
`InheritedVisibility`.
View visiblity is still erratic, although it is less useful to be able
to detect changes
for this flavor of visibility.
Overall, this actually simplifies the API. Since the visibility system
consists of
self-explaining components, it is much easier to document the behavior
and usage.
This approach is more modular and "ECS-like" -- one could
strip out the `ViewVisibility` component entirely if it's not needed,
and rely only on inherited visibility.
---
## Changelog
- `ComputedVisibility` has been removed in favor of:
`InheritedVisibility` and `ViewVisiblity`.
## Migration Guide
The `ComputedVisibilty` component has been split into
`InheritedVisiblity` and
`ViewVisibility`. Replace any usages of
`ComputedVisibility::is_visible_in_hierarchy`
with `InheritedVisibility::get`, and replace
`ComputedVisibility::is_visible_in_view`
with `ViewVisibility::get`.
```rust
// Before:
commands.spawn(VisibilityBundle {
visibility: Visibility::Inherited,
computed_visibility: ComputedVisibility::default(),
});
// After:
commands.spawn(VisibilityBundle {
visibility: Visibility::Inherited,
inherited_visibility: InheritedVisibility::default(),
view_visibility: ViewVisibility::default(),
});
```
```rust
// Before:
fn my_system(q: Query<&ComputedVisibilty>) {
for vis in &q {
if vis.is_visible_in_hierarchy() {
// After:
fn my_system(q: Query<&InheritedVisibility>) {
for inherited_visibility in &q {
if inherited_visibility.get() {
```
```rust
// Before:
fn my_system(q: Query<&ComputedVisibilty>) {
for vis in &q {
if vis.is_visible_in_view() {
// After:
fn my_system(q: Query<&ViewVisibility>) {
for view_visibility in &q {
if view_visibility.get() {
```
```rust
// Before:
fn my_system(mut q: Query<&mut ComputedVisibilty>) {
for vis in &mut q {
vis.set_visible_in_view();
// After:
fn my_system(mut q: Query<&mut ViewVisibility>) {
for view_visibility in &mut q {
view_visibility.set();
```
---------
Co-authored-by: Robert Swain <robert.swain@gmail.com>
2023-09-01 13:00:18 +00:00
|
|
|
inherited_visibility: InheritedVisibility::HIDDEN,
|
|
|
|
|
view_visibility: ViewVisibility::HIDDEN,
|
2022-08-30 22:10:24 +00:00
|
|
|
transform: Transform::IDENTITY,
|
|
|
|
|
global_transform: GlobalTransform::IDENTITY,
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/// An invisible [`SpatialBundle`], with no translation, rotation, and a scale of 1 on all axes.
|
2022-12-25 00:39:29 +00:00
|
|
|
pub const HIDDEN_IDENTITY: Self = SpatialBundle {
|
|
|
|
|
visibility: Visibility::Hidden,
|
|
|
|
|
..Self::INHERITED_IDENTITY
|
2022-08-30 22:10:24 +00:00
|
|
|
};
|
2022-07-18 23:27:30 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
impl From<Transform> for SpatialBundle {
|
|
|
|
|
#[inline]
|
|
|
|
|
fn from(transform: Transform) -> Self {
|
|
|
|
|
Self::from_transform(transform)
|
|
|
|
|
}
|
|
|
|
|
}
|
