2022-07-11 14:36:23 +00:00
use bevy_math ::{ DVec2 , IVec2 , UVec2 , Vec2 } ;
bevy_reflect: Reflect enums (#4761)
# Objective
> This is a revival of #1347. Credit for the original PR should go to @Davier.
Currently, enums are treated as `ReflectRef::Value` types by `bevy_reflect`. Obviously, there needs to be better a better representation for enums using the reflection API.
## Solution
Based on prior work from @Davier, an `Enum` trait has been added as well as the ability to automatically implement it via the `Reflect` derive macro. This allows enums to be expressed dynamically:
```rust
#[derive(Reflect)]
enum Foo {
A,
B(usize),
C { value: f32 },
}
let mut foo = Foo::B(123);
assert_eq!("B", foo.variant_name());
assert_eq!(1, foo.field_len());
let new_value = DynamicEnum::from(Foo::C { value: 1.23 });
foo.apply(&new_value);
assert_eq!(Foo::C{value: 1.23}, foo);
```
### Features
#### Derive Macro
Use the `#[derive(Reflect)]` macro to automatically implement the `Enum` trait for enum definitions. Optionally, you can use `#[reflect(ignore)]` with both variants and variant fields, just like you can with structs. These ignored items will not be considered as part of the reflection and cannot be accessed via reflection.
```rust
#[derive(Reflect)]
enum TestEnum {
A,
// Uncomment to ignore all of `B`
// #[reflect(ignore)]
B(usize),
C {
// Uncomment to ignore only field `foo` of `C`
// #[reflect(ignore)]
foo: f32,
bar: bool,
},
}
```
#### Dynamic Enums
Enums may be created/represented dynamically via the `DynamicEnum` struct. The main purpose of this struct is to allow enums to be deserialized into a partial state and to allow dynamic patching. In order to ensure conversion from a `DynamicEnum` to a concrete enum type goes smoothly, be sure to add `FromReflect` to your derive macro.
```rust
let mut value = TestEnum::A;
// Create from a concrete instance
let dyn_enum = DynamicEnum::from(TestEnum::B(123));
value.apply(&dyn_enum);
assert_eq!(TestEnum::B(123), value);
// Create a purely dynamic instance
let dyn_enum = DynamicEnum::new("TestEnum", "A", ());
value.apply(&dyn_enum);
assert_eq!(TestEnum::A, value);
```
#### Variants
An enum value is always represented as one of its variants— never the enum in its entirety.
```rust
let value = TestEnum::A;
assert_eq!("A", value.variant_name());
// Since we are using the `A` variant, we cannot also be the `B` variant
assert_ne!("B", value.variant_name());
```
All variant types are representable within the `Enum` trait: unit, struct, and tuple.
You can get the current type like:
```rust
match value.variant_type() {
VariantType::Unit => println!("A unit variant!"),
VariantType::Struct => println!("A struct variant!"),
VariantType::Tuple => println!("A tuple variant!"),
}
```
> Notice that they don't contain any values representing the fields. These are purely tags.
If a variant has them, you can access the fields as well:
```rust
let mut value = TestEnum::C {
foo: 1.23,
bar: false
};
// Read/write specific fields
*value.field_mut("bar").unwrap() = true;
// Iterate over the entire collection of fields
for field in value.iter_fields() {
println!("{} = {:?}", field.name(), field.value());
}
```
#### Variant Swapping
It might seem odd to group all variant types under a single trait (why allow `iter_fields` on a unit variant?), but the reason this was done ~~is to easily allow *variant swapping*.~~ As I was recently drafting up the **Design Decisions** section, I discovered that other solutions could have been made to work with variant swapping. So while there are reasons to keep the all-in-one approach, variant swapping is _not_ one of them.
```rust
let mut value: Box<dyn Enum> = Box::new(TestEnum::A);
value.set(Box::new(TestEnum::B(123))).unwrap();
```
#### Serialization
Enums can be serialized and deserialized via reflection without needing to implement `Serialize` or `Deserialize` themselves (which can save thousands of lines of generated code). Below are the ways an enum can be serialized.
> Note, like the rest of reflection-based serialization, the order of the keys in these representations is important!
##### Unit
```json
{
"type": "my_crate::TestEnum",
"enum": {
"variant": "A"
}
}
```
##### Tuple
```json
{
"type": "my_crate::TestEnum",
"enum": {
"variant": "B",
"tuple": [
{
"type": "usize",
"value": 123
}
]
}
}
```
<details>
<summary>Effects on Option</summary>
This ends up making `Option` look a little ugly:
```json
{
"type": "core::option::Option<usize>",
"enum": {
"variant": "Some",
"tuple": [
{
"type": "usize",
"value": 123
}
]
}
}
```
</details>
##### Struct
```json
{
"type": "my_crate::TestEnum",
"enum": {
"variant": "C",
"struct": {
"foo": {
"type": "f32",
"value": 1.23
},
"bar": {
"type": "bool",
"value": false
}
}
}
}
```
## Design Decisions
<details>
<summary><strong>View Section</strong></summary>
This section is here to provide some context for why certain decisions were made for this PR, alternatives that could have been used instead, and what could be improved upon in the future.
### Variant Representation
One of the biggest decisions was to decide on how to represent variants. The current design uses a "all-in-one" design where unit, tuple, and struct variants are all simultaneously represented by the `Enum` trait. This is not the only way it could have been done, though.
#### Alternatives
##### 1. Variant Traits
One way of representing variants would be to define traits for each variant, implementing them whenever an enum featured at least one instance of them. This would allow us to define variants like:
```rust
pub trait Enum: Reflect {
fn variant(&self) -> Variant;
}
pub enum Variant<'a> {
Unit,
Tuple(&'a dyn TupleVariant),
Struct(&'a dyn StructVariant),
}
pub trait TupleVariant {
fn field_len(&self) -> usize;
// ...
}
```
And then do things like:
```rust
fn get_tuple_len(foo: &dyn Enum) -> usize {
match foo.variant() {
Variant::Tuple(tuple) => tuple.field_len(),
_ => panic!("not a tuple variant!")
}
}
```
The reason this PR does not go with this approach is because of the fact that variants are not separate types. In other words, we cannot implement traits on specific variants— these cover the *entire* enum. This means we offer an easy footgun:
```rust
let foo: Option<i32> = None;
let my_enum = Box::new(foo) as Box<dyn TupleVariant>;
```
Here, `my_enum` contains `foo`, which is a unit variant. However, since we need to implement `TupleVariant` for `Option` as a whole, it's possible to perform such a cast. This is obviously wrong, but could easily go unnoticed. So unfortunately, this makes it not a good candidate for representing variants.
##### 2. Variant Structs
To get around the issue of traits necessarily needing to apply to both the enum and its variants, we could instead use structs that are created on a per-variant basis. This was also considered but was ultimately [[removed](https://github.com/bevyengine/bevy/pull/4761/commits/71d27ab3c6871bb188d8b46512db3b0922a56a0c)](https://github.com/bevyengine/bevy/pull/4761/commits/71d27ab3c6871bb188d8b46512db3b0922a56a0c) due to concerns about allocations.
Each variant struct would probably look something like:
```rust
pub trait Enum: Reflect {
fn variant_mut(&self) -> VariantMut;
}
pub enum VariantMut<'a> {
Unit,
Tuple(TupleVariantMut),
Struct(StructVariantMut),
}
struct StructVariantMut<'a> {
fields: Vec<&'a mut dyn Reflect>,
field_indices: HashMap<Cow<'static, str>, usize>
}
```
This allows us to isolate struct variants into their own defined struct and define methods specifically for their use. It also prevents users from casting to it since it's not a trait. However, this is not an optimal solution. Both `field_indices` and `fields` will require an allocation (remember, a `Box<[T]>` still requires a `Vec<T>` in order to be constructed). This *might* be a problem if called frequently enough.
##### 3. Generated Structs
The original design, implemented by @Davier, instead generates structs specific for each variant. So if we had a variant path like `Foo::Bar`, we'd generate a struct named `FooBarWrapper`. This would be newtyped around the original enum and forward tuple or struct methods to the enum with the chosen variant.
Because it involved using the `Tuple` and `Struct` traits (which are also both bound on `Reflect`), this meant a bit more code had to be generated. For a single struct variant with one field, the generated code amounted to ~110LoC. However, each new field added to that variant only added ~6 more LoC.
In order to work properly, the enum had to be transmuted to the generated struct:
```rust
fn variant(&self) -> crate::EnumVariant<'_> {
match self {
Foo::Bar {value: i32} => {
let wrapper_ref = unsafe {
std::mem::transmute::<&Self, &FooBarWrapper>(self)
};
crate::EnumVariant::Struct(wrapper_ref as &dyn crate::Struct)
}
}
}
```
This works because `FooBarWrapper` is defined as `repr(transparent)`.
Out of all the alternatives, this would probably be the one most likely to be used again in the future. The reasons for why this PR did not continue to use it was because:
* To reduce generated code (which would hopefully speed up compile times)
* To avoid cluttering the code with generated structs not visible to the user
* To keep bevy_reflect simple and extensible (these generated structs act as proxies and might not play well with current or future systems)
* To avoid additional unsafe blocks
* My own misunderstanding of @Davier's code
That last point is obviously on me. I misjudged the code to be too unsafe and unable to handle variant swapping (which it probably could) when I was rebasing it. Looking over it again when writing up this whole section, I see that it was actually a pretty clever way of handling variant representation.
#### Benefits of All-in-One
As stated before, the current implementation uses an all-in-one approach. All variants are capable of containing fields as far as `Enum` is concerned. This provides a few benefits that the alternatives do not (reduced indirection, safer code, etc.).
The biggest benefit, though, is direct field access. Rather than forcing users to have to go through pattern matching, we grant direct access to the fields contained by the current variant. The reason we can do this is because all of the pattern matching happens internally. Getting the field at index `2` will automatically return `Some(...)` for the current variant if it has a field at that index or `None` if it doesn't (or can't).
This could be useful for scenarios where the variant has already been verified or just set/swapped (or even where the type of variant doesn't matter):
```rust
let dyn_enum: &mut dyn Enum = &mut Foo::Bar {value: 123};
// We know it's the `Bar` variant
let field = dyn_enum.field("value").unwrap();
```
Reflection is not a type-safe abstraction— almost every return value is wrapped in `Option<...>`. There are plenty of places to check and recheck that a value is what Reflect says it is. Forcing users to have to go through `match` each time they want to access a field might just be an extra step among dozens of other verification processes.
Some might disagree, but ultimately, my view is that the benefit here is an improvement to the ergonomics and usability of reflected enums.
</details>
---
## Changelog
### Added
* Added `Enum` trait
* Added `Enum` impl to `Reflect` derive macro
* Added `DynamicEnum` struct
* Added `DynamicVariant`
* Added `EnumInfo`
* Added `VariantInfo`
* Added `StructVariantInfo`
* Added `TupleVariantInfo`
* Added `UnitVariantInfo`
* Added serializtion/deserialization support for enums
* Added `EnumSerializer`
* Added `VariantType`
* Added `VariantFieldIter`
* Added `VariantField`
* Added `enum_partial_eq(...)`
* Added `enum_hash(...)`
### Changed
* `Option<T>` now implements `Enum`
* `bevy_window` now depends on `bevy_reflect`
* Implemented `Reflect` and `FromReflect` for `WindowId`
* Derive `FromReflect` on `PerspectiveProjection`
* Derive `FromReflect` on `OrthographicProjection`
* Derive `FromReflect` on `WindowOrigin`
* Derive `FromReflect` on `ScalingMode`
* Derive `FromReflect` on `DepthCalculation`
## Migration Guide
* Enums no longer need to be treated as values and usages of `#[reflect_value(...)]` can be removed or replaced by `#[reflect(...)]`
* Enums (including `Option<T>`) now take a different format when serializing. The format is described above, but this may cause issues for existing scenes that make use of enums.
---
Also shout out to @nicopap for helping clean up some of the code here! It's a big feature so help like this is really appreciated!
Co-authored-by: Gino Valente <gino.valente.code@gmail.com>
2022-08-02 22:14:41 +00:00
use bevy_reflect ::{ FromReflect , Reflect } ;
2021-03-03 02:56:50 +00:00
use bevy_utils ::{ tracing ::warn , Uuid } ;
2020-04-05 21:12:14 +00:00
bevy_reflect: Reflect enums (#4761)
# Objective
> This is a revival of #1347. Credit for the original PR should go to @Davier.
Currently, enums are treated as `ReflectRef::Value` types by `bevy_reflect`. Obviously, there needs to be better a better representation for enums using the reflection API.
## Solution
Based on prior work from @Davier, an `Enum` trait has been added as well as the ability to automatically implement it via the `Reflect` derive macro. This allows enums to be expressed dynamically:
```rust
#[derive(Reflect)]
enum Foo {
A,
B(usize),
C { value: f32 },
}
let mut foo = Foo::B(123);
assert_eq!("B", foo.variant_name());
assert_eq!(1, foo.field_len());
let new_value = DynamicEnum::from(Foo::C { value: 1.23 });
foo.apply(&new_value);
assert_eq!(Foo::C{value: 1.23}, foo);
```
### Features
#### Derive Macro
Use the `#[derive(Reflect)]` macro to automatically implement the `Enum` trait for enum definitions. Optionally, you can use `#[reflect(ignore)]` with both variants and variant fields, just like you can with structs. These ignored items will not be considered as part of the reflection and cannot be accessed via reflection.
```rust
#[derive(Reflect)]
enum TestEnum {
A,
// Uncomment to ignore all of `B`
// #[reflect(ignore)]
B(usize),
C {
// Uncomment to ignore only field `foo` of `C`
// #[reflect(ignore)]
foo: f32,
bar: bool,
},
}
```
#### Dynamic Enums
Enums may be created/represented dynamically via the `DynamicEnum` struct. The main purpose of this struct is to allow enums to be deserialized into a partial state and to allow dynamic patching. In order to ensure conversion from a `DynamicEnum` to a concrete enum type goes smoothly, be sure to add `FromReflect` to your derive macro.
```rust
let mut value = TestEnum::A;
// Create from a concrete instance
let dyn_enum = DynamicEnum::from(TestEnum::B(123));
value.apply(&dyn_enum);
assert_eq!(TestEnum::B(123), value);
// Create a purely dynamic instance
let dyn_enum = DynamicEnum::new("TestEnum", "A", ());
value.apply(&dyn_enum);
assert_eq!(TestEnum::A, value);
```
#### Variants
An enum value is always represented as one of its variants— never the enum in its entirety.
```rust
let value = TestEnum::A;
assert_eq!("A", value.variant_name());
// Since we are using the `A` variant, we cannot also be the `B` variant
assert_ne!("B", value.variant_name());
```
All variant types are representable within the `Enum` trait: unit, struct, and tuple.
You can get the current type like:
```rust
match value.variant_type() {
VariantType::Unit => println!("A unit variant!"),
VariantType::Struct => println!("A struct variant!"),
VariantType::Tuple => println!("A tuple variant!"),
}
```
> Notice that they don't contain any values representing the fields. These are purely tags.
If a variant has them, you can access the fields as well:
```rust
let mut value = TestEnum::C {
foo: 1.23,
bar: false
};
// Read/write specific fields
*value.field_mut("bar").unwrap() = true;
// Iterate over the entire collection of fields
for field in value.iter_fields() {
println!("{} = {:?}", field.name(), field.value());
}
```
#### Variant Swapping
It might seem odd to group all variant types under a single trait (why allow `iter_fields` on a unit variant?), but the reason this was done ~~is to easily allow *variant swapping*.~~ As I was recently drafting up the **Design Decisions** section, I discovered that other solutions could have been made to work with variant swapping. So while there are reasons to keep the all-in-one approach, variant swapping is _not_ one of them.
```rust
let mut value: Box<dyn Enum> = Box::new(TestEnum::A);
value.set(Box::new(TestEnum::B(123))).unwrap();
```
#### Serialization
Enums can be serialized and deserialized via reflection without needing to implement `Serialize` or `Deserialize` themselves (which can save thousands of lines of generated code). Below are the ways an enum can be serialized.
> Note, like the rest of reflection-based serialization, the order of the keys in these representations is important!
##### Unit
```json
{
"type": "my_crate::TestEnum",
"enum": {
"variant": "A"
}
}
```
##### Tuple
```json
{
"type": "my_crate::TestEnum",
"enum": {
"variant": "B",
"tuple": [
{
"type": "usize",
"value": 123
}
]
}
}
```
<details>
<summary>Effects on Option</summary>
This ends up making `Option` look a little ugly:
```json
{
"type": "core::option::Option<usize>",
"enum": {
"variant": "Some",
"tuple": [
{
"type": "usize",
"value": 123
}
]
}
}
```
</details>
##### Struct
```json
{
"type": "my_crate::TestEnum",
"enum": {
"variant": "C",
"struct": {
"foo": {
"type": "f32",
"value": 1.23
},
"bar": {
"type": "bool",
"value": false
}
}
}
}
```
## Design Decisions
<details>
<summary><strong>View Section</strong></summary>
This section is here to provide some context for why certain decisions were made for this PR, alternatives that could have been used instead, and what could be improved upon in the future.
### Variant Representation
One of the biggest decisions was to decide on how to represent variants. The current design uses a "all-in-one" design where unit, tuple, and struct variants are all simultaneously represented by the `Enum` trait. This is not the only way it could have been done, though.
#### Alternatives
##### 1. Variant Traits
One way of representing variants would be to define traits for each variant, implementing them whenever an enum featured at least one instance of them. This would allow us to define variants like:
```rust
pub trait Enum: Reflect {
fn variant(&self) -> Variant;
}
pub enum Variant<'a> {
Unit,
Tuple(&'a dyn TupleVariant),
Struct(&'a dyn StructVariant),
}
pub trait TupleVariant {
fn field_len(&self) -> usize;
// ...
}
```
And then do things like:
```rust
fn get_tuple_len(foo: &dyn Enum) -> usize {
match foo.variant() {
Variant::Tuple(tuple) => tuple.field_len(),
_ => panic!("not a tuple variant!")
}
}
```
The reason this PR does not go with this approach is because of the fact that variants are not separate types. In other words, we cannot implement traits on specific variants— these cover the *entire* enum. This means we offer an easy footgun:
```rust
let foo: Option<i32> = None;
let my_enum = Box::new(foo) as Box<dyn TupleVariant>;
```
Here, `my_enum` contains `foo`, which is a unit variant. However, since we need to implement `TupleVariant` for `Option` as a whole, it's possible to perform such a cast. This is obviously wrong, but could easily go unnoticed. So unfortunately, this makes it not a good candidate for representing variants.
##### 2. Variant Structs
To get around the issue of traits necessarily needing to apply to both the enum and its variants, we could instead use structs that are created on a per-variant basis. This was also considered but was ultimately [[removed](https://github.com/bevyengine/bevy/pull/4761/commits/71d27ab3c6871bb188d8b46512db3b0922a56a0c)](https://github.com/bevyengine/bevy/pull/4761/commits/71d27ab3c6871bb188d8b46512db3b0922a56a0c) due to concerns about allocations.
Each variant struct would probably look something like:
```rust
pub trait Enum: Reflect {
fn variant_mut(&self) -> VariantMut;
}
pub enum VariantMut<'a> {
Unit,
Tuple(TupleVariantMut),
Struct(StructVariantMut),
}
struct StructVariantMut<'a> {
fields: Vec<&'a mut dyn Reflect>,
field_indices: HashMap<Cow<'static, str>, usize>
}
```
This allows us to isolate struct variants into their own defined struct and define methods specifically for their use. It also prevents users from casting to it since it's not a trait. However, this is not an optimal solution. Both `field_indices` and `fields` will require an allocation (remember, a `Box<[T]>` still requires a `Vec<T>` in order to be constructed). This *might* be a problem if called frequently enough.
##### 3. Generated Structs
The original design, implemented by @Davier, instead generates structs specific for each variant. So if we had a variant path like `Foo::Bar`, we'd generate a struct named `FooBarWrapper`. This would be newtyped around the original enum and forward tuple or struct methods to the enum with the chosen variant.
Because it involved using the `Tuple` and `Struct` traits (which are also both bound on `Reflect`), this meant a bit more code had to be generated. For a single struct variant with one field, the generated code amounted to ~110LoC. However, each new field added to that variant only added ~6 more LoC.
In order to work properly, the enum had to be transmuted to the generated struct:
```rust
fn variant(&self) -> crate::EnumVariant<'_> {
match self {
Foo::Bar {value: i32} => {
let wrapper_ref = unsafe {
std::mem::transmute::<&Self, &FooBarWrapper>(self)
};
crate::EnumVariant::Struct(wrapper_ref as &dyn crate::Struct)
}
}
}
```
This works because `FooBarWrapper` is defined as `repr(transparent)`.
Out of all the alternatives, this would probably be the one most likely to be used again in the future. The reasons for why this PR did not continue to use it was because:
* To reduce generated code (which would hopefully speed up compile times)
* To avoid cluttering the code with generated structs not visible to the user
* To keep bevy_reflect simple and extensible (these generated structs act as proxies and might not play well with current or future systems)
* To avoid additional unsafe blocks
* My own misunderstanding of @Davier's code
That last point is obviously on me. I misjudged the code to be too unsafe and unable to handle variant swapping (which it probably could) when I was rebasing it. Looking over it again when writing up this whole section, I see that it was actually a pretty clever way of handling variant representation.
#### Benefits of All-in-One
As stated before, the current implementation uses an all-in-one approach. All variants are capable of containing fields as far as `Enum` is concerned. This provides a few benefits that the alternatives do not (reduced indirection, safer code, etc.).
The biggest benefit, though, is direct field access. Rather than forcing users to have to go through pattern matching, we grant direct access to the fields contained by the current variant. The reason we can do this is because all of the pattern matching happens internally. Getting the field at index `2` will automatically return `Some(...)` for the current variant if it has a field at that index or `None` if it doesn't (or can't).
This could be useful for scenarios where the variant has already been verified or just set/swapped (or even where the type of variant doesn't matter):
```rust
let dyn_enum: &mut dyn Enum = &mut Foo::Bar {value: 123};
// We know it's the `Bar` variant
let field = dyn_enum.field("value").unwrap();
```
Reflection is not a type-safe abstraction— almost every return value is wrapped in `Option<...>`. There are plenty of places to check and recheck that a value is what Reflect says it is. Forcing users to have to go through `match` each time they want to access a field might just be an extra step among dozens of other verification processes.
Some might disagree, but ultimately, my view is that the benefit here is an improvement to the ergonomics and usability of reflected enums.
</details>
---
## Changelog
### Added
* Added `Enum` trait
* Added `Enum` impl to `Reflect` derive macro
* Added `DynamicEnum` struct
* Added `DynamicVariant`
* Added `EnumInfo`
* Added `VariantInfo`
* Added `StructVariantInfo`
* Added `TupleVariantInfo`
* Added `UnitVariantInfo`
* Added serializtion/deserialization support for enums
* Added `EnumSerializer`
* Added `VariantType`
* Added `VariantFieldIter`
* Added `VariantField`
* Added `enum_partial_eq(...)`
* Added `enum_hash(...)`
### Changed
* `Option<T>` now implements `Enum`
* `bevy_window` now depends on `bevy_reflect`
* Implemented `Reflect` and `FromReflect` for `WindowId`
* Derive `FromReflect` on `PerspectiveProjection`
* Derive `FromReflect` on `OrthographicProjection`
* Derive `FromReflect` on `WindowOrigin`
* Derive `FromReflect` on `ScalingMode`
* Derive `FromReflect` on `DepthCalculation`
## Migration Guide
* Enums no longer need to be treated as values and usages of `#[reflect_value(...)]` can be removed or replaced by `#[reflect(...)]`
* Enums (including `Option<T>`) now take a different format when serializing. The format is described above, but this may cause issues for existing scenes that make use of enums.
---
Also shout out to @nicopap for helping clean up some of the code here! It's a big feature so help like this is really appreciated!
Co-authored-by: Gino Valente <gino.valente.code@gmail.com>
2022-08-02 22:14:41 +00:00
#[ derive(Copy, Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Reflect, FromReflect) ]
#[ reflect_value(PartialEq, Hash) ]
2022-06-16 13:20:37 +00:00
/// A unique ID for a [`Window`].
Derived `Copy` trait for `bevy_input` events, `Serialize`/`Deserialize` for events in `bevy_input` and `bevy_windows`, `PartialEq` for events in both, and `Eq` where possible in both. (#6023)
# Objective
Add traits to events in `bevy_input` and `bevy_windows`: `Copy`, `Serialize`/`Deserialize`, `PartialEq`, and `Eq`, as requested in https://github.com/bevyengine/bevy/issues/6022, https://github.com/bevyengine/bevy/issues/6023, https://github.com/bevyengine/bevy/issues/6024.
## Solution
Added the traits to events in `bevy_input` and `bevy_windows`. Added dependency of `serde` in `Cargo.toml` of `bevy_input`.
## Migration Guide
If one has been `.clone()`'ing `bevy_input` events, Clippy will now complain about that. Just remove `.clone()` to solve.
## Other Notes
Some events in `bevy_input` had `f32` fields, so `Eq` trait was not derived for them.
Some events in `bevy_windows` had `String` fields, so `Copy` trait was not derived for them.
Co-authored-by: targrub <62773321+targrub@users.noreply.github.com>
2022-09-20 18:24:00 +00:00
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
2020-04-05 21:12:14 +00:00
pub struct WindowId ( Uuid ) ;
2022-02-04 03:37:44 +00:00
/// Presentation mode for a window.
///
/// The presentation mode specifies when a frame is presented to the window. The `Fifo`
/// option corresponds to a traditional `VSync`, where the framerate is capped by the
/// display refresh rate. Both `Immediate` and `Mailbox` are low-latency and are not
/// capped by the refresh rate, but may not be available on all platforms. Tearing
/// may be observed with `Immediate` mode, but will not be observed with `Mailbox` or
/// `Fifo`.
///
2022-10-05 13:51:32 +00:00
/// `AutoVsync` or `AutoNoVsync` will gracefully fallback to `Fifo` when unavailable.
2022-02-04 03:37:44 +00:00
///
2022-10-05 13:51:32 +00:00
/// `Immediate` or `Mailbox` will panic if not supported by the platform.
///
/// The presentation mode may be declared in the [`WindowDescriptor`](WindowDescriptor) using [`WindowDescriptor::present_mode`](WindowDescriptor::present_mode)
/// or updated on a [`Window`](Window) using [`set_present_mode`](Window::set_present_mode).
2022-02-04 03:37:44 +00:00
#[ repr(C) ]
#[ derive(Copy, Clone, Debug, PartialEq, Eq, Hash) ]
Derived `Copy` trait for `bevy_input` events, `Serialize`/`Deserialize` for events in `bevy_input` and `bevy_windows`, `PartialEq` for events in both, and `Eq` where possible in both. (#6023)
# Objective
Add traits to events in `bevy_input` and `bevy_windows`: `Copy`, `Serialize`/`Deserialize`, `PartialEq`, and `Eq`, as requested in https://github.com/bevyengine/bevy/issues/6022, https://github.com/bevyengine/bevy/issues/6023, https://github.com/bevyengine/bevy/issues/6024.
## Solution
Added the traits to events in `bevy_input` and `bevy_windows`. Added dependency of `serde` in `Cargo.toml` of `bevy_input`.
## Migration Guide
If one has been `.clone()`'ing `bevy_input` events, Clippy will now complain about that. Just remove `.clone()` to solve.
## Other Notes
Some events in `bevy_input` had `f32` fields, so `Eq` trait was not derived for them.
Some events in `bevy_windows` had `String` fields, so `Copy` trait was not derived for them.
Co-authored-by: targrub <62773321+targrub@users.noreply.github.com>
2022-09-20 18:24:00 +00:00
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
2022-02-04 03:37:44 +00:00
#[ doc(alias = " vsync " ) ]
pub enum PresentMode {
2022-07-14 21:17:16 +00:00
/// Chooses FifoRelaxed -> Fifo based on availability.
///
/// Because of the fallback behavior, it is supported everywhere.
AutoVsync = 0 ,
/// Chooses Immediate -> Mailbox -> Fifo (on web) based on availability.
///
/// Because of the fallback behavior, it is supported everywhere.
AutoNoVsync = 1 ,
2022-02-04 03:37:44 +00:00
/// The presentation engine does **not** wait for a vertical blanking period and
/// the request is presented immediately. This is a low-latency presentation mode,
2022-10-05 13:51:32 +00:00
/// but visible tearing may be observed. Not optimal for mobile.
2022-07-14 21:17:16 +00:00
///
/// Selecting this variant will panic if not supported, it is preferred to use
/// [`PresentMode::AutoNoVsync`].
Immediate = 2 ,
2022-02-04 03:37:44 +00:00
/// The presentation engine waits for the next vertical blanking period to update
/// the current image, but frames may be submitted without delay. This is a low-latency
2022-10-05 13:51:32 +00:00
/// presentation mode and visible tearing will **not** be observed. Not optimal for mobile.
2022-07-14 21:17:16 +00:00
///
/// Selecting this variant will panic if not supported, it is preferred to use
/// [`PresentMode::AutoNoVsync`].
Mailbox = 3 ,
2022-02-04 03:37:44 +00:00
/// The presentation engine waits for the next vertical blanking period to update
/// the current image. The framerate will be capped at the display refresh rate,
/// corresponding to the `VSync`. Tearing cannot be observed. Optimal for mobile.
2022-07-14 21:17:16 +00:00
Fifo = 4 , // NOTE: The explicit ordinal values mirror wgpu.
2022-02-04 03:37:44 +00:00
}
2022-10-24 14:53:19 +00:00
/// Specifies how the alpha channel of the textures should be handled during compositing.
#[ repr(C) ]
#[ derive(Debug, Clone, Copy, PartialEq, Eq, Hash) ]
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
pub enum CompositeAlphaMode {
/// Chooses either `Opaque` or `Inherit` automatically，
/// `alpha_mode` that the current surface can support.
Auto = 0 ,
/// The alpha channel, if it exists, of the textures is ignored in the
/// compositing process. Instead, the textures is treated as if it has a
/// constant alpha of 1.0.
Opaque = 1 ,
/// The alpha channel, if it exists, of the textures is respected in the
/// compositing process. The non-alpha channels of the textures are
/// expected to already be multiplied by the alpha channel by the
/// application.
PreMultiplied = 2 ,
/// The alpha channel, if it exists, of the textures is respected in the
/// compositing process. The non-alpha channels of the textures are not
/// expected to already be multiplied by the alpha channel by the
/// application; instead, the compositor will multiply the non-alpha
/// channels of the texture by the alpha channel during compositing.
PostMultiplied = 3 ,
/// The alpha channel, if it exists, of the textures is unknown for processing
/// during compositing. Instead, the application is responsible for setting
/// the composite alpha blending mode using native WSI command. If not set,
/// then a platform-specific default will be used.
Inherit = 4 ,
}
2020-04-05 21:12:14 +00:00
impl WindowId {
2022-06-16 13:20:37 +00:00
/// Creates a new [`WindowId`].
2020-06-25 23:02:21 +00:00
pub fn new ( ) -> Self {
WindowId ( Uuid ::new_v4 ( ) )
}
2022-06-16 13:20:37 +00:00
/// The [`WindowId`] for the primary window.
2022-11-14 23:08:24 +00:00
pub const fn primary ( ) -> Self {
2020-07-25 06:04:45 +00:00
WindowId ( Uuid ::from_u128 ( 0 ) )
}
2022-06-16 13:20:37 +00:00
/// Get whether or not this [`WindowId`] is for the primary window.
2020-07-25 06:04:45 +00:00
pub fn is_primary ( & self ) -> bool {
2020-07-26 19:10:18 +00:00
* self = = WindowId ::primary ( )
2020-07-25 06:04:45 +00:00
}
2020-08-16 07:30:04 +00:00
}
2021-12-20 22:04:45 +00:00
use crate ::CursorIcon ;
2020-08-16 07:30:04 +00:00
use std ::fmt ;
2020-07-25 06:04:45 +00:00
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
use crate ::raw_handle ::RawHandleWrapper ;
2021-06-02 02:59:17 +00:00
2020-08-16 07:30:04 +00:00
impl fmt ::Display for WindowId {
fn fmt ( & self , f : & mut fmt ::Formatter < '_ > ) -> fmt ::Result {
2022-05-30 17:26:23 +00:00
self . 0. as_simple ( ) . fmt ( f )
2020-04-05 21:12:14 +00:00
}
}
2020-07-25 06:04:45 +00:00
impl Default for WindowId {
fn default ( ) -> Self {
WindowId ::primary ( )
}
}
2021-03-03 02:56:50 +00:00
/// The size limits on a window.
2022-06-16 13:20:37 +00:00
///
2021-03-03 02:56:50 +00:00
/// These values are measured in logical pixels, so the user's
/// scale factor does affect the size limits on the window.
/// Please note that if the window is resizable, then when the window is
/// maximized it may have a size outside of these limits. The functionality
/// required to disable maximizing is not yet exposed by winit.
Derived `Copy` trait for `bevy_input` events, `Serialize`/`Deserialize` for events in `bevy_input` and `bevy_windows`, `PartialEq` for events in both, and `Eq` where possible in both. (#6023)
# Objective
Add traits to events in `bevy_input` and `bevy_windows`: `Copy`, `Serialize`/`Deserialize`, `PartialEq`, and `Eq`, as requested in https://github.com/bevyengine/bevy/issues/6022, https://github.com/bevyengine/bevy/issues/6023, https://github.com/bevyengine/bevy/issues/6024.
## Solution
Added the traits to events in `bevy_input` and `bevy_windows`. Added dependency of `serde` in `Cargo.toml` of `bevy_input`.
## Migration Guide
If one has been `.clone()`'ing `bevy_input` events, Clippy will now complain about that. Just remove `.clone()` to solve.
## Other Notes
Some events in `bevy_input` had `f32` fields, so `Eq` trait was not derived for them.
Some events in `bevy_windows` had `String` fields, so `Copy` trait was not derived for them.
Co-authored-by: targrub <62773321+targrub@users.noreply.github.com>
2022-09-20 18:24:00 +00:00
#[ derive(Debug, Clone, Copy, PartialEq) ]
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
2021-03-03 02:56:50 +00:00
pub struct WindowResizeConstraints {
pub min_width : f32 ,
pub min_height : f32 ,
pub max_width : f32 ,
pub max_height : f32 ,
}
impl Default for WindowResizeConstraints {
fn default ( ) -> Self {
Self {
min_width : 180. ,
min_height : 120. ,
max_width : f32 ::INFINITY ,
max_height : f32 ::INFINITY ,
}
}
}
impl WindowResizeConstraints {
2022-02-13 22:33:55 +00:00
#[ must_use ]
pub fn check_constraints ( & self ) -> Self {
2021-03-03 02:56:50 +00:00
let WindowResizeConstraints {
mut min_width ,
mut min_height ,
mut max_width ,
mut max_height ,
} = self ;
min_width = min_width . max ( 1. ) ;
min_height = min_height . max ( 1. ) ;
if max_width < min_width {
warn! (
" The given maximum width {} is smaller than the minimum width {} " ,
max_width , min_width
) ;
max_width = min_width ;
}
if max_height < min_height {
warn! (
" The given maximum height {} is smaller than the minimum height {} " ,
max_height , min_height
) ;
max_height = min_height ;
}
WindowResizeConstraints {
min_width ,
min_height ,
max_width ,
max_height ,
}
}
}
2020-12-13 23:05:56 +00:00
/// An operating system window that can present content and receive user input.
///
2022-06-16 13:20:37 +00:00
/// To create a window, use a [`EventWriter<CreateWindow>`](`crate::CreateWindow`).
///
2020-12-13 23:05:56 +00:00
/// ## Window Sizes
///
/// There are three sizes associated with a window. The physical size which is
/// the height and width in physical pixels on the monitor. The logical size
/// which is the physical size scaled by an operating system provided factor to
/// account for monitors with differing pixel densities or user preference. And
/// the requested size, measured in logical pixels, which is the value submitted
/// to the API when creating the window, or requesting that it be resized.
///
/// The actual size, in logical pixels, of the window may not match the
/// requested size due to operating system limits on the window size, or the
/// quantization of the logical size when converting the physical size to the
/// logical size through the scaling factor.
2022-06-16 13:20:37 +00:00
///
/// ## Accessing a `Window` from a system
///
/// To access a `Window` from a system, use [`bevy_ecs::change_detection::ResMut`]`<`[`crate::Windows`]`>`.
///
/// ### Example
/// ```no_run
/// # use bevy_app::App;
/// # use bevy_window::Windows;
/// # use bevy_ecs::change_detection::ResMut;
/// # fn main(){
/// # App::new().add_system(access_window_system).run();
/// # }
/// fn access_window_system(mut windows: ResMut<Windows>){
2022-07-11 15:28:50 +00:00
/// for mut window in windows.iter_mut() {
2022-06-16 13:20:37 +00:00
/// window.set_title(String::from("Yay, I'm a window!"));
/// }
/// }
/// ```
2022-10-17 14:19:24 +00:00
/// To test code that uses `Window`s, one can test it with varying `Window` parameters by
/// creating `WindowResizeConstraints` or `WindowDescriptor` structures.
/// values by setting
///
/// ```
/// # use bevy_utils::default;
/// # use bevy_window::{Window, WindowCommand, WindowDescriptor, WindowId, WindowResizeConstraints};
/// # fn compute_window_area(w: &Window) -> f32 {
/// # w.width() * w.height()
/// # }
/// # fn grow_window_to_text_size(_window: &mut Window, _text: &str) {}
/// # fn set_new_title(window: &mut Window, text: String) { window.set_title(text); }
/// # fn a_window_resize_test() {
/// let resize_constraints = WindowResizeConstraints {
/// min_width: 400.0,
/// min_height: 300.0,
/// max_width: 1280.0,
/// max_height: 1024.0,
/// };
/// let window_descriptor = WindowDescriptor {
/// width: 800.0,
/// height: 600.0,
/// resizable: true,
/// resize_constraints,
/// ..default()
/// };
/// let mut window = Window::new(
/// WindowId::new(),
/// &window_descriptor,
/// 100, // physical_width
/// 100, // physical_height
/// 1.0, // scale_factor
/// None, None);
///
/// let area = compute_window_area(&window);
/// assert_eq!(area, 100.0 * 100.0);
///
/// grow_window_to_text_size(&mut window, "very long text that does not wrap");
/// assert_eq!(window.physical_width(), window.requested_width() as u32);
/// grow_window_to_text_size(&mut window, "very long text that does wrap, creating a maximum width window");
/// assert_eq!(window.physical_width(), window.requested_width() as u32);
///
/// set_new_title(&mut window, "new title".to_string());
/// let mut found_command = false;
/// for command in window.drain_commands() {
/// if command == (WindowCommand::SetTitle{ title: "new title".to_string() }) {
/// found_command = true;
/// break;
/// }
/// }
/// assert_eq!(found_command, true);
/// }
/// ```
2020-06-22 20:21:39 +00:00
#[ derive(Debug) ]
2020-04-05 21:12:14 +00:00
pub struct Window {
2020-10-15 18:42:19 +00:00
id : WindowId ,
2020-12-13 23:05:56 +00:00
requested_width : f32 ,
requested_height : f32 ,
2020-12-07 21:32:57 +00:00
physical_width : u32 ,
physical_height : u32 ,
2021-03-03 02:56:50 +00:00
resize_constraints : WindowResizeConstraints ,
2021-01-25 04:06:06 +00:00
position : Option < IVec2 > ,
2020-12-28 20:26:50 +00:00
scale_factor_override : Option < f64 > ,
backend_scale_factor : f64 ,
2020-10-15 18:42:19 +00:00
title : String ,
2022-02-04 03:37:44 +00:00
present_mode : PresentMode ,
2020-10-15 18:42:19 +00:00
resizable : bool ,
decorations : bool ,
2021-12-20 22:04:45 +00:00
cursor_icon : CursorIcon ,
2020-10-16 21:07:01 +00:00
cursor_visible : bool ,
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
cursor_grab_mode : CursorGrabMode ,
2021-10-15 23:47:42 +00:00
physical_cursor_position : Option < DVec2 > ,
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
raw_handle : Option < RawHandleWrapper > ,
2021-02-13 05:32:32 +00:00
focused : bool ,
2020-10-15 18:42:19 +00:00
mode : WindowMode ,
Optionally resize Window canvas element to fit parent element (#4726)
Currently Bevy's web canvases are "fixed size". They are manually set to specific dimensions. This might be fine for some games and website layouts, but for sites with flexible layouts, or games that want to "fill" the browser window, Bevy doesn't provide the tools needed to make this easy out of the box.
There are third party plugins like [bevy-web-resizer](https://github.com/frewsxcv/bevy-web-resizer/) that listen for window resizes, take the new dimensions, and resize the winit window accordingly. However this only covers a subset of cases and this is common enough functionality that it should be baked into Bevy.
A significant motivating use case here is the [Bevy WASM Examples page](https://bevyengine.org/examples/). This scales the canvas to fit smaller windows (such as mobile). But this approach both breaks winit's mouse events and removes pixel-perfect rendering (which means we might be rendering too many or too few pixels). https://github.com/bevyengine/bevy-website/issues/371
In an ideal world, winit would support this behavior out of the box. But unfortunately that seems blocked for now: https://github.com/rust-windowing/winit/pull/2074. And it builds on the ResizeObserver api, which isn't supported in all browsers yet (and is only supported in very new versions of the popular browsers).
While we wait for a complete winit solution, I've added a `fit_canvas_to_parent` option to WindowDescriptor / Window, which when enabled will listen for window resizes and resize the Bevy canvas/window to fit its parent element. This enables users to scale bevy canvases using arbitrary CSS, by "inheriting" their parents' size. Note that the wrapper element _is_ required because winit overrides the canvas sizing with absolute values on each resize.
There is one limitation worth calling out here: while the majority of canvas resizes will be triggered by window resizes, modifying element layout at runtime (css animations, javascript-driven element changes, dev-tool-injected changes, etc) will not be detected here. I'm not aware of a good / efficient event-driven way to do this outside of the ResizeObserver api. In practice, window-resize-driven canvas resizing should cover the majority of use cases. Users that want to actively poll for element resizes can just do that (or we can build another feature and let people choose based on their specific needs).
I also took the chance to make a couple of minor tweaks:
* Made the `canvas` window setting available on all platforms. Users shouldn't need to deal with cargo feature selection to support web scenarios. We can just ignore the value on non-web platforms. I added documentation that explains this.
* Removed the redundant "initial create windows" handler. With the addition of the code in this pr, the code duplication was untenable.
This enables a number of patterns:
## Easy "fullscreen window" mode for the default canvas
The "parent element" defaults to the `<body>` element.
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
..default()
})
```
And CSS:
```css
html, body {
margin: 0;
height: 100%;
}
```
## Fit custom canvas to "wrapper" parent element
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
canvas: Some("#bevy".to_string()),
..default()
})
```
And the HTML:
```html
<div style="width: 50%; height: 100%">
<canvas id="bevy"></canvas>
</div>
```
2022-05-20 23:13:48 +00:00
canvas : Option < String > ,
fit_canvas_to_parent : bool ,
2020-10-15 18:42:19 +00:00
command_queue : Vec < WindowCommand > ,
2022-10-24 14:53:19 +00:00
alpha_mode : CompositeAlphaMode ,
2022-11-14 22:34:29 +00:00
always_on_top : bool ,
2020-10-15 18:42:19 +00:00
}
2022-06-16 13:20:37 +00:00
/// A command to be sent to a window.
///
/// Bevy apps don't interact with this `enum` directly. Instead, they should use the methods on [`Window`].
/// This `enum` is meant for authors of windowing plugins. See the documentation on [`crate::WindowPlugin`] for more information.
2022-10-17 14:19:24 +00:00
#[ derive(Debug, PartialEq) ]
Derived `Copy` trait for `bevy_input` events, `Serialize`/`Deserialize` for events in `bevy_input` and `bevy_windows`, `PartialEq` for events in both, and `Eq` where possible in both. (#6023)
# Objective
Add traits to events in `bevy_input` and `bevy_windows`: `Copy`, `Serialize`/`Deserialize`, `PartialEq`, and `Eq`, as requested in https://github.com/bevyengine/bevy/issues/6022, https://github.com/bevyengine/bevy/issues/6023, https://github.com/bevyengine/bevy/issues/6024.
## Solution
Added the traits to events in `bevy_input` and `bevy_windows`. Added dependency of `serde` in `Cargo.toml` of `bevy_input`.
## Migration Guide
If one has been `.clone()`'ing `bevy_input` events, Clippy will now complain about that. Just remove `.clone()` to solve.
## Other Notes
Some events in `bevy_input` had `f32` fields, so `Eq` trait was not derived for them.
Some events in `bevy_windows` had `String` fields, so `Copy` trait was not derived for them.
Co-authored-by: targrub <62773321+targrub@users.noreply.github.com>
2022-09-20 18:24:00 +00:00
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
2020-10-15 18:42:19 +00:00
pub enum WindowCommand {
2022-06-16 13:20:37 +00:00
/// Set the window's [`WindowMode`].
2020-10-15 18:42:19 +00:00
SetWindowMode {
mode : WindowMode ,
2022-07-11 14:36:23 +00:00
resolution : UVec2 ,
2020-10-15 18:42:19 +00:00
} ,
2022-06-16 13:20:37 +00:00
/// Set the window's title.
2020-10-15 18:42:19 +00:00
SetTitle {
title : String ,
} ,
2022-06-16 13:20:37 +00:00
/// Set the window's scale factor.
2020-12-28 20:26:50 +00:00
SetScaleFactor {
scale_factor : f64 ,
} ,
2022-06-16 13:20:37 +00:00
/// Set the window's resolution.
2020-10-15 18:42:19 +00:00
SetResolution {
2022-07-11 14:36:23 +00:00
logical_resolution : Vec2 ,
2020-12-28 20:26:50 +00:00
scale_factor : f64 ,
2020-10-15 18:42:19 +00:00
} ,
2022-06-16 13:20:37 +00:00
/// Set the window's [`PresentMode`].
2022-02-04 03:37:44 +00:00
SetPresentMode {
present_mode : PresentMode ,
2020-10-15 18:42:19 +00:00
} ,
2022-06-16 13:20:37 +00:00
/// Set whether or not the window is resizable.
2020-10-15 18:42:19 +00:00
SetResizable {
resizable : bool ,
} ,
2022-06-16 13:20:37 +00:00
/// Set whether or not the window has decorations.
///
/// Examples of decorations include the close, full screen, and minimize buttons
2020-10-15 18:42:19 +00:00
SetDecorations {
decorations : bool ,
} ,
2022-07-21 20:46:54 +00:00
/// Set whether or not the cursor's position is locked.
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
SetCursorGrabMode {
grab_mode : CursorGrabMode ,
2020-10-16 21:07:01 +00:00
} ,
2022-06-16 13:20:37 +00:00
/// Set the cursor's [`CursorIcon`].
2021-12-20 22:04:45 +00:00
SetCursorIcon {
icon : CursorIcon ,
} ,
2022-06-16 13:20:37 +00:00
/// Set whether or not the cursor is visible.
2020-10-16 21:07:01 +00:00
SetCursorVisibility {
visible : bool ,
} ,
2022-06-16 13:20:37 +00:00
/// Set the cursor's position.
2020-11-26 01:31:10 +00:00
SetCursorPosition {
2020-12-03 20:39:03 +00:00
position : Vec2 ,
2020-11-26 01:31:10 +00:00
} ,
2022-07-21 20:46:54 +00:00
/// Set whether or not the window is maximized.
2020-12-04 22:31:17 +00:00
SetMaximized {
maximized : bool ,
} ,
2022-06-16 13:20:37 +00:00
/// Set whether or not the window is minimized.
2021-01-25 04:06:06 +00:00
SetMinimized {
minimized : bool ,
} ,
2022-09-06 14:45:44 +00:00
/// Set the window's position on the selected monitor.
2021-01-25 04:06:06 +00:00
SetPosition {
2022-09-06 14:45:44 +00:00
monitor_selection : MonitorSelection ,
2021-01-25 04:06:06 +00:00
position : IVec2 ,
} ,
2022-09-06 14:45:44 +00:00
/// Sets the position of the window to be in the center of the selected monitor.
2022-07-04 13:04:14 +00:00
Center ( MonitorSelection ) ,
2022-06-16 13:20:37 +00:00
/// Set the window's [`WindowResizeConstraints`]
2021-03-03 02:56:50 +00:00
SetResizeConstraints {
resize_constraints : WindowResizeConstraints ,
} ,
2022-11-14 22:34:29 +00:00
/// Set whether the window is always on top.
SetAlwaysOnTop {
always_on_top : bool ,
} ,
2022-05-05 13:35:43 +00:00
Close ,
2020-08-13 08:47:40 +00:00
}
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
/// Defines if and how the cursor is grabbed.
///
/// Use this enum with [`Window::set_cursor_grab_mode`] to grab the cursor.
#[ derive(Debug, Clone, Copy, PartialEq, Eq) ]
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
pub enum CursorGrabMode {
/// The cursor can freely leave the window.
None ,
/// The cursor is confined to the window area.
Confined ,
/// The cursor is locked inside the window area to a certain position.
Locked ,
}
2022-06-16 13:20:37 +00:00
/// Defines the way a window is displayed.
2022-07-01 13:41:23 +00:00
#[ derive(Debug, Clone, Copy, PartialEq, Eq) ]
Derived `Copy` trait for `bevy_input` events, `Serialize`/`Deserialize` for events in `bevy_input` and `bevy_windows`, `PartialEq` for events in both, and `Eq` where possible in both. (#6023)
# Objective
Add traits to events in `bevy_input` and `bevy_windows`: `Copy`, `Serialize`/`Deserialize`, `PartialEq`, and `Eq`, as requested in https://github.com/bevyengine/bevy/issues/6022, https://github.com/bevyengine/bevy/issues/6023, https://github.com/bevyengine/bevy/issues/6024.
## Solution
Added the traits to events in `bevy_input` and `bevy_windows`. Added dependency of `serde` in `Cargo.toml` of `bevy_input`.
## Migration Guide
If one has been `.clone()`'ing `bevy_input` events, Clippy will now complain about that. Just remove `.clone()` to solve.
## Other Notes
Some events in `bevy_input` had `f32` fields, so `Eq` trait was not derived for them.
Some events in `bevy_windows` had `String` fields, so `Copy` trait was not derived for them.
Co-authored-by: targrub <62773321+targrub@users.noreply.github.com>
2022-09-20 18:24:00 +00:00
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
2020-08-13 08:47:40 +00:00
pub enum WindowMode {
2022-06-16 13:20:37 +00:00
/// Creates a window that uses the given size.
2020-08-13 08:47:40 +00:00
Windowed ,
2022-06-16 13:20:37 +00:00
/// Creates a borderless window that uses the full size of the screen.
2020-08-13 08:47:40 +00:00
BorderlessFullscreen ,
2022-06-16 13:20:37 +00:00
/// Creates a fullscreen window that will render at desktop resolution.
///
/// The app will use the closest supported size from the given size and scale it to fit the screen.
2021-11-30 23:51:11 +00:00
SizedFullscreen ,
2022-06-16 13:20:37 +00:00
/// Creates a fullscreen window that uses the maximum supported size.
2021-11-30 23:51:11 +00:00
Fullscreen ,
2020-04-05 21:12:14 +00:00
}
impl Window {
2022-06-16 13:20:37 +00:00
/// Creates a new [`Window`].
2020-12-13 23:05:56 +00:00
pub fn new (
id : WindowId ,
window_descriptor : & WindowDescriptor ,
physical_width : u32 ,
physical_height : u32 ,
scale_factor : f64 ,
2021-01-25 04:06:06 +00:00
position : Option < IVec2 > ,
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
raw_handle : Option < RawHandleWrapper > ,
2020-12-13 23:05:56 +00:00
) -> Self {
2020-04-05 21:12:14 +00:00
Window {
2020-06-25 23:02:21 +00:00
id ,
2020-12-13 23:05:56 +00:00
requested_width : window_descriptor . width ,
requested_height : window_descriptor . height ,
2021-01-25 04:06:06 +00:00
position ,
2020-12-13 23:05:56 +00:00
physical_width ,
physical_height ,
2021-03-03 02:56:50 +00:00
resize_constraints : window_descriptor . resize_constraints ,
2020-12-28 20:26:50 +00:00
scale_factor_override : window_descriptor . scale_factor_override ,
backend_scale_factor : scale_factor ,
2020-04-05 21:12:14 +00:00
title : window_descriptor . title . clone ( ) ,
2022-02-04 03:37:44 +00:00
present_mode : window_descriptor . present_mode ,
2020-08-13 08:47:40 +00:00
resizable : window_descriptor . resizable ,
2020-10-05 17:51:36 +00:00
decorations : window_descriptor . decorations ,
2020-10-16 21:07:01 +00:00
cursor_visible : window_descriptor . cursor_visible ,
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
cursor_grab_mode : window_descriptor . cursor_grab_mode ,
2021-12-20 22:04:45 +00:00
cursor_icon : CursorIcon ::Default ,
2021-10-15 23:47:42 +00:00
physical_cursor_position : None ,
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
raw_handle ,
2022-11-14 21:59:18 +00:00
focused : false ,
2020-08-13 08:47:40 +00:00
mode : window_descriptor . mode ,
2020-09-21 23:12:34 +00:00
canvas : window_descriptor . canvas . clone ( ) ,
Optionally resize Window canvas element to fit parent element (#4726)
Currently Bevy's web canvases are "fixed size". They are manually set to specific dimensions. This might be fine for some games and website layouts, but for sites with flexible layouts, or games that want to "fill" the browser window, Bevy doesn't provide the tools needed to make this easy out of the box.
There are third party plugins like [bevy-web-resizer](https://github.com/frewsxcv/bevy-web-resizer/) that listen for window resizes, take the new dimensions, and resize the winit window accordingly. However this only covers a subset of cases and this is common enough functionality that it should be baked into Bevy.
A significant motivating use case here is the [Bevy WASM Examples page](https://bevyengine.org/examples/). This scales the canvas to fit smaller windows (such as mobile). But this approach both breaks winit's mouse events and removes pixel-perfect rendering (which means we might be rendering too many or too few pixels). https://github.com/bevyengine/bevy-website/issues/371
In an ideal world, winit would support this behavior out of the box. But unfortunately that seems blocked for now: https://github.com/rust-windowing/winit/pull/2074. And it builds on the ResizeObserver api, which isn't supported in all browsers yet (and is only supported in very new versions of the popular browsers).
While we wait for a complete winit solution, I've added a `fit_canvas_to_parent` option to WindowDescriptor / Window, which when enabled will listen for window resizes and resize the Bevy canvas/window to fit its parent element. This enables users to scale bevy canvases using arbitrary CSS, by "inheriting" their parents' size. Note that the wrapper element _is_ required because winit overrides the canvas sizing with absolute values on each resize.
There is one limitation worth calling out here: while the majority of canvas resizes will be triggered by window resizes, modifying element layout at runtime (css animations, javascript-driven element changes, dev-tool-injected changes, etc) will not be detected here. I'm not aware of a good / efficient event-driven way to do this outside of the ResizeObserver api. In practice, window-resize-driven canvas resizing should cover the majority of use cases. Users that want to actively poll for element resizes can just do that (or we can build another feature and let people choose based on their specific needs).
I also took the chance to make a couple of minor tweaks:
* Made the `canvas` window setting available on all platforms. Users shouldn't need to deal with cargo feature selection to support web scenarios. We can just ignore the value on non-web platforms. I added documentation that explains this.
* Removed the redundant "initial create windows" handler. With the addition of the code in this pr, the code duplication was untenable.
This enables a number of patterns:
## Easy "fullscreen window" mode for the default canvas
The "parent element" defaults to the `<body>` element.
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
..default()
})
```
And CSS:
```css
html, body {
margin: 0;
height: 100%;
}
```
## Fit custom canvas to "wrapper" parent element
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
canvas: Some("#bevy".to_string()),
..default()
})
```
And the HTML:
```html
<div style="width: 50%; height: 100%">
<canvas id="bevy"></canvas>
</div>
```
2022-05-20 23:13:48 +00:00
fit_canvas_to_parent : window_descriptor . fit_canvas_to_parent ,
2020-10-15 18:42:19 +00:00
command_queue : Vec ::new ( ) ,
2022-10-24 14:53:19 +00:00
alpha_mode : window_descriptor . alpha_mode ,
2022-11-14 22:34:29 +00:00
always_on_top : window_descriptor . always_on_top ,
2020-04-05 21:12:14 +00:00
}
}
2022-06-16 13:20:37 +00:00
/// Get the window's [`WindowId`].
2020-10-15 18:42:19 +00:00
#[ inline ]
pub fn id ( & self ) -> WindowId {
self . id
}
2020-12-13 23:05:56 +00:00
/// The current logical width of the window's client area.
2020-10-15 18:42:19 +00:00
#[ inline ]
2020-12-13 23:05:56 +00:00
pub fn width ( & self ) -> f32 {
2020-12-28 20:26:50 +00:00
( self . physical_width as f64 / self . scale_factor ( ) ) as f32
2020-10-15 18:42:19 +00:00
}
2020-12-13 23:05:56 +00:00
/// The current logical height of the window's client area.
2020-12-07 21:32:57 +00:00
#[ inline ]
2020-12-13 23:05:56 +00:00
pub fn height ( & self ) -> f32 {
2020-12-28 20:26:50 +00:00
( self . physical_height as f64 / self . scale_factor ( ) ) as f32
2020-12-02 04:25:31 +00:00
}
2020-12-13 23:05:56 +00:00
/// The requested window client area width in logical pixels from window
2022-01-09 23:20:13 +00:00
/// creation or the last call to [`set_resolution`](Window::set_resolution).
2020-12-13 23:05:56 +00:00
///
/// This may differ from the actual width depending on OS size limits and
/// the scaling factor for high DPI monitors.
2020-12-07 21:32:57 +00:00
#[ inline ]
2020-12-13 23:05:56 +00:00
pub fn requested_width ( & self ) -> f32 {
self . requested_width
2020-12-02 04:25:31 +00:00
}
2020-12-13 23:05:56 +00:00
/// The requested window client area height in logical pixels from window
2022-01-09 23:20:13 +00:00
/// creation or the last call to [`set_resolution`](Window::set_resolution).
2020-12-13 23:05:56 +00:00
///
/// This may differ from the actual width depending on OS size limits and
/// the scaling factor for high DPI monitors.
2020-10-15 18:42:19 +00:00
#[ inline ]
2020-12-13 23:05:56 +00:00
pub fn requested_height ( & self ) -> f32 {
self . requested_height
2020-12-07 21:32:57 +00:00
}
2020-12-13 23:05:56 +00:00
/// The window's client area width in physical pixels.
2020-12-07 21:32:57 +00:00
#[ inline ]
pub fn physical_width ( & self ) -> u32 {
self . physical_width
}
2020-12-13 23:05:56 +00:00
/// The window's client area height in physical pixels.
2020-12-07 21:32:57 +00:00
#[ inline ]
pub fn physical_height ( & self ) -> u32 {
self . physical_height
2020-10-15 18:42:19 +00:00
}
2021-03-03 02:56:50 +00:00
/// The window's client resize constraint in logical pixels.
#[ inline ]
pub fn resize_constraints ( & self ) -> WindowResizeConstraints {
self . resize_constraints
}
2021-01-25 04:06:06 +00:00
/// The window's client position in physical pixels.
#[ inline ]
pub fn position ( & self ) -> Option < IVec2 > {
self . position
}
2022-06-16 13:20:37 +00:00
/// Set whether or not the window is maximized.
2020-12-04 22:31:17 +00:00
#[ inline ]
pub fn set_maximized ( & mut self , maximized : bool ) {
self . command_queue
. push ( WindowCommand ::SetMaximized { maximized } ) ;
}
2021-01-25 04:06:06 +00:00
/// Sets the window to minimized or back.
///
/// # Platform-specific
/// - iOS / Android / Web: Unsupported.
/// - Wayland: Un-minimize is unsupported.
#[ inline ]
pub fn set_minimized ( & mut self , minimized : bool ) {
self . command_queue
. push ( WindowCommand ::SetMinimized { minimized } ) ;
}
2022-09-06 14:45:44 +00:00
/// Sets the `position` of the window on the selected `monitor` in physical pixels.
2021-01-25 04:06:06 +00:00
///
2022-09-06 14:45:44 +00:00
/// This automatically un-maximizes the window if it's maximized.
2021-01-25 04:06:06 +00:00
///
/// # Platform-specific
///
2021-03-11 00:27:30 +00:00
/// - iOS: Can only be called on the main thread. Sets the top left coordinates of the window in
/// the screen space coordinate system.
2021-01-25 04:06:06 +00:00
/// - Web: Sets the top-left coordinates relative to the viewport.
/// - Android / Wayland: Unsupported.
#[ inline ]
2022-09-06 14:45:44 +00:00
pub fn set_position ( & mut self , monitor : MonitorSelection , position : IVec2 ) {
self . command_queue . push ( WindowCommand ::SetPosition {
monitor_selection : monitor ,
position ,
} ) ;
2021-01-25 04:06:06 +00:00
}
2022-07-04 13:04:14 +00:00
/// Modifies the position of the window to be in the center of the current monitor
///
/// # Platform-specific
/// - iOS: Can only be called on the main thread.
/// - Web / Android / Wayland: Unsupported.
#[ inline ]
pub fn center_window ( & mut self , monitor_selection : MonitorSelection ) {
self . command_queue
. push ( WindowCommand ::Center ( monitor_selection ) ) ;
}
2021-03-03 02:56:50 +00:00
/// Modifies the minimum and maximum window bounds for resizing in logical pixels.
#[ inline ]
pub fn set_resize_constraints ( & mut self , resize_constraints : WindowResizeConstraints ) {
self . command_queue
. push ( WindowCommand ::SetResizeConstraints { resize_constraints } ) ;
}
2022-07-21 20:46:54 +00:00
/// Request the OS to resize the window such the client area matches the specified
/// width and height.
2020-12-28 20:26:50 +00:00
#[ allow(clippy::float_cmp) ]
2020-12-13 23:05:56 +00:00
pub fn set_resolution ( & mut self , width : f32 , height : f32 ) {
2020-12-28 20:26:50 +00:00
if self . requested_width = = width & & self . requested_height = = height {
return ;
}
2021-03-03 02:56:50 +00:00
2020-12-13 23:05:56 +00:00
self . requested_width = width ;
self . requested_height = height ;
2020-12-07 21:32:57 +00:00
self . command_queue . push ( WindowCommand ::SetResolution {
2022-07-11 14:36:23 +00:00
logical_resolution : Vec2 ::new ( self . requested_width , self . requested_height ) ,
2020-12-28 20:26:50 +00:00
scale_factor : self . scale_factor ( ) ,
} ) ;
}
2022-06-16 13:20:37 +00:00
/// Override the os-reported scaling factor.
2020-12-28 20:26:50 +00:00
#[ allow(clippy::float_cmp) ]
pub fn set_scale_factor_override ( & mut self , scale_factor : Option < f64 > ) {
if self . scale_factor_override = = scale_factor {
return ;
}
self . scale_factor_override = scale_factor ;
self . command_queue . push ( WindowCommand ::SetScaleFactor {
scale_factor : self . scale_factor ( ) ,
} ) ;
self . command_queue . push ( WindowCommand ::SetResolution {
2022-07-11 14:36:23 +00:00
logical_resolution : Vec2 ::new ( self . requested_width , self . requested_height ) ,
2020-12-28 20:26:50 +00:00
scale_factor : self . scale_factor ( ) ,
2020-12-07 21:32:57 +00:00
} ) ;
2020-10-15 18:42:19 +00:00
}
2020-12-03 19:30:27 +00:00
#[ allow(missing_docs) ]
#[ inline ]
2020-12-13 23:05:56 +00:00
pub fn update_scale_factor_from_backend ( & mut self , scale_factor : f64 ) {
2020-12-28 20:26:50 +00:00
self . backend_scale_factor = scale_factor ;
2020-10-15 18:42:19 +00:00
}
2020-12-01 02:24:49 +00:00
2020-12-03 19:30:27 +00:00
#[ allow(missing_docs) ]
#[ inline ]
2020-12-13 23:05:56 +00:00
pub fn update_actual_size_from_backend ( & mut self , physical_width : u32 , physical_height : u32 ) {
self . physical_width = physical_width ;
self . physical_height = physical_height ;
2020-12-01 02:24:49 +00:00
}
2021-01-25 04:06:06 +00:00
#[ allow(missing_docs) ]
#[ inline ]
pub fn update_actual_position_from_backend ( & mut self , position : IVec2 ) {
self . position = Some ( position ) ;
}
2020-12-13 23:05:56 +00:00
/// The ratio of physical pixels to logical pixels
///
/// `physical_pixels = logical_pixels * scale_factor`
2020-12-01 02:24:49 +00:00
pub fn scale_factor ( & self ) -> f64 {
2020-12-28 20:26:50 +00:00
self . scale_factor_override
. unwrap_or ( self . backend_scale_factor )
}
/// The window scale factor as reported by the window backend.
2022-06-16 13:20:37 +00:00
///
2022-01-09 23:20:13 +00:00
/// This value is unaffected by [`scale_factor_override`](Window::scale_factor_override).
2020-12-28 20:26:50 +00:00
#[ inline ]
pub fn backend_scale_factor ( & self ) -> f64 {
self . backend_scale_factor
}
2022-06-16 13:20:37 +00:00
/// The scale factor set with [`set_scale_factor_override`](Window::set_scale_factor_override).
///
/// This value may be different from the scale factor reported by the window backend.
2020-12-28 20:26:50 +00:00
#[ inline ]
pub fn scale_factor_override ( & self ) -> Option < f64 > {
self . scale_factor_override
2020-12-01 02:24:49 +00:00
}
2022-06-16 13:20:37 +00:00
/// Get the window's title.
2020-11-11 01:20:31 +00:00
#[ inline ]
2020-10-15 18:42:19 +00:00
pub fn title ( & self ) -> & str {
& self . title
}
2022-06-16 13:20:37 +00:00
/// Set the window's title.
2020-10-15 18:42:19 +00:00
pub fn set_title ( & mut self , title : String ) {
self . title = title . to_string ( ) ;
self . command_queue . push ( WindowCommand ::SetTitle { title } ) ;
}
2020-11-11 01:20:31 +00:00
#[ inline ]
2022-02-04 03:37:44 +00:00
#[ doc(alias = " vsync " ) ]
2022-06-16 13:20:37 +00:00
/// Get the window's [`PresentMode`].
2022-02-04 03:37:44 +00:00
pub fn present_mode ( & self ) -> PresentMode {
self . present_mode
2020-10-15 18:42:19 +00:00
}
2022-10-24 14:53:19 +00:00
#[ inline ]
/// Get the window's [`CompositeAlphaMode`].
pub fn alpha_mode ( & self ) -> CompositeAlphaMode {
self . alpha_mode
}
2020-11-11 01:20:31 +00:00
#[ inline ]
2022-02-04 03:37:44 +00:00
#[ doc(alias = " set_vsync " ) ]
2022-06-16 13:20:37 +00:00
/// Set the window's [`PresentMode`].
2022-02-04 03:37:44 +00:00
pub fn set_present_mode ( & mut self , present_mode : PresentMode ) {
self . present_mode = present_mode ;
self . command_queue
. push ( WindowCommand ::SetPresentMode { present_mode } ) ;
2020-10-15 18:42:19 +00:00
}
2022-06-16 13:20:37 +00:00
/// Get whether or not the window is resizable.
2020-11-11 01:20:31 +00:00
#[ inline ]
2020-10-15 18:42:19 +00:00
pub fn resizable ( & self ) -> bool {
self . resizable
}
2022-06-16 13:20:37 +00:00
/// Set whether or not the window is resizable.
2020-10-15 18:42:19 +00:00
pub fn set_resizable ( & mut self , resizable : bool ) {
self . resizable = resizable ;
self . command_queue
. push ( WindowCommand ::SetResizable { resizable } ) ;
}
2022-06-16 13:20:37 +00:00
/// Get whether or not decorations are enabled.
///
/// (Decorations are the minimize, maximize, and close buttons on desktop apps)
///
/// ## Platform-specific
///
/// **`iOS`**, **`Android`**, and the **`Web`** do not have decorations.
2020-11-11 01:20:31 +00:00
#[ inline ]
2020-10-15 18:42:19 +00:00
pub fn decorations ( & self ) -> bool {
self . decorations
}
2022-06-16 13:20:37 +00:00
/// Set whether or not decorations are enabled.
///
/// (Decorations are the minimize, maximize, and close buttons on desktop apps)
///
/// ## Platform-specific
///
/// **`iOS`**, **`Android`**, and the **`Web`** do not have decorations.
2020-10-15 18:42:19 +00:00
pub fn set_decorations ( & mut self , decorations : bool ) {
self . decorations = decorations ;
self . command_queue
. push ( WindowCommand ::SetDecorations { decorations } ) ;
}
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
/// Get whether or how the cursor is grabbed.
2022-06-16 13:20:37 +00:00
///
/// ## Platform-specific
///
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
/// - **`macOS`** doesn't support cursor grab, but most windowing plugins can emulate it. See [issue #4875](https://github.com/bevyengine/bevy/issues/4875#issuecomment-1153977546) for more information.
2022-06-16 13:20:37 +00:00
/// - **`iOS/Android`** don't have cursors.
2020-11-11 01:20:31 +00:00
#[ inline ]
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
pub fn cursor_grab_mode ( & self ) -> CursorGrabMode {
self . cursor_grab_mode
2020-10-16 21:07:01 +00:00
}
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
/// Set whether and how the cursor is grabbed.
2022-06-16 13:20:37 +00:00
///
/// This doesn't hide the cursor. For that, use [`set_cursor_visibility`](Window::set_cursor_visibility)
///
/// ## Platform-specific
///
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
/// - **`macOS`** doesn't support cursor grab, but most windowing plugins can emulate it. See [issue #4875](https://github.com/bevyengine/bevy/issues/4875#issuecomment-1153977546) for more information.
2022-06-16 13:20:37 +00:00
/// - **`iOS/Android`** don't have cursors.
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
pub fn set_cursor_grab_mode ( & mut self , grab_mode : CursorGrabMode ) {
self . cursor_grab_mode = grab_mode ;
2020-10-16 21:07:01 +00:00
self . command_queue
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
. push ( WindowCommand ::SetCursorGrabMode { grab_mode } ) ;
2020-10-16 21:07:01 +00:00
}
2022-06-16 13:20:37 +00:00
/// Get whether or not the cursor is visible.
///
/// ## Platform-specific
///
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
/// - **`Windows`**, **`X11`**, and **`Wayland`**: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, use [`set_cursor_grab_mode`](Window::set_cursor_grab_mode).
2022-06-16 13:20:37 +00:00
/// - **`macOS`**: The cursor is hidden only when the window is focused.
/// - **`iOS`** and **`Android`** do not have cursors
2020-11-11 01:20:31 +00:00
#[ inline ]
2020-10-16 21:07:01 +00:00
pub fn cursor_visible ( & self ) -> bool {
self . cursor_visible
}
2022-06-16 13:20:37 +00:00
/// Set whether or not the cursor is visible.
///
/// ## Platform-specific
///
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
/// - **`Windows`**, **`X11`**, and **`Wayland`**: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, use [`set_cursor_grab_mode`](Window::set_cursor_grab_mode).
2022-06-16 13:20:37 +00:00
/// - **`macOS`**: The cursor is hidden only when the window is focused.
/// - **`iOS`** and **`Android`** do not have cursors
2022-07-22 15:04:32 +00:00
pub fn set_cursor_visibility ( & mut self , visible_mode : bool ) {
self . cursor_visible = visible_mode ;
2020-10-16 21:07:01 +00:00
self . command_queue . push ( WindowCommand ::SetCursorVisibility {
2022-07-22 15:04:32 +00:00
visible : visible_mode ,
2020-10-16 21:07:01 +00:00
} ) ;
}
2022-06-16 13:20:37 +00:00
/// Get the current [`CursorIcon`]
2021-12-20 22:04:45 +00:00
#[ inline ]
pub fn cursor_icon ( & self ) -> CursorIcon {
self . cursor_icon
}
2022-06-16 13:20:37 +00:00
/// Set the [`CursorIcon`]
2021-12-20 22:04:45 +00:00
pub fn set_cursor_icon ( & mut self , icon : CursorIcon ) {
self . command_queue
. push ( WindowCommand ::SetCursorIcon { icon } ) ;
}
2021-10-15 23:47:42 +00:00
/// The current mouse position, in physical pixels.
#[ inline ]
pub fn physical_cursor_position ( & self ) -> Option < DVec2 > {
self . physical_cursor_position
}
/// The current mouse position, in logical pixels, taking into account the screen scale factor.
2020-12-03 19:30:27 +00:00
#[ inline ]
2021-04-28 21:26:47 +00:00
#[ doc(alias = " mouse position " ) ]
2020-12-03 19:30:27 +00:00
pub fn cursor_position ( & self ) -> Option < Vec2 > {
2021-10-15 23:47:42 +00:00
self . physical_cursor_position
. map ( | p | ( p / self . scale_factor ( ) ) . as_vec2 ( ) )
2020-12-03 19:30:27 +00:00
}
2022-06-16 13:20:37 +00:00
/// Set the cursor's position
2020-12-03 20:39:03 +00:00
pub fn set_cursor_position ( & mut self , position : Vec2 ) {
2020-11-26 01:31:10 +00:00
self . command_queue
2020-12-03 20:39:03 +00:00
. push ( WindowCommand ::SetCursorPosition { position } ) ;
2020-11-26 01:31:10 +00:00
}
2021-02-13 05:32:32 +00:00
#[ allow(missing_docs) ]
#[ inline ]
pub fn update_focused_status_from_backend ( & mut self , focused : bool ) {
self . focused = focused ;
}
2020-12-03 19:30:27 +00:00
#[ allow(missing_docs) ]
#[ inline ]
2021-10-15 23:47:42 +00:00
pub fn update_cursor_physical_position_from_backend ( & mut self , cursor_position : Option < DVec2 > ) {
self . physical_cursor_position = cursor_position ;
2020-12-03 19:30:27 +00:00
}
2022-06-16 13:20:37 +00:00
/// Get the window's [`WindowMode`]
2020-11-11 01:20:31 +00:00
#[ inline ]
2020-10-15 18:42:19 +00:00
pub fn mode ( & self ) -> WindowMode {
self . mode
}
2022-06-16 13:20:37 +00:00
/// Set the window's [`WindowMode`]
2020-10-15 18:42:19 +00:00
pub fn set_mode ( & mut self , mode : WindowMode ) {
self . mode = mode ;
self . command_queue . push ( WindowCommand ::SetWindowMode {
mode ,
2022-07-11 14:36:23 +00:00
resolution : UVec2 ::new ( self . physical_width , self . physical_height ) ,
2020-10-15 18:42:19 +00:00
} ) ;
}
2022-11-14 22:34:29 +00:00
/// Get whether or not the window is always on top.
#[ inline ]
pub fn always_on_top ( & self ) -> bool {
self . always_on_top
}
/// Set whether of not the window is always on top.
pub fn set_always_on_top ( & mut self , always_on_top : bool ) {
self . always_on_top = always_on_top ;
self . command_queue
. push ( WindowCommand ::SetAlwaysOnTop { always_on_top } ) ;
}
2022-06-16 13:20:37 +00:00
/// Close the operating system window corresponding to this [`Window`].
///
2022-05-05 13:35:43 +00:00
/// This will also lead to this [`Window`] being removed from the
/// [`Windows`] resource.
///
/// If the default [`WindowPlugin`] is used, when no windows are
/// open, the [app will exit](bevy_app::AppExit).
/// To disable this behaviour, set `exit_on_all_closed` on the [`WindowPlugin`]
/// to `false`
///
/// [`Windows`]: crate::Windows
/// [`WindowPlugin`]: crate::WindowPlugin
pub fn close ( & mut self ) {
self . command_queue . push ( WindowCommand ::Close ) ;
}
2020-11-11 01:20:31 +00:00
#[ inline ]
2020-10-15 19:49:56 +00:00
pub fn drain_commands ( & mut self ) -> impl Iterator < Item = WindowCommand > + '_ {
2020-10-15 18:42:19 +00:00
self . command_queue . drain ( .. )
}
2022-06-16 13:20:37 +00:00
/// Get whether or not the window has focus.
///
/// A window loses focus when the user switches to another window, and regains focus when the user uses the window again
2021-02-13 05:32:32 +00:00
#[ inline ]
pub fn is_focused ( & self ) -> bool {
self . focused
}
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
/// Get the [`RawHandleWrapper`] corresponding to this window if set.
2022-10-17 14:19:24 +00:00
///
/// During normal use, this can be safely unwrapped; the value should only be [`None`] when synthetically constructed for tests.
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
pub fn raw_handle ( & self ) -> Option < RawHandleWrapper > {
self . raw_handle . as_ref ( ) . cloned ( )
2021-06-02 02:59:17 +00:00
}
Optionally resize Window canvas element to fit parent element (#4726)
Currently Bevy's web canvases are "fixed size". They are manually set to specific dimensions. This might be fine for some games and website layouts, but for sites with flexible layouts, or games that want to "fill" the browser window, Bevy doesn't provide the tools needed to make this easy out of the box.
There are third party plugins like [bevy-web-resizer](https://github.com/frewsxcv/bevy-web-resizer/) that listen for window resizes, take the new dimensions, and resize the winit window accordingly. However this only covers a subset of cases and this is common enough functionality that it should be baked into Bevy.
A significant motivating use case here is the [Bevy WASM Examples page](https://bevyengine.org/examples/). This scales the canvas to fit smaller windows (such as mobile). But this approach both breaks winit's mouse events and removes pixel-perfect rendering (which means we might be rendering too many or too few pixels). https://github.com/bevyengine/bevy-website/issues/371
In an ideal world, winit would support this behavior out of the box. But unfortunately that seems blocked for now: https://github.com/rust-windowing/winit/pull/2074. And it builds on the ResizeObserver api, which isn't supported in all browsers yet (and is only supported in very new versions of the popular browsers).
While we wait for a complete winit solution, I've added a `fit_canvas_to_parent` option to WindowDescriptor / Window, which when enabled will listen for window resizes and resize the Bevy canvas/window to fit its parent element. This enables users to scale bevy canvases using arbitrary CSS, by "inheriting" their parents' size. Note that the wrapper element _is_ required because winit overrides the canvas sizing with absolute values on each resize.
There is one limitation worth calling out here: while the majority of canvas resizes will be triggered by window resizes, modifying element layout at runtime (css animations, javascript-driven element changes, dev-tool-injected changes, etc) will not be detected here. I'm not aware of a good / efficient event-driven way to do this outside of the ResizeObserver api. In practice, window-resize-driven canvas resizing should cover the majority of use cases. Users that want to actively poll for element resizes can just do that (or we can build another feature and let people choose based on their specific needs).
I also took the chance to make a couple of minor tweaks:
* Made the `canvas` window setting available on all platforms. Users shouldn't need to deal with cargo feature selection to support web scenarios. We can just ignore the value on non-web platforms. I added documentation that explains this.
* Removed the redundant "initial create windows" handler. With the addition of the code in this pr, the code duplication was untenable.
This enables a number of patterns:
## Easy "fullscreen window" mode for the default canvas
The "parent element" defaults to the `<body>` element.
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
..default()
})
```
And CSS:
```css
html, body {
margin: 0;
height: 100%;
}
```
## Fit custom canvas to "wrapper" parent element
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
canvas: Some("#bevy".to_string()),
..default()
})
```
And the HTML:
```html
<div style="width: 50%; height: 100%">
<canvas id="bevy"></canvas>
</div>
```
2022-05-20 23:13:48 +00:00
2022-06-16 13:20:37 +00:00
/// The "html canvas" element selector.
///
/// If set, this selector will be used to find a matching html canvas element,
Optionally resize Window canvas element to fit parent element (#4726)
Currently Bevy's web canvases are "fixed size". They are manually set to specific dimensions. This might be fine for some games and website layouts, but for sites with flexible layouts, or games that want to "fill" the browser window, Bevy doesn't provide the tools needed to make this easy out of the box.
There are third party plugins like [bevy-web-resizer](https://github.com/frewsxcv/bevy-web-resizer/) that listen for window resizes, take the new dimensions, and resize the winit window accordingly. However this only covers a subset of cases and this is common enough functionality that it should be baked into Bevy.
A significant motivating use case here is the [Bevy WASM Examples page](https://bevyengine.org/examples/). This scales the canvas to fit smaller windows (such as mobile). But this approach both breaks winit's mouse events and removes pixel-perfect rendering (which means we might be rendering too many or too few pixels). https://github.com/bevyengine/bevy-website/issues/371
In an ideal world, winit would support this behavior out of the box. But unfortunately that seems blocked for now: https://github.com/rust-windowing/winit/pull/2074. And it builds on the ResizeObserver api, which isn't supported in all browsers yet (and is only supported in very new versions of the popular browsers).
While we wait for a complete winit solution, I've added a `fit_canvas_to_parent` option to WindowDescriptor / Window, which when enabled will listen for window resizes and resize the Bevy canvas/window to fit its parent element. This enables users to scale bevy canvases using arbitrary CSS, by "inheriting" their parents' size. Note that the wrapper element _is_ required because winit overrides the canvas sizing with absolute values on each resize.
There is one limitation worth calling out here: while the majority of canvas resizes will be triggered by window resizes, modifying element layout at runtime (css animations, javascript-driven element changes, dev-tool-injected changes, etc) will not be detected here. I'm not aware of a good / efficient event-driven way to do this outside of the ResizeObserver api. In practice, window-resize-driven canvas resizing should cover the majority of use cases. Users that want to actively poll for element resizes can just do that (or we can build another feature and let people choose based on their specific needs).
I also took the chance to make a couple of minor tweaks:
* Made the `canvas` window setting available on all platforms. Users shouldn't need to deal with cargo feature selection to support web scenarios. We can just ignore the value on non-web platforms. I added documentation that explains this.
* Removed the redundant "initial create windows" handler. With the addition of the code in this pr, the code duplication was untenable.
This enables a number of patterns:
## Easy "fullscreen window" mode for the default canvas
The "parent element" defaults to the `<body>` element.
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
..default()
})
```
And CSS:
```css
html, body {
margin: 0;
height: 100%;
}
```
## Fit custom canvas to "wrapper" parent element
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
canvas: Some("#bevy".to_string()),
..default()
})
```
And the HTML:
```html
<div style="width: 50%; height: 100%">
<canvas id="bevy"></canvas>
</div>
```
2022-05-20 23:13:48 +00:00
/// rather than creating a new one.
/// Uses the [CSS selector format](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector).
///
/// This value has no effect on non-web platforms.
#[ inline ]
pub fn canvas ( & self ) -> Option < & str > {
self . canvas . as_deref ( )
}
/// Whether or not to fit the canvas element's size to its parent element's size.
///
/// **Warning**: this will not behave as expected for parents that set their size according to the size of their
/// children. This creates a "feedback loop" that will result in the canvas growing on each resize. When using this
/// feature, ensure the parent's size is not affected by its children.
///
/// This value has no effect on non-web platforms.
#[ inline ]
pub fn fit_canvas_to_parent ( & self ) -> bool {
self . fit_canvas_to_parent
}
2020-04-05 21:12:14 +00:00
}
2022-07-04 13:04:14 +00:00
/// Defines where window should be placed at on creation.
Derived `Copy` trait for `bevy_input` events, `Serialize`/`Deserialize` for events in `bevy_input` and `bevy_windows`, `PartialEq` for events in both, and `Eq` where possible in both. (#6023)
# Objective
Add traits to events in `bevy_input` and `bevy_windows`: `Copy`, `Serialize`/`Deserialize`, `PartialEq`, and `Eq`, as requested in https://github.com/bevyengine/bevy/issues/6022, https://github.com/bevyengine/bevy/issues/6023, https://github.com/bevyengine/bevy/issues/6024.
## Solution
Added the traits to events in `bevy_input` and `bevy_windows`. Added dependency of `serde` in `Cargo.toml` of `bevy_input`.
## Migration Guide
If one has been `.clone()`'ing `bevy_input` events, Clippy will now complain about that. Just remove `.clone()` to solve.
## Other Notes
Some events in `bevy_input` had `f32` fields, so `Eq` trait was not derived for them.
Some events in `bevy_windows` had `String` fields, so `Copy` trait was not derived for them.
Co-authored-by: targrub <62773321+targrub@users.noreply.github.com>
2022-09-20 18:24:00 +00:00
#[ derive(Debug, Clone, Copy, PartialEq) ]
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
2022-07-04 13:04:14 +00:00
pub enum WindowPosition {
2022-09-06 14:45:44 +00:00
/// The position will be set by the window manager.
2022-07-04 13:04:14 +00:00
Automatic ,
2022-09-06 14:45:44 +00:00
/// Center the window on the monitor.
///
/// The monitor to center the window on can be selected with the `monitor` field in `WindowDescriptor`.
Centered ,
/// The window's top-left corner will be placed at the specified position in pixels.
2022-07-04 13:04:14 +00:00
///
2022-09-06 14:45:44 +00:00
/// (0,0) represents top-left corner of the monitor.
2022-07-04 13:04:14 +00:00
///
2022-09-06 14:45:44 +00:00
/// The monitor to position the window on can be selected with the `monitor` field in `WindowDescriptor`.
2022-07-04 13:04:14 +00:00
At ( Vec2 ) ,
}
/// Defines which monitor to use.
Derived `Copy` trait for `bevy_input` events, `Serialize`/`Deserialize` for events in `bevy_input` and `bevy_windows`, `PartialEq` for events in both, and `Eq` where possible in both. (#6023)
# Objective
Add traits to events in `bevy_input` and `bevy_windows`: `Copy`, `Serialize`/`Deserialize`, `PartialEq`, and `Eq`, as requested in https://github.com/bevyengine/bevy/issues/6022, https://github.com/bevyengine/bevy/issues/6023, https://github.com/bevyengine/bevy/issues/6024.
## Solution
Added the traits to events in `bevy_input` and `bevy_windows`. Added dependency of `serde` in `Cargo.toml` of `bevy_input`.
## Migration Guide
If one has been `.clone()`'ing `bevy_input` events, Clippy will now complain about that. Just remove `.clone()` to solve.
## Other Notes
Some events in `bevy_input` had `f32` fields, so `Eq` trait was not derived for them.
Some events in `bevy_windows` had `String` fields, so `Copy` trait was not derived for them.
Co-authored-by: targrub <62773321+targrub@users.noreply.github.com>
2022-09-20 18:24:00 +00:00
#[ derive(Debug, Clone, Copy, PartialEq, Eq) ]
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
2022-07-04 13:04:14 +00:00
pub enum MonitorSelection {
/// Uses current monitor of the window.
2022-09-06 14:45:44 +00:00
///
/// Will fall back to the system default if the window has not yet been created.
2022-07-04 13:04:14 +00:00
Current ,
/// Uses primary monitor of the system.
Primary ,
/// Uses monitor with the specified index.
2022-09-06 14:45:44 +00:00
Index ( usize ) ,
2022-07-04 13:04:14 +00:00
}
2022-05-30 16:59:41 +00:00
/// Describes the information needed for creating a window.
///
/// This should be set up before adding the [`WindowPlugin`](crate::WindowPlugin).
/// Most of these settings can also later be configured through the [`Window`](crate::Window) resource.
///
/// See [`examples/window/window_settings.rs`] for usage.
///
/// [`examples/window/window_settings.rs`]: https://github.com/bevyengine/bevy/blob/latest/examples/window/window_settings.rs
Plugins own their settings. Rework PluginGroup trait. (#6336)
# Objective
Fixes #5884 #2879
Alternative to #2988 #5885 #2886
"Immutable" Plugin settings are currently represented as normal ECS resources, which are read as part of plugin init. This presents a number of problems:
1. If a user inserts the plugin settings resource after the plugin is initialized, it will be silently ignored (and use the defaults instead)
2. Users can modify the plugin settings resource after the plugin has been initialized. This creates a false sense of control over settings that can no longer be changed.
(1) and (2) are especially problematic and confusing for the `WindowDescriptor` resource, but this is a general problem.
## Solution
Immutable Plugin settings now live on each Plugin struct (ex: `WindowPlugin`). PluginGroups have been reworked to support overriding plugin values. This also removes the need for the `add_plugins_with` api, as the `add_plugins` api can use the builder pattern directly. Settings that can be used at runtime continue to be represented as ECS resources.
Plugins are now configured like this:
```rust
app.add_plugin(AssetPlugin {
watch_for_changes: true,
..default()
})
```
PluginGroups are now configured like this:
```rust
app.add_plugins(DefaultPlugins
.set(AssetPlugin {
watch_for_changes: true,
..default()
})
)
```
This is an alternative to #2988, which is similar. But I personally prefer this solution for a couple of reasons:
* ~~#2988 doesn't solve (1)~~ #2988 does solve (1) and will panic in that case. I was wrong!
* This PR directly ties plugin settings to Plugin types in a 1:1 relationship, rather than a loose "setup resource" <-> plugin coupling (where the setup resource is consumed by the first plugin that uses it).
* I'm not a huge fan of overloading the ECS resource concept and implementation for something that has very different use cases and constraints.
## Changelog
- PluginGroups can now be configured directly using the builder pattern. Individual plugin values can be overridden by using `plugin_group.set(SomePlugin {})`, which enables overriding default plugin values.
- `WindowDescriptor` plugin settings have been moved to `WindowPlugin` and `AssetServerSettings` have been moved to `AssetPlugin`
- `app.add_plugins_with` has been replaced by using `add_plugins` with the builder pattern.
## Migration Guide
The `WindowDescriptor` settings have been moved from a resource to `WindowPlugin::window`:
```rust
// Old (Bevy 0.8)
app
.insert_resource(WindowDescriptor {
width: 400.0,
..default()
})
.add_plugins(DefaultPlugins)
// New (Bevy 0.9)
app.add_plugins(DefaultPlugins.set(WindowPlugin {
window: WindowDescriptor {
width: 400.0,
..default()
},
..default()
}))
```
The `AssetServerSettings` resource has been removed in favor of direct `AssetPlugin` configuration:
```rust
// Old (Bevy 0.8)
app
.insert_resource(AssetServerSettings {
watch_for_changes: true,
..default()
})
.add_plugins(DefaultPlugins)
// New (Bevy 0.9)
app.add_plugins(DefaultPlugins.set(AssetPlugin {
watch_for_changes: true,
..default()
}))
```
`add_plugins_with` has been replaced by `add_plugins` in combination with the builder pattern:
```rust
// Old (Bevy 0.8)
app.add_plugins_with(DefaultPlugins, |group| group.disable::<AssetPlugin>());
// New (Bevy 0.9)
app.add_plugins(DefaultPlugins.build().disable::<AssetPlugin>());
```
2022-10-24 21:20:33 +00:00
#[ derive(Debug, Clone, PartialEq) ]
Derived `Copy` trait for `bevy_input` events, `Serialize`/`Deserialize` for events in `bevy_input` and `bevy_windows`, `PartialEq` for events in both, and `Eq` where possible in both. (#6023)
# Objective
Add traits to events in `bevy_input` and `bevy_windows`: `Copy`, `Serialize`/`Deserialize`, `PartialEq`, and `Eq`, as requested in https://github.com/bevyengine/bevy/issues/6022, https://github.com/bevyengine/bevy/issues/6023, https://github.com/bevyengine/bevy/issues/6024.
## Solution
Added the traits to events in `bevy_input` and `bevy_windows`. Added dependency of `serde` in `Cargo.toml` of `bevy_input`.
## Migration Guide
If one has been `.clone()`'ing `bevy_input` events, Clippy will now complain about that. Just remove `.clone()` to solve.
## Other Notes
Some events in `bevy_input` had `f32` fields, so `Eq` trait was not derived for them.
Some events in `bevy_windows` had `String` fields, so `Copy` trait was not derived for them.
Co-authored-by: targrub <62773321+targrub@users.noreply.github.com>
2022-09-20 18:24:00 +00:00
#[ cfg_attr(feature = " serialize " , derive(serde::Serialize, serde::Deserialize)) ]
2020-04-05 21:12:14 +00:00
pub struct WindowDescriptor {
2022-05-30 16:59:41 +00:00
/// The requested logical width of the window's client area.
2022-06-16 13:20:37 +00:00
///
2022-05-30 16:59:41 +00:00
/// May vary from the physical width due to different pixel density on different monitors.
2020-12-13 23:05:56 +00:00
pub width : f32 ,
2022-05-30 16:59:41 +00:00
/// The requested logical height of the window's client area.
2022-06-16 13:20:37 +00:00
///
2022-05-30 16:59:41 +00:00
/// May vary from the physical height due to different pixel density on different monitors.
2020-12-13 23:05:56 +00:00
pub height : f32 ,
2022-07-04 13:04:14 +00:00
/// The position on the screen that the window will be placed at.
2022-09-06 14:45:44 +00:00
///
/// The monitor to place the window on can be selected with the `monitor` field.
///
/// Ignored if `mode` is set to something other than [`WindowMode::Windowed`]
///
/// `WindowPosition::Automatic` will be overridden with `WindowPosition::At(Vec2::ZERO)` if a specific monitor is selected.
2022-07-04 13:04:14 +00:00
pub position : WindowPosition ,
2022-09-06 14:45:44 +00:00
/// The monitor to place the window on.
pub monitor : MonitorSelection ,
2022-05-30 16:59:41 +00:00
/// Sets minimum and maximum resize limits.
2021-03-03 02:56:50 +00:00
pub resize_constraints : WindowResizeConstraints ,
2022-05-30 16:59:41 +00:00
/// Overrides the window's ratio of physical pixels to logical pixels.
2022-06-16 13:20:37 +00:00
///
2022-05-30 16:59:41 +00:00
/// If there are some scaling problems on X11 try to set this option to `Some(1.0)`.
2020-12-28 20:26:50 +00:00
pub scale_factor_override : Option < f64 > ,
2022-05-30 16:59:41 +00:00
/// Sets the title that displays on the window top bar, on the system task bar and other OS specific places.
2022-06-16 13:20:37 +00:00
///
2022-05-30 16:59:41 +00:00
/// ## Platform-specific
/// - Web: Unsupported.
2020-04-05 21:12:14 +00:00
pub title : String ,
2022-05-30 16:59:41 +00:00
/// Controls when a frame is presented to the screen.
2022-02-04 03:37:44 +00:00
#[ doc(alias = " vsync " ) ]
2022-06-16 13:20:37 +00:00
/// The window's [`PresentMode`].
///
/// Used to select whether or not VSync is used
2022-02-04 03:37:44 +00:00
pub present_mode : PresentMode ,
2022-05-30 16:59:41 +00:00
/// Sets whether the window is resizable.
2022-06-16 13:20:37 +00:00
///
2022-05-30 16:59:41 +00:00
/// ## Platform-specific
/// - iOS / Android / Web: Unsupported.
2020-08-13 08:47:40 +00:00
pub resizable : bool ,
2022-05-30 16:59:41 +00:00
/// Sets whether the window should have borders and bars.
2020-10-05 17:51:36 +00:00
pub decorations : bool ,
2022-05-30 16:59:41 +00:00
/// Sets whether the cursor is visible when the window has focus.
2020-10-16 21:07:01 +00:00
pub cursor_visible : bool ,
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
/// Sets whether and how the window grabs the cursor.
pub cursor_grab_mode : CursorGrabMode ,
2022-05-30 16:59:41 +00:00
/// Sets the [`WindowMode`](crate::WindowMode).
2022-09-06 14:45:44 +00:00
///
/// The monitor to go fullscreen on can be selected with the `monitor` field.
2020-08-13 08:47:40 +00:00
pub mode : WindowMode ,
2021-12-08 20:53:35 +00:00
/// Sets whether the background of the window should be transparent.
2022-06-16 13:20:37 +00:00
///
2022-05-30 16:59:41 +00:00
/// ## Platform-specific
2021-12-08 20:53:35 +00:00
/// - iOS / Android / Web: Unsupported.
2022-10-24 14:53:18 +00:00
/// - macOS: Not working as expected. See [Bevy #6330](https://github.com/bevyengine/bevy/issues/6330).
/// - Linux (Wayland): Not working as expected. See [Bevy #5779](https://github.com/bevyengine/bevy/issues/5779).
2021-12-08 20:53:35 +00:00
pub transparent : bool ,
2022-06-16 13:20:37 +00:00
/// The "html canvas" element selector.
///
/// If set, this selector will be used to find a matching html canvas element,
Optionally resize Window canvas element to fit parent element (#4726)
Currently Bevy's web canvases are "fixed size". They are manually set to specific dimensions. This might be fine for some games and website layouts, but for sites with flexible layouts, or games that want to "fill" the browser window, Bevy doesn't provide the tools needed to make this easy out of the box.
There are third party plugins like [bevy-web-resizer](https://github.com/frewsxcv/bevy-web-resizer/) that listen for window resizes, take the new dimensions, and resize the winit window accordingly. However this only covers a subset of cases and this is common enough functionality that it should be baked into Bevy.
A significant motivating use case here is the [Bevy WASM Examples page](https://bevyengine.org/examples/). This scales the canvas to fit smaller windows (such as mobile). But this approach both breaks winit's mouse events and removes pixel-perfect rendering (which means we might be rendering too many or too few pixels). https://github.com/bevyengine/bevy-website/issues/371
In an ideal world, winit would support this behavior out of the box. But unfortunately that seems blocked for now: https://github.com/rust-windowing/winit/pull/2074. And it builds on the ResizeObserver api, which isn't supported in all browsers yet (and is only supported in very new versions of the popular browsers).
While we wait for a complete winit solution, I've added a `fit_canvas_to_parent` option to WindowDescriptor / Window, which when enabled will listen for window resizes and resize the Bevy canvas/window to fit its parent element. This enables users to scale bevy canvases using arbitrary CSS, by "inheriting" their parents' size. Note that the wrapper element _is_ required because winit overrides the canvas sizing with absolute values on each resize.
There is one limitation worth calling out here: while the majority of canvas resizes will be triggered by window resizes, modifying element layout at runtime (css animations, javascript-driven element changes, dev-tool-injected changes, etc) will not be detected here. I'm not aware of a good / efficient event-driven way to do this outside of the ResizeObserver api. In practice, window-resize-driven canvas resizing should cover the majority of use cases. Users that want to actively poll for element resizes can just do that (or we can build another feature and let people choose based on their specific needs).
I also took the chance to make a couple of minor tweaks:
* Made the `canvas` window setting available on all platforms. Users shouldn't need to deal with cargo feature selection to support web scenarios. We can just ignore the value on non-web platforms. I added documentation that explains this.
* Removed the redundant "initial create windows" handler. With the addition of the code in this pr, the code duplication was untenable.
This enables a number of patterns:
## Easy "fullscreen window" mode for the default canvas
The "parent element" defaults to the `<body>` element.
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
..default()
})
```
And CSS:
```css
html, body {
margin: 0;
height: 100%;
}
```
## Fit custom canvas to "wrapper" parent element
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
canvas: Some("#bevy".to_string()),
..default()
})
```
And the HTML:
```html
<div style="width: 50%; height: 100%">
<canvas id="bevy"></canvas>
</div>
```
2022-05-20 23:13:48 +00:00
/// rather than creating a new one.
/// Uses the [CSS selector format](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector).
///
/// This value has no effect on non-web platforms.
2020-09-21 23:12:34 +00:00
pub canvas : Option < String > ,
Optionally resize Window canvas element to fit parent element (#4726)
Currently Bevy's web canvases are "fixed size". They are manually set to specific dimensions. This might be fine for some games and website layouts, but for sites with flexible layouts, or games that want to "fill" the browser window, Bevy doesn't provide the tools needed to make this easy out of the box.
There are third party plugins like [bevy-web-resizer](https://github.com/frewsxcv/bevy-web-resizer/) that listen for window resizes, take the new dimensions, and resize the winit window accordingly. However this only covers a subset of cases and this is common enough functionality that it should be baked into Bevy.
A significant motivating use case here is the [Bevy WASM Examples page](https://bevyengine.org/examples/). This scales the canvas to fit smaller windows (such as mobile). But this approach both breaks winit's mouse events and removes pixel-perfect rendering (which means we might be rendering too many or too few pixels). https://github.com/bevyengine/bevy-website/issues/371
In an ideal world, winit would support this behavior out of the box. But unfortunately that seems blocked for now: https://github.com/rust-windowing/winit/pull/2074. And it builds on the ResizeObserver api, which isn't supported in all browsers yet (and is only supported in very new versions of the popular browsers).
While we wait for a complete winit solution, I've added a `fit_canvas_to_parent` option to WindowDescriptor / Window, which when enabled will listen for window resizes and resize the Bevy canvas/window to fit its parent element. This enables users to scale bevy canvases using arbitrary CSS, by "inheriting" their parents' size. Note that the wrapper element _is_ required because winit overrides the canvas sizing with absolute values on each resize.
There is one limitation worth calling out here: while the majority of canvas resizes will be triggered by window resizes, modifying element layout at runtime (css animations, javascript-driven element changes, dev-tool-injected changes, etc) will not be detected here. I'm not aware of a good / efficient event-driven way to do this outside of the ResizeObserver api. In practice, window-resize-driven canvas resizing should cover the majority of use cases. Users that want to actively poll for element resizes can just do that (or we can build another feature and let people choose based on their specific needs).
I also took the chance to make a couple of minor tweaks:
* Made the `canvas` window setting available on all platforms. Users shouldn't need to deal with cargo feature selection to support web scenarios. We can just ignore the value on non-web platforms. I added documentation that explains this.
* Removed the redundant "initial create windows" handler. With the addition of the code in this pr, the code duplication was untenable.
This enables a number of patterns:
## Easy "fullscreen window" mode for the default canvas
The "parent element" defaults to the `<body>` element.
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
..default()
})
```
And CSS:
```css
html, body {
margin: 0;
height: 100%;
}
```
## Fit custom canvas to "wrapper" parent element
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
canvas: Some("#bevy".to_string()),
..default()
})
```
And the HTML:
```html
<div style="width: 50%; height: 100%">
<canvas id="bevy"></canvas>
</div>
```
2022-05-20 23:13:48 +00:00
/// Whether or not to fit the canvas element's size to its parent element's size.
///
/// **Warning**: this will not behave as expected for parents that set their size according to the size of their
/// children. This creates a "feedback loop" that will result in the canvas growing on each resize. When using this
/// feature, ensure the parent's size is not affected by its children.
///
/// This value has no effect on non-web platforms.
pub fit_canvas_to_parent : bool ,
2022-10-24 14:53:19 +00:00
/// Specifies how the alpha channel of the textures should be handled during compositing.
pub alpha_mode : CompositeAlphaMode ,
2022-11-14 22:34:29 +00:00
/// Sets the window to always be on top of other windows.
///
/// ## Platform-specific
/// - iOS / Android / Web: Unsupported.
/// - Linux (Wayland): Unsupported.
pub always_on_top : bool ,
2020-04-05 21:12:14 +00:00
}
impl Default for WindowDescriptor {
fn default ( ) -> Self {
WindowDescriptor {
2022-02-04 02:42:58 +00:00
title : " app " . to_string ( ) ,
2020-12-13 23:05:56 +00:00
width : 1280. ,
height : 720. ,
2022-07-04 13:04:14 +00:00
position : WindowPosition ::Automatic ,
2022-09-06 14:45:44 +00:00
monitor : MonitorSelection ::Current ,
2021-03-03 02:56:50 +00:00
resize_constraints : WindowResizeConstraints ::default ( ) ,
2020-12-28 20:26:50 +00:00
scale_factor_override : None ,
2022-02-04 03:37:44 +00:00
present_mode : PresentMode ::Fifo ,
2020-08-13 08:47:40 +00:00
resizable : true ,
2020-10-05 17:51:36 +00:00
decorations : true ,
Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7 (#6218)
# Objective
- Update `wgpu` to 0.14.0, `naga` to `0.10.0`, `winit` to 0.27.4, `raw-window-handle` to 0.5.0, `ndk` to 0.7.
## Solution
---
## Changelog
### Changed
- Changed `RawWindowHandleWrapper` to `RawHandleWrapper` which wraps both `RawWindowHandle` and `RawDisplayHandle`, which satisfies the `impl HasRawWindowHandle and HasRawDisplayHandle` that `wgpu` 0.14.0 requires.
- Changed `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, change its type from `bool` to `bevy_window::CursorGrabMode`.
## Migration Guide
- Adjust usage of `bevy_window::WindowDescriptor`'s `cursor_locked` to `cursor_grab_mode`, and adjust its type from `bool` to `bevy_window::CursorGrabMode`.
2022-10-19 17:40:23 +00:00
cursor_grab_mode : CursorGrabMode ::None ,
2020-10-16 21:07:01 +00:00
cursor_visible : true ,
2020-08-13 08:47:40 +00:00
mode : WindowMode ::Windowed ,
2021-12-08 20:53:35 +00:00
transparent : false ,
2020-09-21 23:12:34 +00:00
canvas : None ,
Optionally resize Window canvas element to fit parent element (#4726)
Currently Bevy's web canvases are "fixed size". They are manually set to specific dimensions. This might be fine for some games and website layouts, but for sites with flexible layouts, or games that want to "fill" the browser window, Bevy doesn't provide the tools needed to make this easy out of the box.
There are third party plugins like [bevy-web-resizer](https://github.com/frewsxcv/bevy-web-resizer/) that listen for window resizes, take the new dimensions, and resize the winit window accordingly. However this only covers a subset of cases and this is common enough functionality that it should be baked into Bevy.
A significant motivating use case here is the [Bevy WASM Examples page](https://bevyengine.org/examples/). This scales the canvas to fit smaller windows (such as mobile). But this approach both breaks winit's mouse events and removes pixel-perfect rendering (which means we might be rendering too many or too few pixels). https://github.com/bevyengine/bevy-website/issues/371
In an ideal world, winit would support this behavior out of the box. But unfortunately that seems blocked for now: https://github.com/rust-windowing/winit/pull/2074. And it builds on the ResizeObserver api, which isn't supported in all browsers yet (and is only supported in very new versions of the popular browsers).
While we wait for a complete winit solution, I've added a `fit_canvas_to_parent` option to WindowDescriptor / Window, which when enabled will listen for window resizes and resize the Bevy canvas/window to fit its parent element. This enables users to scale bevy canvases using arbitrary CSS, by "inheriting" their parents' size. Note that the wrapper element _is_ required because winit overrides the canvas sizing with absolute values on each resize.
There is one limitation worth calling out here: while the majority of canvas resizes will be triggered by window resizes, modifying element layout at runtime (css animations, javascript-driven element changes, dev-tool-injected changes, etc) will not be detected here. I'm not aware of a good / efficient event-driven way to do this outside of the ResizeObserver api. In practice, window-resize-driven canvas resizing should cover the majority of use cases. Users that want to actively poll for element resizes can just do that (or we can build another feature and let people choose based on their specific needs).
I also took the chance to make a couple of minor tweaks:
* Made the `canvas` window setting available on all platforms. Users shouldn't need to deal with cargo feature selection to support web scenarios. We can just ignore the value on non-web platforms. I added documentation that explains this.
* Removed the redundant "initial create windows" handler. With the addition of the code in this pr, the code duplication was untenable.
This enables a number of patterns:
## Easy "fullscreen window" mode for the default canvas
The "parent element" defaults to the `<body>` element.
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
..default()
})
```
And CSS:
```css
html, body {
margin: 0;
height: 100%;
}
```
## Fit custom canvas to "wrapper" parent element
```rust
app
.insert_resource(WindowDescriptor {
fit_canvas_to_parent: true,
canvas: Some("#bevy".to_string()),
..default()
})
```
And the HTML:
```html
<div style="width: 50%; height: 100%">
<canvas id="bevy"></canvas>
</div>
```
2022-05-20 23:13:48 +00:00
fit_canvas_to_parent : false ,
2022-10-24 14:53:19 +00:00
alpha_mode : CompositeAlphaMode ::Auto ,
2022-11-14 22:34:29 +00:00
always_on_top : false ,
2020-04-05 21:12:14 +00:00
}
}
2020-04-06 23:15:59 +00:00
}
