2023-09-15 12:45:32 +00:00
use crate ::{ UiRect , Val } ;
2021-12-14 03:58:23 +00:00
use bevy_asset ::Handle ;
use bevy_ecs ::{ prelude ::Component , reflect ::ReflectComponent } ;
2022-09-02 12:35:23 +00:00
use bevy_math ::{ Rect , Vec2 } ;
2022-05-03 19:20:13 +00:00
use bevy_reflect ::prelude ::* ;
Bevy Asset V2 (#8624)
# Bevy Asset V2 Proposal
## Why Does Bevy Need A New Asset System?
Asset pipelines are a central part of the gamedev process. Bevy's
current asset system is missing a number of features that make it
non-viable for many classes of gamedev. After plenty of discussions and
[a long community feedback
period](https://github.com/bevyengine/bevy/discussions/3972), we've
identified a number missing features:
* **Asset Preprocessing**: it should be possible to "preprocess" /
"compile" / "crunch" assets at "development time" rather than when the
game starts up. This enables offloading expensive work from deployed
apps, faster asset loading, less runtime memory usage, etc.
* **Per-Asset Loader Settings**: Individual assets cannot define their
own loaders that override the defaults. Additionally, they cannot
provide per-asset settings to their loaders. This is a huge limitation,
as many asset types don't provide all information necessary for Bevy
_inside_ the asset. For example, a raw PNG image says nothing about how
it should be sampled (ex: linear vs nearest).
* **Asset `.meta` files**: assets should have configuration files stored
adjacent to the asset in question, which allows the user to configure
asset-type-specific settings. These settings should be accessible during
the pre-processing phase. Modifying a `.meta` file should trigger a
re-processing / re-load of the asset. It should be possible to configure
asset loaders from the meta file.
* **Processed Asset Hot Reloading**: Changes to processed assets (or
their dependencies) should result in re-processing them and re-loading
the results in live Bevy Apps.
* **Asset Dependency Tracking**: The current bevy_asset has no good way
to wait for asset dependencies to load. It punts this as an exercise for
consumers of the loader apis, which is unreasonable and error prone.
There should be easy, ergonomic ways to wait for assets to load and
block some logic on an asset's entire dependency tree loading.
* **Runtime Asset Loading**: it should be (optionally) possible to load
arbitrary assets dynamically at runtime. This necessitates being able to
deploy and run the asset server alongside Bevy Apps on _all platforms_.
For example, we should be able to invoke the shader compiler at runtime,
stream scenes from sources like the internet, etc. To keep deployed
binaries (and startup times) small, the runtime asset server
configuration should be configurable with different settings compared to
the "pre processor asset server".
* **Multiple Backends**: It should be possible to load assets from
arbitrary sources (filesystems, the internet, remote asset serves, etc).
* **Asset Packing**: It should be possible to deploy assets in
compressed "packs", which makes it easier and more efficient to
distribute assets with Bevy Apps.
* **Asset Handoff**: It should be possible to hold a "live" asset
handle, which correlates to runtime data, without actually holding the
asset in memory. Ex: it must be possible to hold a reference to a GPU
mesh generated from a "mesh asset" without keeping the mesh data in CPU
memory
* **Per-Platform Processed Assets**: Different platforms and app
distributions have different capabilities and requirements. Some
platforms need lower asset resolutions or different asset formats to
operate within the hardware constraints of the platform. It should be
possible to define per-platform asset processing profiles. And it should
be possible to deploy only the assets required for a given platform.
These features have architectural implications that are significant
enough to require a full rewrite. The current Bevy Asset implementation
got us this far, but it can take us no farther. This PR defines a brand
new asset system that implements most of these features, while laying
the foundations for the remaining features to be built.
## Bevy Asset V2
Here is a quick overview of the features introduced in this PR.
* **Asset Preprocessing**: Preprocess assets at development time into
more efficient (and configurable) representations
* **Dependency Aware**: Dependencies required to process an asset are
tracked. If an asset's processed dependency changes, it will be
reprocessed
* **Hot Reprocessing/Reloading**: detect changes to asset source files,
reprocess them if they have changed, and then hot-reload them in Bevy
Apps.
* **Only Process Changes**: Assets are only re-processed when their
source file (or meta file) has changed. This uses hashing and timestamps
to avoid processing assets that haven't changed.
* **Transactional and Reliable**: Uses write-ahead logging (a technique
commonly used by databases) to recover from crashes / forced-exits.
Whenever possible it avoids full-reprocessing / only uncompleted
transactions will be reprocessed. When the processor is running in
parallel with a Bevy App, processor asset writes block Bevy App asset
reads. Reading metadata + asset bytes is guaranteed to be transactional
/ correctly paired.
* **Portable / Run anywhere / Database-free**: The processor does not
rely on an in-memory database (although it uses some database techniques
for reliability). This is important because pretty much all in-memory
databases have unsupported platforms or build complications.
* **Configure Processor Defaults Per File Type**: You can say "use this
processor for all files of this type".
* **Custom Processors**: The `Processor` trait is flexible and
unopinionated. It can be implemented by downstream plugins.
* **LoadAndSave Processors**: Most asset processing scenarios can be
expressed as "run AssetLoader A, save the results using AssetSaver X,
and then load the result using AssetLoader B". For example, load this
png image using `PngImageLoader`, which produces an `Image` asset and
then save it using `CompressedImageSaver` (which also produces an
`Image` asset, but in a compressed format), which takes an `Image` asset
as input. This means if you have an `AssetLoader` for an asset, you are
already half way there! It also means that you can share AssetSavers
across multiple loaders. Because `CompressedImageSaver` accepts Bevy's
generic Image asset as input, it means you can also use it with some
future `JpegImageLoader`.
* **Loader and Saver Settings**: Asset Loaders and Savers can now define
their own settings types, which are passed in as input when an asset is
loaded / saved. Each asset can define its own settings.
* **Asset `.meta` files**: configure asset loaders, their settings,
enable/disable processing, and configure processor settings
* **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex:
if an asset contains a `Handle<Image>`) are tracked by the asset server.
An event is emitted when an asset and all of its dependencies have been
loaded
* **Unprocessed Asset Loading**: Assets do not require preprocessing.
They can be loaded directly. A processed asset is just a "normal" asset
with some extra metadata. Asset Loaders don't need to know or care about
whether or not an asset was processed.
* **Async Asset IO**: Asset readers/writers use async non-blocking
interfaces. Note that because Rust doesn't yet support async traits,
there is a bit of manual Boxing / Future boilerplate. This will
hopefully be removed in the near future when Rust gets async traits.
* **Pluggable Asset Readers and Writers**: Arbitrary asset source
readers/writers are supported, both by the processor and the asset
server.
* **Better Asset Handles**
* **Single Arc Tree**: Asset Handles now use a single arc tree that
represents the lifetime of the asset. This makes their implementation
simpler, more efficient, and allows us to cheaply attach metadata to
handles. Ex: the AssetPath of a handle is now directly accessible on the
handle itself!
* **Const Typed Handles**: typed handles can be constructed in a const
context. No more weird "const untyped converted to typed at runtime"
patterns!
* **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed
`Handle<T>` is now much smaller in memory and `AssetId<T>` is even
smaller.
* **Weak Handle Usage Reduction**: In general Handles are now considered
to be "strong". Bevy features that previously used "weak `Handle<T>`"
have been ported to `AssetId<T>`, which makes it statically clear that
the features do not hold strong handles (while retaining strong type
information). Currently Handle::Weak still exists, but it is very
possible that we can remove that entirely.
* **Efficient / Dense Asset Ids**: Assets now have efficient dense
runtime asset ids, which means we can avoid expensive hash lookups.
Assets are stored in Vecs instead of HashMaps. There are now typed and
untyped ids, which means we no longer need to store dynamic type
information in the ID for typed handles. "AssetPathId" (which was a
nightmare from a performance and correctness standpoint) has been
entirely removed in favor of dense ids (which are retrieved for a path
on load)
* **Direct Asset Loading, with Dependency Tracking**: Assets that are
defined at runtime can still have their dependencies tracked by the
Asset Server (ex: if you create a material at runtime, you can still
wait for its textures to load). This is accomplished via the (currently
optional) "asset dependency visitor" trait. This system can also be used
to define a set of assets to load, then wait for those assets to load.
* **Async folder loading**: Folder loading also uses this system and
immediately returns a handle to the LoadedFolder asset, which means
folder loading no longer blocks on directory traversals.
* **Improved Loader Interface**: Loaders now have a specific "top level
asset type", which makes returning the top-level asset simpler and
statically typed.
* **Basic Image Settings and Processing**: Image assets can now be
processed into the gpu-friendly Basic Universal format. The ImageLoader
now has a setting to define what format the image should be loaded as.
Note that this is just a minimal MVP ... plenty of additional work to do
here. To demo this, enable the `basis-universal` feature and turn on
asset processing.
* **Simpler Audio Play / AudioSink API**: Asset handle providers are
cloneable, which means the Audio resource can mint its own handles. This
means you can now do `let sink_handle = audio.play(music)` instead of
`let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that
this might still be replaced by
https://github.com/bevyengine/bevy/pull/8424.
**Removed Handle Casting From Engine Features**: Ex: FontAtlases no
longer use casting between handle types
## Using The New Asset System
### Normal Unprocessed Asset Loading
By default the `AssetPlugin` does not use processing. It behaves pretty
much the same way as the old system.
If you are defining a custom asset, first derive `Asset`:
```rust
#[derive(Asset)]
struct Thing {
value: String,
}
```
Initialize the asset:
```rust
app.init_asset:<Thing>()
```
Implement a new `AssetLoader` for it:
```rust
#[derive(Default)]
struct ThingLoader;
#[derive(Serialize, Deserialize, Default)]
pub struct ThingSettings {
some_setting: bool,
}
impl AssetLoader for ThingLoader {
type Asset = Thing;
type Settings = ThingSettings;
fn load<'a>(
&'a self,
reader: &'a mut Reader,
settings: &'a ThingSettings,
load_context: &'a mut LoadContext,
) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> {
Box::pin(async move {
let mut bytes = Vec::new();
reader.read_to_end(&mut bytes).await?;
// convert bytes to value somehow
Ok(Thing {
value
})
})
}
fn extensions(&self) -> &[&str] {
&["thing"]
}
}
```
Note that this interface will get much cleaner once Rust gets support
for async traits. `Reader` is an async futures_io::AsyncRead. You can
stream bytes as they come in or read them all into a `Vec<u8>`,
depending on the context. You can use `let handle =
load_context.load(path)` to kick off a dependency load, retrieve a
handle, and register the dependency for the asset.
Then just register the loader in your Bevy app:
```rust
app.init_asset_loader::<ThingLoader>()
```
Now just add your `Thing` asset files into the `assets` folder and load
them like this:
```rust
fn system(asset_server: Res<AssetServer>) {
let handle = Handle<Thing> = asset_server.load("cool.thing");
}
```
You can check load states directly via the asset server:
```rust
if asset_server.load_state(&handle) == LoadState::Loaded { }
```
You can also listen for events:
```rust
fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) {
for event in events.iter() {
if event.is_loaded_with_dependencies(&handle) {
}
}
}
```
Note the new `AssetEvent::LoadedWithDependencies`, which only fires when
the asset is loaded _and_ all dependencies (and their dependencies) have
loaded.
Unlike the old asset system, for a given asset path all `Handle<T>`
values point to the same underlying Arc. This means Handles can cheaply
hold more asset information, such as the AssetPath:
```rust
// prints the AssetPath of the handle
info!("{:?}", handle.path())
```
### Processed Assets
Asset processing can be enabled via the `AssetPlugin`. When developing
Bevy Apps with processed assets, do this:
```rust
app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))
```
This runs the `AssetProcessor` in the background with hot-reloading. It
reads assets from the `assets` folder, processes them, and writes them
to the `.imported_assets` folder. Asset loads in the Bevy App will wait
for a processed version of the asset to become available. If an asset in
the `assets` folder changes, it will be reprocessed and hot-reloaded in
the Bevy App.
When deploying processed Bevy apps, do this:
```rust
app.add_plugins(DefaultPlugins.set(AssetPlugin::processed()))
```
This does not run the `AssetProcessor` in the background. It behaves
like `AssetPlugin::unprocessed()`, but reads assets from
`.imported_assets`.
When the `AssetProcessor` is running, it will populate sibling `.meta`
files for assets in the `assets` folder. Meta files for assets that do
not have a processor configured look like this:
```rust
(
meta_format_version: "1.0",
asset: Load(
loader: "bevy_render::texture::image_loader::ImageLoader",
settings: (
format: FromExtension,
),
),
)
```
This is metadata for an image asset. For example, if you have
`assets/my_sprite.png`, this could be the metadata stored at
`assets/my_sprite.png.meta`. Meta files are totally optional. If no
metadata exists, the default settings will be used.
In short, this file says "load this asset with the ImageLoader and use
the file extension to determine the image type". This type of meta file
is supported in all AssetPlugin modes. If in `Unprocessed` mode, the
asset (with the meta settings) will be loaded directly. If in
`ProcessedDev` mode, the asset file will be copied directly to the
`.imported_assets` folder. The meta will also be copied directly to the
`.imported_assets` folder, but with one addition:
```rust
(
meta_format_version: "1.0",
processed_info: Some((
hash: 12415480888597742505,
full_hash: 14344495437905856884,
process_dependencies: [],
)),
asset: Load(
loader: "bevy_render::texture::image_loader::ImageLoader",
settings: (
format: FromExtension,
),
),
)
```
`processed_info` contains `hash` (a direct hash of the asset and meta
bytes), `full_hash` (a hash of `hash` and the hashes of all
`process_dependencies`), and `process_dependencies` (the `path` and
`full_hash` of every process_dependency). A "process dependency" is an
asset dependency that is _directly_ used when processing the asset.
Images do not have process dependencies, so this is empty.
When the processor is enabled, you can use the `Process` metadata
config:
```rust
(
meta_format_version: "1.0",
asset: Process(
processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>",
settings: (
loader_settings: (
format: FromExtension,
),
saver_settings: (
generate_mipmaps: true,
),
),
),
)
```
This configures the asset to use the `LoadAndSave` processor, which runs
an AssetLoader and feeds the result into an AssetSaver (which saves the
given Asset and defines a loader to load it with). (for terseness
LoadAndSave will likely get a shorter/friendlier type name when [Stable
Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common
processor type, but arbitrary processors are supported.
`CompressedImageSaver` saves an `Image` in the Basis Universal format
and configures the ImageLoader to load it as basis universal. The
`AssetProcessor` will read this meta, run it through the LoadAndSave
processor, and write the basis-universal version of the image to
`.imported_assets`. The final metadata will look like this:
```rust
(
meta_format_version: "1.0",
processed_info: Some((
hash: 905599590923828066,
full_hash: 9948823010183819117,
process_dependencies: [],
)),
asset: Load(
loader: "bevy_render::texture::image_loader::ImageLoader",
settings: (
format: Format(Basis),
),
),
)
```
To try basis-universal processing out in Bevy examples, (for example
`sprite.rs`), change `add_plugins(DefaultPlugins)` to
`add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run
with the `basis-universal` feature enabled: `cargo run
--features=basis-universal --example sprite`.
To create a custom processor, there are two main paths:
1. Use the `LoadAndSave` processor with an existing `AssetLoader`.
Implement the `AssetSaver` trait, register the processor using
`asset_processor.register_processor::<LoadAndSave<ImageLoader,
CompressedImageSaver>>(image_saver.into())`.
2. Implement the `Process` trait directly and register it using:
`asset_processor.register_processor(thing_processor)`.
You can configure default processors for file extensions like this:
```rust
asset_processor.set_default_processor::<ThingProcessor>("thing")
```
There is one more metadata type to be aware of:
```rust
(
meta_format_version: "1.0",
asset: Ignore,
)
```
This will ignore the asset during processing / prevent it from being
written to `.imported_assets`.
The AssetProcessor stores a transaction log at `.imported_assets/log`
and uses it to gracefully recover from unexpected stops. This means you
can force-quit the processor (and Bevy Apps running the processor in
parallel) at arbitrary times!
`.imported_assets` is "local state". It should _not_ be checked into
source control. It should also be considered "read only". In practice,
you _can_ modify processed assets and processed metadata if you really
need to test something. But those modifications will not be represented
in the hashes of the assets, so the processed state will be "out of
sync" with the source assets. The processor _will not_ fix this for you.
Either revert the change after you have tested it, or delete the
processed files so they can be re-populated.
## Open Questions
There are a number of open questions to be discussed. We should decide
if they need to be addressed in this PR and if so, how we will address
them:
### Implied Dependencies vs Dependency Enumeration
There are currently two ways to populate asset dependencies:
* **Implied via AssetLoaders**: if an AssetLoader loads an asset (and
retrieves a handle), a dependency is added to the list.
* **Explicit via the optional Asset::visit_dependencies**: if
`server.load_asset(my_asset)` is called, it will call
`my_asset.visit_dependencies`, which will grab dependencies that have
been manually defined for the asset via the Asset trait impl (which can
be derived).
This means that defining explicit dependencies is optional for "loaded
assets". And the list of dependencies is always accurate because loaders
can only produce Handles if they register dependencies. If an asset was
loaded with an AssetLoader, it only uses the implied dependencies. If an
asset was created at runtime and added with
`asset_server.load_asset(MyAsset)`, it will use
`Asset::visit_dependencies`.
However this can create a behavior mismatch between loaded assets and
equivalent "created at runtime" assets if `Assets::visit_dependencies`
doesn't exactly match the dependencies produced by the AssetLoader. This
behavior mismatch can be resolved by completely removing "implied loader
dependencies" and requiring `Asset::visit_dependencies` to supply
dependency data. But this creates two problems:
* It makes defining loaded assets harder and more error prone: Devs must
remember to manually annotate asset dependencies with `#[dependency]`
when deriving `Asset`. For more complicated assets (such as scenes), the
derive likely wouldn't be sufficient and a manual `visit_dependencies`
impl would be required.
* Removes the ability to immediately kick off dependency loads: When
AssetLoaders retrieve a Handle, they also immediately kick off an asset
load for the handle, which means it can start loading in parallel
_before_ the asset finishes loading. For large assets, this could be
significant. (although this could be mitigated for processed assets if
we store dependencies in the processed meta file and load them ahead of
time)
### Eager ProcessorDev Asset Loading
I made a controversial call in the interest of fast startup times ("time
to first pixel") for the "processor dev mode configuration". When
initializing the AssetProcessor, current processed versions of unchanged
assets are yielded immediately, even if their dependencies haven't been
checked yet for reprocessing. This means that
non-current-state-of-filesystem-but-previously-valid assets might be
returned to the App first, then hot-reloaded if/when their dependencies
change and the asset is reprocessed.
Is this behavior desirable? There is largely one alternative: do not
yield an asset from the processor to the app until all of its
dependencies have been checked for changes. In some common cases (load
dependency has not changed since last run) this will increase startup
time. The main question is "by how much" and is that slower startup time
worth it in the interest of only yielding assets that are true to the
current state of the filesystem. Should this be configurable? I'm
starting to think we should only yield an asset after its (historical)
dependencies have been checked for changes + processed as necessary, but
I'm curious what you all think.
### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs?
In this implementation AssetPaths are the only canonical asset
identifier (just like the previous Bevy Asset system and Godot). Moving
assets will result in re-scans (and currently reprocessing, although
reprocessing can easily be avoided with some changes). Asset
renames/moves will break code and assets that rely on specific paths,
unless those paths are fixed up.
Do we want / need "stable asset uuids"? Introducing them is very
possible:
1. Generate a UUID and include it in .meta files
2. Support UUID in AssetPath
3. Generate "asset indices" which are loaded on startup and map UUIDs to
paths.
4 (maybe). Consider only supporting UUIDs for processed assets so we can
generate quick-to-load indices instead of scanning meta files.
The main "pro" is that assets referencing UUIDs don't need to be
migrated when a path changes. The main "con" is that UUIDs cannot be
"lazily resolved" like paths. They need a full view of all assets to
answer the question "does this UUID exist". Which means UUIDs require
the AssetProcessor to fully finish startup scans before saying an asset
doesnt exist. And they essentially require asset pre-processing to use
in apps, because scanning all asset metadata files at runtime to resolve
a UUID is not viable for medium-to-large apps. It really requires a
pre-generated UUID index, which must be loaded before querying for
assets.
I personally think this should be investigated in a separate PR. Paths
aren't going anywhere ... _everyone_ uses filesystems (and
filesystem-like apis) to manage their asset source files. I consider
them permanent canonical asset information. Additionally, they behave
well for both processed and unprocessed asset modes. Given that Bevy is
supporting both, this feels like the right canonical ID to start with.
UUIDS (and maybe even other indexed-identifier types) can be added later
as necessary.
### Folder / File Naming Conventions
All asset processing config currently lives in the `.imported_assets`
folder. The processor transaction log is in `.imported_assets/log`.
Processed assets are added to `.imported_assets/Default`, which will
make migrating to processed asset profiles (ex: a
`.imported_assets/Mobile` profile) a non-breaking change. It also allows
us to create top-level files like `.imported_assets/log` without it
being interpreted as an asset. Meta files currently have a `.meta`
suffix. Do we like these names and conventions?
### Should the `AssetPlugin::processed_dev` configuration enable
`watch_for_changes` automatically?
Currently it does (which I think makes sense), but it does make it the
only configuration that enables watch_for_changes by default.
### Discuss on_loaded High Level Interface:
This PR includes a very rough "proof of concept" `on_loaded` system
adapter that uses the `LoadedWithDependencies` event in combination with
`asset_server.load_asset` dependency tracking to support this pattern
```rust
fn main() {
App::new()
.init_asset::<MyAssets>()
.add_systems(Update, on_loaded(create_array_texture))
.run();
}
#[derive(Asset, Clone)]
struct MyAssets {
#[dependency]
picture_of_my_cat: Handle<Image>,
#[dependency]
picture_of_my_other_cat: Handle<Image>,
}
impl FromWorld for ArrayTexture {
fn from_world(world: &mut World) -> Self {
picture_of_my_cat: server.load("meow.png"),
picture_of_my_other_cat: server.load("meeeeeeeow.png"),
}
}
fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) {
commands.spawn(SpriteBundle {
texture: my_assets.picture_of_my_cat.clone(),
..default()
});
commands.spawn(SpriteBundle {
texture: my_assets.picture_of_my_other_cat.clone(),
..default()
});
}
```
The implementation is _very_ rough. And it is currently unsafe because
`bevy_ecs` doesn't expose some internals to do this safely from inside
`bevy_asset`. There are plenty of unanswered questions like:
* "do we add a Loadable" derive? (effectively automate the FromWorld
implementation above)
* Should `MyAssets` even be an Asset? (largely implemented this way
because it elegantly builds on `server.load_asset(MyAsset { .. })`
dependency tracking).
We should think hard about what our ideal API looks like (and if this is
a pattern we want to support). Not necessarily something we need to
solve in this PR. The current `on_loaded` impl should probably be
removed from this PR before merging.
## Clarifying Questions
### What about Assets as Entities?
This Bevy Asset V2 proposal implementation initially stored Assets as
ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used
`Entity` as the asset id and Asset values were just ECS components.
There are plenty of compelling reasons to do this:
1. Easier to inline assets in Bevy Scenes (as they are "just" normal
entities + components)
2. More flexible queries: use the power of the ECS to filter assets (ex:
`Query<Mesh, With<Tree>>`).
3. Extensible. Users can add arbitrary component data to assets.
4. Things like "component visualization tools" work out of the box to
visualize asset data.
However Assets as Entities has a ton of caveats right now:
* We need to be able to allocate entity ids without a direct World
reference (aka rework id allocator in Entities ... i worked around this
in my prototypes by just pre allocating big chunks of entities)
* We want asset change events in addition to ECS change tracking ... how
do we populate them when mutations can come from anywhere? Do we use
Changed queries? This would require iterating over the change data for
all assets every frame. Is this acceptable or should we implement a new
"event based" component change detection option?
* Reconciling manually created assets with asset-system managed assets
has some nuance (ex: are they "loaded" / do they also have that
component metadata?)
* "how do we handle "static" / default entity handles" (ties in to the
Entity Indices discussion:
https://github.com/bevyengine/bevy/discussions/8319). This is necessary
for things like "built in" assets and default handles in things like
SpriteBundle.
* Storing asset information as a component makes it easy to "invalidate"
asset state by removing the component (or forcing modifications).
Ideally we have ways to lock this down (some combination of Rust type
privacy and ECS validation)
In practice, how we store and identify assets is a reasonably
superficial change (porting off of Assets as Entities and implementing
dedicated storage + ids took less than a day). So once we sort out the
remaining challenges the flip should be straightforward. Additionally, I
do still have "Assets as Entities" in my commit history, so we can reuse
that work. I personally think "assets as entities" is a good endgame,
but it also doesn't provide _significant_ value at the moment and it
certainly isn't ready yet with the current state of things.
### Why not Distill?
[Distill](https://github.com/amethyst/distill) is a high quality fully
featured asset system built in Rust. It is very natural to ask "why not
just use Distill?".
It is also worth calling out that for awhile, [we planned on adopting
Distill / I signed off on
it](https://github.com/bevyengine/bevy/issues/708).
However I think Bevy has a number of constraints that make Distill
adoption suboptimal:
* **Architectural Simplicity:**
* Distill's processor requires an in-memory database (lmdb) and RPC
networked API (using Cap'n Proto). Each of these introduces API
complexity that increases maintenance burden and "code grokability".
Ignoring tests, documentation, and examples, Distill has 24,237 lines of
Rust code (including generated code for RPC + database interactions). If
you ignore generated code, it has 11,499 lines.
* Bevy builds the AssetProcessor and AssetServer using pluggable
AssetReader/AssetWriter Rust traits with simple io interfaces. They do
not necessitate databases or RPC interfaces (although Readers/Writers
could use them if that is desired). Bevy Asset V2 (at the time of
writing this PR) is 5,384 lines of Rust code (ignoring tests,
documentation, and examples). Grain of salt: Distill does have more
features currently (ex: Asset Packing, GUIDS, remote-out-of-process
asset processor). I do plan to implement these features in Bevy Asset V2
and I personally highly doubt they will meaningfully close the 6115
lines-of-code gap.
* This complexity gap (which while illustrated by lines of code, is much
bigger than just that) is noteworthy to me. Bevy should be hackable and
there are pillars of Distill that are very hard to understand and
extend. This is a matter of opinion (and Bevy Asset V2 also has
complicated areas), but I think Bevy Asset V2 is much more approachable
for the average developer.
* Necessary disclaimer: counting lines of code is an extremely rough
complexity metric. Read the code and form your own opinions.
* **Optional Asset Processing:** Not all Bevy Apps (or Bevy App
developers) need / want asset preprocessing. Processing increases the
complexity of the development environment by introducing things like
meta files, imported asset storage, running processors in the
background, waiting for processing to finish, etc. Distill _requires_
preprocessing to work. With Bevy Asset V2 processing is fully opt-in.
The AssetServer isn't directly aware of asset processors at all.
AssetLoaders only care about converting bytes to runtime Assets ... they
don't know or care if the bytes were pre-processed or not. Processing is
"elegantly" (forgive my self-congratulatory phrasing) layered on top and
builds on the existing Asset system primitives.
* **Direct Filesystem Access to Processed Asset State:** Distill stores
processed assets in a database. This makes debugging / inspecting the
processed outputs harder (either requires special tooling to query the
database or they need to be "deployed" to be inspected). Bevy Asset V2,
on the other hand, stores processed assets in the filesystem (by default
... this is configurable). This makes interacting with the processed
state more natural. Note that both Godot and Unity's new asset system
store processed assets in the filesystem.
* **Portability**: Because Distill's processor uses lmdb and RPC
networking, it cannot be run on certain platforms (ex: lmdb is a
non-rust dependency that cannot run on the web, some platforms don't
support running network servers). Bevy should be able to process assets
everywhere (ex: run the Bevy Editor on the web, compile + process
shaders on mobile, etc). Distill does partially mitigate this problem by
supporting "streaming" assets via the RPC protocol, but this is not a
full solve from my perspective. And Bevy Asset V2 can (in theory) also
stream assets (without requiring RPC, although this isn't implemented
yet)
Note that I _do_ still think Distill would be a solid asset system for
Bevy. But I think the approach in this PR is a better solve for Bevy's
specific "asset system requirements".
### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the
point?
"True async file io" has limited / spotty platform support. async-fs
(and the rust async ecosystem generally ... ex Tokio) currently use
async wrappers over std::fs that offload blocking requests to separate
threads. This may feel unsatisfying, but it _does_ still provide value
because it prevents our task pools from blocking on file system
operations (which would prevent progress when there are many tasks to
do, but all threads in a pool are currently blocking on file system
ops).
Additionally, using async APIs for our AssetReaders and AssetWriters
also provides value because we can later add support for "true async
file io" for platforms that support it. _And_ we can implement other
"true async io" asset backends (such as networked asset io).
## Draft TODO
- [x] Fill in missing filesystem event APIs: file removed event (which
is expressed as dangling RenameFrom events in some cases), file/folder
renamed event
- [x] Assets without loaders are not moved to the processed folder. This
breaks things like referenced `.bin` files for GLTFs. This should be
configurable per-non-asset-type.
- [x] Initial implementation of Reflect and FromReflect for Handle. The
"deserialization" parity bar is low here as this only worked with static
UUIDs in the old impl ... this is a non-trivial problem. Either we add a
Handle::AssetPath variant that gets "upgraded" to a strong handle on
scene load or we use a separate AssetRef type for Bevy scenes (which is
converted to a runtime Handle on load). This deserves its own discussion
in a different pr.
- [x] Populate read_asset_bytes hash when run by the processor (a bit of
a special case .. when run by the processor the processed meta will
contain the hash so we don't need to compute it on the spot, but we
don't want/need to read the meta when run by the main AssetServer)
- [x] Delay hot reloading: currently filesystem events are handled
immediately, which creates timing issues in some cases. For example hot
reloading images can sometimes break because the image isn't finished
writing. We should add a delay, likely similar to the [implementation in
this PR](https://github.com/bevyengine/bevy/pull/8503).
- [x] Port old platform-specific AssetIo implementations to the new
AssetReader interface (currently missing Android and web)
- [x] Resolve on_loaded unsafety (either by removing the API entirely or
removing the unsafe)
- [x] Runtime loader setting overrides
- [x] Remove remaining unwraps that should be error-handled. There are
number of TODOs here
- [x] Pretty AssetPath Display impl
- [x] Document more APIs
- [x] Resolve spurious "reloading because it has changed" events (to
repro run load_gltf with `processed_dev()`)
- [x] load_dependency hot reloading currently only works for processed
assets. If processing is disabled, load_dependency changes are not hot
reloaded.
- [x] Replace AssetInfo dependency load/fail counters with
`loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from
(potentially) breaking counters. Storing this will also enable
"dependency reloaded" events (see [Next Steps](#next-steps))
- [x] Re-add filesystem watcher cargo feature gate (currently it is not
optional)
- [ ] Migration Guide
- [ ] Changelog
## Followup TODO
- [ ] Replace "eager unchanged processed asset loading" behavior with
"don't returned unchanged processed asset until dependencies have been
checked".
- [ ] Add true `Ignore` AssetAction that does not copy the asset to the
imported_assets folder.
- [ ] Finish "live asset unloading" (ex: free up CPU asset memory after
uploading an image to the GPU), rethink RenderAssets, and port renderer
features. The `Assets` collection uses `Option<T>` for asset storage to
support its removal. (1) the Option might not actually be necessary ...
might be able to just remove from the collection entirely (2) need to
finalize removal apis
- [ ] Try replacing the "channel based" asset id recycling with
something a bit more efficient (ex: we might be able to use raw atomic
ints with some cleverness)
- [ ] Consider adding UUIDs to processed assets (scoped just to helping
identify moved assets ... not exposed to load queries ... see [Next
Steps](#next-steps))
- [ ] Store "last modified" source asset and meta timestamps in
processed meta files to enable skipping expensive hashing when the file
wasn't changed
- [ ] Fix "slow loop" handle drop fix
- [ ] Migrate to TypeName
- [x] Handle "loader preregistration". See #9429
## Next Steps
* **Configurable per-type defaults for AssetMeta**: It should be
possible to add configuration like "all png image meta should default to
using nearest sampling" (currently this hard-coded per-loader/processor
Settings::default() impls). Also see the "Folder Meta" bullet point.
* **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical
asset ids" discussion in [Open Questions](#open-questions) and the
relevant bullet point in [Draft TODO](#draft-todo). Even without
canonical ids, folder renames could avoid reprocessing in some cases.
* **Multiple Asset Sources**: Expand AssetPath to support "asset source
names" and support multiple AssetReaders in the asset server (ex:
`webserver://some_path/image.png` backed by an Http webserver
AssetReader). The "default" asset reader would use normal
`some_path/image.png` paths. Ideally this works in combination with
multiple AssetWatchers for hot-reloading
* **Stable Type Names**: this pr removes the TypeUuid requirement from
assets in favor of `std::any::type_name`. This makes defining assets
easier (no need to generate a new uuid / use weird proc macro syntax).
It also makes reading meta files easier (because things have "friendly
names"). We also use type names for components in scene files. If they
are good enough for components, they are good enough for assets. And
consistency across Bevy pillars is desirable. However,
`std::any::type_name` is not guaranteed to be stable (although in
practice it is). We've developed a [stable type
path](https://github.com/bevyengine/bevy/pull/7184) to resolve this,
which should be adopted when it is ready.
* **Command Line Interface**: It should be possible to run the asset
processor in a separate process from the command line. This will also
require building a network-server-backed AssetReader to communicate
between the app and the processor. We've been planning to build a "bevy
cli" for awhile. This seems like a good excuse to build it.
* **Asset Packing**: This is largely an additive feature, so it made
sense to me to punt this until we've laid the foundations in this PR.
* **Per-Platform Processed Assets**: It should be possible to generate
assets for multiple platforms by supporting multiple "processor
profiles" per asset (ex: compress with format X on PC and Y on iOS). I
think there should probably be arbitrary "profiles" (which can be
separate from actual platforms), which are then assigned to a given
platform when generating the final asset distribution for that platform.
Ex: maybe devs want a "Mobile" profile that is shared between iOS and
Android. Or a "LowEnd" profile shared between web and mobile.
* **Versioning and Migrations**: Assets, Loaders, Savers, and Processors
need to have versions to determine if their schema is valid. If an asset
/ loader version is incompatible with the current version expected at
runtime, the processor should be able to migrate them. I think we should
try using Bevy Reflect for this, as it would allow us to load the old
version as a dynamic Reflect type without actually having the old Rust
type. It would also allow us to define "patches" to migrate between
versions (Bevy Reflect devs are currently working on patching). The
`.meta` file already has its own format version. Migrating that to new
versions should also be possible.
* **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write
type) currently used by AssetPath can still result in String clones that
aren't actually necessary (cloning an Owned Cow clones the contents).
Bevy's asset system requires cloning AssetPaths in a number of places,
which result in actual clones of the internal Strings. This is not
efficient. AssetPath internals should be reworked to exhibit truer
cow-like-behavior that reduces String clones to the absolute minimum.
* **Consider processor-less processing**: In theory the AssetServer
could run processors "inline" even if the background AssetProcessor is
disabled. If we decide this is actually desirable, we could add this.
But I don't think its a priority in the short or medium term.
* **Pre-emptive dependency loading**: We could encode dependencies in
processed meta files, which could then be used by the Asset Server to
kick of dependency loads as early as possible (prior to starting the
actual asset load). Is this desirable? How much time would this save in
practice?
* **Optimize Processor With UntypedAssetIds**: The processor exclusively
uses AssetPath to identify assets currently. It might be possible to
swap these out for UntypedAssetIds in some places, which are smaller /
cheaper to hash and compare.
* **One to Many Asset Processing**: An asset source file that produces
many assets currently must be processed into a single "processed" asset
source. If labeled assets can be written separately they can each have
their own configured savers _and_ they could be loaded more granularly.
Definitely worth exploring!
* **Automatically Track "Runtime-only" Asset Dependencies**: Right now,
tracking "created at runtime" asset dependencies requires adding them
via `asset_server.load_asset(StandardMaterial::default())`. I think with
some cleverness we could also do this for
`materials.add(StandardMaterial::default())`, making tracking work
"everywhere". There are challenges here relating to change detection /
ensuring the server is made aware of dependency changes. This could be
expensive in some cases.
* **"Dependency Changed" events**: Some assets have runtime artifacts
that need to be re-generated when one of their dependencies change (ex:
regenerate a material's bind group when a Texture needs to change). We
are generating the dependency graph so we can definitely produce these
events. Buuuuut generating these events will have a cost / they could be
high frequency for some assets, so we might want this to be opt-in for
specific cases.
* **Investigate Storing More Information In Handles**: Handles can now
store arbitrary information, which makes it cheaper and easier to
access. How much should we move into them? Canonical asset load states
(via atomics)? (`handle.is_loaded()` would be very cool). Should we
store the entire asset and remove the `Assets<T>` collection?
(`Arc<RwLock<Option<Image>>>`?)
* **Support processing and loading files without extensions**: This is a
pretty arbitrary restriction and could be supported with very minimal
changes.
* **Folder Meta**: It would be nice if we could define per folder
processor configuration defaults (likely in a `.meta` or `.folder_meta`
file). Things like "default to linear filtering for all Images in this
folder".
* **Replace async_broadcast with event-listener?** This might be
approximately drop-in for some uses and it feels more light weight
* **Support Running the AssetProcessor on the Web**: Most of the hard
work is done here, but there are some easy straggling TODOs (make the
transaction log an interface instead of a direct file writer so we can
write a web storage backend, implement an AssetReader/AssetWriter that
reads/writes to something like LocalStorage).
* **Consider identifying and preventing circular dependencies**: This is
especially important for "processor dependencies", as processing will
silently never finish in these cases.
* **Built-in/Inlined Asset Hot Reloading**: This PR regresses
"built-in/inlined" asset hot reloading (previously provided by the
DebugAssetServer). I'm intentionally punting this because I think it can
be cleanly implemented with "multiple asset sources" by registering a
"debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset
paths) in combination with an AssetWatcher for that asset source and
support for "manually loading pats with asset bytes instead of
AssetReaders". The old DebugAssetServer was quite nasty and I'd love to
avoid that hackery going forward.
* **Investigate ways to remove double-parsing meta files**: Parsing meta
files currently involves parsing once with "minimal" versions of the
meta file to extract the type name of the loader/processor config, then
parsing again to parse the "full" meta. This is suboptimal. We should be
able to define custom deserializers that (1) assume the loader/processor
type name comes first (2) dynamically looks up the loader/processor
registrations to deserialize settings in-line (similar to components in
the bevy scene format). Another alternative: deserialize as dynamic
Reflect objects and then convert.
* **More runtime loading configuration**: Support using the Handle type
as a hint to select an asset loader (instead of relying on AssetPath
extensions)
* **More high level Processor trait implementations**: For example, it
might be worth adding support for arbitrary chains of "asset transforms"
that modify an in-memory asset representation between loading and
saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by
a `flip_normals` transform, then save the mesh to an efficient
compressed format).
* **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO
item](#draft-todo) for context)
* **Explore High Level Load Interfaces**: See [this
discussion](#discuss-on_loaded-high-level-interface) for one prototype.
* **Asset Streaming**: It would be great if we could stream Assets (ex:
stream a long video file piece by piece)
* **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than
they need to be because they have a Uuid enum variant. If we implement
an "id exchanging" system that trades Uuids for "efficient runtime ids",
we can cut down on the size of AssetIds, making them more efficient.
This has some open design questions, such as how to spawn entities with
"default" handle values (as these wouldn't have access to the exchange
api in the current system).
* **Asset Path Fixup Tooling**: Assets that inline asset paths inside
them will break when an asset moves. The asset system provides the
functionality to detect when paths break. We should build a framework
that enables formats to define "path migrations". This is especially
important for scene files. For editor-generated files, we should also
consider using UUIDs (see other bullet point) to avoid the need to
migrate in these cases.
---------
Co-authored-by: BeastLe9enD <beastle9end@outlook.de>
Co-authored-by: Mike <mike.hsu@gmail.com>
Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
use bevy_render ::{ color ::Color , texture ::Image } ;
2023-03-09 14:12:54 +00:00
use bevy_transform ::prelude ::GlobalTransform ;
2023-12-24 15:35:09 +00:00
use bevy_utils ::smallvec ::SmallVec ;
2023-09-15 12:45:32 +00:00
use std ::num ::{ NonZeroI16 , NonZeroU16 } ;
2022-10-24 14:33:46 +00:00
use thiserror ::Error ;
2020-01-13 00:51:21 +00:00
2022-01-07 22:20:34 +00:00
/// Describes the size of a UI node
bevy_reflect: `FromReflect` Ergonomics Implementation (#6056)
# Objective
**This implementation is based on
https://github.com/bevyengine/rfcs/pull/59.**
---
Resolves #4597
Full details and motivation can be found in the RFC, but here's a brief
summary.
`FromReflect` is a very powerful and important trait within the
reflection API. It allows Dynamic types (e.g., `DynamicList`, etc.) to
be formed into Real ones (e.g., `Vec<i32>`, etc.).
This mainly comes into play concerning deserialization, where the
reflection deserializers both return a `Box<dyn Reflect>` that almost
always contain one of these Dynamic representations of a Real type. To
convert this to our Real type, we need to use `FromReflect`.
It also sneaks up in other ways. For example, it's a required bound for
`T` in `Vec<T>` so that `Vec<T>` as a whole can be made `FromReflect`.
It's also required by all fields of an enum as it's used as part of the
`Reflect::apply` implementation.
So in other words, much like `GetTypeRegistration` and `Typed`, it is
very much a core reflection trait.
The problem is that it is not currently treated like a core trait and is
not automatically derived alongside `Reflect`. This makes using it a bit
cumbersome and easy to forget.
## Solution
Automatically derive `FromReflect` when deriving `Reflect`.
Users can then choose to opt-out if needed using the
`#[reflect(from_reflect = false)]` attribute.
```rust
#[derive(Reflect)]
struct Foo;
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Bar;
fn test<T: FromReflect>(value: T) {}
test(Foo); // <-- OK
test(Bar); // <-- Panic! Bar does not implement trait `FromReflect`
```
#### `ReflectFromReflect`
This PR also automatically adds the `ReflectFromReflect` (introduced in
#6245) registration to the derived `GetTypeRegistration` impl— if the
type hasn't opted out of `FromReflect` of course.
<details>
<summary><h4>Improved Deserialization</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
And since we can do all the above, we might as well improve
deserialization. We can now choose to deserialize into a Dynamic type or
automatically convert it using `FromReflect` under the hood.
`[Un]TypedReflectDeserializer::new` will now perform the conversion and
return the `Box`'d Real type.
`[Un]TypedReflectDeserializer::new_dynamic` will work like what we have
now and simply return the `Box`'d Dynamic type.
```rust
// Returns the Real type
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: SomeStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
// Returns the Dynamic type
let reflect_deserializer = UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: DynamicStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
```
</details>
---
## Changelog
* `FromReflect` is now automatically derived within the `Reflect` derive
macro
* This includes auto-registering `ReflectFromReflect` in the derived
`GetTypeRegistration` impl
* ~~Renamed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic`, respectively~~ **Descoped**
* ~~Changed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to automatically convert the
deserialized output using `FromReflect`~~ **Descoped**
## Migration Guide
* `FromReflect` is now automatically derived within the `Reflect` derive
macro. Items with both derives will need to remove the `FromReflect`
one.
```rust
// OLD
#[derive(Reflect, FromReflect)]
struct Foo;
// NEW
#[derive(Reflect)]
struct Foo;
```
If using a manual implementation of `FromReflect` and the `Reflect`
derive, users will need to opt-out of the automatic implementation.
```rust
// OLD
#[derive(Reflect)]
struct Foo;
impl FromReflect for Foo {/* ... */}
// NEW
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Foo;
impl FromReflect for Foo {/* ... */}
```
<details>
<summary><h4>Removed Migrations</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
* The reflect deserializers now perform a `FromReflect` conversion
internally. The expected output of `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` is no longer a Dynamic (e.g.,
`DynamicList`), but its Real counterpart (e.g., `Vec<i32>`).
```rust
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
// OLD
let output: DynamicStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
// NEW
let output: SomeStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
```
Alternatively, if this behavior isn't desired, use the
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic` methods instead:
```rust
// OLD
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
// NEW
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
```
</details>
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-06-29 01:31:34 +00:00
#[ derive(Component, Debug, Copy, Clone, Reflect) ]
#[ reflect(Component, Default) ]
2020-01-13 00:51:21 +00:00
pub struct Node {
2023-10-31 23:32:51 +00:00
/// The order of the node in the UI layout.
/// Nodes with a higher stack index are drawn on top of and recieve interactions before nodes with lower stack indices.
pub ( crate ) stack_index : u32 ,
/// The size of the node as width and height in logical pixels
2023-10-21 17:38:15 +00:00
///
2023-10-31 23:32:51 +00:00
/// automatically calculated by [`super::layout::ui_layout_system`]
2022-10-17 13:27:24 +00:00
pub ( crate ) calculated_size : Vec2 ,
2023-10-21 17:38:15 +00:00
/// The width of this node's outline.
/// If this value is `Auto`, negative or `0.` then no outline will be rendered.
///
/// Automatically calculated by [`super::layout::resolve_outlines_system`].
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
pub ( crate ) outline_width : f32 ,
2023-10-21 17:38:15 +00:00
/// The amount of space between the outline and the edge of the node.
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
pub ( crate ) outline_offset : f32 ,
2023-10-21 17:38:15 +00:00
/// The unrounded size of the node as width and height in logical pixels.
///
/// Automatically calculated by [`super::layout::ui_layout_system`].
2023-09-28 22:42:13 +00:00
pub ( crate ) unrounded_size : Vec2 ,
2022-10-17 13:27:24 +00:00
}
impl Node {
2023-10-21 17:38:15 +00:00
/// The calculated node size as width and height in logical pixels.
///
/// Automatically calculated by [`super::layout::ui_layout_system`].
2023-05-11 18:38:01 +00:00
pub const fn size ( & self ) -> Vec2 {
2022-10-17 13:27:24 +00:00
self . calculated_size
}
2023-03-09 14:12:54 +00:00
2023-10-31 23:32:51 +00:00
/// The order of the node in the UI layout.
/// Nodes with a higher stack index are drawn on top of and recieve interactions before nodes with lower stack indices.
pub const fn stack_index ( & self ) -> u32 {
self . stack_index
}
2023-10-21 17:38:15 +00:00
/// The calculated node size as width and height in logical pixels before rounding.
///
/// Automatically calculated by [`super::layout::ui_layout_system`].
2023-09-28 22:42:13 +00:00
pub const fn unrounded_size ( & self ) -> Vec2 {
self . unrounded_size
}
Divide by `UiScale` when converting UI coordinates from physical to logical (#8720)
# Objective
After the UI layout is computed when the coordinates are converted back
from physical coordinates to logical coordinates the `UiScale` is
ignored. This results in a confusing situation where we have two
different systems of logical coordinates.
Example:
```rust
use bevy::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.add_systems(Update, update)
.run();
}
fn setup(mut commands: Commands, mut ui_scale: ResMut<UiScale>) {
ui_scale.scale = 4.;
commands.spawn(Camera2dBundle::default());
commands.spawn(NodeBundle {
style: Style {
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
width: Val::Percent(100.),
..Default::default()
},
..Default::default()
})
.with_children(|builder| {
builder.spawn(NodeBundle {
style: Style {
width: Val::Px(100.),
height: Val::Px(100.),
..Default::default()
},
background_color: Color::MAROON.into(),
..Default::default()
}).with_children(|builder| {
builder.spawn(TextBundle::from_section("", TextStyle::default());
});
});
}
fn update(
mut text_query: Query<(&mut Text, &Parent)>,
node_query: Query<Ref<Node>>,
) {
for (mut text, parent) in text_query.iter_mut() {
let node = node_query.get(parent.get()).unwrap();
if node.is_changed() {
text.sections[0].value = format!("size: {}", node.size());
}
}
}
```
result:
We asked for a 100x100 UI node but the Node's size is multiplied by the
value of `UiScale` to give a logical size of 400x400.
## Solution
Divide the output physical coordinates by `UiScale` in
`ui_layout_system` and multiply the logical viewport size by `UiScale`
when creating the projection matrix for the UI's `ExtractedView` in
`extract_default_ui_camera_view`.
---
## Changelog
* The UI layout's physical coordinates are divided by both the window
scale factor and `UiScale` when converting them back to logical
coordinates. The logical size of Ui nodes now matches the values given
to their size constraints.
* Multiply the logical viewport size by `UiScale` before creating the
projection matrix for the UI's `ExtractedView` in
`extract_default_ui_camera_view`.
* In `ui_focus_system` the cursor position returned from `Window` is
divided by `UiScale`.
* Added a scale factor parameter to `Node::physical_size` and
`Node::physical_rect`.
* The example `viewport_debug` now uses a `UiScale` of 2. to ensure that
viewport coordinates are working correctly with a non-unit `UiScale`.
## Migration Guide
Physical UI coordinates are now divided by both the `UiScale` and the
window's scale factor to compute the logical sizes and positions of UI
nodes.
This ensures that UI Node size and position values, held by the `Node`
and `GlobalTransform` components, conform to the same logical coordinate
system as the style constraints from which they are derived,
irrespective of the current `scale_factor` and `UiScale`.
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-07-06 20:27:54 +00:00
/// Returns the size of the node in physical pixels based on the given scale factor and `UiScale`.
2023-05-11 18:38:01 +00:00
#[ inline ]
2023-12-14 14:56:40 +00:00
pub fn physical_size ( & self , scale_factor : f32 , ui_scale : f32 ) -> Vec2 {
2023-05-11 18:38:01 +00:00
Vec2 ::new (
2023-12-14 14:56:40 +00:00
self . calculated_size . x * scale_factor * ui_scale ,
self . calculated_size . y * scale_factor * ui_scale ,
2023-05-11 18:38:01 +00:00
)
}
2023-04-23 17:28:36 +00:00
/// Returns the logical pixel coordinates of the UI node, based on its [`GlobalTransform`].
2023-03-09 14:12:54 +00:00
#[ inline ]
pub fn logical_rect ( & self , transform : & GlobalTransform ) -> Rect {
Rect ::from_center_size ( transform . translation ( ) . truncate ( ) , self . size ( ) )
}
2023-04-23 17:28:36 +00:00
/// Returns the physical pixel coordinates of the UI node, based on its [`GlobalTransform`] and the scale factor.
2023-03-09 14:12:54 +00:00
#[ inline ]
Divide by `UiScale` when converting UI coordinates from physical to logical (#8720)
# Objective
After the UI layout is computed when the coordinates are converted back
from physical coordinates to logical coordinates the `UiScale` is
ignored. This results in a confusing situation where we have two
different systems of logical coordinates.
Example:
```rust
use bevy::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.add_systems(Update, update)
.run();
}
fn setup(mut commands: Commands, mut ui_scale: ResMut<UiScale>) {
ui_scale.scale = 4.;
commands.spawn(Camera2dBundle::default());
commands.spawn(NodeBundle {
style: Style {
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
width: Val::Percent(100.),
..Default::default()
},
..Default::default()
})
.with_children(|builder| {
builder.spawn(NodeBundle {
style: Style {
width: Val::Px(100.),
height: Val::Px(100.),
..Default::default()
},
background_color: Color::MAROON.into(),
..Default::default()
}).with_children(|builder| {
builder.spawn(TextBundle::from_section("", TextStyle::default());
});
});
}
fn update(
mut text_query: Query<(&mut Text, &Parent)>,
node_query: Query<Ref<Node>>,
) {
for (mut text, parent) in text_query.iter_mut() {
let node = node_query.get(parent.get()).unwrap();
if node.is_changed() {
text.sections[0].value = format!("size: {}", node.size());
}
}
}
```
result:
We asked for a 100x100 UI node but the Node's size is multiplied by the
value of `UiScale` to give a logical size of 400x400.
## Solution
Divide the output physical coordinates by `UiScale` in
`ui_layout_system` and multiply the logical viewport size by `UiScale`
when creating the projection matrix for the UI's `ExtractedView` in
`extract_default_ui_camera_view`.
---
## Changelog
* The UI layout's physical coordinates are divided by both the window
scale factor and `UiScale` when converting them back to logical
coordinates. The logical size of Ui nodes now matches the values given
to their size constraints.
* Multiply the logical viewport size by `UiScale` before creating the
projection matrix for the UI's `ExtractedView` in
`extract_default_ui_camera_view`.
* In `ui_focus_system` the cursor position returned from `Window` is
divided by `UiScale`.
* Added a scale factor parameter to `Node::physical_size` and
`Node::physical_rect`.
* The example `viewport_debug` now uses a `UiScale` of 2. to ensure that
viewport coordinates are working correctly with a non-unit `UiScale`.
## Migration Guide
Physical UI coordinates are now divided by both the `UiScale` and the
window's scale factor to compute the logical sizes and positions of UI
nodes.
This ensures that UI Node size and position values, held by the `Node`
and `GlobalTransform` components, conform to the same logical coordinate
system as the style constraints from which they are derived,
irrespective of the current `scale_factor` and `UiScale`.
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-07-06 20:27:54 +00:00
pub fn physical_rect (
& self ,
transform : & GlobalTransform ,
2023-12-14 14:56:40 +00:00
scale_factor : f32 ,
ui_scale : f32 ,
Divide by `UiScale` when converting UI coordinates from physical to logical (#8720)
# Objective
After the UI layout is computed when the coordinates are converted back
from physical coordinates to logical coordinates the `UiScale` is
ignored. This results in a confusing situation where we have two
different systems of logical coordinates.
Example:
```rust
use bevy::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.add_systems(Update, update)
.run();
}
fn setup(mut commands: Commands, mut ui_scale: ResMut<UiScale>) {
ui_scale.scale = 4.;
commands.spawn(Camera2dBundle::default());
commands.spawn(NodeBundle {
style: Style {
align_items: AlignItems::Center,
justify_content: JustifyContent::Center,
width: Val::Percent(100.),
..Default::default()
},
..Default::default()
})
.with_children(|builder| {
builder.spawn(NodeBundle {
style: Style {
width: Val::Px(100.),
height: Val::Px(100.),
..Default::default()
},
background_color: Color::MAROON.into(),
..Default::default()
}).with_children(|builder| {
builder.spawn(TextBundle::from_section("", TextStyle::default());
});
});
}
fn update(
mut text_query: Query<(&mut Text, &Parent)>,
node_query: Query<Ref<Node>>,
) {
for (mut text, parent) in text_query.iter_mut() {
let node = node_query.get(parent.get()).unwrap();
if node.is_changed() {
text.sections[0].value = format!("size: {}", node.size());
}
}
}
```
result:
We asked for a 100x100 UI node but the Node's size is multiplied by the
value of `UiScale` to give a logical size of 400x400.
## Solution
Divide the output physical coordinates by `UiScale` in
`ui_layout_system` and multiply the logical viewport size by `UiScale`
when creating the projection matrix for the UI's `ExtractedView` in
`extract_default_ui_camera_view`.
---
## Changelog
* The UI layout's physical coordinates are divided by both the window
scale factor and `UiScale` when converting them back to logical
coordinates. The logical size of Ui nodes now matches the values given
to their size constraints.
* Multiply the logical viewport size by `UiScale` before creating the
projection matrix for the UI's `ExtractedView` in
`extract_default_ui_camera_view`.
* In `ui_focus_system` the cursor position returned from `Window` is
divided by `UiScale`.
* Added a scale factor parameter to `Node::physical_size` and
`Node::physical_rect`.
* The example `viewport_debug` now uses a `UiScale` of 2. to ensure that
viewport coordinates are working correctly with a non-unit `UiScale`.
## Migration Guide
Physical UI coordinates are now divided by both the `UiScale` and the
window's scale factor to compute the logical sizes and positions of UI
nodes.
This ensures that UI Node size and position values, held by the `Node`
and `GlobalTransform` components, conform to the same logical coordinate
system as the style constraints from which they are derived,
irrespective of the current `scale_factor` and `UiScale`.
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-07-06 20:27:54 +00:00
) -> Rect {
2023-03-09 14:12:54 +00:00
let rect = self . logical_rect ( transform ) ;
Rect {
2023-05-11 18:38:01 +00:00
min : Vec2 ::new (
2023-12-14 14:56:40 +00:00
rect . min . x * scale_factor * ui_scale ,
rect . min . y * scale_factor * ui_scale ,
2023-05-11 18:38:01 +00:00
) ,
max : Vec2 ::new (
2023-12-14 14:56:40 +00:00
rect . max . x * scale_factor * ui_scale ,
rect . max . y * scale_factor * ui_scale ,
2023-05-11 18:38:01 +00:00
) ,
2023-03-09 14:12:54 +00:00
}
}
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
#[ inline ]
/// Returns the thickness of the UI node's outline.
/// If this value is negative or `0.` then no outline will be rendered.
pub fn outline_width ( & self ) -> f32 {
self . outline_width
}
2020-01-13 00:51:21 +00:00
}
2020-07-26 19:27:09 +00:00
2023-01-04 19:58:09 +00:00
impl Node {
pub const DEFAULT : Self = Self {
2023-10-31 23:32:51 +00:00
stack_index : 0 ,
2023-01-04 19:58:09 +00:00
calculated_size : Vec2 ::ZERO ,
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
outline_width : 0. ,
outline_offset : 0. ,
2023-09-28 22:42:13 +00:00
unrounded_size : Vec2 ::ZERO ,
2023-01-04 19:58:09 +00:00
} ;
}
impl Default for Node {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-04-17 16:21:38 +00:00
/// Describes the style of a UI container node
2022-01-07 22:20:34 +00:00
///
2023-10-21 17:38:15 +00:00
/// Nodes can be laid out using either Flexbox or CSS Grid Layout.
///
2023-04-17 16:21:38 +00:00
/// See below for general learning resources and for documentation on the individual style properties.
///
/// ### Flexbox
///
2023-09-26 22:18:41 +00:00
/// - [MDN: Basic Concepts of Flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox)
2023-07-10 00:11:51 +00:00
/// - [A Complete Guide To Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) by CSS Tricks. This is detailed guide with illustrations and comprehensive written explanation of the different Flexbox properties and how they work.
2023-09-26 19:46:24 +00:00
/// - [Flexbox Froggy](https://flexboxfroggy.com/). An interactive tutorial/game that teaches the essential parts of Flexbox in a fun engaging way.
2023-04-17 16:21:38 +00:00
///
/// ### CSS Grid
///
2023-09-26 22:18:41 +00:00
/// - [MDN: Basic Concepts of Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Basic_Concepts_of_Grid_Layout)
2023-07-10 00:11:51 +00:00
/// - [A Complete Guide To CSS Grid](https://css-tricks.com/snippets/css/complete-guide-grid/) by CSS Tricks. This is detailed guide with illustrations and comprehensive written explanation of the different CSS Grid properties and how they work.
2023-04-17 16:21:38 +00:00
/// - [CSS Grid Garden](https://cssgridgarden.com/). An interactive tutorial/game that teaches the essential parts of CSS Grid in a fun engaging way.
2024-01-03 17:52:16 +00:00
#[ derive(Component, Clone, PartialEq, Debug, Reflect) ]
#[ reflect(Component, Default, PartialEq) ]
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2020-07-26 19:27:09 +00:00
pub struct Style {
2023-04-17 16:21:38 +00:00
/// Which layout algorithm to use when laying out this node's contents:
/// - [`Display::Flex`]: Use the Flexbox layout algorithm
/// - [`Display::Grid`]: Use the CSS Grid layout algorithm
/// - [`Display::None`]: Hide this node and perform layout as if it does not exist.
Disable UI node `Interaction` when `ComputedVisibility` is false (#5361)
# Objective
UI nodes can be hidden by setting their `Visibility` property. Since #5310 was merged, this is now ergonomic to use, as visibility is now inherited.
However, UI nodes still receive (and store) interactions when hidden, resulting in surprising hidden state (and an inability to otherwise disable UI nodes.
## Solution
Fixes #5360.
I've updated the `ui_focus_system` to accomplish this in a minimally intrusive way, and updated the docs to match.
**NOTE:** I have not added automated tests to verify this behavior, as we do not currently have a good testing paradigm for `bevy_ui`. I'm not thrilled with that by any means, but I'm not sure fixing it is within scope.
## Paths not taken
### Separate `Disabled` component
This is a much larger and more controversial change, and not well-scoped to UI.
Furthermore, it is extremely rare that you want hidden UI elements to function: the most common cases are for things like changing tabs, collapsing elements or so on.
Splitting this behavior would be more complex, and substantially violate user expectations.
### A separate limbo world
Mentioned in the linked issue. Super cool, but all of the problems of the `Disabled` component solution with a whole new RFC-worth of complexity.
### Using change detection to reduce the amount of redundant work
Adds a lot of complexity for questionable performance gains. Likely involves a complete refactor of the entire system.
We simply don't have the tests or benchmarks here to justify this.
## Changelog
- UI nodes are now always in an `Interaction::None` state while they are hidden (via the `ComputedVisibility` component).
2022-07-20 21:26:47 +00:00
///
2023-04-17 16:21:38 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/display>
2020-07-26 19:27:09 +00:00
pub display : Display ,
2023-04-17 16:21:38 +00:00
2023-10-21 17:38:15 +00:00
/// Whether a node should be laid out in-flow with, or independently of its siblings:
2023-04-17 16:21:38 +00:00
/// - [`PositionType::Relative`]: Layout this node in-flow with other nodes using the usual (flexbox/grid) layout algorithm.
/// - [`PositionType::Absolute`]: Layout this node on top and independently of other nodes.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/position>
2020-07-26 19:27:09 +00:00
pub position_type : PositionType ,
2023-04-17 16:21:38 +00:00
/// Whether overflowing content should be displayed or clipped.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/overflow>
pub overflow : Overflow ,
2023-10-21 17:38:15 +00:00
/// Defines the text direction. For example, English is written LTR (left-to-right) while Arabic is written RTL (right-to-left).
///
/// Note: the corresponding CSS property also affects box layout order, but this isn't yet implemented in Bevy.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/direction>
pub direction : Direction ,
/// The horizontal position of the left edge of the node.
/// - For relatively positioned nodes, this is relative to the node's position as computed during regular layout.
/// - For absolutely positioned nodes, this is relative to the *parent* node's bounding box.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/left>
2023-03-13 15:17:00 +00:00
pub left : Val ,
2023-04-17 16:21:38 +00:00
/// The horizontal position of the right edge of the node.
/// - For relatively positioned nodes, this is relative to the node's position as computed during regular layout.
/// - For absolutely positioned nodes, this is relative to the *parent* node's bounding box.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/right>
2023-03-13 15:17:00 +00:00
pub right : Val ,
2023-04-17 16:21:38 +00:00
/// The vertical position of the top edge of the node.
/// - For relatively positioned nodes, this is relative to the node's position as computed during regular layout.
/// - For absolutely positioned nodes, this is relative to the *parent* node's bounding box.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/top>
2023-03-13 15:17:00 +00:00
pub top : Val ,
2023-04-17 16:21:38 +00:00
/// The vertical position of the bottom edge of the node.
/// - For relatively positioned nodes, this is relative to the node's position as computed during regular layout.
/// - For absolutely positioned nodes, this is relative to the *parent* node's bounding box.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/bottom>
2023-03-13 15:17:00 +00:00
pub bottom : Val ,
2023-04-17 16:21:38 +00:00
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
/// The ideal width of the node. `width` is used when it is within the bounds defined by `min_width` and `max_width`.
2023-04-17 16:21:38 +00:00
///
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/width>
pub width : Val ,
/// The ideal height of the node. `height` is used when it is within the bounds defined by `min_height` and `max_height`.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/height>
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
pub height : Val ,
2023-04-17 16:21:38 +00:00
2023-10-21 17:38:15 +00:00
/// The minimum width of the node. `min_width` is used if it is greater than `width` and/or `max_width`.
2023-04-17 16:21:38 +00:00
///
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/min-width>
pub min_width : Val ,
2023-10-21 17:38:15 +00:00
/// The minimum height of the node. `min_height` is used if it is greater than `height` and/or `max_height`.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/min-height>
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
pub min_height : Val ,
2023-04-17 16:21:38 +00:00
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
/// The maximum width of the node. `max_width` is used if it is within the bounds defined by `min_width` and `width`.
2023-04-17 16:21:38 +00:00
///
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/max-width>
pub max_width : Val ,
/// The maximum height of the node. `max_height` is used if it is within the bounds defined by `min_height` and `height`.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/max-height>
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
pub max_height : Val ,
2023-04-17 16:21:38 +00:00
/// The aspect ratio of the node (defined as `width / height`)
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio>
pub aspect_ratio : Option < f32 > ,
2023-10-29 15:32:11 +00:00
/// Used to control how each individual item is aligned by default within the space they're given.
/// - For Flexbox containers, sets default cross axis alignment of the child items.
2023-07-29 22:22:24 +00:00
/// - For CSS Grid containers, controls block (vertical) axis alignment of children of this grid container within their grid areas.
2023-04-17 16:21:38 +00:00
///
2023-09-11 19:15:20 +00:00
/// This value is overridden if [`AlignSelf`] on the child node is set.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-items>
2020-07-26 19:27:09 +00:00
pub align_items : AlignItems ,
2023-04-17 16:21:38 +00:00
2023-10-29 15:32:11 +00:00
/// Used to control how each individual item is aligned by default within the space they're given.
/// - For Flexbox containers, this property has no effect. See `justify_content` for main axis alignment of flex items.
2023-07-29 22:22:24 +00:00
/// - For CSS Grid containers, sets default inline (horizontal) axis alignment of child items within their grid areas.
2023-04-17 16:21:38 +00:00
///
2023-09-11 19:15:20 +00:00
/// This value is overridden if [`JustifySelf`] on the child node is set.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items>
pub justify_items : JustifyItems ,
2023-10-29 15:32:11 +00:00
/// Used to control how the specified item is aligned within the space it's given.
/// - For Flexbox items, controls cross axis alignment of the item.
2023-10-21 17:38:15 +00:00
/// - For CSS Grid items, controls block (vertical) axis alignment of a grid item within its grid area.
2023-04-17 16:21:38 +00:00
///
/// If set to `Auto`, alignment is inherited from the value of [`AlignItems`] set on the parent node.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-self>
2020-07-26 19:27:09 +00:00
pub align_self : AlignSelf ,
2023-04-17 16:21:38 +00:00
2023-10-29 15:32:11 +00:00
/// Used to control how the specified item is aligned within the space it's given.
/// - For Flexbox items, this property has no effect. See `justify_content` for main axis alignment of flex items.
2023-10-21 17:38:15 +00:00
/// - For CSS Grid items, controls inline (horizontal) axis alignment of a grid item within its grid area.
2023-04-17 16:21:38 +00:00
///
/// If set to `Auto`, alignment is inherited from the value of [`JustifyItems`] set on the parent node.
///
2023-10-21 17:38:15 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-self>
2023-04-17 16:21:38 +00:00
pub justify_self : JustifySelf ,
2023-10-29 15:32:11 +00:00
/// Used to control how items are distributed.
/// - For Flexbox containers, controls alignment of lines if `flex_wrap` is set to [`FlexWrap::Wrap`] and there are multiple lines of items.
2023-07-29 22:22:24 +00:00
/// - For CSS Grid containers, controls alignment of grid rows.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-content>
2020-07-26 19:27:09 +00:00
pub align_content : AlignContent ,
2023-04-17 16:21:38 +00:00
2023-10-29 15:32:11 +00:00
/// Used to control how items are distributed.
2023-07-29 22:22:24 +00:00
/// - For Flexbox containers, controls alignment of items in the main axis.
/// - For CSS Grid containers, controls alignment of grid columns.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content>
2020-07-26 19:27:09 +00:00
pub justify_content : JustifyContent ,
2023-04-17 16:21:38 +00:00
2023-02-25 16:38:03 +00:00
/// The amount of space around a node outside its border.
///
/// If a percentage value is used, the percentage is calculated based on the width of the parent node.
///
/// # Example
/// ```
/// # use bevy_ui::{Style, UiRect, Val};
/// let style = Style {
/// margin: UiRect {
/// left: Val::Percent(10.),
/// right: Val::Percent(10.),
/// top: Val::Percent(15.),
/// bottom: Val::Percent(15.)
/// },
/// ..Default::default()
/// };
/// ```
2023-10-21 17:38:15 +00:00
/// A node with this style and a parent with dimensions of 100px by 300px will have calculated margins of 10px on both left and right edges, and 15px on both top and bottom edges.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/margin>
2022-08-01 16:27:16 +00:00
pub margin : UiRect ,
2023-04-17 16:21:38 +00:00
2023-02-25 16:38:03 +00:00
/// The amount of space between the edges of a node and its contents.
///
/// If a percentage value is used, the percentage is calculated based on the width of the parent node.
///
/// # Example
/// ```
/// # use bevy_ui::{Style, UiRect, Val};
/// let style = Style {
/// padding: UiRect {
/// left: Val::Percent(1.),
/// right: Val::Percent(2.),
/// top: Val::Percent(3.),
/// bottom: Val::Percent(4.)
/// },
/// ..Default::default()
/// };
/// ```
2023-10-21 17:38:15 +00:00
/// A node with this style and a parent with dimensions of 300px by 100px will have calculated padding of 3px on the left, 6px on the right, 9px on the top and 12px on the bottom.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/padding>
2022-08-01 16:27:16 +00:00
pub padding : UiRect ,
2023-04-17 16:21:38 +00:00
2023-03-02 17:37:09 +00:00
/// The amount of space between the margins of a node and its padding.
///
/// If a percentage value is used, the percentage is calculated based on the width of the parent node.
///
/// The size of the node will be expanded if there are constraints that prevent the layout algorithm from placing the border within the existing node boundary.
///
2023-04-17 16:21:38 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/border-width>
2022-08-01 16:27:16 +00:00
pub border : UiRect ,
2023-04-17 16:21:38 +00:00
2023-10-21 17:38:15 +00:00
/// Whether a Flexbox container should be a row or a column. This property has no effect on Grid nodes.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction>
pub flex_direction : FlexDirection ,
2023-10-21 17:38:15 +00:00
/// Whether a Flexbox container should wrap its contents onto multiple lines if they overflow. This property has no effect on Grid nodes.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap>
pub flex_wrap : FlexWrap ,
/// Defines how much a flexbox item should grow if there's space available. Defaults to 0 (don't grow at all).
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow>
2020-07-26 19:27:09 +00:00
pub flex_grow : f32 ,
2023-04-17 16:21:38 +00:00
/// Defines how much a flexbox item should shrink if there's not enough space available. Defaults to 1.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink>
2020-07-26 19:27:09 +00:00
pub flex_shrink : f32 ,
2023-04-17 16:21:38 +00:00
/// The initial length of a flexbox in the main axis, before flex growing/shrinking properties are applied.
2023-02-15 13:58:01 +00:00
///
2023-10-21 17:38:15 +00:00
/// `flex_basis` overrides `size` on the main axis if both are set, but it obeys the bounds defined by `min_size` and `max_size`.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-basis>
2020-07-26 19:27:09 +00:00
pub flex_basis : Val ,
2023-04-17 16:21:38 +00:00
2023-10-21 17:38:15 +00:00
/// The size of the gutters between items in a vertical flexbox layout or between rows in a grid layout.
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
///
/// Note: Values of `Val::Auto` are not valid and are treated as zero.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap>
pub row_gap : Val ,
2023-10-21 17:38:15 +00:00
/// The size of the gutters between items in a horizontal flexbox layout or between column in a grid layout.
2023-02-10 23:50:28 +00:00
///
2023-04-17 16:21:38 +00:00
/// Note: Values of `Val::Auto` are not valid and are treated as zero.
2023-02-10 23:50:28 +00:00
///
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap>
pub column_gap : Val ,
2023-04-17 16:21:38 +00:00
2023-10-21 17:38:15 +00:00
/// Controls whether automatically placed grid items are placed row-wise or column-wise as well as whether the sparse or dense packing algorithm is used.
/// Only affects Grid layouts.
2023-02-10 23:50:28 +00:00
///
2023-04-17 16:21:38 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow>
pub grid_auto_flow : GridAutoFlow ,
/// Defines the number of rows a grid has and the sizes of those rows. If grid items are given explicit placements then more rows may
/// be implicitly generated by items that are placed out of bounds. The sizes of those rows are controlled by `grid_auto_rows` property.
2022-12-21 02:15:53 +00:00
///
2023-04-17 16:21:38 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-rows>
pub grid_template_rows : Vec < RepeatedGridTrack > ,
/// Defines the number of columns a grid has and the sizes of those columns. If grid items are given explicit placements then more columns may
/// be implicitly generated by items that are placed out of bounds. The sizes of those columns are controlled by `grid_auto_columns` property.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns>
pub grid_template_columns : Vec < RepeatedGridTrack > ,
/// Defines the size of implicitly created rows. Rows are created implicitly when grid items are given explicit placements that are out of bounds
/// of the rows explicitly created using `grid_template_rows`.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-rows>
pub grid_auto_rows : Vec < GridTrack > ,
/// Defines the size of implicitly created columns. Columns are created implicitly when grid items are given explicit placements that are out of bounds
2023-07-10 00:11:51 +00:00
/// of the columns explicitly created using `grid_template_columns`.
2023-04-17 16:21:38 +00:00
///
2023-10-21 17:38:15 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-columns>
2023-04-17 16:21:38 +00:00
pub grid_auto_columns : Vec < GridTrack > ,
/// The row in which a grid item starts and how many rows it spans.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row>
pub grid_row : GridPlacement ,
/// The column in which a grid item starts and how many columns it spans.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column>
pub grid_column : GridPlacement ,
2020-07-26 19:27:09 +00:00
}
2023-01-04 19:58:09 +00:00
impl Style {
pub const DEFAULT : Self = Self {
display : Display ::DEFAULT ,
position_type : PositionType ::DEFAULT ,
2023-03-13 15:17:00 +00:00
left : Val ::Auto ,
right : Val ::Auto ,
top : Val ::Auto ,
bottom : Val ::Auto ,
2023-01-04 19:58:09 +00:00
direction : Direction ::DEFAULT ,
flex_direction : FlexDirection ::DEFAULT ,
flex_wrap : FlexWrap ::DEFAULT ,
align_items : AlignItems ::DEFAULT ,
2023-04-17 16:21:38 +00:00
justify_items : JustifyItems ::DEFAULT ,
2023-01-04 19:58:09 +00:00
align_self : AlignSelf ::DEFAULT ,
2023-04-17 16:21:38 +00:00
justify_self : JustifySelf ::DEFAULT ,
2023-01-04 19:58:09 +00:00
align_content : AlignContent ::DEFAULT ,
justify_content : JustifyContent ::DEFAULT ,
margin : UiRect ::DEFAULT ,
padding : UiRect ::DEFAULT ,
border : UiRect ::DEFAULT ,
flex_grow : 0.0 ,
flex_shrink : 1.0 ,
flex_basis : Val ::Auto ,
Flatten UI `Style` properties that use `Size` + remove `Size` (#8548)
# Objective
- Simplify API and make authoring styles easier
See:
https://github.com/bevyengine/bevy/issues/8540#issuecomment-1536177102
## Solution
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by `width`, `height`, `min_width`, `min_height`, `max_width`,
`max_height`, `row_gap`, and `column_gap` properties
---
## Changelog
- Flattened `Style` properties that have a `Size` value directly into
`Style`
## Migration Guide
- The `size`, `min_size`, `max_size`, and `gap` properties have been
replaced by the `width`, `height`, `min_width`, `min_height`,
`max_width`, `max_height`, `row_gap`, and `column_gap` properties. Use
the new properties instead.
---------
Co-authored-by: ickshonpe <david.curthoys@googlemail.com>
2023-05-16 01:36:32 +00:00
width : Val ::Auto ,
height : Val ::Auto ,
min_width : Val ::Auto ,
min_height : Val ::Auto ,
max_width : Val ::Auto ,
max_height : Val ::Auto ,
2023-01-04 19:58:09 +00:00
aspect_ratio : None ,
overflow : Overflow ::DEFAULT ,
2023-08-26 14:00:53 +00:00
row_gap : Val ::ZERO ,
column_gap : Val ::ZERO ,
2023-04-17 16:21:38 +00:00
grid_auto_flow : GridAutoFlow ::DEFAULT ,
grid_template_rows : Vec ::new ( ) ,
grid_template_columns : Vec ::new ( ) ,
grid_auto_rows : Vec ::new ( ) ,
grid_auto_columns : Vec ::new ( ) ,
grid_column : GridPlacement ::DEFAULT ,
grid_row : GridPlacement ::DEFAULT ,
2023-01-04 19:58:09 +00:00
} ;
}
2020-07-26 19:27:09 +00:00
impl Default for Style {
fn default ( ) -> Self {
2023-01-04 19:58:09 +00:00
Self ::DEFAULT
2020-07-26 19:27:09 +00:00
}
}
2023-10-29 15:32:11 +00:00
/// Used to control how each individual item is aligned by default within the space they're given.
/// - For Flexbox containers, sets default cross axis alignment of the child items.
/// - For CSS Grid containers, controls block (vertical) axis alignment of children of this grid container within their grid areas.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-items>
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2020-07-26 19:27:09 +00:00
pub enum AlignItems {
2023-10-21 17:38:15 +00:00
/// The items are packed in their default position as if no alignment was applied.
2023-04-17 16:21:38 +00:00
Default ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the start of the axis.
2023-03-04 14:09:47 +00:00
Start ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the end of the axis.
2023-03-04 14:09:47 +00:00
End ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the start of the axis, unless the flex direction is reversed;
2023-03-04 14:09:47 +00:00
/// then they are packed towards the end of the axis.
2020-07-26 19:27:09 +00:00
FlexStart ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the end of the axis, unless the flex direction is reversed;
2023-04-02 00:02:01 +00:00
/// then they are packed towards the start of the axis.
2020-07-26 19:27:09 +00:00
FlexEnd ,
2023-10-29 15:32:11 +00:00
/// The items are packed along the center of the axis.
2020-07-26 19:27:09 +00:00
Center ,
2023-10-29 15:32:11 +00:00
/// The items are packed such that their baselines align.
2020-07-26 19:27:09 +00:00
Baseline ,
2023-10-29 15:32:11 +00:00
/// The items are stretched to fill the space they're given.
2020-07-26 19:27:09 +00:00
Stretch ,
}
2023-01-04 19:58:09 +00:00
impl AlignItems {
2023-04-17 16:21:38 +00:00
pub const DEFAULT : Self = Self ::Default ;
2023-01-04 19:58:09 +00:00
}
impl Default for AlignItems {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-10-29 15:32:11 +00:00
/// Used to control how each individual item is aligned by default within the space they're given.
/// - For Flexbox containers, this property has no effect. See `justify_content` for main axis alignment of flex items.
/// - For CSS Grid containers, sets default inline (horizontal) axis alignment of child items within their grid areas.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items>
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
pub enum JustifyItems {
2023-10-21 17:38:15 +00:00
/// The items are packed in their default position as if no alignment was applied.
2023-04-17 16:21:38 +00:00
Default ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the start of the axis.
2023-04-17 16:21:38 +00:00
Start ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the end of the axis.
2023-04-17 16:21:38 +00:00
End ,
2023-10-29 15:32:11 +00:00
/// The items are packed along the center of the axis
2023-04-17 16:21:38 +00:00
Center ,
2023-10-29 15:32:11 +00:00
/// The items are packed such that their baselines align.
2023-04-17 16:21:38 +00:00
Baseline ,
2023-10-29 15:32:11 +00:00
/// The items are stretched to fill the space they're given.
2023-04-17 16:21:38 +00:00
Stretch ,
}
impl JustifyItems {
pub const DEFAULT : Self = Self ::Default ;
}
impl Default for JustifyItems {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-10-29 15:32:11 +00:00
/// Used to control how the specified item is aligned within the space it's given.
/// - For Flexbox items, controls cross axis alignment of the item.
/// - For CSS Grid items, controls block (vertical) axis alignment of a grid item within its grid area.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-self>
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2020-07-26 19:27:09 +00:00
pub enum AlignSelf {
2023-03-04 14:09:47 +00:00
/// Use the parent node's [`AlignItems`] value to determine how this item should be aligned.
2020-07-26 19:27:09 +00:00
Auto ,
2023-03-04 14:09:47 +00:00
/// This item will be aligned with the start of the axis.
Start ,
/// This item will be aligned with the end of the axis.
End ,
/// This item will be aligned with the start of the axis, unless the flex direction is reversed;
/// then it will be aligned with the end of the axis.
2020-07-26 19:27:09 +00:00
FlexStart ,
2023-04-02 00:02:01 +00:00
/// This item will be aligned with the end of the axis, unless the flex direction is reversed;
/// then it will be aligned with the start of the axis.
2020-07-26 19:27:09 +00:00
FlexEnd ,
2023-10-29 15:32:11 +00:00
/// This item will be aligned along the center of the axis.
2020-07-26 19:27:09 +00:00
Center ,
2023-03-04 14:09:47 +00:00
/// This item will be aligned at the baseline.
2020-07-26 19:27:09 +00:00
Baseline ,
2023-10-29 15:32:11 +00:00
/// This item will be stretched to fill the container.
2020-07-26 19:27:09 +00:00
Stretch ,
}
2023-01-04 19:58:09 +00:00
impl AlignSelf {
pub const DEFAULT : Self = Self ::Auto ;
}
impl Default for AlignSelf {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-10-29 15:32:11 +00:00
/// Used to control how the specified item is aligned within the space it's given.
/// - For Flexbox items, this property has no effect. See `justify_content` for main axis alignment of flex items.
/// - For CSS Grid items, controls inline (horizontal) axis alignment of a grid item within its grid area.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-self>
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
pub enum JustifySelf {
2023-08-23 23:57:24 +00:00
/// Use the parent node's [`JustifyItems`] value to determine how this item should be aligned.
2023-04-17 16:21:38 +00:00
Auto ,
/// This item will be aligned with the start of the axis.
Start ,
/// This item will be aligned with the end of the axis.
End ,
2023-10-29 15:32:11 +00:00
/// This item will be aligned along the center of the axis.
2023-04-17 16:21:38 +00:00
Center ,
/// This item will be aligned at the baseline.
Baseline ,
2023-10-29 15:32:11 +00:00
/// This item will be stretched to fill the space it's given.
2023-04-17 16:21:38 +00:00
Stretch ,
}
impl JustifySelf {
pub const DEFAULT : Self = Self ::Auto ;
}
impl Default for JustifySelf {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-10-29 15:32:11 +00:00
/// Used to control how items are distributed.
/// - For Flexbox containers, controls alignment of lines if `flex_wrap` is set to [`FlexWrap::Wrap`] and there are multiple lines of items.
/// - For CSS Grid containers, controls alignment of grid rows.
2022-01-07 22:20:34 +00:00
///
2023-10-29 15:32:11 +00:00
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/align-content>
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2020-07-26 19:27:09 +00:00
pub enum AlignContent {
2023-10-21 17:38:15 +00:00
/// The items are packed in their default position as if no alignment was applied.
2023-04-17 16:21:38 +00:00
Default ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the start of the axis.
2023-03-04 14:09:47 +00:00
Start ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the end of the axis.
2023-03-04 14:09:47 +00:00
End ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the start of the axis, unless the flex direction is reversed;
/// then the items are packed towards the end of the axis.
2020-07-26 19:27:09 +00:00
FlexStart ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the end of the axis, unless the flex direction is reversed;
/// then the items are packed towards the start of the axis.
2020-07-26 19:27:09 +00:00
FlexEnd ,
2023-10-29 15:32:11 +00:00
/// The items are packed along the center of the axis.
2020-07-26 19:27:09 +00:00
Center ,
2023-10-29 15:32:11 +00:00
/// The items are stretched to fill the container along the axis.
2020-07-26 19:27:09 +00:00
Stretch ,
2023-10-29 15:32:11 +00:00
/// The items are distributed such that the gap between any two items is equal.
2020-07-26 19:27:09 +00:00
SpaceBetween ,
2023-10-29 15:32:11 +00:00
/// The items are distributed such that the gap between and around any two items is equal.
2023-03-04 14:09:47 +00:00
SpaceEvenly ,
2023-10-29 15:32:11 +00:00
/// The items are distributed such that the gap between and around any two items is equal, with half-size gaps on either end.
2020-07-26 19:27:09 +00:00
SpaceAround ,
}
2023-01-04 19:58:09 +00:00
impl AlignContent {
2023-04-17 16:21:38 +00:00
pub const DEFAULT : Self = Self ::Default ;
2023-01-04 19:58:09 +00:00
}
impl Default for AlignContent {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-10-29 15:32:11 +00:00
/// Used to control how items are distributed.
/// - For Flexbox containers, controls alignment of items in the main axis.
/// - For CSS Grid containers, controls alignment of grid columns.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content>
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
pub enum JustifyContent {
2023-10-21 17:38:15 +00:00
/// The items are packed in their default position as if no alignment was applied.
2023-04-17 16:21:38 +00:00
Default ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the start of the axis.
2023-04-17 16:21:38 +00:00
Start ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the end of the axis.
2023-04-17 16:21:38 +00:00
End ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the start of the axis, unless the flex direction is reversed;
/// then the items are packed towards the end of the axis.
2023-04-17 16:21:38 +00:00
FlexStart ,
2023-10-29 15:32:11 +00:00
/// The items are packed towards the end of the axis, unless the flex direction is reversed;
/// then the items are packed towards the start of the axis.
2023-04-17 16:21:38 +00:00
FlexEnd ,
2023-10-29 15:32:11 +00:00
/// The items are packed along the center of the axis.
2023-04-17 16:21:38 +00:00
Center ,
2023-10-29 15:32:11 +00:00
/// The items are stretched to fill the container along the axis.
Stretch ,
/// The items are distributed such that the gap between any two items is equal.
2023-04-17 16:21:38 +00:00
SpaceBetween ,
2023-10-29 15:32:11 +00:00
/// The items are distributed such that the gap between and around any two items is equal.
2023-04-17 16:21:38 +00:00
SpaceEvenly ,
2023-10-29 15:32:11 +00:00
/// The items are distributed such that the gap between and around any two items is equal, with half-size gaps on either end.
SpaceAround ,
2023-04-17 16:21:38 +00:00
}
impl JustifyContent {
pub const DEFAULT : Self = Self ::Default ;
}
impl Default for JustifyContent {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-10-21 17:38:15 +00:00
/// Defines the text direction.
2022-01-07 22:20:34 +00:00
///
2023-10-21 17:38:15 +00:00
/// For example, English is written LTR (left-to-right) while Arabic is written RTL (right-to-left).
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2020-07-26 19:27:09 +00:00
pub enum Direction {
2023-03-04 14:09:47 +00:00
/// Inherit from parent node.
2020-07-26 19:27:09 +00:00
Inherit ,
2023-03-04 14:09:47 +00:00
/// Text is written left to right.
2021-08-24 01:50:21 +00:00
LeftToRight ,
2023-03-04 14:09:47 +00:00
/// Text is written right to left.
2021-08-24 01:50:21 +00:00
RightToLeft ,
2020-07-26 19:27:09 +00:00
}
2023-01-04 19:58:09 +00:00
impl Direction {
pub const DEFAULT : Self = Self ::Inherit ;
}
impl Default for Direction {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-10-21 17:38:15 +00:00
/// Defines the layout model used by this node.
Disable UI node `Interaction` when `ComputedVisibility` is false (#5361)
# Objective
UI nodes can be hidden by setting their `Visibility` property. Since #5310 was merged, this is now ergonomic to use, as visibility is now inherited.
However, UI nodes still receive (and store) interactions when hidden, resulting in surprising hidden state (and an inability to otherwise disable UI nodes.
## Solution
Fixes #5360.
I've updated the `ui_focus_system` to accomplish this in a minimally intrusive way, and updated the docs to match.
**NOTE:** I have not added automated tests to verify this behavior, as we do not currently have a good testing paradigm for `bevy_ui`. I'm not thrilled with that by any means, but I'm not sure fixing it is within scope.
## Paths not taken
### Separate `Disabled` component
This is a much larger and more controversial change, and not well-scoped to UI.
Furthermore, it is extremely rare that you want hidden UI elements to function: the most common cases are for things like changing tabs, collapsing elements or so on.
Splitting this behavior would be more complex, and substantially violate user expectations.
### A separate limbo world
Mentioned in the linked issue. Super cool, but all of the problems of the `Disabled` component solution with a whole new RFC-worth of complexity.
### Using change detection to reduce the amount of redundant work
Adds a lot of complexity for questionable performance gains. Likely involves a complete refactor of the entire system.
We simply don't have the tests or benchmarks here to justify this.
## Changelog
- UI nodes are now always in an `Interaction::None` state while they are hidden (via the `ComputedVisibility` component).
2022-07-20 21:26:47 +00:00
///
/// Part of the [`Style`] component.
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2020-07-26 19:27:09 +00:00
pub enum Display {
Disable UI node `Interaction` when `ComputedVisibility` is false (#5361)
# Objective
UI nodes can be hidden by setting their `Visibility` property. Since #5310 was merged, this is now ergonomic to use, as visibility is now inherited.
However, UI nodes still receive (and store) interactions when hidden, resulting in surprising hidden state (and an inability to otherwise disable UI nodes.
## Solution
Fixes #5360.
I've updated the `ui_focus_system` to accomplish this in a minimally intrusive way, and updated the docs to match.
**NOTE:** I have not added automated tests to verify this behavior, as we do not currently have a good testing paradigm for `bevy_ui`. I'm not thrilled with that by any means, but I'm not sure fixing it is within scope.
## Paths not taken
### Separate `Disabled` component
This is a much larger and more controversial change, and not well-scoped to UI.
Furthermore, it is extremely rare that you want hidden UI elements to function: the most common cases are for things like changing tabs, collapsing elements or so on.
Splitting this behavior would be more complex, and substantially violate user expectations.
### A separate limbo world
Mentioned in the linked issue. Super cool, but all of the problems of the `Disabled` component solution with a whole new RFC-worth of complexity.
### Using change detection to reduce the amount of redundant work
Adds a lot of complexity for questionable performance gains. Likely involves a complete refactor of the entire system.
We simply don't have the tests or benchmarks here to justify this.
## Changelog
- UI nodes are now always in an `Interaction::None` state while they are hidden (via the `ComputedVisibility` component).
2022-07-20 21:26:47 +00:00
/// Use Flexbox layout model to determine the position of this [`Node`].
2020-07-26 19:27:09 +00:00
Flex ,
2023-04-17 16:21:38 +00:00
/// Use CSS Grid layout model to determine the position of this [`Node`].
Grid ,
Disable UI node `Interaction` when `ComputedVisibility` is false (#5361)
# Objective
UI nodes can be hidden by setting their `Visibility` property. Since #5310 was merged, this is now ergonomic to use, as visibility is now inherited.
However, UI nodes still receive (and store) interactions when hidden, resulting in surprising hidden state (and an inability to otherwise disable UI nodes.
## Solution
Fixes #5360.
I've updated the `ui_focus_system` to accomplish this in a minimally intrusive way, and updated the docs to match.
**NOTE:** I have not added automated tests to verify this behavior, as we do not currently have a good testing paradigm for `bevy_ui`. I'm not thrilled with that by any means, but I'm not sure fixing it is within scope.
## Paths not taken
### Separate `Disabled` component
This is a much larger and more controversial change, and not well-scoped to UI.
Furthermore, it is extremely rare that you want hidden UI elements to function: the most common cases are for things like changing tabs, collapsing elements or so on.
Splitting this behavior would be more complex, and substantially violate user expectations.
### A separate limbo world
Mentioned in the linked issue. Super cool, but all of the problems of the `Disabled` component solution with a whole new RFC-worth of complexity.
### Using change detection to reduce the amount of redundant work
Adds a lot of complexity for questionable performance gains. Likely involves a complete refactor of the entire system.
We simply don't have the tests or benchmarks here to justify this.
## Changelog
- UI nodes are now always in an `Interaction::None` state while they are hidden (via the `ComputedVisibility` component).
2022-07-20 21:26:47 +00:00
/// Use no layout, don't render this node and its children.
///
/// If you want to hide a node and its children,
/// but keep its layout in place, set its [`Visibility`](bevy_render::view::Visibility) component instead.
2020-07-26 19:27:09 +00:00
None ,
}
2023-01-04 19:58:09 +00:00
impl Display {
pub const DEFAULT : Self = Self ::Flex ;
}
impl Default for Display {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2022-01-07 22:20:34 +00:00
/// Defines how flexbox items are ordered within a flexbox
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2020-07-26 19:27:09 +00:00
pub enum FlexDirection {
2023-03-04 14:09:47 +00:00
/// Same way as text direction along the main axis.
2020-07-26 19:27:09 +00:00
Row ,
2023-03-04 14:09:47 +00:00
/// Flex from top to bottom.
2020-07-26 19:27:09 +00:00
Column ,
2023-03-04 14:09:47 +00:00
/// Opposite way as text direction along the main axis.
2020-07-26 19:27:09 +00:00
RowReverse ,
2023-03-04 14:09:47 +00:00
/// Flex from bottom to top.
2020-07-26 19:27:09 +00:00
ColumnReverse ,
}
2023-01-04 19:58:09 +00:00
impl FlexDirection {
pub const DEFAULT : Self = Self ::Row ;
}
impl Default for FlexDirection {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2022-01-07 22:20:34 +00:00
/// Whether to show or hide overflowing items
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 22:23:52 +00:00
pub struct Overflow {
2023-08-22 12:22:47 +00:00
/// Whether to show or clip overflowing items on the x axis
2023-04-17 22:23:52 +00:00
pub x : OverflowAxis ,
/// Whether to show or clip overflowing items on the y axis
pub y : OverflowAxis ,
}
impl Overflow {
pub const DEFAULT : Self = Self {
x : OverflowAxis ::DEFAULT ,
y : OverflowAxis ::DEFAULT ,
} ;
/// Show overflowing items on both axes
pub const fn visible ( ) -> Self {
Self {
x : OverflowAxis ::Visible ,
y : OverflowAxis ::Visible ,
}
}
/// Clip overflowing items on both axes
pub const fn clip ( ) -> Self {
Self {
x : OverflowAxis ::Clip ,
y : OverflowAxis ::Clip ,
}
}
/// Clip overflowing items on the x axis
pub const fn clip_x ( ) -> Self {
Self {
x : OverflowAxis ::Clip ,
y : OverflowAxis ::Visible ,
}
}
/// Clip overflowing items on the y axis
pub const fn clip_y ( ) -> Self {
Self {
x : OverflowAxis ::Visible ,
y : OverflowAxis ::Clip ,
}
}
/// Overflow is visible on both axes
pub const fn is_visible ( & self ) -> bool {
self . x . is_visible ( ) & & self . y . is_visible ( )
}
}
impl Default for Overflow {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
/// Whether to show or hide overflowing items
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 22:23:52 +00:00
pub enum OverflowAxis {
2023-03-04 14:09:47 +00:00
/// Show overflowing items.
2021-12-19 05:44:28 +00:00
Visible ,
2023-03-04 14:09:47 +00:00
/// Hide overflowing items.
2023-04-17 22:23:52 +00:00
Clip ,
2021-12-19 05:44:28 +00:00
}
2020-07-26 19:27:09 +00:00
2023-04-17 22:23:52 +00:00
impl OverflowAxis {
2023-01-04 19:58:09 +00:00
pub const DEFAULT : Self = Self ::Visible ;
2023-04-17 22:23:52 +00:00
/// Overflow is visible on this axis
pub const fn is_visible ( & self ) -> bool {
matches! ( self , Self ::Visible )
}
2023-01-04 19:58:09 +00:00
}
2023-04-17 22:23:52 +00:00
impl Default for OverflowAxis {
2023-01-04 19:58:09 +00:00
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2022-01-07 22:20:34 +00:00
/// The strategy used to position this node
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2020-07-26 19:27:09 +00:00
pub enum PositionType {
2023-03-04 14:09:47 +00:00
/// Relative to all other nodes with the [`PositionType::Relative`] value.
2020-07-26 19:27:09 +00:00
Relative ,
2023-10-21 17:38:15 +00:00
/// Independent of all other nodes, but relative to its parent node.
2020-07-26 19:27:09 +00:00
Absolute ,
}
2023-01-04 19:58:09 +00:00
impl PositionType {
2023-08-22 12:22:47 +00:00
pub const DEFAULT : Self = Self ::Relative ;
2023-01-04 19:58:09 +00:00
}
impl Default for PositionType {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2022-01-07 22:20:34 +00:00
/// Defines if flexbox items appear on a single line or on multiple lines
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2020-07-26 19:27:09 +00:00
pub enum FlexWrap {
2023-03-04 14:09:47 +00:00
/// Single line, will overflow if needed.
2020-07-26 19:27:09 +00:00
NoWrap ,
2023-03-04 14:09:47 +00:00
/// Multiple lines, if needed.
2020-07-26 19:27:09 +00:00
Wrap ,
2023-03-04 14:09:47 +00:00
/// Same as [`FlexWrap::Wrap`] but new lines will appear before the previous one.
2020-07-26 19:27:09 +00:00
WrapReverse ,
}
2023-01-04 19:58:09 +00:00
impl FlexWrap {
2023-08-22 12:22:47 +00:00
pub const DEFAULT : Self = Self ::NoWrap ;
2023-01-04 19:58:09 +00:00
}
impl Default for FlexWrap {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-10-21 17:38:15 +00:00
/// Controls whether grid items are placed row-wise or column-wise as well as whether the sparse or dense packing algorithm is used.
2023-04-17 16:21:38 +00:00
///
2023-10-21 17:38:15 +00:00
/// The "dense" packing algorithm attempts to fill in holes earlier in the grid, if smaller items come up later.
/// This may cause items to appear out-of-order when doing so would fill in holes left by larger items.
2023-04-17 16:21:38 +00:00
///
2023-10-21 17:38:15 +00:00
/// Defaults to [`GridAutoFlow::Row`].
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow>
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
pub enum GridAutoFlow {
2023-10-21 17:38:15 +00:00
/// Items are placed by filling each row in turn, adding new rows as necessary.
2023-04-17 16:21:38 +00:00
Row ,
/// Items are placed by filling each column in turn, adding new columns as necessary.
Column ,
/// Combines `Row` with the dense packing algorithm.
RowDense ,
/// Combines `Column` with the dense packing algorithm.
ColumnDense ,
}
impl GridAutoFlow {
2023-08-22 12:22:47 +00:00
pub const DEFAULT : Self = Self ::Row ;
2023-04-17 16:21:38 +00:00
}
impl Default for GridAutoFlow {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Debug, Reflect) ]
#[ reflect_value(PartialEq) ]
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect_value ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
pub enum MinTrackSizingFunction {
/// Track minimum size should be a fixed pixel value
Px ( f32 ) ,
/// Track minimum size should be a percentage value
Percent ( f32 ) ,
/// Track minimum size should be content sized under a min-content constraint
MinContent ,
/// Track minimum size should be content sized under a max-content constraint
MaxContent ,
/// Track minimum size should be automatically sized
Auto ,
}
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Debug, Reflect) ]
#[ reflect_value(PartialEq) ]
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect_value ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
pub enum MaxTrackSizingFunction {
/// Track maximum size should be a fixed pixel value
Px ( f32 ) ,
/// Track maximum size should be a percentage value
Percent ( f32 ) ,
/// Track maximum size should be content sized under a min-content constraint
MinContent ,
/// Track maximum size should be content sized under a max-content constraint
MaxContent ,
/// Track maximum size should be sized according to the fit-content formula with a fixed pixel limit
FitContentPx ( f32 ) ,
/// Track maximum size should be sized according to the fit-content formula with a percentage limit
FitContentPercent ( f32 ) ,
/// Track maximum size should be automatically sized
Auto ,
/// The dimension as a fraction of the total available grid space (`fr` units in CSS)
2023-10-21 17:38:15 +00:00
/// Specified value is the numerator of the fraction. Denominator is the sum of all fractions specified in that grid dimension.
///
2023-04-17 16:21:38 +00:00
/// Spec: <https://www.w3.org/TR/css3-grid-layout/#fr-unit>
Fraction ( f32 ) ,
}
/// A [`GridTrack`] is a Row or Column of a CSS Grid. This struct specifies what size the track should be.
/// See below for the different "track sizing functions" you can specify.
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
pub struct GridTrack {
pub ( crate ) min_sizing_function : MinTrackSizingFunction ,
pub ( crate ) max_sizing_function : MaxTrackSizingFunction ,
}
impl GridTrack {
2023-08-22 12:22:47 +00:00
pub const DEFAULT : Self = Self {
2023-04-17 16:21:38 +00:00
min_sizing_function : MinTrackSizingFunction ::Auto ,
max_sizing_function : MaxTrackSizingFunction ::Auto ,
} ;
/// Create a grid track with a fixed pixel size
pub fn px < T : From < Self > > ( value : f32 ) -> T {
Self {
min_sizing_function : MinTrackSizingFunction ::Px ( value ) ,
max_sizing_function : MaxTrackSizingFunction ::Px ( value ) ,
}
. into ( )
}
/// Create a grid track with a percentage size
pub fn percent < T : From < Self > > ( value : f32 ) -> T {
Self {
min_sizing_function : MinTrackSizingFunction ::Percent ( value ) ,
max_sizing_function : MaxTrackSizingFunction ::Percent ( value ) ,
}
. into ( )
}
/// Create a grid track with an `fr` size.
/// Note that this will give the track a content-based minimum size.
2023-10-21 17:38:15 +00:00
/// Usually you are best off using `GridTrack::flex` instead which uses a zero minimum size.
2023-04-17 16:21:38 +00:00
pub fn fr < T : From < Self > > ( value : f32 ) -> T {
Self {
min_sizing_function : MinTrackSizingFunction ::Auto ,
max_sizing_function : MaxTrackSizingFunction ::Fraction ( value ) ,
}
. into ( )
}
2023-10-21 17:38:15 +00:00
/// Create a grid track with a `minmax(0, Nfr)` size.
2023-04-17 16:21:38 +00:00
pub fn flex < T : From < Self > > ( value : f32 ) -> T {
Self {
min_sizing_function : MinTrackSizingFunction ::Px ( 0.0 ) ,
max_sizing_function : MaxTrackSizingFunction ::Fraction ( value ) ,
}
. into ( )
}
2023-10-21 17:38:15 +00:00
/// Create a grid track which is automatically sized to fit its contents.
2023-04-17 16:21:38 +00:00
pub fn auto < T : From < Self > > ( ) -> T {
Self {
min_sizing_function : MinTrackSizingFunction ::Auto ,
max_sizing_function : MaxTrackSizingFunction ::Auto ,
}
. into ( )
}
2023-10-21 17:38:15 +00:00
/// Create a grid track which is automatically sized to fit its contents when sized at their "min-content" sizes
2023-04-17 16:21:38 +00:00
pub fn min_content < T : From < Self > > ( ) -> T {
Self {
min_sizing_function : MinTrackSizingFunction ::MinContent ,
max_sizing_function : MaxTrackSizingFunction ::MinContent ,
}
. into ( )
}
2023-10-21 17:38:15 +00:00
/// Create a grid track which is automatically sized to fit its contents when sized at their "max-content" sizes
2023-04-17 16:21:38 +00:00
pub fn max_content < T : From < Self > > ( ) -> T {
Self {
min_sizing_function : MinTrackSizingFunction ::MaxContent ,
max_sizing_function : MaxTrackSizingFunction ::MaxContent ,
}
. into ( )
}
2023-12-30 09:07:31 +00:00
/// Create a `fit-content()` grid track with fixed pixel limit.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/fit-content_function>
pub fn fit_content_px < T : From < Self > > ( limit : f32 ) -> T {
Self {
min_sizing_function : MinTrackSizingFunction ::Auto ,
max_sizing_function : MaxTrackSizingFunction ::FitContentPx ( limit ) ,
}
. into ( )
}
2023-12-30 09:07:31 +00:00
/// Create a `fit-content()` grid track with percentage limit.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/fit-content_function>
pub fn fit_content_percent < T : From < Self > > ( limit : f32 ) -> T {
Self {
min_sizing_function : MinTrackSizingFunction ::Auto ,
max_sizing_function : MaxTrackSizingFunction ::FitContentPercent ( limit ) ,
}
. into ( )
}
2023-12-30 09:07:31 +00:00
/// Create a `minmax()` grid track.
2023-04-17 16:21:38 +00:00
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/minmax>
pub fn minmax < T : From < Self > > ( min : MinTrackSizingFunction , max : MaxTrackSizingFunction ) -> T {
Self {
min_sizing_function : min ,
max_sizing_function : max ,
}
. into ( )
}
}
impl Default for GridTrack {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Debug, Reflect) ]
#[ reflect(PartialEq) ]
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
/// How many times to repeat a repeated grid track
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/repeat>
pub enum GridTrackRepetition {
/// Repeat the track fixed number of times
Count ( u16 ) ,
/// Repeat the track to fill available space
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/repeat#auto-fill>
AutoFill ,
/// Repeat the track to fill available space but collapse any tracks that do not end up with
/// an item placed in them.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/repeat#auto-fit>
AutoFit ,
}
impl From < u16 > for GridTrackRepetition {
fn from ( count : u16 ) -> Self {
Self ::Count ( count )
}
}
impl From < i32 > for GridTrackRepetition {
fn from ( count : i32 ) -> Self {
Self ::Count ( count as u16 )
}
}
impl From < usize > for GridTrackRepetition {
fn from ( count : usize ) -> Self {
Self ::Count ( count as u16 )
}
}
/// Represents a *possibly* repeated [`GridTrack`].
///
/// The repetition parameter can either be:
/// - The integer `1`, in which case the track is non-repeated.
2023-10-21 17:38:15 +00:00
/// - a `u16` count to repeat the track N times.
/// - A `GridTrackRepetition::AutoFit` or `GridTrackRepetition::AutoFill`.
2023-04-17 16:21:38 +00:00
///
/// Note: that in the common case you want a non-repeating track (repetition count 1), you may use the constructor methods on [`GridTrack`]
/// to create a `RepeatedGridTrack`. i.e. `GridTrack::px(10.0)` is equivalent to `RepeatedGridTrack::px(1, 10.0)`.
///
/// You may only use one auto-repetition per track list. And if your track list contains an auto repetition
2023-10-21 17:38:15 +00:00
/// then all tracks (in and outside of the repetition) must be fixed size (px or percent). Integer repetitions are just shorthand for writing out
2023-04-17 16:21:38 +00:00
/// N tracks longhand and are not subject to the same limitations.
2024-01-03 17:52:16 +00:00
#[ derive(Clone, PartialEq, Debug, Reflect) ]
#[ reflect(PartialEq) ]
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
pub struct RepeatedGridTrack {
pub ( crate ) repetition : GridTrackRepetition ,
pub ( crate ) tracks : SmallVec < [ GridTrack ; 1 ] > ,
}
impl RepeatedGridTrack {
/// Create a repeating set of grid tracks with a fixed pixel size
pub fn px < T : From < Self > > ( repetition : impl Into < GridTrackRepetition > , value : f32 ) -> T {
Self {
repetition : repetition . into ( ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::px ( value ) ] ) ,
}
. into ( )
}
/// Create a repeating set of grid tracks with a percentage size
pub fn percent < T : From < Self > > ( repetition : impl Into < GridTrackRepetition > , value : f32 ) -> T {
Self {
repetition : repetition . into ( ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::percent ( value ) ] ) ,
}
. into ( )
}
/// Create a repeating set of grid tracks with automatic size
pub fn auto < T : From < Self > > ( repetition : u16 ) -> T {
Self {
repetition : GridTrackRepetition ::Count ( repetition ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::auto ( ) ] ) ,
}
. into ( )
}
/// Create a repeating set of grid tracks with an `fr` size.
/// Note that this will give the track a content-based minimum size.
2023-10-21 17:38:15 +00:00
/// Usually you are best off using `GridTrack::flex` instead which uses a zero minimum size.
2023-04-17 16:21:38 +00:00
pub fn fr < T : From < Self > > ( repetition : u16 , value : f32 ) -> T {
Self {
repetition : GridTrackRepetition ::Count ( repetition ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::fr ( value ) ] ) ,
}
. into ( )
}
2023-10-21 17:38:15 +00:00
/// Create a repeating set of grid tracks with a `minmax(0, Nfr)` size.
2023-04-17 16:21:38 +00:00
pub fn flex < T : From < Self > > ( repetition : u16 , value : f32 ) -> T {
Self {
repetition : GridTrackRepetition ::Count ( repetition ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::flex ( value ) ] ) ,
}
. into ( )
}
/// Create a repeating set of grid tracks with min-content size
pub fn min_content < T : From < Self > > ( repetition : u16 ) -> T {
Self {
repetition : GridTrackRepetition ::Count ( repetition ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::min_content ( ) ] ) ,
}
. into ( )
}
/// Create a repeating set of grid tracks with max-content size
pub fn max_content < T : From < Self > > ( repetition : u16 ) -> T {
Self {
repetition : GridTrackRepetition ::Count ( repetition ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::max_content ( ) ] ) ,
}
. into ( )
}
2023-12-30 09:07:31 +00:00
/// Create a repeating set of `fit-content()` grid tracks with fixed pixel limit
2023-04-17 16:21:38 +00:00
pub fn fit_content_px < T : From < Self > > ( repetition : u16 , limit : f32 ) -> T {
Self {
repetition : GridTrackRepetition ::Count ( repetition ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::fit_content_px ( limit ) ] ) ,
}
. into ( )
}
2023-12-30 09:07:31 +00:00
/// Create a repeating set of `fit-content()` grid tracks with percentage limit
2023-04-17 16:21:38 +00:00
pub fn fit_content_percent < T : From < Self > > ( repetition : u16 , limit : f32 ) -> T {
Self {
repetition : GridTrackRepetition ::Count ( repetition ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::fit_content_percent ( limit ) ] ) ,
}
. into ( )
}
2023-12-30 09:07:31 +00:00
/// Create a repeating set of `minmax()` grid track
2023-04-17 16:21:38 +00:00
pub fn minmax < T : From < Self > > (
repetition : impl Into < GridTrackRepetition > ,
min : MinTrackSizingFunction ,
max : MaxTrackSizingFunction ,
) -> T {
Self {
repetition : repetition . into ( ) ,
tracks : SmallVec ::from_buf ( [ GridTrack ::minmax ( min , max ) ] ) ,
}
. into ( )
}
/// Create a repetition of a set of tracks
pub fn repeat_many < T : From < Self > > (
repetition : impl Into < GridTrackRepetition > ,
tracks : impl Into < Vec < GridTrack > > ,
) -> T {
Self {
repetition : repetition . into ( ) ,
tracks : SmallVec ::from_vec ( tracks . into ( ) ) ,
}
. into ( )
}
}
impl From < GridTrack > for RepeatedGridTrack {
fn from ( track : GridTrack ) -> Self {
Self {
repetition : GridTrackRepetition ::Count ( 1 ) ,
tracks : SmallVec ::from_buf ( [ track ] ) ,
}
}
}
impl From < GridTrack > for Vec < GridTrack > {
fn from ( track : GridTrack ) -> Self {
vec! [ GridTrack {
min_sizing_function : track . min_sizing_function ,
max_sizing_function : track . max_sizing_function ,
} ]
}
}
impl From < GridTrack > for Vec < RepeatedGridTrack > {
fn from ( track : GridTrack ) -> Self {
vec! [ RepeatedGridTrack {
repetition : GridTrackRepetition ::Count ( 1 ) ,
tracks : SmallVec ::from_buf ( [ track ] ) ,
} ]
}
}
impl From < RepeatedGridTrack > for Vec < RepeatedGridTrack > {
fn from ( track : RepeatedGridTrack ) -> Self {
vec! [ track ]
}
}
2024-01-03 17:52:16 +00:00
#[ derive(Copy, Clone, PartialEq, Eq, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Default, PartialEq) ]
2024-01-03 17:52:16 +00:00
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-04-17 16:21:38 +00:00
/// Represents the position of a grid item in a single axis.
///
/// There are 3 fields which may be set:
/// - `start`: which grid line the item should start at
/// - `end`: which grid line the item should end at
/// - `span`: how many tracks the item should span
///
/// The default `span` is 1. If neither `start` or `end` is set then the item will be placed automatically.
///
2023-07-10 00:11:51 +00:00
/// Generally, at most two fields should be set. If all three fields are specified then `span` will be ignored. If `end` specifies an earlier
2023-04-17 16:21:38 +00:00
/// grid line than `start` then `end` will be ignored and the item will have a span of 1.
///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Line-based_Placement_with_CSS_Grid>
pub struct GridPlacement {
2023-10-21 17:38:15 +00:00
/// The grid line at which the item should start.
/// Lines are 1-indexed.
/// Negative indexes count backwards from the end of the grid.
/// Zero is not a valid index.
2023-08-28 17:21:08 +00:00
pub ( crate ) start : Option < NonZeroI16 > ,
2023-10-21 17:38:15 +00:00
/// How many grid tracks the item should span.
/// Defaults to 1.
2023-08-28 17:21:08 +00:00
pub ( crate ) span : Option < NonZeroU16 > ,
2023-10-21 17:38:15 +00:00
/// The grid line at which the item should end.
/// Lines are 1-indexed.
/// Negative indexes count backwards from the end of the grid.
/// Zero is not a valid index.
2023-08-28 17:21:08 +00:00
pub ( crate ) end : Option < NonZeroI16 > ,
2023-04-17 16:21:38 +00:00
}
impl GridPlacement {
2023-08-22 12:22:47 +00:00
pub const DEFAULT : Self = Self {
2023-04-17 16:21:38 +00:00
start : None ,
2023-11-21 02:06:24 +00:00
// SAFETY: This is trivially safe as 1 is non-zero.
2023-08-28 17:21:08 +00:00
span : Some ( unsafe { NonZeroU16 ::new_unchecked ( 1 ) } ) ,
2023-04-17 16:21:38 +00:00
end : None ,
} ;
/// Place the grid item automatically (letting the `span` default to `1`).
pub fn auto ( ) -> Self {
2023-08-28 17:21:08 +00:00
Self ::DEFAULT
2023-04-17 16:21:38 +00:00
}
/// Place the grid item automatically, specifying how many tracks it should `span`.
2023-08-28 17:21:08 +00:00
///
/// # Panics
///
2023-10-21 17:38:15 +00:00
/// Panics if `span` is `0`.
2023-04-17 16:21:38 +00:00
pub fn span ( span : u16 ) -> Self {
Self {
start : None ,
end : None ,
2023-08-28 17:21:08 +00:00
span : try_into_grid_span ( span ) . expect ( " Invalid span value of 0. " ) ,
2023-04-17 16:21:38 +00:00
}
}
/// Place the grid item specifying the `start` grid line (letting the `span` default to `1`).
2023-08-28 17:21:08 +00:00
///
/// # Panics
///
2023-10-21 17:38:15 +00:00
/// Panics if `start` is `0`.
2023-04-17 16:21:38 +00:00
pub fn start ( start : i16 ) -> Self {
Self {
2023-08-28 17:21:08 +00:00
start : try_into_grid_index ( start ) . expect ( " Invalid start value of 0. " ) ,
.. Self ::DEFAULT
2023-04-17 16:21:38 +00:00
}
}
/// Place the grid item specifying the `end` grid line (letting the `span` default to `1`).
2023-08-28 17:21:08 +00:00
///
/// # Panics
///
2023-10-21 17:38:15 +00:00
/// Panics if `end` is `0`.
2023-04-17 16:21:38 +00:00
pub fn end ( end : i16 ) -> Self {
Self {
2023-08-28 17:21:08 +00:00
end : try_into_grid_index ( end ) . expect ( " Invalid end value of 0. " ) ,
.. Self ::DEFAULT
2023-04-17 16:21:38 +00:00
}
}
/// Place the grid item specifying the `start` grid line and how many tracks it should `span`.
2023-08-28 17:21:08 +00:00
///
/// # Panics
///
2023-10-21 17:38:15 +00:00
/// Panics if `start` or `span` is `0`.
2023-04-17 16:21:38 +00:00
pub fn start_span ( start : i16 , span : u16 ) -> Self {
Self {
2023-08-28 17:21:08 +00:00
start : try_into_grid_index ( start ) . expect ( " Invalid start value of 0. " ) ,
2023-04-17 16:21:38 +00:00
end : None ,
2023-08-28 17:21:08 +00:00
span : try_into_grid_span ( span ) . expect ( " Invalid span value of 0. " ) ,
2023-04-17 16:21:38 +00:00
}
}
/// Place the grid item specifying `start` and `end` grid lines (`span` will be inferred)
2023-08-28 17:21:08 +00:00
///
/// # Panics
///
2023-10-21 17:38:15 +00:00
/// Panics if `start` or `end` is `0`.
2023-04-17 16:21:38 +00:00
pub fn start_end ( start : i16 , end : i16 ) -> Self {
Self {
2023-08-28 17:21:08 +00:00
start : try_into_grid_index ( start ) . expect ( " Invalid start value of 0. " ) ,
end : try_into_grid_index ( end ) . expect ( " Invalid end value of 0. " ) ,
2023-04-17 16:21:38 +00:00
span : None ,
}
}
/// Place the grid item specifying the `end` grid line and how many tracks it should `span`.
2023-08-28 17:21:08 +00:00
///
/// # Panics
///
2023-10-21 17:38:15 +00:00
/// Panics if `end` or `span` is `0`.
2023-04-17 16:21:38 +00:00
pub fn end_span ( end : i16 , span : u16 ) -> Self {
Self {
start : None ,
2023-08-28 17:21:08 +00:00
end : try_into_grid_index ( end ) . expect ( " Invalid end value of 0. " ) ,
span : try_into_grid_span ( span ) . expect ( " Invalid span value of 0. " ) ,
2023-04-17 16:21:38 +00:00
}
}
/// Mutate the item, setting the `start` grid line
2023-08-28 17:21:08 +00:00
///
/// # Panics
///
2023-10-21 17:38:15 +00:00
/// Panics if `start` is `0`.
2023-04-17 16:21:38 +00:00
pub fn set_start ( mut self , start : i16 ) -> Self {
2023-08-28 17:21:08 +00:00
self . start = try_into_grid_index ( start ) . expect ( " Invalid start value of 0. " ) ;
2023-04-17 16:21:38 +00:00
self
}
/// Mutate the item, setting the `end` grid line
2023-08-28 17:21:08 +00:00
///
/// # Panics
///
2023-10-21 17:38:15 +00:00
/// Panics if `end` is `0`.
2023-04-17 16:21:38 +00:00
pub fn set_end ( mut self , end : i16 ) -> Self {
2023-08-28 17:21:08 +00:00
self . end = try_into_grid_index ( end ) . expect ( " Invalid end value of 0. " ) ;
2023-04-17 16:21:38 +00:00
self
}
/// Mutate the item, setting the number of tracks the item should `span`
2023-08-28 17:21:08 +00:00
///
/// # Panics
///
2023-10-21 17:38:15 +00:00
/// Panics if `span` is `0`.
2023-04-17 16:21:38 +00:00
pub fn set_span ( mut self , span : u16 ) -> Self {
2023-08-28 17:21:08 +00:00
self . span = try_into_grid_span ( span ) . expect ( " Invalid span value of 0. " ) ;
2023-04-17 16:21:38 +00:00
self
}
2023-08-28 17:21:08 +00:00
/// Returns the grid line at which the item should start, or `None` if not set.
pub fn get_start ( self ) -> Option < i16 > {
self . start . map ( NonZeroI16 ::get )
}
/// Returns the grid line at which the item should end, or `None` if not set.
pub fn get_end ( self ) -> Option < i16 > {
self . end . map ( NonZeroI16 ::get )
}
/// Returns span for this grid item, or `None` if not set.
pub fn get_span ( self ) -> Option < u16 > {
self . span . map ( NonZeroU16 ::get )
}
2023-04-17 16:21:38 +00:00
}
impl Default for GridPlacement {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2023-08-28 17:21:08 +00:00
/// Convert an `i16` to `NonZeroI16`, fails on `0` and returns the `InvalidZeroIndex` error.
fn try_into_grid_index ( index : i16 ) -> Result < Option < NonZeroI16 > , GridPlacementError > {
Ok ( Some (
NonZeroI16 ::new ( index ) . ok_or ( GridPlacementError ::InvalidZeroIndex ) ? ,
) )
}
/// Convert a `u16` to `NonZeroU16`, fails on `0` and returns the `InvalidZeroSpan` error.
fn try_into_grid_span ( span : u16 ) -> Result < Option < NonZeroU16 > , GridPlacementError > {
Ok ( Some (
NonZeroU16 ::new ( span ) . ok_or ( GridPlacementError ::InvalidZeroSpan ) ? ,
) )
}
2023-09-29 12:26:41 +00:00
/// Errors that occur when setting constraints for a `GridPlacement`
2023-08-28 17:21:08 +00:00
#[ derive(Debug, Eq, PartialEq, Clone, Copy, Error) ]
pub enum GridPlacementError {
#[ error( " Zero is not a valid grid position " ) ]
InvalidZeroIndex ,
#[ error( " Spans cannot be zero length " ) ]
InvalidZeroSpan ,
}
2022-09-25 00:39:17 +00:00
/// The background color of the node
///
/// This serves as the "fill" color.
/// When combined with [`UiImage`], tints the provided texture.
2024-01-03 17:52:16 +00:00
#[ derive(Component, Copy, Clone, Debug, Reflect) ]
#[ reflect(Component, Default) ]
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2022-09-25 00:39:17 +00:00
pub struct BackgroundColor ( pub Color ) ;
2021-12-14 03:58:23 +00:00
2023-01-04 19:58:09 +00:00
impl BackgroundColor {
pub const DEFAULT : Self = Self ( Color ::WHITE ) ;
}
impl Default for BackgroundColor {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2022-09-25 00:39:17 +00:00
impl From < Color > for BackgroundColor {
2021-12-14 03:58:23 +00:00
fn from ( color : Color ) -> Self {
Self ( color )
}
}
2023-06-19 21:52:02 +00:00
/// The atlas sprite to be used in a UI Texture Atlas Node
bevy_reflect: `FromReflect` Ergonomics Implementation (#6056)
# Objective
**This implementation is based on
https://github.com/bevyengine/rfcs/pull/59.**
---
Resolves #4597
Full details and motivation can be found in the RFC, but here's a brief
summary.
`FromReflect` is a very powerful and important trait within the
reflection API. It allows Dynamic types (e.g., `DynamicList`, etc.) to
be formed into Real ones (e.g., `Vec<i32>`, etc.).
This mainly comes into play concerning deserialization, where the
reflection deserializers both return a `Box<dyn Reflect>` that almost
always contain one of these Dynamic representations of a Real type. To
convert this to our Real type, we need to use `FromReflect`.
It also sneaks up in other ways. For example, it's a required bound for
`T` in `Vec<T>` so that `Vec<T>` as a whole can be made `FromReflect`.
It's also required by all fields of an enum as it's used as part of the
`Reflect::apply` implementation.
So in other words, much like `GetTypeRegistration` and `Typed`, it is
very much a core reflection trait.
The problem is that it is not currently treated like a core trait and is
not automatically derived alongside `Reflect`. This makes using it a bit
cumbersome and easy to forget.
## Solution
Automatically derive `FromReflect` when deriving `Reflect`.
Users can then choose to opt-out if needed using the
`#[reflect(from_reflect = false)]` attribute.
```rust
#[derive(Reflect)]
struct Foo;
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Bar;
fn test<T: FromReflect>(value: T) {}
test(Foo); // <-- OK
test(Bar); // <-- Panic! Bar does not implement trait `FromReflect`
```
#### `ReflectFromReflect`
This PR also automatically adds the `ReflectFromReflect` (introduced in
#6245) registration to the derived `GetTypeRegistration` impl— if the
type hasn't opted out of `FromReflect` of course.
<details>
<summary><h4>Improved Deserialization</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
And since we can do all the above, we might as well improve
deserialization. We can now choose to deserialize into a Dynamic type or
automatically convert it using `FromReflect` under the hood.
`[Un]TypedReflectDeserializer::new` will now perform the conversion and
return the `Box`'d Real type.
`[Un]TypedReflectDeserializer::new_dynamic` will work like what we have
now and simply return the `Box`'d Dynamic type.
```rust
// Returns the Real type
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: SomeStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
// Returns the Dynamic type
let reflect_deserializer = UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: DynamicStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
```
</details>
---
## Changelog
* `FromReflect` is now automatically derived within the `Reflect` derive
macro
* This includes auto-registering `ReflectFromReflect` in the derived
`GetTypeRegistration` impl
* ~~Renamed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic`, respectively~~ **Descoped**
* ~~Changed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to automatically convert the
deserialized output using `FromReflect`~~ **Descoped**
## Migration Guide
* `FromReflect` is now automatically derived within the `Reflect` derive
macro. Items with both derives will need to remove the `FromReflect`
one.
```rust
// OLD
#[derive(Reflect, FromReflect)]
struct Foo;
// NEW
#[derive(Reflect)]
struct Foo;
```
If using a manual implementation of `FromReflect` and the `Reflect`
derive, users will need to opt-out of the automatic implementation.
```rust
// OLD
#[derive(Reflect)]
struct Foo;
impl FromReflect for Foo {/* ... */}
// NEW
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Foo;
impl FromReflect for Foo {/* ... */}
```
<details>
<summary><h4>Removed Migrations</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
* The reflect deserializers now perform a `FromReflect` conversion
internally. The expected output of `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` is no longer a Dynamic (e.g.,
`DynamicList`), but its Real counterpart (e.g., `Vec<i32>`).
```rust
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
// OLD
let output: DynamicStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
// NEW
let output: SomeStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
```
Alternatively, if this behavior isn't desired, use the
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic` methods instead:
```rust
// OLD
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
// NEW
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
```
</details>
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-06-29 01:31:34 +00:00
#[ derive(Component, Clone, Debug, Reflect, Default) ]
2023-06-19 21:52:02 +00:00
#[ reflect(Component, Default) ]
pub struct UiTextureAtlasImage {
/// Texture index in the TextureAtlas
pub index : usize ,
/// Whether to flip the sprite in the X axis
pub flip_x : bool ,
/// Whether to flip the sprite in the Y axis
pub flip_y : bool ,
}
2023-06-14 22:43:38 +00:00
/// The border color of the UI node.
2024-01-03 17:52:16 +00:00
#[ derive(Component, Copy, Clone, Debug, Reflect) ]
#[ reflect(Component, Default) ]
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
2023-06-14 22:43:38 +00:00
pub struct BorderColor ( pub Color ) ;
impl From < Color > for BorderColor {
fn from ( color : Color ) -> Self {
Self ( color )
}
}
impl BorderColor {
pub const DEFAULT : Self = BorderColor ( Color ::WHITE ) ;
}
impl Default for BorderColor {
fn default ( ) -> Self {
Self ::DEFAULT
}
}
2024-01-03 17:52:16 +00:00
#[ derive(Component, Copy, Clone, Default, Debug, Reflect) ]
#[ reflect(Component, Default) ]
#[ cfg_attr(
feature = " serialize " ,
derive ( serde ::Serialize , serde ::Deserialize ) ,
reflect ( Serialize , Deserialize )
) ]
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
/// The [`Outline`] component adds an outline outside the edge of a UI node.
2023-10-21 17:38:15 +00:00
/// Outlines do not take up space in the layout.
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
///
/// To add an [`Outline`] to a ui node you can spawn a `(NodeBundle, Outline)` tuple bundle:
/// ```
/// # use bevy_ecs::prelude::*;
/// # use bevy_ui::prelude::*;
/// # use bevy_render::prelude::Color;
/// fn setup_ui(mut commands: Commands) {
/// commands.spawn((
/// NodeBundle {
/// style: Style {
/// width: Val::Px(100.),
/// height: Val::Px(100.),
/// ..Default::default()
/// },
/// background_color: Color::BLUE.into(),
/// ..Default::default()
/// },
/// Outline::new(Val::Px(10.), Val::ZERO, Color::RED)
/// ));
/// }
/// ```
///
/// [`Outline`] components can also be added later to existing UI nodes:
/// ```
/// # use bevy_ecs::prelude::*;
/// # use bevy_ui::prelude::*;
/// # use bevy_render::prelude::Color;
/// fn outline_hovered_button_system(
/// mut commands: Commands,
/// mut node_query: Query<(Entity, &Interaction, Option<&mut Outline>), Changed<Interaction>>,
/// ) {
/// for (entity, interaction, mut maybe_outline) in node_query.iter_mut() {
/// let outline_color =
/// if matches!(*interaction, Interaction::Hovered) {
2023-10-21 17:38:15 +00:00
/// Color::WHITE
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
/// } else {
/// Color::NONE
/// };
/// if let Some(mut outline) = maybe_outline {
/// outline.color = outline_color;
/// } else {
/// commands.entity(entity).insert(Outline::new(Val::Px(10.), Val::ZERO, outline_color));
/// }
/// }
/// }
/// ```
/// Inserting and removing an [`Outline`] component repeatedly will result in table moves, so it is generally preferable to
/// set `Outline::color` to `Color::NONE` to hide an outline.
pub struct Outline {
/// The width of the outline.
///
2023-10-21 17:38:15 +00:00
/// Percentage `Val` values are resolved based on the width of the outlined [`Node`].
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
pub width : Val ,
2023-10-21 17:38:15 +00:00
/// The amount of space between a node's outline the edge of the node.
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
///
2023-10-21 17:38:15 +00:00
/// Percentage `Val` values are resolved based on the width of the outlined [`Node`].
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
pub offset : Val ,
2023-10-21 17:38:15 +00:00
/// The color of the outline.
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
///
/// If you are frequently toggling outlines for a UI node on and off it is recommended to set `Color::None` to hide the outline.
2023-10-21 17:38:15 +00:00
/// This avoids the table moves that would occur from the repeated insertion and removal of the `Outline` component.
UI node outlines (#9931)
# Objective
Add support for drawing outlines outside the borders of UI nodes.
## Solution
Add a new `Outline` component with `width`, `offset` and `color` fields.
Added `outline_width` and `outline_offset` fields to `Node`. This is set
after layout recomputation by the `resolve_outlines_system`.
Properties of outlines:
* Unlike borders, outlines have to be the same width on each edge.
* Outlines do not occupy any space in the layout.
* The `Outline` component won't be added to any of the UI node bundles,
it needs to be inserted separately.
* Outlines are drawn outside the node's border, so they are clipped
using the clipping rect of their entity's parent UI node (if it exists).
* `Val::Percent` outline widths are resolved based on the width of the
outlined UI node.
* The offset of the `Outline` adds space between an outline and the edge
of its node.
I was leaning towards adding an `outline` field to `Style` but a
separate component seems more efficient for queries and change
detection. The `Outline` component isn't added to bundles for the same
reason.
---
## Examples
* This image is from the `borders` example from the Bevy UI examples but
modified to include outlines. The UI nodes are the dark red rectangles,
the bright red rectangles are borders and the white lines offset from
each node are the outlines. The yellow rectangles are separate nodes
contained with the dark red nodes:
<img width="406" alt="outlines"
src="https://github.com/bevyengine/bevy/assets/27962798/4e6f315a-019f-42a4-94ee-cca8e684d64a">
* This is from the same example but using a branch that implements
border-radius. Here the the outlines are in orange and there is no
offset applied. I broke the borders implementation somehow during the
merge, which is why some of the borders from the first screenshot are
missing :sweat_smile:. The outlines work nicely though (as long as you
can forgive the lack of anti-aliasing):
---
## Notes
As I explained above, I don't think the `Outline` component should be
added to UI node bundles. We can have helper functions though, perhaps
something as simple as:
```rust
impl NodeBundle {
pub fn with_outline(self, outline: Outline) -> (Self, Outline) {
(self, outline)
}
}
```
I didn't include anything like this as I wanted to keep the PR's scope
as narrow as possible. Maybe `with_outline` should be in a trait that we
implement for each UI node bundle.
---
## Changelog
Added support for outlines to Bevy UI.
* The `Outline` component adds an outline to a UI node.
* The `outline_width` field added to `Node` holds the resolved width of
the outline, which is set by the `resolve_outlines_system` after layout
recomputation.
* Outlines are drawn by the system `extract_uinode_outlines`.
2023-10-05 12:10:32 +00:00
pub color : Color ,
}
impl Outline {
/// Create a new outline
pub const fn new ( width : Val , offset : Val , color : Color ) -> Self {
Self {
width ,
offset ,
color ,
}
}
}
2022-09-25 00:39:17 +00:00
/// The 2D texture displayed for this UI node
Bevy Asset V2 (#8624)
# Bevy Asset V2 Proposal
## Why Does Bevy Need A New Asset System?
Asset pipelines are a central part of the gamedev process. Bevy's
current asset system is missing a number of features that make it
non-viable for many classes of gamedev. After plenty of discussions and
[a long community feedback
period](https://github.com/bevyengine/bevy/discussions/3972), we've
identified a number missing features:
* **Asset Preprocessing**: it should be possible to "preprocess" /
"compile" / "crunch" assets at "development time" rather than when the
game starts up. This enables offloading expensive work from deployed
apps, faster asset loading, less runtime memory usage, etc.
* **Per-Asset Loader Settings**: Individual assets cannot define their
own loaders that override the defaults. Additionally, they cannot
provide per-asset settings to their loaders. This is a huge limitation,
as many asset types don't provide all information necessary for Bevy
_inside_ the asset. For example, a raw PNG image says nothing about how
it should be sampled (ex: linear vs nearest).
* **Asset `.meta` files**: assets should have configuration files stored
adjacent to the asset in question, which allows the user to configure
asset-type-specific settings. These settings should be accessible during
the pre-processing phase. Modifying a `.meta` file should trigger a
re-processing / re-load of the asset. It should be possible to configure
asset loaders from the meta file.
* **Processed Asset Hot Reloading**: Changes to processed assets (or
their dependencies) should result in re-processing them and re-loading
the results in live Bevy Apps.
* **Asset Dependency Tracking**: The current bevy_asset has no good way
to wait for asset dependencies to load. It punts this as an exercise for
consumers of the loader apis, which is unreasonable and error prone.
There should be easy, ergonomic ways to wait for assets to load and
block some logic on an asset's entire dependency tree loading.
* **Runtime Asset Loading**: it should be (optionally) possible to load
arbitrary assets dynamically at runtime. This necessitates being able to
deploy and run the asset server alongside Bevy Apps on _all platforms_.
For example, we should be able to invoke the shader compiler at runtime,
stream scenes from sources like the internet, etc. To keep deployed
binaries (and startup times) small, the runtime asset server
configuration should be configurable with different settings compared to
the "pre processor asset server".
* **Multiple Backends**: It should be possible to load assets from
arbitrary sources (filesystems, the internet, remote asset serves, etc).
* **Asset Packing**: It should be possible to deploy assets in
compressed "packs", which makes it easier and more efficient to
distribute assets with Bevy Apps.
* **Asset Handoff**: It should be possible to hold a "live" asset
handle, which correlates to runtime data, without actually holding the
asset in memory. Ex: it must be possible to hold a reference to a GPU
mesh generated from a "mesh asset" without keeping the mesh data in CPU
memory
* **Per-Platform Processed Assets**: Different platforms and app
distributions have different capabilities and requirements. Some
platforms need lower asset resolutions or different asset formats to
operate within the hardware constraints of the platform. It should be
possible to define per-platform asset processing profiles. And it should
be possible to deploy only the assets required for a given platform.
These features have architectural implications that are significant
enough to require a full rewrite. The current Bevy Asset implementation
got us this far, but it can take us no farther. This PR defines a brand
new asset system that implements most of these features, while laying
the foundations for the remaining features to be built.
## Bevy Asset V2
Here is a quick overview of the features introduced in this PR.
* **Asset Preprocessing**: Preprocess assets at development time into
more efficient (and configurable) representations
* **Dependency Aware**: Dependencies required to process an asset are
tracked. If an asset's processed dependency changes, it will be
reprocessed
* **Hot Reprocessing/Reloading**: detect changes to asset source files,
reprocess them if they have changed, and then hot-reload them in Bevy
Apps.
* **Only Process Changes**: Assets are only re-processed when their
source file (or meta file) has changed. This uses hashing and timestamps
to avoid processing assets that haven't changed.
* **Transactional and Reliable**: Uses write-ahead logging (a technique
commonly used by databases) to recover from crashes / forced-exits.
Whenever possible it avoids full-reprocessing / only uncompleted
transactions will be reprocessed. When the processor is running in
parallel with a Bevy App, processor asset writes block Bevy App asset
reads. Reading metadata + asset bytes is guaranteed to be transactional
/ correctly paired.
* **Portable / Run anywhere / Database-free**: The processor does not
rely on an in-memory database (although it uses some database techniques
for reliability). This is important because pretty much all in-memory
databases have unsupported platforms or build complications.
* **Configure Processor Defaults Per File Type**: You can say "use this
processor for all files of this type".
* **Custom Processors**: The `Processor` trait is flexible and
unopinionated. It can be implemented by downstream plugins.
* **LoadAndSave Processors**: Most asset processing scenarios can be
expressed as "run AssetLoader A, save the results using AssetSaver X,
and then load the result using AssetLoader B". For example, load this
png image using `PngImageLoader`, which produces an `Image` asset and
then save it using `CompressedImageSaver` (which also produces an
`Image` asset, but in a compressed format), which takes an `Image` asset
as input. This means if you have an `AssetLoader` for an asset, you are
already half way there! It also means that you can share AssetSavers
across multiple loaders. Because `CompressedImageSaver` accepts Bevy's
generic Image asset as input, it means you can also use it with some
future `JpegImageLoader`.
* **Loader and Saver Settings**: Asset Loaders and Savers can now define
their own settings types, which are passed in as input when an asset is
loaded / saved. Each asset can define its own settings.
* **Asset `.meta` files**: configure asset loaders, their settings,
enable/disable processing, and configure processor settings
* **Runtime Asset Dependency Tracking** Runtime asset dependencies (ex:
if an asset contains a `Handle<Image>`) are tracked by the asset server.
An event is emitted when an asset and all of its dependencies have been
loaded
* **Unprocessed Asset Loading**: Assets do not require preprocessing.
They can be loaded directly. A processed asset is just a "normal" asset
with some extra metadata. Asset Loaders don't need to know or care about
whether or not an asset was processed.
* **Async Asset IO**: Asset readers/writers use async non-blocking
interfaces. Note that because Rust doesn't yet support async traits,
there is a bit of manual Boxing / Future boilerplate. This will
hopefully be removed in the near future when Rust gets async traits.
* **Pluggable Asset Readers and Writers**: Arbitrary asset source
readers/writers are supported, both by the processor and the asset
server.
* **Better Asset Handles**
* **Single Arc Tree**: Asset Handles now use a single arc tree that
represents the lifetime of the asset. This makes their implementation
simpler, more efficient, and allows us to cheaply attach metadata to
handles. Ex: the AssetPath of a handle is now directly accessible on the
handle itself!
* **Const Typed Handles**: typed handles can be constructed in a const
context. No more weird "const untyped converted to typed at runtime"
patterns!
* **Handles and Ids are Smaller / Faster To Hash / Compare**: Typed
`Handle<T>` is now much smaller in memory and `AssetId<T>` is even
smaller.
* **Weak Handle Usage Reduction**: In general Handles are now considered
to be "strong". Bevy features that previously used "weak `Handle<T>`"
have been ported to `AssetId<T>`, which makes it statically clear that
the features do not hold strong handles (while retaining strong type
information). Currently Handle::Weak still exists, but it is very
possible that we can remove that entirely.
* **Efficient / Dense Asset Ids**: Assets now have efficient dense
runtime asset ids, which means we can avoid expensive hash lookups.
Assets are stored in Vecs instead of HashMaps. There are now typed and
untyped ids, which means we no longer need to store dynamic type
information in the ID for typed handles. "AssetPathId" (which was a
nightmare from a performance and correctness standpoint) has been
entirely removed in favor of dense ids (which are retrieved for a path
on load)
* **Direct Asset Loading, with Dependency Tracking**: Assets that are
defined at runtime can still have their dependencies tracked by the
Asset Server (ex: if you create a material at runtime, you can still
wait for its textures to load). This is accomplished via the (currently
optional) "asset dependency visitor" trait. This system can also be used
to define a set of assets to load, then wait for those assets to load.
* **Async folder loading**: Folder loading also uses this system and
immediately returns a handle to the LoadedFolder asset, which means
folder loading no longer blocks on directory traversals.
* **Improved Loader Interface**: Loaders now have a specific "top level
asset type", which makes returning the top-level asset simpler and
statically typed.
* **Basic Image Settings and Processing**: Image assets can now be
processed into the gpu-friendly Basic Universal format. The ImageLoader
now has a setting to define what format the image should be loaded as.
Note that this is just a minimal MVP ... plenty of additional work to do
here. To demo this, enable the `basis-universal` feature and turn on
asset processing.
* **Simpler Audio Play / AudioSink API**: Asset handle providers are
cloneable, which means the Audio resource can mint its own handles. This
means you can now do `let sink_handle = audio.play(music)` instead of
`let sink_handle = audio_sinks.get_handle(audio.play(music))`. Note that
this might still be replaced by
https://github.com/bevyengine/bevy/pull/8424.
**Removed Handle Casting From Engine Features**: Ex: FontAtlases no
longer use casting between handle types
## Using The New Asset System
### Normal Unprocessed Asset Loading
By default the `AssetPlugin` does not use processing. It behaves pretty
much the same way as the old system.
If you are defining a custom asset, first derive `Asset`:
```rust
#[derive(Asset)]
struct Thing {
value: String,
}
```
Initialize the asset:
```rust
app.init_asset:<Thing>()
```
Implement a new `AssetLoader` for it:
```rust
#[derive(Default)]
struct ThingLoader;
#[derive(Serialize, Deserialize, Default)]
pub struct ThingSettings {
some_setting: bool,
}
impl AssetLoader for ThingLoader {
type Asset = Thing;
type Settings = ThingSettings;
fn load<'a>(
&'a self,
reader: &'a mut Reader,
settings: &'a ThingSettings,
load_context: &'a mut LoadContext,
) -> BoxedFuture<'a, Result<Thing, anyhow::Error>> {
Box::pin(async move {
let mut bytes = Vec::new();
reader.read_to_end(&mut bytes).await?;
// convert bytes to value somehow
Ok(Thing {
value
})
})
}
fn extensions(&self) -> &[&str] {
&["thing"]
}
}
```
Note that this interface will get much cleaner once Rust gets support
for async traits. `Reader` is an async futures_io::AsyncRead. You can
stream bytes as they come in or read them all into a `Vec<u8>`,
depending on the context. You can use `let handle =
load_context.load(path)` to kick off a dependency load, retrieve a
handle, and register the dependency for the asset.
Then just register the loader in your Bevy app:
```rust
app.init_asset_loader::<ThingLoader>()
```
Now just add your `Thing` asset files into the `assets` folder and load
them like this:
```rust
fn system(asset_server: Res<AssetServer>) {
let handle = Handle<Thing> = asset_server.load("cool.thing");
}
```
You can check load states directly via the asset server:
```rust
if asset_server.load_state(&handle) == LoadState::Loaded { }
```
You can also listen for events:
```rust
fn system(mut events: EventReader<AssetEvent<Thing>>, handle: Res<SomeThingHandle>) {
for event in events.iter() {
if event.is_loaded_with_dependencies(&handle) {
}
}
}
```
Note the new `AssetEvent::LoadedWithDependencies`, which only fires when
the asset is loaded _and_ all dependencies (and their dependencies) have
loaded.
Unlike the old asset system, for a given asset path all `Handle<T>`
values point to the same underlying Arc. This means Handles can cheaply
hold more asset information, such as the AssetPath:
```rust
// prints the AssetPath of the handle
info!("{:?}", handle.path())
```
### Processed Assets
Asset processing can be enabled via the `AssetPlugin`. When developing
Bevy Apps with processed assets, do this:
```rust
app.add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))
```
This runs the `AssetProcessor` in the background with hot-reloading. It
reads assets from the `assets` folder, processes them, and writes them
to the `.imported_assets` folder. Asset loads in the Bevy App will wait
for a processed version of the asset to become available. If an asset in
the `assets` folder changes, it will be reprocessed and hot-reloaded in
the Bevy App.
When deploying processed Bevy apps, do this:
```rust
app.add_plugins(DefaultPlugins.set(AssetPlugin::processed()))
```
This does not run the `AssetProcessor` in the background. It behaves
like `AssetPlugin::unprocessed()`, but reads assets from
`.imported_assets`.
When the `AssetProcessor` is running, it will populate sibling `.meta`
files for assets in the `assets` folder. Meta files for assets that do
not have a processor configured look like this:
```rust
(
meta_format_version: "1.0",
asset: Load(
loader: "bevy_render::texture::image_loader::ImageLoader",
settings: (
format: FromExtension,
),
),
)
```
This is metadata for an image asset. For example, if you have
`assets/my_sprite.png`, this could be the metadata stored at
`assets/my_sprite.png.meta`. Meta files are totally optional. If no
metadata exists, the default settings will be used.
In short, this file says "load this asset with the ImageLoader and use
the file extension to determine the image type". This type of meta file
is supported in all AssetPlugin modes. If in `Unprocessed` mode, the
asset (with the meta settings) will be loaded directly. If in
`ProcessedDev` mode, the asset file will be copied directly to the
`.imported_assets` folder. The meta will also be copied directly to the
`.imported_assets` folder, but with one addition:
```rust
(
meta_format_version: "1.0",
processed_info: Some((
hash: 12415480888597742505,
full_hash: 14344495437905856884,
process_dependencies: [],
)),
asset: Load(
loader: "bevy_render::texture::image_loader::ImageLoader",
settings: (
format: FromExtension,
),
),
)
```
`processed_info` contains `hash` (a direct hash of the asset and meta
bytes), `full_hash` (a hash of `hash` and the hashes of all
`process_dependencies`), and `process_dependencies` (the `path` and
`full_hash` of every process_dependency). A "process dependency" is an
asset dependency that is _directly_ used when processing the asset.
Images do not have process dependencies, so this is empty.
When the processor is enabled, you can use the `Process` metadata
config:
```rust
(
meta_format_version: "1.0",
asset: Process(
processor: "bevy_asset::processor::process::LoadAndSave<bevy_render::texture::image_loader::ImageLoader, bevy_render::texture::compressed_image_saver::CompressedImageSaver>",
settings: (
loader_settings: (
format: FromExtension,
),
saver_settings: (
generate_mipmaps: true,
),
),
),
)
```
This configures the asset to use the `LoadAndSave` processor, which runs
an AssetLoader and feeds the result into an AssetSaver (which saves the
given Asset and defines a loader to load it with). (for terseness
LoadAndSave will likely get a shorter/friendlier type name when [Stable
Type Paths](#7184) lands). `LoadAndSave` is likely to be the most common
processor type, but arbitrary processors are supported.
`CompressedImageSaver` saves an `Image` in the Basis Universal format
and configures the ImageLoader to load it as basis universal. The
`AssetProcessor` will read this meta, run it through the LoadAndSave
processor, and write the basis-universal version of the image to
`.imported_assets`. The final metadata will look like this:
```rust
(
meta_format_version: "1.0",
processed_info: Some((
hash: 905599590923828066,
full_hash: 9948823010183819117,
process_dependencies: [],
)),
asset: Load(
loader: "bevy_render::texture::image_loader::ImageLoader",
settings: (
format: Format(Basis),
),
),
)
```
To try basis-universal processing out in Bevy examples, (for example
`sprite.rs`), change `add_plugins(DefaultPlugins)` to
`add_plugins(DefaultPlugins.set(AssetPlugin::processed_dev()))` and run
with the `basis-universal` feature enabled: `cargo run
--features=basis-universal --example sprite`.
To create a custom processor, there are two main paths:
1. Use the `LoadAndSave` processor with an existing `AssetLoader`.
Implement the `AssetSaver` trait, register the processor using
`asset_processor.register_processor::<LoadAndSave<ImageLoader,
CompressedImageSaver>>(image_saver.into())`.
2. Implement the `Process` trait directly and register it using:
`asset_processor.register_processor(thing_processor)`.
You can configure default processors for file extensions like this:
```rust
asset_processor.set_default_processor::<ThingProcessor>("thing")
```
There is one more metadata type to be aware of:
```rust
(
meta_format_version: "1.0",
asset: Ignore,
)
```
This will ignore the asset during processing / prevent it from being
written to `.imported_assets`.
The AssetProcessor stores a transaction log at `.imported_assets/log`
and uses it to gracefully recover from unexpected stops. This means you
can force-quit the processor (and Bevy Apps running the processor in
parallel) at arbitrary times!
`.imported_assets` is "local state". It should _not_ be checked into
source control. It should also be considered "read only". In practice,
you _can_ modify processed assets and processed metadata if you really
need to test something. But those modifications will not be represented
in the hashes of the assets, so the processed state will be "out of
sync" with the source assets. The processor _will not_ fix this for you.
Either revert the change after you have tested it, or delete the
processed files so they can be re-populated.
## Open Questions
There are a number of open questions to be discussed. We should decide
if they need to be addressed in this PR and if so, how we will address
them:
### Implied Dependencies vs Dependency Enumeration
There are currently two ways to populate asset dependencies:
* **Implied via AssetLoaders**: if an AssetLoader loads an asset (and
retrieves a handle), a dependency is added to the list.
* **Explicit via the optional Asset::visit_dependencies**: if
`server.load_asset(my_asset)` is called, it will call
`my_asset.visit_dependencies`, which will grab dependencies that have
been manually defined for the asset via the Asset trait impl (which can
be derived).
This means that defining explicit dependencies is optional for "loaded
assets". And the list of dependencies is always accurate because loaders
can only produce Handles if they register dependencies. If an asset was
loaded with an AssetLoader, it only uses the implied dependencies. If an
asset was created at runtime and added with
`asset_server.load_asset(MyAsset)`, it will use
`Asset::visit_dependencies`.
However this can create a behavior mismatch between loaded assets and
equivalent "created at runtime" assets if `Assets::visit_dependencies`
doesn't exactly match the dependencies produced by the AssetLoader. This
behavior mismatch can be resolved by completely removing "implied loader
dependencies" and requiring `Asset::visit_dependencies` to supply
dependency data. But this creates two problems:
* It makes defining loaded assets harder and more error prone: Devs must
remember to manually annotate asset dependencies with `#[dependency]`
when deriving `Asset`. For more complicated assets (such as scenes), the
derive likely wouldn't be sufficient and a manual `visit_dependencies`
impl would be required.
* Removes the ability to immediately kick off dependency loads: When
AssetLoaders retrieve a Handle, they also immediately kick off an asset
load for the handle, which means it can start loading in parallel
_before_ the asset finishes loading. For large assets, this could be
significant. (although this could be mitigated for processed assets if
we store dependencies in the processed meta file and load them ahead of
time)
### Eager ProcessorDev Asset Loading
I made a controversial call in the interest of fast startup times ("time
to first pixel") for the "processor dev mode configuration". When
initializing the AssetProcessor, current processed versions of unchanged
assets are yielded immediately, even if their dependencies haven't been
checked yet for reprocessing. This means that
non-current-state-of-filesystem-but-previously-valid assets might be
returned to the App first, then hot-reloaded if/when their dependencies
change and the asset is reprocessed.
Is this behavior desirable? There is largely one alternative: do not
yield an asset from the processor to the app until all of its
dependencies have been checked for changes. In some common cases (load
dependency has not changed since last run) this will increase startup
time. The main question is "by how much" and is that slower startup time
worth it in the interest of only yielding assets that are true to the
current state of the filesystem. Should this be configurable? I'm
starting to think we should only yield an asset after its (historical)
dependencies have been checked for changes + processed as necessary, but
I'm curious what you all think.
### Paths Are Currently The Only Canonical ID / Do We Want Asset UUIDs?
In this implementation AssetPaths are the only canonical asset
identifier (just like the previous Bevy Asset system and Godot). Moving
assets will result in re-scans (and currently reprocessing, although
reprocessing can easily be avoided with some changes). Asset
renames/moves will break code and assets that rely on specific paths,
unless those paths are fixed up.
Do we want / need "stable asset uuids"? Introducing them is very
possible:
1. Generate a UUID and include it in .meta files
2. Support UUID in AssetPath
3. Generate "asset indices" which are loaded on startup and map UUIDs to
paths.
4 (maybe). Consider only supporting UUIDs for processed assets so we can
generate quick-to-load indices instead of scanning meta files.
The main "pro" is that assets referencing UUIDs don't need to be
migrated when a path changes. The main "con" is that UUIDs cannot be
"lazily resolved" like paths. They need a full view of all assets to
answer the question "does this UUID exist". Which means UUIDs require
the AssetProcessor to fully finish startup scans before saying an asset
doesnt exist. And they essentially require asset pre-processing to use
in apps, because scanning all asset metadata files at runtime to resolve
a UUID is not viable for medium-to-large apps. It really requires a
pre-generated UUID index, which must be loaded before querying for
assets.
I personally think this should be investigated in a separate PR. Paths
aren't going anywhere ... _everyone_ uses filesystems (and
filesystem-like apis) to manage their asset source files. I consider
them permanent canonical asset information. Additionally, they behave
well for both processed and unprocessed asset modes. Given that Bevy is
supporting both, this feels like the right canonical ID to start with.
UUIDS (and maybe even other indexed-identifier types) can be added later
as necessary.
### Folder / File Naming Conventions
All asset processing config currently lives in the `.imported_assets`
folder. The processor transaction log is in `.imported_assets/log`.
Processed assets are added to `.imported_assets/Default`, which will
make migrating to processed asset profiles (ex: a
`.imported_assets/Mobile` profile) a non-breaking change. It also allows
us to create top-level files like `.imported_assets/log` without it
being interpreted as an asset. Meta files currently have a `.meta`
suffix. Do we like these names and conventions?
### Should the `AssetPlugin::processed_dev` configuration enable
`watch_for_changes` automatically?
Currently it does (which I think makes sense), but it does make it the
only configuration that enables watch_for_changes by default.
### Discuss on_loaded High Level Interface:
This PR includes a very rough "proof of concept" `on_loaded` system
adapter that uses the `LoadedWithDependencies` event in combination with
`asset_server.load_asset` dependency tracking to support this pattern
```rust
fn main() {
App::new()
.init_asset::<MyAssets>()
.add_systems(Update, on_loaded(create_array_texture))
.run();
}
#[derive(Asset, Clone)]
struct MyAssets {
#[dependency]
picture_of_my_cat: Handle<Image>,
#[dependency]
picture_of_my_other_cat: Handle<Image>,
}
impl FromWorld for ArrayTexture {
fn from_world(world: &mut World) -> Self {
picture_of_my_cat: server.load("meow.png"),
picture_of_my_other_cat: server.load("meeeeeeeow.png"),
}
}
fn spawn_cat(In(my_assets): In<MyAssets>, mut commands: Commands) {
commands.spawn(SpriteBundle {
texture: my_assets.picture_of_my_cat.clone(),
..default()
});
commands.spawn(SpriteBundle {
texture: my_assets.picture_of_my_other_cat.clone(),
..default()
});
}
```
The implementation is _very_ rough. And it is currently unsafe because
`bevy_ecs` doesn't expose some internals to do this safely from inside
`bevy_asset`. There are plenty of unanswered questions like:
* "do we add a Loadable" derive? (effectively automate the FromWorld
implementation above)
* Should `MyAssets` even be an Asset? (largely implemented this way
because it elegantly builds on `server.load_asset(MyAsset { .. })`
dependency tracking).
We should think hard about what our ideal API looks like (and if this is
a pattern we want to support). Not necessarily something we need to
solve in this PR. The current `on_loaded` impl should probably be
removed from this PR before merging.
## Clarifying Questions
### What about Assets as Entities?
This Bevy Asset V2 proposal implementation initially stored Assets as
ECS Entities. Instead of `AssetId<T>` + the `Assets<T>` resource it used
`Entity` as the asset id and Asset values were just ECS components.
There are plenty of compelling reasons to do this:
1. Easier to inline assets in Bevy Scenes (as they are "just" normal
entities + components)
2. More flexible queries: use the power of the ECS to filter assets (ex:
`Query<Mesh, With<Tree>>`).
3. Extensible. Users can add arbitrary component data to assets.
4. Things like "component visualization tools" work out of the box to
visualize asset data.
However Assets as Entities has a ton of caveats right now:
* We need to be able to allocate entity ids without a direct World
reference (aka rework id allocator in Entities ... i worked around this
in my prototypes by just pre allocating big chunks of entities)
* We want asset change events in addition to ECS change tracking ... how
do we populate them when mutations can come from anywhere? Do we use
Changed queries? This would require iterating over the change data for
all assets every frame. Is this acceptable or should we implement a new
"event based" component change detection option?
* Reconciling manually created assets with asset-system managed assets
has some nuance (ex: are they "loaded" / do they also have that
component metadata?)
* "how do we handle "static" / default entity handles" (ties in to the
Entity Indices discussion:
https://github.com/bevyengine/bevy/discussions/8319). This is necessary
for things like "built in" assets and default handles in things like
SpriteBundle.
* Storing asset information as a component makes it easy to "invalidate"
asset state by removing the component (or forcing modifications).
Ideally we have ways to lock this down (some combination of Rust type
privacy and ECS validation)
In practice, how we store and identify assets is a reasonably
superficial change (porting off of Assets as Entities and implementing
dedicated storage + ids took less than a day). So once we sort out the
remaining challenges the flip should be straightforward. Additionally, I
do still have "Assets as Entities" in my commit history, so we can reuse
that work. I personally think "assets as entities" is a good endgame,
but it also doesn't provide _significant_ value at the moment and it
certainly isn't ready yet with the current state of things.
### Why not Distill?
[Distill](https://github.com/amethyst/distill) is a high quality fully
featured asset system built in Rust. It is very natural to ask "why not
just use Distill?".
It is also worth calling out that for awhile, [we planned on adopting
Distill / I signed off on
it](https://github.com/bevyengine/bevy/issues/708).
However I think Bevy has a number of constraints that make Distill
adoption suboptimal:
* **Architectural Simplicity:**
* Distill's processor requires an in-memory database (lmdb) and RPC
networked API (using Cap'n Proto). Each of these introduces API
complexity that increases maintenance burden and "code grokability".
Ignoring tests, documentation, and examples, Distill has 24,237 lines of
Rust code (including generated code for RPC + database interactions). If
you ignore generated code, it has 11,499 lines.
* Bevy builds the AssetProcessor and AssetServer using pluggable
AssetReader/AssetWriter Rust traits with simple io interfaces. They do
not necessitate databases or RPC interfaces (although Readers/Writers
could use them if that is desired). Bevy Asset V2 (at the time of
writing this PR) is 5,384 lines of Rust code (ignoring tests,
documentation, and examples). Grain of salt: Distill does have more
features currently (ex: Asset Packing, GUIDS, remote-out-of-process
asset processor). I do plan to implement these features in Bevy Asset V2
and I personally highly doubt they will meaningfully close the 6115
lines-of-code gap.
* This complexity gap (which while illustrated by lines of code, is much
bigger than just that) is noteworthy to me. Bevy should be hackable and
there are pillars of Distill that are very hard to understand and
extend. This is a matter of opinion (and Bevy Asset V2 also has
complicated areas), but I think Bevy Asset V2 is much more approachable
for the average developer.
* Necessary disclaimer: counting lines of code is an extremely rough
complexity metric. Read the code and form your own opinions.
* **Optional Asset Processing:** Not all Bevy Apps (or Bevy App
developers) need / want asset preprocessing. Processing increases the
complexity of the development environment by introducing things like
meta files, imported asset storage, running processors in the
background, waiting for processing to finish, etc. Distill _requires_
preprocessing to work. With Bevy Asset V2 processing is fully opt-in.
The AssetServer isn't directly aware of asset processors at all.
AssetLoaders only care about converting bytes to runtime Assets ... they
don't know or care if the bytes were pre-processed or not. Processing is
"elegantly" (forgive my self-congratulatory phrasing) layered on top and
builds on the existing Asset system primitives.
* **Direct Filesystem Access to Processed Asset State:** Distill stores
processed assets in a database. This makes debugging / inspecting the
processed outputs harder (either requires special tooling to query the
database or they need to be "deployed" to be inspected). Bevy Asset V2,
on the other hand, stores processed assets in the filesystem (by default
... this is configurable). This makes interacting with the processed
state more natural. Note that both Godot and Unity's new asset system
store processed assets in the filesystem.
* **Portability**: Because Distill's processor uses lmdb and RPC
networking, it cannot be run on certain platforms (ex: lmdb is a
non-rust dependency that cannot run on the web, some platforms don't
support running network servers). Bevy should be able to process assets
everywhere (ex: run the Bevy Editor on the web, compile + process
shaders on mobile, etc). Distill does partially mitigate this problem by
supporting "streaming" assets via the RPC protocol, but this is not a
full solve from my perspective. And Bevy Asset V2 can (in theory) also
stream assets (without requiring RPC, although this isn't implemented
yet)
Note that I _do_ still think Distill would be a solid asset system for
Bevy. But I think the approach in this PR is a better solve for Bevy's
specific "asset system requirements".
### Doesn't async-fs just shim requests to "sync" `std::fs`? What is the
point?
"True async file io" has limited / spotty platform support. async-fs
(and the rust async ecosystem generally ... ex Tokio) currently use
async wrappers over std::fs that offload blocking requests to separate
threads. This may feel unsatisfying, but it _does_ still provide value
because it prevents our task pools from blocking on file system
operations (which would prevent progress when there are many tasks to
do, but all threads in a pool are currently blocking on file system
ops).
Additionally, using async APIs for our AssetReaders and AssetWriters
also provides value because we can later add support for "true async
file io" for platforms that support it. _And_ we can implement other
"true async io" asset backends (such as networked asset io).
## Draft TODO
- [x] Fill in missing filesystem event APIs: file removed event (which
is expressed as dangling RenameFrom events in some cases), file/folder
renamed event
- [x] Assets without loaders are not moved to the processed folder. This
breaks things like referenced `.bin` files for GLTFs. This should be
configurable per-non-asset-type.
- [x] Initial implementation of Reflect and FromReflect for Handle. The
"deserialization" parity bar is low here as this only worked with static
UUIDs in the old impl ... this is a non-trivial problem. Either we add a
Handle::AssetPath variant that gets "upgraded" to a strong handle on
scene load or we use a separate AssetRef type for Bevy scenes (which is
converted to a runtime Handle on load). This deserves its own discussion
in a different pr.
- [x] Populate read_asset_bytes hash when run by the processor (a bit of
a special case .. when run by the processor the processed meta will
contain the hash so we don't need to compute it on the spot, but we
don't want/need to read the meta when run by the main AssetServer)
- [x] Delay hot reloading: currently filesystem events are handled
immediately, which creates timing issues in some cases. For example hot
reloading images can sometimes break because the image isn't finished
writing. We should add a delay, likely similar to the [implementation in
this PR](https://github.com/bevyengine/bevy/pull/8503).
- [x] Port old platform-specific AssetIo implementations to the new
AssetReader interface (currently missing Android and web)
- [x] Resolve on_loaded unsafety (either by removing the API entirely or
removing the unsafe)
- [x] Runtime loader setting overrides
- [x] Remove remaining unwraps that should be error-handled. There are
number of TODOs here
- [x] Pretty AssetPath Display impl
- [x] Document more APIs
- [x] Resolve spurious "reloading because it has changed" events (to
repro run load_gltf with `processed_dev()`)
- [x] load_dependency hot reloading currently only works for processed
assets. If processing is disabled, load_dependency changes are not hot
reloaded.
- [x] Replace AssetInfo dependency load/fail counters with
`loading_dependencies: HashSet<UntypedAssetId>` to prevent reloads from
(potentially) breaking counters. Storing this will also enable
"dependency reloaded" events (see [Next Steps](#next-steps))
- [x] Re-add filesystem watcher cargo feature gate (currently it is not
optional)
- [ ] Migration Guide
- [ ] Changelog
## Followup TODO
- [ ] Replace "eager unchanged processed asset loading" behavior with
"don't returned unchanged processed asset until dependencies have been
checked".
- [ ] Add true `Ignore` AssetAction that does not copy the asset to the
imported_assets folder.
- [ ] Finish "live asset unloading" (ex: free up CPU asset memory after
uploading an image to the GPU), rethink RenderAssets, and port renderer
features. The `Assets` collection uses `Option<T>` for asset storage to
support its removal. (1) the Option might not actually be necessary ...
might be able to just remove from the collection entirely (2) need to
finalize removal apis
- [ ] Try replacing the "channel based" asset id recycling with
something a bit more efficient (ex: we might be able to use raw atomic
ints with some cleverness)
- [ ] Consider adding UUIDs to processed assets (scoped just to helping
identify moved assets ... not exposed to load queries ... see [Next
Steps](#next-steps))
- [ ] Store "last modified" source asset and meta timestamps in
processed meta files to enable skipping expensive hashing when the file
wasn't changed
- [ ] Fix "slow loop" handle drop fix
- [ ] Migrate to TypeName
- [x] Handle "loader preregistration". See #9429
## Next Steps
* **Configurable per-type defaults for AssetMeta**: It should be
possible to add configuration like "all png image meta should default to
using nearest sampling" (currently this hard-coded per-loader/processor
Settings::default() impls). Also see the "Folder Meta" bullet point.
* **Avoid Reprocessing on Asset Renames / Moves**: See the "canonical
asset ids" discussion in [Open Questions](#open-questions) and the
relevant bullet point in [Draft TODO](#draft-todo). Even without
canonical ids, folder renames could avoid reprocessing in some cases.
* **Multiple Asset Sources**: Expand AssetPath to support "asset source
names" and support multiple AssetReaders in the asset server (ex:
`webserver://some_path/image.png` backed by an Http webserver
AssetReader). The "default" asset reader would use normal
`some_path/image.png` paths. Ideally this works in combination with
multiple AssetWatchers for hot-reloading
* **Stable Type Names**: this pr removes the TypeUuid requirement from
assets in favor of `std::any::type_name`. This makes defining assets
easier (no need to generate a new uuid / use weird proc macro syntax).
It also makes reading meta files easier (because things have "friendly
names"). We also use type names for components in scene files. If they
are good enough for components, they are good enough for assets. And
consistency across Bevy pillars is desirable. However,
`std::any::type_name` is not guaranteed to be stable (although in
practice it is). We've developed a [stable type
path](https://github.com/bevyengine/bevy/pull/7184) to resolve this,
which should be adopted when it is ready.
* **Command Line Interface**: It should be possible to run the asset
processor in a separate process from the command line. This will also
require building a network-server-backed AssetReader to communicate
between the app and the processor. We've been planning to build a "bevy
cli" for awhile. This seems like a good excuse to build it.
* **Asset Packing**: This is largely an additive feature, so it made
sense to me to punt this until we've laid the foundations in this PR.
* **Per-Platform Processed Assets**: It should be possible to generate
assets for multiple platforms by supporting multiple "processor
profiles" per asset (ex: compress with format X on PC and Y on iOS). I
think there should probably be arbitrary "profiles" (which can be
separate from actual platforms), which are then assigned to a given
platform when generating the final asset distribution for that platform.
Ex: maybe devs want a "Mobile" profile that is shared between iOS and
Android. Or a "LowEnd" profile shared between web and mobile.
* **Versioning and Migrations**: Assets, Loaders, Savers, and Processors
need to have versions to determine if their schema is valid. If an asset
/ loader version is incompatible with the current version expected at
runtime, the processor should be able to migrate them. I think we should
try using Bevy Reflect for this, as it would allow us to load the old
version as a dynamic Reflect type without actually having the old Rust
type. It would also allow us to define "patches" to migrate between
versions (Bevy Reflect devs are currently working on patching). The
`.meta` file already has its own format version. Migrating that to new
versions should also be possible.
* **Real Copy-on-write AssetPaths**: Rust's actual Cow (clone-on-write
type) currently used by AssetPath can still result in String clones that
aren't actually necessary (cloning an Owned Cow clones the contents).
Bevy's asset system requires cloning AssetPaths in a number of places,
which result in actual clones of the internal Strings. This is not
efficient. AssetPath internals should be reworked to exhibit truer
cow-like-behavior that reduces String clones to the absolute minimum.
* **Consider processor-less processing**: In theory the AssetServer
could run processors "inline" even if the background AssetProcessor is
disabled. If we decide this is actually desirable, we could add this.
But I don't think its a priority in the short or medium term.
* **Pre-emptive dependency loading**: We could encode dependencies in
processed meta files, which could then be used by the Asset Server to
kick of dependency loads as early as possible (prior to starting the
actual asset load). Is this desirable? How much time would this save in
practice?
* **Optimize Processor With UntypedAssetIds**: The processor exclusively
uses AssetPath to identify assets currently. It might be possible to
swap these out for UntypedAssetIds in some places, which are smaller /
cheaper to hash and compare.
* **One to Many Asset Processing**: An asset source file that produces
many assets currently must be processed into a single "processed" asset
source. If labeled assets can be written separately they can each have
their own configured savers _and_ they could be loaded more granularly.
Definitely worth exploring!
* **Automatically Track "Runtime-only" Asset Dependencies**: Right now,
tracking "created at runtime" asset dependencies requires adding them
via `asset_server.load_asset(StandardMaterial::default())`. I think with
some cleverness we could also do this for
`materials.add(StandardMaterial::default())`, making tracking work
"everywhere". There are challenges here relating to change detection /
ensuring the server is made aware of dependency changes. This could be
expensive in some cases.
* **"Dependency Changed" events**: Some assets have runtime artifacts
that need to be re-generated when one of their dependencies change (ex:
regenerate a material's bind group when a Texture needs to change). We
are generating the dependency graph so we can definitely produce these
events. Buuuuut generating these events will have a cost / they could be
high frequency for some assets, so we might want this to be opt-in for
specific cases.
* **Investigate Storing More Information In Handles**: Handles can now
store arbitrary information, which makes it cheaper and easier to
access. How much should we move into them? Canonical asset load states
(via atomics)? (`handle.is_loaded()` would be very cool). Should we
store the entire asset and remove the `Assets<T>` collection?
(`Arc<RwLock<Option<Image>>>`?)
* **Support processing and loading files without extensions**: This is a
pretty arbitrary restriction and could be supported with very minimal
changes.
* **Folder Meta**: It would be nice if we could define per folder
processor configuration defaults (likely in a `.meta` or `.folder_meta`
file). Things like "default to linear filtering for all Images in this
folder".
* **Replace async_broadcast with event-listener?** This might be
approximately drop-in for some uses and it feels more light weight
* **Support Running the AssetProcessor on the Web**: Most of the hard
work is done here, but there are some easy straggling TODOs (make the
transaction log an interface instead of a direct file writer so we can
write a web storage backend, implement an AssetReader/AssetWriter that
reads/writes to something like LocalStorage).
* **Consider identifying and preventing circular dependencies**: This is
especially important for "processor dependencies", as processing will
silently never finish in these cases.
* **Built-in/Inlined Asset Hot Reloading**: This PR regresses
"built-in/inlined" asset hot reloading (previously provided by the
DebugAssetServer). I'm intentionally punting this because I think it can
be cleanly implemented with "multiple asset sources" by registering a
"debug asset source" (ex: `debug://bevy_pbr/src/render/pbr.wgsl` asset
paths) in combination with an AssetWatcher for that asset source and
support for "manually loading pats with asset bytes instead of
AssetReaders". The old DebugAssetServer was quite nasty and I'd love to
avoid that hackery going forward.
* **Investigate ways to remove double-parsing meta files**: Parsing meta
files currently involves parsing once with "minimal" versions of the
meta file to extract the type name of the loader/processor config, then
parsing again to parse the "full" meta. This is suboptimal. We should be
able to define custom deserializers that (1) assume the loader/processor
type name comes first (2) dynamically looks up the loader/processor
registrations to deserialize settings in-line (similar to components in
the bevy scene format). Another alternative: deserialize as dynamic
Reflect objects and then convert.
* **More runtime loading configuration**: Support using the Handle type
as a hint to select an asset loader (instead of relying on AssetPath
extensions)
* **More high level Processor trait implementations**: For example, it
might be worth adding support for arbitrary chains of "asset transforms"
that modify an in-memory asset representation between loading and
saving. (ex: load a Mesh, run a `subdivide_mesh` transform, followed by
a `flip_normals` transform, then save the mesh to an efficient
compressed format).
* **Bevy Scene Handle Deserialization**: (see the relevant [Draft TODO
item](#draft-todo) for context)
* **Explore High Level Load Interfaces**: See [this
discussion](#discuss-on_loaded-high-level-interface) for one prototype.
* **Asset Streaming**: It would be great if we could stream Assets (ex:
stream a long video file piece by piece)
* **ID Exchanging**: In this PR Asset Handles/AssetIds are bigger than
they need to be because they have a Uuid enum variant. If we implement
an "id exchanging" system that trades Uuids for "efficient runtime ids",
we can cut down on the size of AssetIds, making them more efficient.
This has some open design questions, such as how to spawn entities with
"default" handle values (as these wouldn't have access to the exchange
api in the current system).
* **Asset Path Fixup Tooling**: Assets that inline asset paths inside
them will break when an asset moves. The asset system provides the
functionality to detect when paths break. We should build a framework
that enables formats to define "path migrations". This is especially
important for scene files. For editor-generated files, we should also
consider using UUIDs (see other bullet point) to avoid the need to
migrate in these cases.
---------
Co-authored-by: BeastLe9enD <beastle9end@outlook.de>
Co-authored-by: Mike <mike.hsu@gmail.com>
Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>
2023-09-07 02:07:27 +00:00
#[ derive(Component, Clone, Debug, Reflect, Default) ]
bevy_reflect: `FromReflect` Ergonomics Implementation (#6056)
# Objective
**This implementation is based on
https://github.com/bevyengine/rfcs/pull/59.**
---
Resolves #4597
Full details and motivation can be found in the RFC, but here's a brief
summary.
`FromReflect` is a very powerful and important trait within the
reflection API. It allows Dynamic types (e.g., `DynamicList`, etc.) to
be formed into Real ones (e.g., `Vec<i32>`, etc.).
This mainly comes into play concerning deserialization, where the
reflection deserializers both return a `Box<dyn Reflect>` that almost
always contain one of these Dynamic representations of a Real type. To
convert this to our Real type, we need to use `FromReflect`.
It also sneaks up in other ways. For example, it's a required bound for
`T` in `Vec<T>` so that `Vec<T>` as a whole can be made `FromReflect`.
It's also required by all fields of an enum as it's used as part of the
`Reflect::apply` implementation.
So in other words, much like `GetTypeRegistration` and `Typed`, it is
very much a core reflection trait.
The problem is that it is not currently treated like a core trait and is
not automatically derived alongside `Reflect`. This makes using it a bit
cumbersome and easy to forget.
## Solution
Automatically derive `FromReflect` when deriving `Reflect`.
Users can then choose to opt-out if needed using the
`#[reflect(from_reflect = false)]` attribute.
```rust
#[derive(Reflect)]
struct Foo;
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Bar;
fn test<T: FromReflect>(value: T) {}
test(Foo); // <-- OK
test(Bar); // <-- Panic! Bar does not implement trait `FromReflect`
```
#### `ReflectFromReflect`
This PR also automatically adds the `ReflectFromReflect` (introduced in
#6245) registration to the derived `GetTypeRegistration` impl— if the
type hasn't opted out of `FromReflect` of course.
<details>
<summary><h4>Improved Deserialization</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
And since we can do all the above, we might as well improve
deserialization. We can now choose to deserialize into a Dynamic type or
automatically convert it using `FromReflect` under the hood.
`[Un]TypedReflectDeserializer::new` will now perform the conversion and
return the `Box`'d Real type.
`[Un]TypedReflectDeserializer::new_dynamic` will work like what we have
now and simply return the `Box`'d Dynamic type.
```rust
// Returns the Real type
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: SomeStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
// Returns the Dynamic type
let reflect_deserializer = UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: DynamicStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
```
</details>
---
## Changelog
* `FromReflect` is now automatically derived within the `Reflect` derive
macro
* This includes auto-registering `ReflectFromReflect` in the derived
`GetTypeRegistration` impl
* ~~Renamed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic`, respectively~~ **Descoped**
* ~~Changed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to automatically convert the
deserialized output using `FromReflect`~~ **Descoped**
## Migration Guide
* `FromReflect` is now automatically derived within the `Reflect` derive
macro. Items with both derives will need to remove the `FromReflect`
one.
```rust
// OLD
#[derive(Reflect, FromReflect)]
struct Foo;
// NEW
#[derive(Reflect)]
struct Foo;
```
If using a manual implementation of `FromReflect` and the `Reflect`
derive, users will need to opt-out of the automatic implementation.
```rust
// OLD
#[derive(Reflect)]
struct Foo;
impl FromReflect for Foo {/* ... */}
// NEW
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Foo;
impl FromReflect for Foo {/* ... */}
```
<details>
<summary><h4>Removed Migrations</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
* The reflect deserializers now perform a `FromReflect` conversion
internally. The expected output of `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` is no longer a Dynamic (e.g.,
`DynamicList`), but its Real counterpart (e.g., `Vec<i32>`).
```rust
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
// OLD
let output: DynamicStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
// NEW
let output: SomeStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
```
Alternatively, if this behavior isn't desired, use the
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic` methods instead:
```rust
// OLD
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
// NEW
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
```
</details>
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-06-29 01:31:34 +00:00
#[ reflect(Component, Default) ]
2022-11-14 21:59:17 +00:00
pub struct UiImage {
/// Handle to the texture
pub texture : Handle < Image > ,
/// Whether the image should be flipped along its x-axis
pub flip_x : bool ,
/// Whether the image should be flipped along its y-axis
pub flip_y : bool ,
}
2021-12-14 03:58:23 +00:00
2022-11-14 21:59:17 +00:00
impl UiImage {
pub fn new ( texture : Handle < Image > ) -> Self {
Self {
texture ,
.. Default ::default ( )
}
2021-12-14 03:58:23 +00:00
}
2023-04-05 22:19:46 +00:00
2023-10-21 17:38:15 +00:00
/// Flip the image along its x-axis
2023-04-05 22:19:46 +00:00
#[ must_use ]
pub const fn with_flip_x ( mut self ) -> Self {
self . flip_x = true ;
self
}
2023-10-21 17:38:15 +00:00
/// Flip the image along its y-axis
2023-04-05 22:19:46 +00:00
#[ must_use ]
pub const fn with_flip_y ( mut self ) -> Self {
self . flip_y = true ;
self
}
2021-12-14 03:58:23 +00:00
}
impl From < Handle < Image > > for UiImage {
2022-11-14 21:59:17 +00:00
fn from ( texture : Handle < Image > ) -> Self {
Self ::new ( texture )
2021-12-14 03:58:23 +00:00
}
}
2021-12-19 05:44:28 +00:00
2022-01-07 22:20:34 +00:00
/// The calculated clip of the node
bevy_reflect: `FromReflect` Ergonomics Implementation (#6056)
# Objective
**This implementation is based on
https://github.com/bevyengine/rfcs/pull/59.**
---
Resolves #4597
Full details and motivation can be found in the RFC, but here's a brief
summary.
`FromReflect` is a very powerful and important trait within the
reflection API. It allows Dynamic types (e.g., `DynamicList`, etc.) to
be formed into Real ones (e.g., `Vec<i32>`, etc.).
This mainly comes into play concerning deserialization, where the
reflection deserializers both return a `Box<dyn Reflect>` that almost
always contain one of these Dynamic representations of a Real type. To
convert this to our Real type, we need to use `FromReflect`.
It also sneaks up in other ways. For example, it's a required bound for
`T` in `Vec<T>` so that `Vec<T>` as a whole can be made `FromReflect`.
It's also required by all fields of an enum as it's used as part of the
`Reflect::apply` implementation.
So in other words, much like `GetTypeRegistration` and `Typed`, it is
very much a core reflection trait.
The problem is that it is not currently treated like a core trait and is
not automatically derived alongside `Reflect`. This makes using it a bit
cumbersome and easy to forget.
## Solution
Automatically derive `FromReflect` when deriving `Reflect`.
Users can then choose to opt-out if needed using the
`#[reflect(from_reflect = false)]` attribute.
```rust
#[derive(Reflect)]
struct Foo;
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Bar;
fn test<T: FromReflect>(value: T) {}
test(Foo); // <-- OK
test(Bar); // <-- Panic! Bar does not implement trait `FromReflect`
```
#### `ReflectFromReflect`
This PR also automatically adds the `ReflectFromReflect` (introduced in
#6245) registration to the derived `GetTypeRegistration` impl— if the
type hasn't opted out of `FromReflect` of course.
<details>
<summary><h4>Improved Deserialization</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
And since we can do all the above, we might as well improve
deserialization. We can now choose to deserialize into a Dynamic type or
automatically convert it using `FromReflect` under the hood.
`[Un]TypedReflectDeserializer::new` will now perform the conversion and
return the `Box`'d Real type.
`[Un]TypedReflectDeserializer::new_dynamic` will work like what we have
now and simply return the `Box`'d Dynamic type.
```rust
// Returns the Real type
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: SomeStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
// Returns the Dynamic type
let reflect_deserializer = UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: DynamicStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
```
</details>
---
## Changelog
* `FromReflect` is now automatically derived within the `Reflect` derive
macro
* This includes auto-registering `ReflectFromReflect` in the derived
`GetTypeRegistration` impl
* ~~Renamed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic`, respectively~~ **Descoped**
* ~~Changed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to automatically convert the
deserialized output using `FromReflect`~~ **Descoped**
## Migration Guide
* `FromReflect` is now automatically derived within the `Reflect` derive
macro. Items with both derives will need to remove the `FromReflect`
one.
```rust
// OLD
#[derive(Reflect, FromReflect)]
struct Foo;
// NEW
#[derive(Reflect)]
struct Foo;
```
If using a manual implementation of `FromReflect` and the `Reflect`
derive, users will need to opt-out of the automatic implementation.
```rust
// OLD
#[derive(Reflect)]
struct Foo;
impl FromReflect for Foo {/* ... */}
// NEW
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Foo;
impl FromReflect for Foo {/* ... */}
```
<details>
<summary><h4>Removed Migrations</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
* The reflect deserializers now perform a `FromReflect` conversion
internally. The expected output of `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` is no longer a Dynamic (e.g.,
`DynamicList`), but its Real counterpart (e.g., `Vec<i32>`).
```rust
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
// OLD
let output: DynamicStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
// NEW
let output: SomeStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
```
Alternatively, if this behavior isn't desired, use the
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic` methods instead:
```rust
// OLD
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
// NEW
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
```
</details>
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-06-29 01:31:34 +00:00
#[ derive(Component, Default, Copy, Clone, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Component, Default) ]
2021-12-19 05:44:28 +00:00
pub struct CalculatedClip {
2022-01-07 22:20:34 +00:00
/// The rect of the clip
2022-09-02 12:35:23 +00:00
pub clip : Rect ,
2021-12-19 05:44:28 +00:00
}
2022-10-24 14:33:46 +00:00
Add z-index support with a predictable UI stack (#5877)
# Objective
Add consistent UI rendering and interaction where deep nodes inside two different hierarchies will never render on top of one-another by default and offer an escape hatch (z-index) for nodes to change their depth.
## The problem with current implementation
The current implementation of UI rendering is broken in that regard, mainly because [it sets the Z value of the `Transform` component based on a "global Z" space](https://github.com/bevyengine/bevy/blob/main/crates/bevy_ui/src/update.rs#L43) shared by all nodes in the UI. This doesn't account for the fact that each node's final `GlobalTransform` value will be relative to its parent. This effectively makes the depth unpredictable when two deep trees are rendered on top of one-another.
At the moment, it's also up to each part of the UI code to sort all of the UI nodes. The solution that's offered here does the full sorting of UI node entities once and offers the result through a resource so that all systems can use it.
## Solution
### New ZIndex component
This adds a new optional `ZIndex` enum component for nodes which offers two mechanism:
- `ZIndex::Local(i32)`: Overrides the depth of the node relative to its siblings.
- `ZIndex::Global(i32)`: Overrides the depth of the node relative to the UI root. This basically allows any node in the tree to "escape" the parent and be ordered relative to the entire UI.
Note that in the current implementation, omitting `ZIndex` on a node has the same result as adding `ZIndex::Local(0)`. Additionally, the "global" stacking context is essentially a way to add your node to the root stacking context, so using `ZIndex::Local(n)` on a root node (one without parent) will share that space with all nodes using `Index::Global(n)`.
### New UiStack resource
This adds a new `UiStack` resource which is calculated from both hierarchy and `ZIndex` during UI update and contains a vector of all node entities in the UI, ordered by depth (from farthest from camera to closest). This is exposed publicly by the bevy_ui crate with the hope that it can be used for consistent ordering and to reduce the amount of sorting that needs to be done by UI systems (i.e. instead of sorting everything by `global_transform.z` in every system, this array can be iterated over).
### New z_index example
This also adds a new z_index example that showcases the new `ZIndex` component. It's also a good general demo of the new UI stack system, because making this kind of UI was very broken with the old system (e.g. nodes would render on top of each other, not respecting hierarchy or insert order at all).
---
## Changelog
- Added the `ZIndex` component to bevy_ui.
- Added the `UiStack` resource to bevy_ui, and added implementation in a new `stack.rs` module.
- Removed the previous Z updating system from bevy_ui, because it was replaced with the above.
- Changed bevy_ui rendering to use UiStack instead of z ordering.
- Changed bevy_ui focus/interaction system to use UiStack instead of z ordering.
- Added a new z_index example.
## ZIndex demo
Here's a demo I wrote to test these features
https://user-images.githubusercontent.com/1060971/188329295-d7beebd6-9aee-43ab-821e-d437df5dbe8a.mp4
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-11-02 22:06:04 +00:00
/// Indicates that this [`Node`] entity's front-to-back ordering is not controlled solely
/// by its location in the UI hierarchy. A node with a higher z-index will appear on top
/// of other nodes with a lower z-index.
///
/// UI nodes that have the same z-index will appear according to the order in which they
/// appear in the UI hierarchy. In such a case, the last node to be added to its parent
2023-10-21 17:38:15 +00:00
/// will appear in front of its siblings.
Add z-index support with a predictable UI stack (#5877)
# Objective
Add consistent UI rendering and interaction where deep nodes inside two different hierarchies will never render on top of one-another by default and offer an escape hatch (z-index) for nodes to change their depth.
## The problem with current implementation
The current implementation of UI rendering is broken in that regard, mainly because [it sets the Z value of the `Transform` component based on a "global Z" space](https://github.com/bevyengine/bevy/blob/main/crates/bevy_ui/src/update.rs#L43) shared by all nodes in the UI. This doesn't account for the fact that each node's final `GlobalTransform` value will be relative to its parent. This effectively makes the depth unpredictable when two deep trees are rendered on top of one-another.
At the moment, it's also up to each part of the UI code to sort all of the UI nodes. The solution that's offered here does the full sorting of UI node entities once and offers the result through a resource so that all systems can use it.
## Solution
### New ZIndex component
This adds a new optional `ZIndex` enum component for nodes which offers two mechanism:
- `ZIndex::Local(i32)`: Overrides the depth of the node relative to its siblings.
- `ZIndex::Global(i32)`: Overrides the depth of the node relative to the UI root. This basically allows any node in the tree to "escape" the parent and be ordered relative to the entire UI.
Note that in the current implementation, omitting `ZIndex` on a node has the same result as adding `ZIndex::Local(0)`. Additionally, the "global" stacking context is essentially a way to add your node to the root stacking context, so using `ZIndex::Local(n)` on a root node (one without parent) will share that space with all nodes using `Index::Global(n)`.
### New UiStack resource
This adds a new `UiStack` resource which is calculated from both hierarchy and `ZIndex` during UI update and contains a vector of all node entities in the UI, ordered by depth (from farthest from camera to closest). This is exposed publicly by the bevy_ui crate with the hope that it can be used for consistent ordering and to reduce the amount of sorting that needs to be done by UI systems (i.e. instead of sorting everything by `global_transform.z` in every system, this array can be iterated over).
### New z_index example
This also adds a new z_index example that showcases the new `ZIndex` component. It's also a good general demo of the new UI stack system, because making this kind of UI was very broken with the old system (e.g. nodes would render on top of each other, not respecting hierarchy or insert order at all).
---
## Changelog
- Added the `ZIndex` component to bevy_ui.
- Added the `UiStack` resource to bevy_ui, and added implementation in a new `stack.rs` module.
- Removed the previous Z updating system from bevy_ui, because it was replaced with the above.
- Changed bevy_ui rendering to use UiStack instead of z ordering.
- Changed bevy_ui focus/interaction system to use UiStack instead of z ordering.
- Added a new z_index example.
## ZIndex demo
Here's a demo I wrote to test these features
https://user-images.githubusercontent.com/1060971/188329295-d7beebd6-9aee-43ab-821e-d437df5dbe8a.mp4
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-11-02 22:06:04 +00:00
///
/// Internally, nodes with a global z-index share the stacking context of root UI nodes
/// (nodes that have no parent). Because of this, there is no difference between using
2023-10-21 17:38:15 +00:00
/// `ZIndex::Local(n)` and `ZIndex::Global(n)` for root nodes.
Add z-index support with a predictable UI stack (#5877)
# Objective
Add consistent UI rendering and interaction where deep nodes inside two different hierarchies will never render on top of one-another by default and offer an escape hatch (z-index) for nodes to change their depth.
## The problem with current implementation
The current implementation of UI rendering is broken in that regard, mainly because [it sets the Z value of the `Transform` component based on a "global Z" space](https://github.com/bevyengine/bevy/blob/main/crates/bevy_ui/src/update.rs#L43) shared by all nodes in the UI. This doesn't account for the fact that each node's final `GlobalTransform` value will be relative to its parent. This effectively makes the depth unpredictable when two deep trees are rendered on top of one-another.
At the moment, it's also up to each part of the UI code to sort all of the UI nodes. The solution that's offered here does the full sorting of UI node entities once and offers the result through a resource so that all systems can use it.
## Solution
### New ZIndex component
This adds a new optional `ZIndex` enum component for nodes which offers two mechanism:
- `ZIndex::Local(i32)`: Overrides the depth of the node relative to its siblings.
- `ZIndex::Global(i32)`: Overrides the depth of the node relative to the UI root. This basically allows any node in the tree to "escape" the parent and be ordered relative to the entire UI.
Note that in the current implementation, omitting `ZIndex` on a node has the same result as adding `ZIndex::Local(0)`. Additionally, the "global" stacking context is essentially a way to add your node to the root stacking context, so using `ZIndex::Local(n)` on a root node (one without parent) will share that space with all nodes using `Index::Global(n)`.
### New UiStack resource
This adds a new `UiStack` resource which is calculated from both hierarchy and `ZIndex` during UI update and contains a vector of all node entities in the UI, ordered by depth (from farthest from camera to closest). This is exposed publicly by the bevy_ui crate with the hope that it can be used for consistent ordering and to reduce the amount of sorting that needs to be done by UI systems (i.e. instead of sorting everything by `global_transform.z` in every system, this array can be iterated over).
### New z_index example
This also adds a new z_index example that showcases the new `ZIndex` component. It's also a good general demo of the new UI stack system, because making this kind of UI was very broken with the old system (e.g. nodes would render on top of each other, not respecting hierarchy or insert order at all).
---
## Changelog
- Added the `ZIndex` component to bevy_ui.
- Added the `UiStack` resource to bevy_ui, and added implementation in a new `stack.rs` module.
- Removed the previous Z updating system from bevy_ui, because it was replaced with the above.
- Changed bevy_ui rendering to use UiStack instead of z ordering.
- Changed bevy_ui focus/interaction system to use UiStack instead of z ordering.
- Added a new z_index example.
## ZIndex demo
Here's a demo I wrote to test these features
https://user-images.githubusercontent.com/1060971/188329295-d7beebd6-9aee-43ab-821e-d437df5dbe8a.mp4
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-11-02 22:06:04 +00:00
///
2023-10-21 17:38:15 +00:00
/// Nodes without this component will be treated as if they had a value of `ZIndex::Local(0)`.
bevy_reflect: `FromReflect` Ergonomics Implementation (#6056)
# Objective
**This implementation is based on
https://github.com/bevyengine/rfcs/pull/59.**
---
Resolves #4597
Full details and motivation can be found in the RFC, but here's a brief
summary.
`FromReflect` is a very powerful and important trait within the
reflection API. It allows Dynamic types (e.g., `DynamicList`, etc.) to
be formed into Real ones (e.g., `Vec<i32>`, etc.).
This mainly comes into play concerning deserialization, where the
reflection deserializers both return a `Box<dyn Reflect>` that almost
always contain one of these Dynamic representations of a Real type. To
convert this to our Real type, we need to use `FromReflect`.
It also sneaks up in other ways. For example, it's a required bound for
`T` in `Vec<T>` so that `Vec<T>` as a whole can be made `FromReflect`.
It's also required by all fields of an enum as it's used as part of the
`Reflect::apply` implementation.
So in other words, much like `GetTypeRegistration` and `Typed`, it is
very much a core reflection trait.
The problem is that it is not currently treated like a core trait and is
not automatically derived alongside `Reflect`. This makes using it a bit
cumbersome and easy to forget.
## Solution
Automatically derive `FromReflect` when deriving `Reflect`.
Users can then choose to opt-out if needed using the
`#[reflect(from_reflect = false)]` attribute.
```rust
#[derive(Reflect)]
struct Foo;
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Bar;
fn test<T: FromReflect>(value: T) {}
test(Foo); // <-- OK
test(Bar); // <-- Panic! Bar does not implement trait `FromReflect`
```
#### `ReflectFromReflect`
This PR also automatically adds the `ReflectFromReflect` (introduced in
#6245) registration to the derived `GetTypeRegistration` impl— if the
type hasn't opted out of `FromReflect` of course.
<details>
<summary><h4>Improved Deserialization</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
And since we can do all the above, we might as well improve
deserialization. We can now choose to deserialize into a Dynamic type or
automatically convert it using `FromReflect` under the hood.
`[Un]TypedReflectDeserializer::new` will now perform the conversion and
return the `Box`'d Real type.
`[Un]TypedReflectDeserializer::new_dynamic` will work like what we have
now and simply return the `Box`'d Dynamic type.
```rust
// Returns the Real type
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: SomeStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
// Returns the Dynamic type
let reflect_deserializer = UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
let output: DynamicStruct = reflect_deserializer.deserialize(&mut deserializer)?.take()?;
```
</details>
---
## Changelog
* `FromReflect` is now automatically derived within the `Reflect` derive
macro
* This includes auto-registering `ReflectFromReflect` in the derived
`GetTypeRegistration` impl
* ~~Renamed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic`, respectively~~ **Descoped**
* ~~Changed `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` to automatically convert the
deserialized output using `FromReflect`~~ **Descoped**
## Migration Guide
* `FromReflect` is now automatically derived within the `Reflect` derive
macro. Items with both derives will need to remove the `FromReflect`
one.
```rust
// OLD
#[derive(Reflect, FromReflect)]
struct Foo;
// NEW
#[derive(Reflect)]
struct Foo;
```
If using a manual implementation of `FromReflect` and the `Reflect`
derive, users will need to opt-out of the automatic implementation.
```rust
// OLD
#[derive(Reflect)]
struct Foo;
impl FromReflect for Foo {/* ... */}
// NEW
#[derive(Reflect)]
#[reflect(from_reflect = false)]
struct Foo;
impl FromReflect for Foo {/* ... */}
```
<details>
<summary><h4>Removed Migrations</h4></summary>
> **Warning**
> This section includes changes that have since been descoped from this
PR. They will likely be implemented again in a followup PR. I am mainly
leaving these details in for archival purposes, as well as for reference
when implementing this logic again.
* The reflect deserializers now perform a `FromReflect` conversion
internally. The expected output of `TypedReflectDeserializer::new` and
`UntypedReflectDeserializer::new` is no longer a Dynamic (e.g.,
`DynamicList`), but its Real counterpart (e.g., `Vec<i32>`).
```rust
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
let mut deserializer = ron::de::Deserializer::from_str(input)?;
// OLD
let output: DynamicStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
// NEW
let output: SomeStruct = reflect_deserializer.deserialize(&mut
deserializer)?.take()?;
```
Alternatively, if this behavior isn't desired, use the
`TypedReflectDeserializer::new_dynamic` and
`UntypedReflectDeserializer::new_dynamic` methods instead:
```rust
// OLD
let reflect_deserializer = UntypedReflectDeserializer::new(®istry);
// NEW
let reflect_deserializer =
UntypedReflectDeserializer::new_dynamic(®istry);
```
</details>
---------
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2023-06-29 01:31:34 +00:00
#[ derive(Component, Copy, Clone, Debug, Reflect) ]
2024-01-03 18:57:05 +00:00
#[ reflect(Component, Default) ]
Add z-index support with a predictable UI stack (#5877)
# Objective
Add consistent UI rendering and interaction where deep nodes inside two different hierarchies will never render on top of one-another by default and offer an escape hatch (z-index) for nodes to change their depth.
## The problem with current implementation
The current implementation of UI rendering is broken in that regard, mainly because [it sets the Z value of the `Transform` component based on a "global Z" space](https://github.com/bevyengine/bevy/blob/main/crates/bevy_ui/src/update.rs#L43) shared by all nodes in the UI. This doesn't account for the fact that each node's final `GlobalTransform` value will be relative to its parent. This effectively makes the depth unpredictable when two deep trees are rendered on top of one-another.
At the moment, it's also up to each part of the UI code to sort all of the UI nodes. The solution that's offered here does the full sorting of UI node entities once and offers the result through a resource so that all systems can use it.
## Solution
### New ZIndex component
This adds a new optional `ZIndex` enum component for nodes which offers two mechanism:
- `ZIndex::Local(i32)`: Overrides the depth of the node relative to its siblings.
- `ZIndex::Global(i32)`: Overrides the depth of the node relative to the UI root. This basically allows any node in the tree to "escape" the parent and be ordered relative to the entire UI.
Note that in the current implementation, omitting `ZIndex` on a node has the same result as adding `ZIndex::Local(0)`. Additionally, the "global" stacking context is essentially a way to add your node to the root stacking context, so using `ZIndex::Local(n)` on a root node (one without parent) will share that space with all nodes using `Index::Global(n)`.
### New UiStack resource
This adds a new `UiStack` resource which is calculated from both hierarchy and `ZIndex` during UI update and contains a vector of all node entities in the UI, ordered by depth (from farthest from camera to closest). This is exposed publicly by the bevy_ui crate with the hope that it can be used for consistent ordering and to reduce the amount of sorting that needs to be done by UI systems (i.e. instead of sorting everything by `global_transform.z` in every system, this array can be iterated over).
### New z_index example
This also adds a new z_index example that showcases the new `ZIndex` component. It's also a good general demo of the new UI stack system, because making this kind of UI was very broken with the old system (e.g. nodes would render on top of each other, not respecting hierarchy or insert order at all).
---
## Changelog
- Added the `ZIndex` component to bevy_ui.
- Added the `UiStack` resource to bevy_ui, and added implementation in a new `stack.rs` module.
- Removed the previous Z updating system from bevy_ui, because it was replaced with the above.
- Changed bevy_ui rendering to use UiStack instead of z ordering.
- Changed bevy_ui focus/interaction system to use UiStack instead of z ordering.
- Added a new z_index example.
## ZIndex demo
Here's a demo I wrote to test these features
https://user-images.githubusercontent.com/1060971/188329295-d7beebd6-9aee-43ab-821e-d437df5dbe8a.mp4
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
2022-11-02 22:06:04 +00:00
pub enum ZIndex {
/// Indicates the order in which this node should be rendered relative to its siblings.
Local ( i32 ) ,
/// Indicates the order in which this node should be rendered relative to root nodes and
/// all other nodes that have a global z-index.
Global ( i32 ) ,
}
impl Default for ZIndex {
fn default ( ) -> Self {
Self ::Local ( 0 )
}
}
2022-10-24 14:33:46 +00:00
#[ cfg(test) ]
mod tests {
2023-08-28 17:21:08 +00:00
use crate ::GridPlacement ;
#[ test ]
fn invalid_grid_placement_values ( ) {
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::span ( 0 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::start ( 0 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::end ( 0 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::start_end ( 0 , 1 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::start_end ( - 1 , 0 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::start_span ( 1 , 0 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::start_span ( 0 , 1 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::end_span ( 0 , 1 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::end_span ( 1 , 0 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::default ( ) . set_start ( 0 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::default ( ) . set_end ( 0 ) ) . is_err ( ) ) ;
assert! ( std ::panic ::catch_unwind ( | | GridPlacement ::default ( ) . set_span ( 0 ) ) . is_err ( ) ) ;
}
#[ test ]
fn grid_placement_accessors ( ) {
assert_eq! ( GridPlacement ::start ( 5 ) . get_start ( ) , Some ( 5 ) ) ;
assert_eq! ( GridPlacement ::end ( - 4 ) . get_end ( ) , Some ( - 4 ) ) ;
assert_eq! ( GridPlacement ::span ( 2 ) . get_span ( ) , Some ( 2 ) ) ;
assert_eq! ( GridPlacement ::start_end ( 11 , 21 ) . get_span ( ) , None ) ;
assert_eq! ( GridPlacement ::start_span ( 3 , 5 ) . get_end ( ) , None ) ;
assert_eq! ( GridPlacement ::end_span ( - 4 , 12 ) . get_start ( ) , None ) ;
}
2022-10-24 14:33:46 +00:00
}
