├── assets
    └── mirror.png
├── .gitignore
├── src
    ├── shaders
    │   └── portal.wgsl
    ├── gizmos.rs
    ├── lib.rs
    ├── material.rs
    ├── picking.rs
    └── camera.rs
├── LICENSE-MIT
├── Cargo.toml
├── examples
    ├── basic.rs
    ├── mirror.rs
    ├── mesh_picking.rs
    └── teleport.rs
├── README.md
└── LICENSE-APACHE


/assets/mirror.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/chompaa/bevy_easy_portals/HEAD/assets/mirror.png


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Rust builds
2 | /target
3 | # This file contains environment-specific configuration like linker settings
4 | .cargo/config.toml
5 | 


--------------------------------------------------------------------------------
/src/shaders/portal.wgsl:
--------------------------------------------------------------------------------
 1 | #import bevy_pbr::{
 2 |     forward_io::VertexOutput,
 3 |     mesh_view_bindings::view, 
 4 |     utils::coords_to_viewport_uv,
 5 | }
 6 | 
 7 | @group(#{MATERIAL_BIND_GROUP}) @binding(0) var base_color_texture: texture_2d<f32>;
 8 | @group(#{MATERIAL_BIND_GROUP}) @binding(1) var base_color_sampler: sampler;
 9 | 
10 | @fragment
11 | fn fragment(mesh: VertexOutput) -> @location(0) vec4<f32> {
12 |     let viewport_uv = coords_to_viewport_uv(mesh.position.xy, view.viewport);
13 |     return textureSample(base_color_texture, base_color_sampler, viewport_uv);
14 | }
15 | 


--------------------------------------------------------------------------------
/LICENSE-MIT:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Permission is hereby granted, free of charge, to any person obtaining a copy
 4 | of this software and associated documentation files (the "Software"), to deal
 5 | in the Software without restriction, including without limitation the rights
 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 7 | copies of the Software, and to permit persons to whom the Software is
 8 | furnished to do so, subject to the following conditions:
 9 | 
10 | The above copyright notice and this permission notice shall be included in all
11 | copies or substantial portions of the Software.
12 | 
13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19 | SOFTWARE.
20 | 


--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
 1 | [package]
 2 | name = "bevy_easy_portals"
 3 | version = "0.6.0"
 4 | edition = "2024"
 5 | description = "Bevy plugin for easy-to-use portals."
 6 | keywords = ["bevy", "gamedev"]
 7 | categories = ["game-development"]
 8 | readme = "README.md"
 9 | license = "MIT OR Apache-2.0"
10 | repository = "https://github.com/chompaa/bevy_easy_portals"
11 | documentation = "https://docs.rs/bevy_easy_portals"
12 | exclude = [".github"]
13 | 
14 | [dependencies]
15 | uuid = { version = "1.11.0", features = ["v4"], optional = true }
16 | 
17 | [dependencies.bevy]
18 | version = "0.17"
19 | default-features = false
20 | features = [
21 | 	"bevy_core_pipeline",
22 | 	"bevy_image",
23 | 	"bevy_pbr",
24 | 	"bevy_render",
25 | 	"bevy_window",
26 | 	"bevy_log",
27 | ]
28 | 
29 | [dev-dependencies.bevy]
30 | version = "0.17"
31 | 
32 | [features]
33 | default = []
34 | gizmos = ["bevy/bevy_gizmos"]
35 | picking = ["bevy/bevy_picking", "dep:uuid"]
36 | 
37 | [lints.clippy]
38 | too_many_arguments = "allow"
39 | type_complexity = "allow"
40 | 
41 | [package.metadata.docs.rs]
42 | all-features = true
43 | 
44 | [[example]]
45 | name = "basic"
46 | 
47 | [[example]]
48 | name = "mesh_picking"
49 | required-features = ["picking"]
50 | 
51 | [[example]]
52 | name = "mirror"
53 | 
54 | [[example]]
55 | name = "teleport"
56 | 


--------------------------------------------------------------------------------
/src/gizmos.rs:
--------------------------------------------------------------------------------
 1 | //! Gizmos for [`Portal`] debugging.
 2 | 
 3 | use bevy::{camera::primitives::Aabb, color::palettes::tailwind::ORANGE_600, prelude::*};
 4 | 
 5 | use crate::Portal;
 6 | 
 7 | #[derive(Reflect, Default, GizmoConfigGroup)]
 8 | pub struct PortalGizmos;
 9 | 
10 | /// Gizmo plugin for [`Portal`] debugging.
11 | ///
12 | /// These gizmos help visualize aspects like [`Portal`] meshes and where the
13 | /// [`Portal::target_transform`] is located (along with its facing direction).
14 | pub struct PortalGizmosPlugin;
15 | 
16 | impl Plugin for PortalGizmosPlugin {
17 |     fn build(&self, app: &mut App) {
18 |         app.init_gizmo_group::<PortalGizmos>()
19 |             .add_systems(Update, (debug_portal_meshes, debug_portal_cameras));
20 |     }
21 | }
22 | 
23 | /// System that renders the [`Aabb`]s of a [`Portal`]'s mesh.
24 | fn debug_portal_meshes(
25 |     mut gizmos: Gizmos<PortalGizmos>,
26 |     portal_query: Query<(&GlobalTransform, &Aabb), With<Portal>>,
27 | ) {
28 |     for (&global_transform, aabb) in &portal_query {
29 |         let transform = Transform {
30 |             translation: global_transform.translation(),
31 |             rotation: global_transform.rotation(),
32 |             scale: (aabb.half_extents * 2.0).into(),
33 |         };
34 |         gizmos.cuboid(transform, ORANGE_600);
35 |     }
36 | }
37 | 
38 | /// System that renders arrows indicating the translation and rotation of [`PortalCamera`]s.
39 | fn debug_portal_cameras(
40 |     mut gizmos: Gizmos<PortalGizmos>,
41 |     portal_query: Query<&Portal>,
42 |     global_transform_query: Query<&GlobalTransform>,
43 | ) {
44 |     for portal in &portal_query {
45 |         let target_transform = global_transform_query
46 |             .get(portal.target)
47 |             .map(GlobalTransform::compute_transform)
48 |             .expect("target should have GlobalTransform");
49 |         let start_target = target_transform.translation;
50 |         let end_target = start_target + target_transform.forward() * 0.5;
51 |         gizmos.arrow(start_target, end_target, ORANGE_600);
52 |     }
53 | }
54 | 


--------------------------------------------------------------------------------
/examples/basic.rs:
--------------------------------------------------------------------------------
 1 | use bevy::{color::palettes::tailwind::ORANGE_600, prelude::*};
 2 | #[cfg(feature = "gizmos")]
 3 | use bevy_easy_portals::gizmos::PortalGizmosPlugin;
 4 | use bevy_easy_portals::{Portal, PortalPlugins};
 5 | 
 6 | fn main() {
 7 |     App::new()
 8 |         .add_plugins((
 9 |             DefaultPlugins,
10 |             PortalPlugins,
11 |             #[cfg(feature = "gizmos")]
12 |             PortalGizmosPlugin,
13 |         ))
14 |         .add_systems(Startup, setup)
15 |         .run();
16 | }
17 | 
18 | fn setup(
19 |     mut commands: Commands,
20 |     mut meshes: ResMut<Assets<Mesh>>,
21 |     mut materials: ResMut<Assets<StandardMaterial>>,
22 | ) {
23 |     let primary_camera = commands
24 |         .spawn((
25 |             Camera3d::default(),
26 |             Camera {
27 |                 clear_color: ClearColorConfig::Custom(Color::BLACK),
28 |                 ..default()
29 |             },
30 |             Transform::from_xyz(-3.5, 0.0, 8.0).looking_at(Vec3::ZERO, Vec3::Y),
31 |         ))
32 |         .id();
33 | 
34 |     commands.insert_resource(AmbientLight {
35 |         brightness: 750.0,
36 |         ..default()
37 |     });
38 | 
39 |     let shape = commands
40 |         .spawn((
41 |             Mesh3d(meshes.add(Cuboid::default())),
42 |             MeshMaterial3d(materials.add(Color::from(ORANGE_600))),
43 |             Transform::from_xyz(1.5, 0.0, 0.0),
44 |         ))
45 |         .id();
46 | 
47 |     let target_transform = Transform::from_xyz(0.0, 0.0, 2.0);
48 |     let target = commands.spawn(target_transform).id();
49 | 
50 |     // We'll set the target relative to our shape, since that's what we want to look at
51 |     commands.entity(shape).add_child(target);
52 | 
53 |     let rectangle = Rectangle::from_size(Vec2::splat(2.5));
54 |     let portal_transform = Transform::from_xyz(-1.5, 0.0, 0.0);
55 |     commands
56 |         .spawn((
57 |             // No need to spawn a material for the mesh here, it will be taken care of by the
58 |             // portal setup
59 |             Mesh3d(meshes.add(rectangle)),
60 |             portal_transform,
61 |             Portal::new(primary_camera, target),
62 |         ))
63 |         .with_children(|parent| {
64 |             // We can use another mesh for our portal if we wish
65 |             parent.spawn((
66 |                 Mesh3d(meshes.add(rectangle)),
67 |                 MeshMaterial3d(materials.add(Color::WHITE.with_alpha(0.05))),
68 |             ));
69 |         });
70 | }
71 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # `bevy_easy_portals`
 2 | 
 3 | Easy-to-use portals for Bevy
 4 | 
 5 | ![screenshot showing a cube being reflected in a mirror using portals](https://raw.githubusercontent.com/chompaa/bevy_easy_portals/main/assets/mirror.png)
 6 | 
 7 | ## Getting Started
 8 | 
 9 | First, add `PortalPlugin` to your app, then use the `Portal` component, et voila!
10 | 
11 | See [the examples](https://github.com/chompaa/bevy_easy_portals/tree/main/examples) for more references.
12 | 
13 | <details>
14 | 
15 | <summary>Example usage</summary>
16 | 
17 | ```rust
18 | use bevy::prelude::*;
19 | use bevy_easy_portals::{Portal, PortalPlugins}
20 | 
21 | fn main() {
22 |     App::new()
23 |         .add_plugins((DefaultPlugins, PortalPlugins))
24 |         .add_systems(Startup, setup)
25 |         .run();
26 | }
27 | 
28 | fn setup(
29 |     mut commands: Commands,
30 |     mut materials: ResMut<Assets<StandardMaterial>>,
31 |     mut meshes: ResMut<Assets<Mesh>>,
32 | ) {
33 |     let primary_camera = commands
34 |         .spawn((Camera3d::default(), Transform::from_xyz(0.0, 0.0, 10.0)))
35 |         .id();
36 | 
37 |     // Spawn something for the portal to look at
38 |     commands.spawn((
39 |         Mesh3d(meshes.add(Cuboid::default())),
40 |         MeshMaterial3d(materials.add(Color::WHITE)),
41 |         Transform::from_xyz(10.0, 0.0, 0.0),
42 |     ));
43 | 
44 |     // Where the portal's target camera should be
45 |     let target = commands.spawn(Transform::from_xyz(10.0, 0.0, 10.0)).id();
46 |     // Where the portal should be located
47 |     let portal_transform = Transform::default();
48 |     // Spawn the portal, omit a material since one will be added automatically
49 |     commands.spawn((
50 |         Mesh3d(meshes.add(Rectangle::default())),
51 |         portal_transform,
52 |         Portal::new(primary_camera, target),
53 |     ));
54 | }
55 | ```
56 | 
57 | </details>
58 | 
59 | ## Compatibility
60 | 
61 | | `bevy_easy_portals` | `bevy` |
62 | | :--                 | :--    |
63 | | `0.6`               | `0.17` |
64 | | `0.5`               | `0.16` |
65 | | `0.3..0.4`          | `0.15` |
66 | | `0.1..0.2`          | `0.14` |
67 | 
68 | ## Features
69 | 
70 | | Feature                | Description                                                       |
71 | | :--                    | :--                                                               |
72 | | `picking`              | Support picking through portals with using your favorite backend  |
73 | | `gizmos`               | Use gizmos for the portal's aabb and camera transform             |
74 | 
75 | ## Contributing
76 | 
77 | Feel free to open a PR!
78 | 
79 | If possible, please try to keep it minimal and scoped.
80 | 
81 | ## Alternatives
82 | 
83 | - [`bevy_basic_portals`](https://github.com/Selene-Amanita/bevy_basic_portals)
84 | 


--------------------------------------------------------------------------------
/examples/mirror.rs:
--------------------------------------------------------------------------------
 1 | use std::f32::consts::PI;
 2 | 
 3 | use bevy::{color::palettes::tailwind::ORANGE_600, prelude::*};
 4 | #[cfg(feature = "gizmos")]
 5 | use bevy_easy_portals::gizmos::PortalGizmosPlugin;
 6 | use bevy_easy_portals::{Portal, PortalPlugins};
 7 | 
 8 | fn main() {
 9 |     App::new()
10 |         .add_plugins((
11 |             DefaultPlugins,
12 |             PortalPlugins,
13 |             #[cfg(feature = "gizmos")]
14 |             PortalGizmosPlugin,
15 |         ))
16 |         .add_systems(Startup, setup)
17 |         .add_systems(Update, rotate_shape)
18 |         .run();
19 | }
20 | 
21 | #[derive(Component)]
22 | struct Shape;
23 | 
24 | fn setup(
25 |     mut commands: Commands,
26 |     mut meshes: ResMut<Assets<Mesh>>,
27 |     mut materials: ResMut<Assets<StandardMaterial>>,
28 | ) {
29 |     // It's important we keep track of this entity, since the portal with require it
30 |     let primary_camera = commands
31 |         .spawn((
32 |             Camera3d::default(),
33 |             Camera {
34 |                 // The portal will inherit properties of the primary camera
35 |                 clear_color: ClearColorConfig::Custom(Color::BLACK),
36 |                 ..default()
37 |             },
38 |             Transform::from_xyz(2.5, 0.0, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
39 |         ))
40 |         .id();
41 | 
42 |     // Spawn a shape so we can see something in the reflection
43 |     let shape_transform = Transform::from_xyz(0.0, 0.0, 4.0);
44 |     commands.spawn((
45 |         Mesh3d(meshes.add(Cuboid::default())),
46 |         MeshMaterial3d(materials.add(Color::from(ORANGE_600))),
47 |         shape_transform,
48 |         Shape,
49 |     ));
50 |     commands.spawn((
51 |         PointLight {
52 |             intensity: 10_000_000.0,
53 |             ..default()
54 |         },
55 |         Transform::from_xyz(0.0, 10.0, 0.0).looking_at(shape_transform.translation, Vec3::Y),
56 |     ));
57 | 
58 |     let rectangle = Rectangle::from_size(Vec2::splat(5.0));
59 | 
60 |     let mirror = commands
61 |         .spawn((
62 |             // No need to spawn a material for the mesh here, it will be taken care of by the
63 |             // portal setup
64 |             Mesh3d(meshes.add(rectangle)),
65 |             Transform::from_xyz(0.0, 0.0, 0.0),
66 |         ))
67 |         .with_children(|parent| {
68 |             // We can use another mesh for our mirror if we wish
69 |             parent.spawn((
70 |                 Mesh3d(meshes.add(rectangle)),
71 |                 MeshMaterial3d(materials.add(Color::WHITE.with_alpha(0.2))),
72 |             ));
73 |         })
74 |         .id();
75 | 
76 |     // The target should be the transform of the mirror itself, but flipped
77 |     let target_transform = Transform::default().with_rotation(Quat::from_rotation_y(PI));
78 |     let target = commands.spawn(target_transform).id();
79 | 
80 |     commands
81 |         .entity(mirror)
82 |         // Since we're constructing a mirror, let's parent the target to the mirror itself
83 |         .add_child(target)
84 |         // Now let's create the portal!
85 |         .insert(Portal::new(primary_camera, target));
86 | }
87 | 
88 | fn rotate_shape(mut shape_transform: Single<&mut Transform, With<Shape>>, time: Res<Time>) {
89 |     let angle = time.delta_secs() / 2.0;
90 |     shape_transform.rotate(Quat::from_axis_angle(Vec3::new(1.0, 1.0, 0.0), angle));
91 | }
92 | 


--------------------------------------------------------------------------------
/src/lib.rs:
--------------------------------------------------------------------------------
  1 | #![doc = include_str!("../README.md")]
  2 | 
  3 | pub mod camera;
  4 | #[cfg(feature = "gizmos")]
  5 | pub mod gizmos;
  6 | pub mod material;
  7 | #[cfg(feature = "picking")]
  8 | pub mod picking;
  9 | 
 10 | use bevy::{app::PluginGroupBuilder, prelude::*, render::render_resource::Face};
 11 | 
 12 | /// A group of plugins that provides the required systems to make a [`Portal`] work.
 13 | pub struct PortalPlugins;
 14 | 
 15 | impl PluginGroup for PortalPlugins {
 16 |     fn build(self) -> PluginGroupBuilder {
 17 |         PluginGroupBuilder::start::<Self>()
 18 |             .add(camera::PortalCameraPlugin)
 19 |             .add(material::PortalMaterialPlugin)
 20 |     }
 21 | }
 22 | 
 23 | /// Component used to create a portal.
 24 | ///
 25 | /// If [`camera::PortalCameraPlugin`] is enabled, adding this to an entity causes a camera (marked
 26 | /// with [`camera::PortalCamera`], and with [`RenderTarget::Image`]) to be spawned, inheriting the
 27 | /// the properties of [`Portal::primary_camera`].
 28 | ///
 29 | /// If [`material::PortalMaterialPlugin`] is enabled, a [`material::PortalMaterial`] is inserted on
 30 | /// the entity, inherting [`Portal::cull_mode`] for convenience.
 31 | ///
 32 | /// [`RenderTarget::Image`]: bevy::render::camera::RenderTarget
 33 | #[non_exhaustive]
 34 | #[derive(Component, Reflect, Debug)]
 35 | #[reflect(Component)]
 36 | #[require(Transform)]
 37 | pub struct Portal {
 38 |     /// The entity with the primary render [`Camera`].
 39 |     ///
 40 |     /// In other words, the camera used to look at this portal.
 41 |     pub primary_camera: Entity,
 42 |     /// The target entity that should be used to decide the camera's position.
 43 |     ///
 44 |     /// This entity should contain a [`Transform`] component.
 45 |     pub target: Entity,
 46 |     /// Specifies which side of the portal to cull: "front", "back", or neither.
 47 |     ///
 48 |     /// If set to `None`, both sides of the portal’s mesh will be rendered.
 49 |     ///
 50 |     /// Defaults to `Some(Face::Back)`, similar to [`StandardMaterial::cull_mode`].
 51 |     ///
 52 |     /// # Note
 53 |     ///
 54 |     /// If you are using `Some(Face::Front)` or `None` here, and your mesh is flat, you should
 55 |     /// consider setting [`Portal::conditionally_flip_near_plane_normal`] to `true`.
 56 |     // TODO: Can this be remotely reflected upstream now that #6042 has landed?
 57 |     #[reflect(ignore)]
 58 |     pub cull_mode: Option<Face>,
 59 |     /// The entity that has this portal's [`camera::PortalCamera`].
 60 |     pub linked_camera: Option<Entity>,
 61 |     /// If set to `true` this will flip the near plane of the [`camera::PortalCamera`]s frustum if
 62 |     /// the primary camera is facing the back face of the portal.
 63 |     ///
 64 |     /// This is particularly useful for portals that are flat meshes and don't have their back face
 65 |     /// culled. In other words, set this to `true` if you have a bidirectional portal with a flat
 66 |     /// mesh. Otherwise, set it to `false`.
 67 |     ///
 68 |     /// Set to `false` by default.
 69 |     pub flip_near_plane_normal: bool,
 70 | }
 71 | 
 72 | impl Portal {
 73 |     /// Creates a new [`Portal`] from a given `primary_camera` and `target`.
 74 |     ///
 75 |     /// # See Also
 76 |     ///
 77 |     /// * [`Portal::primary_camera`]
 78 |     /// * [`Portal::target`]
 79 |     #[inline]
 80 |     #[must_use]
 81 |     pub fn new(primary_camera: Entity, target: Entity) -> Self {
 82 |         Self {
 83 |             primary_camera,
 84 |             target,
 85 |             cull_mode: Some(Face::Back),
 86 |             linked_camera: None,
 87 |             flip_near_plane_normal: false,
 88 |         }
 89 |     }
 90 | 
 91 |     #[inline]
 92 |     #[must_use]
 93 |     pub fn with_cull_mode(mut self, cull_mode: Option<Face>) -> Self {
 94 |         self.cull_mode = cull_mode;
 95 |         self
 96 |     }
 97 | 
 98 |     #[inline]
 99 |     #[must_use]
100 |     pub fn with_flip_near_plane_normal(mut self, with_flip_near_plane_normal: bool) -> Self {
101 |         self.flip_near_plane_normal = with_flip_near_plane_normal;
102 |         self
103 |     }
104 | }
105 | 


--------------------------------------------------------------------------------
/src/material.rs:
--------------------------------------------------------------------------------
  1 | use bevy::{
  2 |     asset::{AssetPath, embedded_asset, embedded_path},
  3 |     core_pipeline::core_3d::CORE_3D_DEPTH_FORMAT,
  4 |     mesh::MeshVertexBufferLayoutRef,
  5 |     pbr::{MaterialPipeline, MaterialPipelineKey},
  6 |     prelude::*,
  7 |     render::render_resource::{
  8 |         AsBindGroup, CompareFunction, DepthBiasState, DepthStencilState, Face,
  9 |         RenderPipelineDescriptor, SpecializedMeshPipelineError, StencilFaceState, StencilState,
 10 |     },
 11 |     shader::ShaderRef,
 12 |     window::WindowResized,
 13 | };
 14 | 
 15 | use crate::{
 16 |     Portal,
 17 |     camera::{PortalCameraSystems, PortalImage},
 18 | };
 19 | 
 20 | pub struct PortalMaterialPlugin;
 21 | 
 22 | impl Plugin for PortalMaterialPlugin {
 23 |     fn build(&self, app: &mut App) {
 24 |         embedded_asset!(app, "shaders/portal.wgsl");
 25 | 
 26 |         app.add_plugins(MaterialPlugin::<PortalMaterial>::default())
 27 |             .add_systems(
 28 |                 PreUpdate,
 29 |                 update_materials::<PortalMaterial>
 30 |                     .run_if(on_message::<WindowResized>)
 31 |                     .after(PortalCameraSystems::ResizeImage),
 32 |             )
 33 |             .add_observer(spawn_material);
 34 |     }
 35 | }
 36 | 
 37 | /// Material used for a [`Portal`]'s mesh.
 38 | #[derive(Asset, AsBindGroup, Clone, Reflect)]
 39 | #[bind_group_data(PortalMaterialKey)]
 40 | pub struct PortalMaterial {
 41 |     #[texture(0)]
 42 |     #[sampler(1)]
 43 |     base_color_texture: Option<Handle<Image>>,
 44 |     /// Specifies which side of the portal to cull: "front", "back", or neither.
 45 |     ///
 46 |     /// If set to `None`, both sides of the portal’s mesh will be rendered.
 47 |     ///
 48 |     /// This field's value is inherited from what is set on [`Portal`], but not kept in sync.
 49 |     ///
 50 |     /// Defaults to `Some(Face::Back)`, similar to [`StandardMaterial::cull_mode`] and [`Portal`].
 51 |     #[reflect(ignore)]
 52 |     pub cull_mode: Option<Face>,
 53 |     /// The effect of draw calls on the depth and stencil aspects of the portal.
 54 |     ///
 55 |     /// You can make use of this field to resolve z-fighting.
 56 |     ///
 57 |     /// Defaults to the standard mesh [`DepthStencilState`].
 58 |     #[reflect(ignore)]
 59 |     pub depth_stencil: Option<DepthStencilState>,
 60 | }
 61 | 
 62 | impl Default for PortalMaterial {
 63 |     fn default() -> Self {
 64 |         Self {
 65 |             base_color_texture: None,
 66 |             cull_mode: Some(Face::Back),
 67 |             depth_stencil: Some(DepthStencilState {
 68 |                 format: CORE_3D_DEPTH_FORMAT,
 69 |                 depth_write_enabled: true,
 70 |                 depth_compare: CompareFunction::GreaterEqual,
 71 |                 stencil: StencilState {
 72 |                     front: StencilFaceState::IGNORE,
 73 |                     back: StencilFaceState::IGNORE,
 74 |                     read_mask: 0,
 75 |                     write_mask: 0,
 76 |                 },
 77 |                 bias: DepthBiasState::default(),
 78 |             }),
 79 |         }
 80 |     }
 81 | }
 82 | 
 83 | impl Material for PortalMaterial {
 84 |     fn fragment_shader() -> ShaderRef {
 85 |         ShaderRef::Path(
 86 |             AssetPath::from_path_buf(embedded_path!("shaders/portal.wgsl")).with_source("embedded"),
 87 |         )
 88 |     }
 89 | 
 90 |     fn specialize(
 91 |         _pipeline: &MaterialPipeline,
 92 |         descriptor: &mut RenderPipelineDescriptor,
 93 |         _layout: &MeshVertexBufferLayoutRef,
 94 |         key: MaterialPipelineKey<Self>,
 95 |     ) -> Result<(), SpecializedMeshPipelineError> {
 96 |         descriptor.primitive.cull_mode = key.bind_group_data.cull_mode;
 97 |         descriptor.depth_stencil = key.bind_group_data.depth_stencil;
 98 |         Ok(())
 99 |     }
100 | }
101 | 
102 | #[derive(Clone, PartialEq, Eq, Hash)]
103 | pub struct PortalMaterialKey {
104 |     cull_mode: Option<Face>,
105 |     depth_stencil: Option<DepthStencilState>,
106 | }
107 | 
108 | impl From<&PortalMaterial> for PortalMaterialKey {
109 |     fn from(material: &PortalMaterial) -> Self {
110 |         Self {
111 |             cull_mode: material.cull_mode,
112 |             depth_stencil: material.depth_stencil.clone(),
113 |         }
114 |     }
115 | }
116 | 
117 | /// Marks all materials `T` that are on [`Portal`] entities as changed in the asset system.
118 | ///
119 | /// See https://github.com/bevyengine/bevy/issues/5069 for context.
120 | pub fn update_materials<T: Material>(
121 |     material_query: Query<&MeshMaterial3d<T>, With<Portal>>,
122 |     mut materials: ResMut<Assets<T>>,
123 | ) {
124 |     for material_handle in &material_query {
125 |         materials.get_mut(material_handle);
126 |     }
127 | }
128 | 
129 | fn spawn_material(
130 |     trigger: On<Add, PortalImage>,
131 |     mut commands: Commands,
132 |     portal_query: Query<(&Portal, &PortalImage)>,
133 |     mut materials: ResMut<Assets<PortalMaterial>>,
134 | ) {
135 |     let entity = trigger.event_target();
136 |     let Ok((portal, portal_image)) = portal_query.get(entity) else {
137 |         return;
138 |     };
139 |     commands
140 |         .entity(entity)
141 |         .insert_if_new(MeshMaterial3d(materials.add(PortalMaterial {
142 |             base_color_texture: Some(portal_image.0.clone()),
143 |             cull_mode: portal.cull_mode,
144 |             ..default()
145 |         })));
146 | }
147 | 


--------------------------------------------------------------------------------
/examples/mesh_picking.rs:
--------------------------------------------------------------------------------
  1 | use std::f32::consts::FRAC_PI_4;
  2 | 
  3 | use bevy::{
  4 |     camera::visibility::RenderLayers,
  5 |     color::palettes::tailwind::{SKY_200, VIOLET_400},
  6 |     picking::pointer::PointerInteraction,
  7 |     prelude::*,
  8 | };
  9 | #[cfg(feature = "gizmos")]
 10 | use bevy_easy_portals::gizmos::{PortalGizmos, PortalGizmosPlugin};
 11 | use bevy_easy_portals::{Portal, PortalPlugins, picking::PortalPickingPlugin};
 12 | 
 13 | fn main() {
 14 |     App::new()
 15 |         .add_plugins((
 16 |             DefaultPlugins,
 17 |             PortalPlugins,
 18 |             PortalPickingPlugin,
 19 |             #[cfg(feature = "gizmos")]
 20 |             PortalGizmosPlugin,
 21 |             MeshPickingPlugin,
 22 |         ))
 23 |         .add_systems(Startup, setup)
 24 |         .add_systems(Update, draw_mesh_intersections)
 25 |         .run();
 26 | }
 27 | 
 28 | #[derive(Component)]
 29 | struct Glass;
 30 | 
 31 | fn setup(
 32 |     mut commands: Commands,
 33 |     mut meshes: ResMut<Assets<Mesh>>,
 34 |     mut materials: ResMut<Assets<StandardMaterial>>,
 35 |     #[cfg(feature = "gizmos")] mut config_store: ResMut<GizmoConfigStore>,
 36 | ) {
 37 |     let primary_camera = commands
 38 |         .spawn((
 39 |             Camera3d::default(),
 40 |             Camera {
 41 |                 clear_color: ClearColorConfig::Custom(Color::BLACK),
 42 |                 ..default()
 43 |             },
 44 |             Transform::from_xyz(0.0, 0.0, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
 45 |             RenderLayers::from_layers(&[0, 1]),
 46 |         ))
 47 |         .id();
 48 | 
 49 |     #[cfg(feature = "gizmos")]
 50 |     {
 51 |         let (config, _) = config_store.config_mut::<PortalGizmos>();
 52 |         config.render_layers = RenderLayers::layer(1)
 53 |     }
 54 | 
 55 |     commands.insert_resource(AmbientLight {
 56 |         brightness: 375.0,
 57 |         ..default()
 58 |     });
 59 | 
 60 |     let idle_material = materials.add(Color::from(SKY_200));
 61 |     let drag_material = materials.add(Color::from(VIOLET_400));
 62 | 
 63 |     commands
 64 |         .spawn((
 65 |             Mesh3d(meshes.add(Cuboid::default())),
 66 |             MeshMaterial3d(idle_material.clone()),
 67 |             Transform::from_xyz(0.0, 0.0, 0.0).with_rotation(Quat::from_rotation_z(-FRAC_PI_4)),
 68 |         ))
 69 |         .observe(rotate_xy_on_drag)
 70 |         .observe(update_material_on::<Pointer<DragStart>>(drag_material))
 71 |         .observe(update_material_on::<Pointer<DragEnd>>(idle_material));
 72 | 
 73 |     let target = commands.spawn(Transform::from_xyz(0.0, 0.0, 2.0)).id();
 74 |     let rectangle = Cuboid::from_size(Vec3::splat(2.0));
 75 | 
 76 |     let idle_material = materials.add(Color::WHITE.with_alpha(0.01));
 77 |     let hover_material = materials.add(Color::WHITE.with_alpha(0.04));
 78 | 
 79 |     for portal_transform in [
 80 |         Transform::from_xyz(-2.5, 0.0, -1.0).with_rotation(Quat::from_rotation_y(FRAC_PI_4)),
 81 |         Transform::from_xyz(2.5, 0.0, -1.0).with_rotation(Quat::from_rotation_y(-FRAC_PI_4)),
 82 |     ] {
 83 |         commands
 84 |             .spawn((
 85 |                 Mesh3d(meshes.add(rectangle)),
 86 |                 portal_transform,
 87 |                 Portal::new(primary_camera, target),
 88 |                 RenderLayers::layer(1),
 89 |                 // We want to be able to hover the glass
 90 |                 Pickable {
 91 |                     should_block_lower: false,
 92 |                     is_hoverable: true,
 93 |                 },
 94 |             ))
 95 |             .with_children(|parent| {
 96 |                 parent
 97 |                     .spawn((
 98 |                         Mesh3d(meshes.add(rectangle)),
 99 |                         MeshMaterial3d(idle_material.clone()),
100 |                         Glass,
101 |                         RenderLayers::layer(1),
102 |                         // Similarly, we want to be able to hover the portal (to pick through)
103 |                         Pickable {
104 |                             should_block_lower: false,
105 |                             is_hoverable: true,
106 |                         },
107 |                     ))
108 |                     .observe(update_material_on::<Pointer<Over>>(hover_material.clone()))
109 |                     .observe(update_material_on::<Pointer<Out>>(idle_material.clone()));
110 |             })
111 |             .observe(rotate_y_on_drag);
112 |     }
113 | }
114 | 
115 | fn update_material_on<E: EntityEvent>(
116 |     new_material: Handle<StandardMaterial>,
117 | ) -> impl Fn(On<E>, Query<&mut MeshMaterial3d<StandardMaterial>>) {
118 |     move |trigger, mut material_query| {
119 |         if let Ok(mut material) = material_query.get_mut(trigger.event_target()) {
120 |             material.0 = new_material.clone();
121 |         }
122 |     }
123 | }
124 | 
125 | fn draw_mesh_intersections(
126 |     pointers: Query<&PointerInteraction>,
127 |     untargetable: Query<Entity, Or<(With<Portal>, With<Glass>)>>,
128 |     mut gizmos: Gizmos,
129 | ) {
130 |     for (point, normal) in pointers
131 |         .iter()
132 |         .flat_map(|interaction| interaction.iter())
133 |         .filter_map(|(entity, hit)| {
134 |             if !untargetable.contains(*entity) {
135 |                 hit.position.zip(hit.normal)
136 |             } else {
137 |                 None
138 |             }
139 |         })
140 |     {
141 |         gizmos.arrow(point, point + normal.normalize() * 0.5, Color::WHITE);
142 |     }
143 | }
144 | 
145 | fn rotate_y_on_drag(drag: On<Pointer<Drag>>, mut transform_query: Query<&mut Transform>) {
146 |     if !matches!(drag.button, PointerButton::Secondary) {
147 |         return;
148 |     }
149 |     let mut transform = transform_query.get_mut(drag.event_target()).unwrap();
150 |     transform.rotate_y(drag.delta.x * 0.005);
151 | }
152 | 
153 | fn rotate_xy_on_drag(drag: On<Pointer<Drag>>, mut transform_query: Query<&mut Transform>) {
154 |     if !matches!(drag.button, PointerButton::Primary) {
155 |         return;
156 |     }
157 |     let mut transform = transform_query.get_mut(drag.event_target()).unwrap();
158 |     transform.rotate_y(drag.delta.x * 0.02);
159 |     transform.rotate_x(drag.delta.y * 0.02);
160 | }
161 | 


--------------------------------------------------------------------------------
/src/picking.rs:
--------------------------------------------------------------------------------
  1 | //! Portal picking functionality for `bevy_picking`.
  2 | //!
  3 | //! Add the [`PortalPickingPlugin`] to propagate picking messages from backends "through" portals.
  4 | //!
  5 | //! This module does *not* provide any backend for you. It provides custom inputs that are
  6 | //! compatible with any backend. The entity containing the [`Portal`] will need to be picked via a
  7 | //! backend, hits will then be sent "through" the target.
  8 | //!
  9 | //! Some backends support opt-in behavior for picking, where cameras and entities require a marker
 10 | //! component to be considered in the backend. This also applies to portal cameras.
 11 | 
 12 | use bevy::{
 13 |     camera::NormalizedRenderTarget,
 14 |     picking::{
 15 |         PickingSystems,
 16 |         hover::HoverMap,
 17 |         pointer::{Location, PointerAction, PointerId, PointerInput, PointerLocation},
 18 |     },
 19 |     platform::collections::HashSet,
 20 |     prelude::*,
 21 | };
 22 | use uuid::Uuid;
 23 | 
 24 | use crate::{Portal, camera::PortalImage};
 25 | 
 26 | /// Enables picking "through" [`Portal`]s.
 27 | pub struct PortalPickingPlugin;
 28 | 
 29 | impl Plugin for PortalPickingPlugin {
 30 |     fn build(&self, app: &mut App) {
 31 |         app.add_message::<PortalInput>()
 32 |             .add_systems(
 33 |                 PreUpdate,
 34 |                 (
 35 |                     portal_inputs.in_set(PickingSystems::Input),
 36 |                     portal_picking.in_set(PickingSystems::Last),
 37 |                 ),
 38 |             )
 39 |             .add_observer(add_pointer);
 40 |     }
 41 | }
 42 | 
 43 | /// Used to send inputs obtained in [`portal_picking`] in the next frame.
 44 | #[derive(Message, Debug)]
 45 | struct PortalInput {
 46 |     pointer_id: PointerId,
 47 |     location: Location,
 48 |     action: PointerAction,
 49 | }
 50 | 
 51 | /// Adds [`PointerId`] and [`PointerLocation`] to entities that have a [`PortalImage`] added.
 52 | fn add_pointer(
 53 |     trigger: On<Add, PortalImage>,
 54 |     mut commands: Commands,
 55 |     query: Query<(Entity, &PortalImage)>,
 56 | ) {
 57 |     let (entity, portal_image) = query.get(trigger.event_target()).unwrap();
 58 | 
 59 |     let location = Location {
 60 |         target: NormalizedRenderTarget::Image(portal_image.0.clone().into()),
 61 |         position: Vec2::ZERO,
 62 |     };
 63 | 
 64 |     commands.entity(entity).insert((
 65 |         PointerId::Custom(Uuid::new_v4()),
 66 |         PointerLocation::new(location),
 67 |     ));
 68 | }
 69 | 
 70 | /// Maps incoming [`PortalInput`]s to [`PointerInput`]s.
 71 | fn portal_inputs(
 72 |     mut portal_inputs: MessageReader<PortalInput>,
 73 |     mut output: MessageWriter<PointerInput>,
 74 | ) {
 75 |     for message in portal_inputs.read() {
 76 |         output.write(PointerInput {
 77 |             pointer_id: message.pointer_id,
 78 |             location: message.location.clone(),
 79 |             action: message.action,
 80 |         });
 81 |     }
 82 | }
 83 | 
 84 | /// Handles picking.
 85 | ///
 86 | /// To allow for the [`PointerLocation`] to not lag behind, we raycast against the portal's normal.
 87 | /// This comes at the cost of a single frame hit delay.
 88 | fn portal_picking(
 89 |     portal_query: Query<(&Portal, &Transform, &PointerId, &PointerLocation)>,
 90 |     camera_global_transform_query: Query<(&Camera, &GlobalTransform)>,
 91 |     camera_query: Query<&Camera>,
 92 |     hover_map: Res<HoverMap>,
 93 |     pointer_state: Res<PointerState>,
 94 |     mut pointer_inputs: MessageReader<PointerInput>,
 95 |     mut portal_inputs: MessageWriter<PortalInput>,
 96 |     mut dragged_last_frame: Local<HashSet<(PointerId, Entity)>>,
 97 | ) {
 98 |     let mut portals: HashSet<(PointerId, Entity)> = dragged_last_frame.drain().collect();
 99 | 
100 |     for (hover_pointer_id, hits) in hover_map.iter() {
101 |         for (entity, _hit_data) in hits.iter() {
102 |             if portal_query.contains(*entity) {
103 |                 portals.insert((*hover_pointer_id, *entity));
104 |             }
105 |         }
106 |     }
107 | 
108 |     // Currently, we have only retrieved portal entities if they are being hovered. However, this
109 |     // does not allow dragging in-and-out of portals.
110 |     for ((pointer_id, _pointer_button), pointer_state) in pointer_state.pointer_buttons.iter() {
111 |         for &target in pointer_state
112 |             .dragging
113 |             .keys()
114 |             .filter(|&entity| portal_query.contains(*entity))
115 |         {
116 |             dragged_last_frame.insert((*pointer_id, target));
117 |             portals.insert((*pointer_id, target));
118 |         }
119 |     }
120 | 
121 |     for (pointer_id, entity) in portals {
122 |         let Ok((portal, &portal_transform, &portal_pointer_id, portal_pointer_location)) =
123 |             portal_query.get(entity)
124 |         else {
125 |             // This could fail because we store entities from the previous frame in
126 |             // `dragged_last_frame`. There's no guarantee they will still have these components
127 |             // this frame
128 |             continue;
129 |         };
130 | 
131 |         let Some(portal_camera) = portal
132 |             .linked_camera
133 |             .and_then(|camera| camera_query.get(camera).ok())
134 |         else {
135 |             continue;
136 |         };
137 |         let Ok((primary_camera, primary_camera_transform)) =
138 |             camera_global_transform_query.get(portal.primary_camera)
139 |         else {
140 |             continue;
141 |         };
142 |         // TODO: Having `target` cached here is nice, but shouldn't `PointerLocation::Location` be
143 |         // set to `None` if the portal isn't being hovered?
144 |         let target = portal_pointer_location.location().cloned().unwrap().target;
145 | 
146 |         for input in pointer_inputs
147 |             .read()
148 |             .filter(|input| input.pointer_id == pointer_id)
149 |         {
150 |             // Manually retrieve the current pointer's position, so that it doesn't lag a frame
151 |             // behind
152 |             //
153 |             // First, shoot a ray forward (w.r.t `primary_camera_transform`)
154 |             let Ok(ray) =
155 |                 primary_camera.viewport_to_world(primary_camera_transform, input.location.position)
156 |             else {
157 |                 continue;
158 |             };
159 |             // Get the distance from the ray's origin to the portal's normal
160 |             let Some(distance) = ray.intersect_plane(
161 |                 portal_transform.translation,
162 |                 InfinitePlane3d::new(portal_transform.forward()),
163 |             ) else {
164 |                 continue;
165 |             };
166 |             // We can get the world position of the intersection now. Finally, we use it and
167 |             // convert to the portal camera's viewport
168 |             let Ok(position) =
169 |                 portal_camera.world_to_viewport(primary_camera_transform, ray.get_point(distance))
170 |             else {
171 |                 continue;
172 |             };
173 | 
174 |             // We could use `Commands::send_message` here, but I'm not sure if it will hurt
175 |             // performance
176 |             portal_inputs.write(PortalInput {
177 |                 pointer_id: portal_pointer_id,
178 |                 location: Location {
179 |                     target: target.clone(),
180 |                     position,
181 |                 },
182 |                 action: input.action,
183 |             });
184 |         }
185 |     }
186 | }
187 | 


--------------------------------------------------------------------------------
/LICENSE-APACHE:
--------------------------------------------------------------------------------
  1 |                                  Apache License
  2 |                            Version 2.0, January 2004
  3 |                         http://www.apache.org/licenses/
  4 | 
  5 |    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  6 | 
  7 |    1. Definitions.
  8 | 
  9 |       "License" shall mean the terms and conditions for use, reproduction,
 10 |       and distribution as defined by Sections 1 through 9 of this document.
 11 | 
 12 |       "Licensor" shall mean the copyright owner or entity authorized by
 13 |       the copyright owner that is granting the License.
 14 | 
 15 |       "Legal Entity" shall mean the union of the acting entity and all
 16 |       other entities that control, are controlled by, or are under common
 17 |       control with that entity. For the purposes of this definition,
 18 |       "control" means (i) the power, direct or indirect, to cause the
 19 |       direction or management of such entity, whether by contract or
 20 |       otherwise, or (ii) ownership of fifty percent (50%) or more of the
 21 |       outstanding shares, or (iii) beneficial ownership of such entity.
 22 | 
 23 |       "You" (or "Your") shall mean an individual or Legal Entity
 24 |       exercising permissions granted by this License.
 25 | 
 26 |       "Source" form shall mean the preferred form for making modifications,
 27 |       including but not limited to software source code, documentation
 28 |       source, and configuration files.
 29 | 
 30 |       "Object" form shall mean any form resulting from mechanical
 31 |       transformation or translation of a Source form, including but
 32 |       not limited to compiled object code, generated documentation,
 33 |       and conversions to other media types.
 34 | 
 35 |       "Work" shall mean the work of authorship, whether in Source or
 36 |       Object form, made available under the License, as indicated by a
 37 |       copyright notice that is included in or attached to the work
 38 |       (an example is provided in the Appendix below).
 39 | 
 40 |       "Derivative Works" shall mean any work, whether in Source or Object
 41 |       form, that is based on (or derived from) the Work and for which the
 42 |       editorial revisions, annotations, elaborations, or other modifications
 43 |       represent, as a whole, an original work of authorship. For the purposes
 44 |       of this License, Derivative Works shall not include works that remain
 45 |       separable from, or merely link (or bind by name) to the interfaces of,
 46 |       the Work and Derivative Works thereof.
 47 | 
 48 |       "Contribution" shall mean any work of authorship, including
 49 |       the original version of the Work and any modifications or additions
 50 |       to that Work or Derivative Works thereof, that is intentionally
 51 |       submitted to Licensor for inclusion in the Work by the copyright owner
 52 |       or by an individual or Legal Entity authorized to submit on behalf of
 53 |       the copyright owner. For the purposes of this definition, "submitted"
 54 |       means any form of electronic, verbal, or written communication sent
 55 |       to the Licensor or its representatives, including but not limited to
 56 |       communication on electronic mailing lists, source code control systems,
 57 |       and issue tracking systems that are managed by, or on behalf of, the
 58 |       Licensor for the purpose of discussing and improving the Work, but
 59 |       excluding communication that is conspicuously marked or otherwise
 60 |       designated in writing by the copyright owner as "Not a Contribution."
 61 | 
 62 |       "Contributor" shall mean Licensor and any individual or Legal Entity
 63 |       on behalf of whom a Contribution has been received by Licensor and
 64 |       subsequently incorporated within the Work.
 65 | 
 66 |    2. Grant of Copyright License. Subject to the terms and conditions of
 67 |       this License, each Contributor hereby grants to You a perpetual,
 68 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 69 |       copyright license to reproduce, prepare Derivative Works of,
 70 |       publicly display, publicly perform, sublicense, and distribute the
 71 |       Work and such Derivative Works in Source or Object form.
 72 | 
 73 |    3. Grant of Patent License. Subject to the terms and conditions of
 74 |       this License, each Contributor hereby grants to You a perpetual,
 75 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 76 |       (except as stated in this section) patent license to make, have made,
 77 |       use, offer to sell, sell, import, and otherwise transfer the Work,
 78 |       where such license applies only to those patent claims licensable
 79 |       by such Contributor that are necessarily infringed by their
 80 |       Contribution(s) alone or by combination of their Contribution(s)
 81 |       with the Work to which such Contribution(s) was submitted. If You
 82 |       institute patent litigation against any entity (including a
 83 |       cross-claim or counterclaim in a lawsuit) alleging that the Work
 84 |       or a Contribution incorporated within the Work constitutes direct
 85 |       or contributory patent infringement, then any patent licenses
 86 |       granted to You under this License for that Work shall terminate
 87 |       as of the date such litigation is filed.
 88 | 
 89 |    4. Redistribution. You may reproduce and distribute copies of the
 90 |       Work or Derivative Works thereof in any medium, with or without
 91 |       modifications, and in Source or Object form, provided that You
 92 |       meet the following conditions:
 93 | 
 94 |       (a) You must give any other recipients of the Work or
 95 |           Derivative Works a copy of this License; and
 96 | 
 97 |       (b) You must cause any modified files to carry prominent notices
 98 |           stating that You changed the files; and
 99 | 
100 |       (c) You must retain, in the Source form of any Derivative Works
101 |           that You distribute, all copyright, patent, trademark, and
102 |           attribution notices from the Source form of the Work,
103 |           excluding those notices that do not pertain to any part of
104 |           the Derivative Works; and
105 | 
106 |       (d) If the Work includes a "NOTICE" text file as part of its
107 |           distribution, then any Derivative Works that You distribute must
108 |           include a readable copy of the attribution notices contained
109 |           within such NOTICE file, excluding those notices that do not
110 |           pertain to any part of the Derivative Works, in at least one
111 |           of the following places: within a NOTICE text file distributed
112 |           as part of the Derivative Works; within the Source form or
113 |           documentation, if provided along with the Derivative Works; or,
114 |           within a display generated by the Derivative Works, if and
115 |           wherever such third-party notices normally appear. The contents
116 |           of the NOTICE file are for informational purposes only and
117 |           do not modify the License. You may add Your own attribution
118 |           notices within Derivative Works that You distribute, alongside
119 |           or as an addendum to the NOTICE text from the Work, provided
120 |           that such additional attribution notices cannot be construed
121 |           as modifying the License.
122 | 
123 |       You may add Your own copyright statement to Your modifications and
124 |       may provide additional or different license terms and conditions
125 |       for use, reproduction, or distribution of Your modifications, or
126 |       for any such Derivative Works as a whole, provided Your use,
127 |       reproduction, and distribution of the Work otherwise complies with
128 |       the conditions stated in this License.
129 | 
130 |    5. Submission of Contributions. Unless You explicitly state otherwise,
131 |       any Contribution intentionally submitted for inclusion in the Work
132 |       by You to the Licensor shall be under the terms and conditions of
133 |       this License, without any additional terms or conditions.
134 |       Notwithstanding the above, nothing herein shall supersede or modify
135 |       the terms of any separate license agreement you may have executed
136 |       with Licensor regarding such Contributions.
137 | 
138 |    6. Trademarks. This License does not grant permission to use the trade
139 |       names, trademarks, service marks, or product names of the Licensor,
140 |       except as required for reasonable and customary use in describing the
141 |       origin of the Work and reproducing the content of the NOTICE file.
142 | 
143 |    7. Disclaimer of Warranty. Unless required by applicable law or
144 |       agreed to in writing, Licensor provides the Work (and each
145 |       Contributor provides its Contributions) on an "AS IS" BASIS,
146 |       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 |       implied, including, without limitation, any warranties or conditions
148 |       of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 |       PARTICULAR PURPOSE. You are solely responsible for determining the
150 |       appropriateness of using or redistributing the Work and assume any
151 |       risks associated with Your exercise of permissions under this License.
152 | 
153 |    8. Limitation of Liability. In no event and under no legal theory,
154 |       whether in tort (including negligence), contract, or otherwise,
155 |       unless required by applicable law (such as deliberate and grossly
156 |       negligent acts) or agreed to in writing, shall any Contributor be
157 |       liable to You for damages, including any direct, indirect, special,
158 |       incidental, or consequential damages of any character arising as a
159 |       result of this License or out of the use or inability to use the
160 |       Work (including but not limited to damages for loss of goodwill,
161 |       work stoppage, computer failure or malfunction, or any and all
162 |       other commercial damages or losses), even if such Contributor
163 |       has been advised of the possibility of such damages.
164 | 
165 |    9. Accepting Warranty or Additional Liability. While redistributing
166 |       the Work or Derivative Works thereof, You may choose to offer,
167 |       and charge a fee for, acceptance of support, warranty, indemnity,
168 |       or other liability obligations and/or rights consistent with this
169 |       License. However, in accepting such obligations, You may act only
170 |       on Your own behalf and on Your sole responsibility, not on behalf
171 |       of any other Contributor, and only if You agree to indemnify,
172 |       defend, and hold each Contributor harmless for any liability
173 |       incurred by, or claims asserted against, such Contributor by reason
174 |       of your accepting any such warranty or additional liability.
175 | 
176 |    END OF TERMS AND CONDITIONS
177 | 


--------------------------------------------------------------------------------
/examples/teleport.rs:
--------------------------------------------------------------------------------
  1 | //! Demonstrates setting up two bidirectional portals with teleportation between them.
  2 | //!
  3 | //! Includes basic collision handling for transitioning seamlessly between portals, a simple camera
  4 | //! controller for movement and looking around, and a basic scene setup
  5 | 
  6 | use std::f32::consts::FRAC_PI_4;
  7 | 
  8 | use bevy::{
  9 |     camera::visibility::RenderLayers,
 10 |     color::palettes::tailwind::{SKY_200, SLATE_200},
 11 |     input::mouse::MouseMotion,
 12 |     math::bounding::{Aabb3d, IntersectsVolume},
 13 |     prelude::*,
 14 |     render::render_resource::Face,
 15 |     window::{CursorGrabMode, CursorOptions, PrimaryWindow},
 16 | };
 17 | #[cfg(feature = "gizmos")]
 18 | use bevy_easy_portals::gizmos::PortalGizmosPlugin;
 19 | use bevy_easy_portals::{Portal, PortalPlugins, camera::PortalCameraSystems};
 20 | 
 21 | fn main() {
 22 |     App::new()
 23 |         .add_plugins((
 24 |             DefaultPlugins,
 25 |             PortalPlugins,
 26 |             #[cfg(feature = "gizmos")]
 27 |             PortalGizmosPlugin,
 28 |         ))
 29 |         .add_systems(Startup, setup)
 30 |         .add_systems(
 31 |             Update,
 32 |             (handle_camera_look, handle_movement, apply_shape_rotation),
 33 |         )
 34 |         .add_systems(
 35 |             PostUpdate,
 36 |             handle_portal_collision.before(PortalCameraSystems::UpdateFrusta),
 37 |         )
 38 |         .run();
 39 | }
 40 | 
 41 | const CAMERA_START_XYZ: Vec3 = Vec3::new(10.0, 0.5, 5.0);
 42 | const FLOOR_MESH_SIZE: f32 = 10.0;
 43 | const WALL_MESH_SIZE: f32 = 20.0;
 44 | const PORTAL_MESH_SIZE: f32 = 2.5;
 45 | const PORTAL_FRAME_SIZES_AND_TRANSLATIONS: [(Vec3, Vec3); 4] = [
 46 |     // Left
 47 |     (Vec3::new(0.1, 2.5, 0.2), Vec3::new(-1.3, -0.009, 0.0)),
 48 |     // Right
 49 |     (Vec3::new(0.1, 2.5, 0.2), Vec3::new(1.3, -0.009, 0.0)),
 50 |     // Top
 51 |     (Vec3::new(2.7, 0.1, 0.2), Vec3::new(0.0, 1.291, 0.0)),
 52 |     // Bottom
 53 |     (Vec3::new(2.7, 0.1, 0.2), Vec3::new(-0.0, -1.309, 0.0)),
 54 | ];
 55 | 
 56 | // Component used for camera controlling
 57 | #[derive(Component)]
 58 | struct CameraController {
 59 |     // Sensitivity of the camera with respect to mouse movement
 60 |     sensitivity: f32,
 61 |     // Speed the controller moves in world space
 62 |     speed: f32,
 63 | }
 64 | 
 65 | impl Default for CameraController {
 66 |     fn default() -> Self {
 67 |         Self {
 68 |             sensitivity: 0.03,
 69 |             speed: 3.0,
 70 |         }
 71 |     }
 72 | }
 73 | 
 74 | // Component used to track collisions between an entity and portal
 75 | #[derive(Component, Clone, Copy)]
 76 | #[component(storage = "SparseSet")]
 77 | struct Collision {
 78 |     // Offset of the entity from the portal
 79 |     offset: Vec3,
 80 |     // Portal entity that is being collided with
 81 |     portal_entity: Entity,
 82 | }
 83 | 
 84 | // Component used to mark shapes to be rotated
 85 | #[derive(Component)]
 86 | struct Shape;
 87 | 
 88 | fn setup(
 89 |     mut commands: Commands,
 90 |     mut cursor_options: Single<&mut CursorOptions, With<PrimaryWindow>>,
 91 |     mut meshes: ResMut<Assets<Mesh>>,
 92 |     mut materials: ResMut<Assets<StandardMaterial>>,
 93 | ) {
 94 |     cursor_options.grab_mode = CursorGrabMode::Locked;
 95 |     cursor_options.visible = false;
 96 | 
 97 |     let primary_camera = commands
 98 |         .spawn((
 99 |             Camera3d::default(),
100 |             Camera {
101 |                 clear_color: ClearColorConfig::Custom(Color::BLACK),
102 |                 ..default()
103 |             },
104 |             // TODO: A not-so-nice hack to help the rendering depth conflicts between the portal's
105 |             // mesh and the near clipping plane of the camera. The value has been "fine-tuned" to
106 |             // visual correctness. PRs that remove this hack are welcome :)
107 |             Projection::Perspective(PerspectiveProjection {
108 |                 near: 1e-8,
109 |                 ..default()
110 |             }),
111 |             Transform::from_translation(CAMERA_START_XYZ),
112 |             CameraController::default(),
113 |             RenderLayers::from_layers(&[0, 1]),
114 |         ))
115 |         .id();
116 | 
117 |     commands.insert_resource(AmbientLight {
118 |         brightness: 750.0,
119 |         ..default()
120 |     });
121 | 
122 |     let target_a = commands.spawn(Transform::IDENTITY).id();
123 |     let portal_a = commands.spawn_empty().add_child(target_a).id();
124 | 
125 |     let target_b = commands.spawn(Transform::IDENTITY).id();
126 |     let portal_b = commands.spawn_empty().add_child(target_b).id();
127 | 
128 |     let y_offset = -PORTAL_MESH_SIZE / 2.0 - 0.01;
129 | 
130 |     let floor_mesh = meshes.add(Plane3d::new(Vec3::Y, Vec2::splat(FLOOR_MESH_SIZE)));
131 |     let torus_mesh = meshes.add(Torus::default());
132 |     let portal_mesh = meshes.add(Rectangle::from_size(Vec2::splat(PORTAL_MESH_SIZE)));
133 |     let wall_mesh = meshes.add(Cuboid::from_size(Vec3::splat(WALL_MESH_SIZE)));
134 | 
135 |     for (sign, color, portal, target) in [
136 |         (-1.0, SKY_200, portal_a, target_b),
137 |         (1.0, SLATE_200, portal_b, target_a),
138 |     ] {
139 |         // Floor
140 |         commands.spawn((
141 |             Mesh3d(floor_mesh.clone()),
142 |             MeshMaterial3d(materials.add(Color::from(color))),
143 |             Transform::from_xyz(10.0 * sign, y_offset, 0.0),
144 |         ));
145 | 
146 |         // Walls
147 |         let wall_material = StandardMaterial {
148 |             reflectance: 0.0,
149 |             base_color: color.into(),
150 |             cull_mode: Some(Face::Front),
151 |             ..default()
152 |         };
153 |         commands.spawn((
154 |             Mesh3d(wall_mesh.clone()),
155 |             MeshMaterial3d(materials.add(wall_material)),
156 |             Transform::from_xyz(10.0 * sign, y_offset, 0.0),
157 |         ));
158 | 
159 |         commands.spawn((
160 |             Mesh3d(torus_mesh.clone()),
161 |             MeshMaterial3d(materials.add(Color::BLACK)),
162 |             Transform::from_xyz(15.0 * sign, y_offset + 1.5, 5.0 * sign)
163 |                 .with_rotation(Quat::from_axis_angle(Vec3::Z, FRAC_PI_4)),
164 |             Shape,
165 |         ));
166 | 
167 |         let portal_transform = Transform::from_xyz(10.0 * sign, 0.0, 0.0)
168 |             .with_rotation(Quat::from_axis_angle(Vec3::Y, FRAC_PI_4));
169 |         commands
170 |             .entity(portal)
171 |             .insert((
172 |                 Mesh3d(portal_mesh.clone()),
173 |                 portal_transform,
174 |                 // The mesh is a `Rectangle`, so to allow for the portal to be seen from both
175 |                 // sides, don't cull any of its faces.
176 |                 //
177 |                 // We should also flip the near plane normal when we are looking at the portal's
178 |                 // back face.
179 |                 Portal::new(primary_camera, target)
180 |                     .with_cull_mode(None)
181 |                     .with_flip_near_plane_normal(true),
182 |                 // Stop portals from recursively rendering eachother
183 |                 RenderLayers::layer(1),
184 |             ))
185 |             .with_children(|parent| {
186 |                 // Portal borders
187 |                 for (size, translation) in PORTAL_FRAME_SIZES_AND_TRANSLATIONS {
188 |                     parent.spawn((
189 |                         Mesh3d(meshes.add(Cuboid::from_size(size.into()))),
190 |                         MeshMaterial3d(materials.add(Color::BLACK)),
191 |                         Transform::from_translation(translation.into()),
192 |                     ));
193 |                 }
194 |             });
195 |     }
196 | }
197 | 
198 | fn handle_portal_collision(
199 |     mut commands: Commands,
200 |     mut camera_query: Query<(Entity, &mut Transform), With<CameraController>>,
201 |     portal_query: Query<(Entity, &Portal), With<Portal>>,
202 |     transform_query: Query<&GlobalTransform, Without<CameraController>>,
203 |     mut stored_collision: Option<Single<&mut Collision>>,
204 | ) {
205 |     let (camera_entity, mut camera_transform) = camera_query.single_mut().unwrap();
206 |     let camera_aabb = Aabb3d::new(camera_transform.translation, Vec3::ZERO);
207 | 
208 |     for (portal_entity, portal) in &portal_query {
209 |         let portal_transform = transform_query.get(portal_entity).unwrap();
210 |         let portal_aabb = Aabb3d::new(
211 |             portal_transform.translation(),
212 |             Vec2::splat(PORTAL_MESH_SIZE).extend(1.0),
213 |         );
214 | 
215 |         // Are we currently inside a portal?
216 |         if portal_aabb.intersects(&camera_aabb) {
217 |             let offset = camera_transform.translation - portal_transform.translation();
218 | 
219 |             let Some(ref mut collision) = stored_collision else {
220 |                 commands.entity(camera_entity).insert(Collision {
221 |                     offset,
222 |                     portal_entity,
223 |                 });
224 |                 return;
225 |             };
226 | 
227 |             if collision.portal_entity == portal_entity {
228 |                 let portal_forward = *portal_transform.forward();
229 |                 let start_side = collision.offset.dot(portal_forward).signum();
230 |                 let end_side = offset.dot(portal_forward).signum();
231 | 
232 |                 // Have we moved to the other side of the portal?
233 |                 if start_side != end_side {
234 |                     let target_transform = transform_query.get(portal.target).unwrap();
235 | 
236 |                     let relative_translation = portal_transform
237 |                         .affine()
238 |                         .inverse()
239 |                         .transform_point3(camera_transform.translation);
240 |                     // Now transform it back to world space using the target's transform
241 |                     let translation = target_transform.transform_point(relative_translation);
242 | 
243 |                     let relative_rotation =
244 |                         portal_transform.rotation().inverse() * camera_transform.rotation;
245 |                     let rotation = target_transform.rotation() * relative_rotation;
246 | 
247 |                     camera_transform.translation = translation;
248 |                     camera_transform.rotation = rotation;
249 |                 } else {
250 |                     collision.offset = offset;
251 |                 }
252 |             }
253 |         } else if stored_collision
254 |             .as_ref()
255 |             .is_some_and(|c| c.portal_entity == portal_entity)
256 |         {
257 |             commands.entity(camera_entity).remove::<Collision>();
258 |         }
259 |     }
260 | }
261 | 
262 | fn handle_camera_look(
263 |     mut mouse_motion: MessageReader<MouseMotion>,
264 |     mut camera_query: Query<(&CameraController, &mut Transform)>,
265 | ) {
266 |     let (camera_controller, mut transform) = camera_query.single_mut().unwrap();
267 | 
268 |     for message in mouse_motion.read() {
269 |         let yaw_delta = Quat::from_rotation_y(
270 |             (-message.delta.x * camera_controller.sensitivity)
271 |                 .clamp(-89.0, 89.0)
272 |                 .to_radians(),
273 |         );
274 |         let pitch_delta =
275 |             Quat::from_rotation_x((-message.delta.y * camera_controller.sensitivity).to_radians());
276 |         transform.rotation = yaw_delta * transform.rotation.normalize() * pitch_delta;
277 |     }
278 | }
279 | 
280 | fn handle_movement(
281 |     keys: Res<ButtonInput<KeyCode>>,
282 |     mut camera_query: Query<(&CameraController, &mut Transform)>,
283 |     time: Res<Time>,
284 | ) {
285 |     let (camera_controller, mut transform) = camera_query.single_mut().unwrap();
286 | 
287 |     // Zero the y-vector to only allow lateral movement
288 |     let forward = transform.forward().with_y(0.0).normalize();
289 |     let right = transform.right().with_y(0.0).normalize();
290 | 
291 |     let mut movement = Vec3::ZERO;
292 | 
293 |     if keys.pressed(KeyCode::KeyW) {
294 |         movement += forward;
295 |     }
296 |     if keys.pressed(KeyCode::KeyS) {
297 |         movement -= forward;
298 |     }
299 |     if keys.pressed(KeyCode::KeyA) {
300 |         movement -= right;
301 |     }
302 |     if keys.pressed(KeyCode::KeyD) {
303 |         movement += right;
304 |     }
305 | 
306 |     transform.translation += movement * camera_controller.speed * time.delta_secs();
307 | }
308 | 
309 | fn apply_shape_rotation(mut shape_query: Query<&mut Transform, With<Shape>>, time: Res<Time>) {
310 |     for mut transform in &mut shape_query {
311 |         let angle = time.delta_secs() / 2.0;
312 |         transform.rotate(Quat::from_axis_angle(Vec3::Z, angle));
313 |     }
314 | }
315 | 


--------------------------------------------------------------------------------
/src/camera.rs:
--------------------------------------------------------------------------------
  1 | use bevy::{
  2 |     camera::{
  3 |         Exposure, ImageRenderTarget, RenderTarget,
  4 |         primitives::{Frustum, HalfSpace},
  5 |         visibility::VisibilitySystems,
  6 |     },
  7 |     core_pipeline::tonemapping::{DebandDither, Tonemapping},
  8 |     ecs::system::SystemParam,
  9 |     image::{TextureFormatPixelInfo, Volume},
 10 |     log::error,
 11 |     math::FloatOrd,
 12 |     prelude::*,
 13 |     render::{
 14 |         render_resource::{
 15 |             Extent3d, TextureDescriptor, TextureDimension, TextureFormat, TextureUsages,
 16 |         },
 17 |         view::ColorGrading,
 18 |     },
 19 |     window::{PrimaryWindow, WindowRef, WindowResized},
 20 | };
 21 | 
 22 | use crate::Portal;
 23 | 
 24 | /// Plugin that provides [`PortalCamera`] spawning/despawning, transform and frusta updates, and
 25 | /// resizing rendered portal images.
 26 | pub struct PortalCameraPlugin;
 27 | 
 28 | /// Label for systems that update [`Portal`] related cameras.
 29 | #[derive(Debug, PartialEq, Eq, Clone, Hash, SystemSet)]
 30 | pub enum PortalCameraSystems {
 31 |     /// Resizes [`Portal::linked_camera`]'s rendered image if any [`WindowResized`] messages are
 32 |     /// read.
 33 |     ResizeImage,
 34 |     /// Updates the [`GlobalTransform`] and [`Transform`] components for [`Portal::linked_camera`]
 35 |     /// based on the [`Portal::primary_camera`]s [`GlobalTransform`].
 36 |     UpdateTransform,
 37 |     /// Updates the [`Frustum`] for [`Portal::linked_camera`].
 38 |     UpdateFrusta,
 39 | }
 40 | 
 41 | impl Plugin for PortalCameraPlugin {
 42 |     fn build(&self, app: &mut App) {
 43 |         app.configure_sets(
 44 |             PostUpdate,
 45 |             (
 46 |                 PortalCameraSystems::UpdateTransform.after(TransformSystems::Propagate),
 47 |                 PortalCameraSystems::UpdateFrusta.after(VisibilitySystems::UpdateFrusta),
 48 |             )
 49 |                 .chain(),
 50 |         )
 51 |         .add_systems(
 52 |             PreUpdate,
 53 |             resize_portal_images.in_set(PortalCameraSystems::ResizeImage),
 54 |         )
 55 |         .add_systems(
 56 |             PostUpdate,
 57 |             (
 58 |                 update_portal_camera_transform.in_set(PortalCameraSystems::UpdateTransform),
 59 |                 update_portal_camera_frusta.in_set(PortalCameraSystems::UpdateFrusta),
 60 |             ),
 61 |         )
 62 |         .add_observer(setup_portal_camera)
 63 |         .add_observer(despawn_portal_camera)
 64 |         .register_type::<(PortalCamera, PortalImage)>();
 65 |     }
 66 | }
 67 | 
 68 | /// Component used to mark a [`Portal`]'s associated camera.
 69 | #[derive(Component, Reflect, Debug)]
 70 | #[reflect(Component)]
 71 | pub struct PortalCamera(pub Entity);
 72 | 
 73 | /// Component used to store a weak reference to a [`PortalCamera`]'s rendered image.
 74 | #[derive(Component, Reflect, Debug, Deref, DerefMut)]
 75 | #[reflect(Component)]
 76 | pub struct PortalImage(pub Handle<Image>);
 77 | 
 78 | /// System that is triggered whenever a [`Portal`] component is added to an entity.
 79 | ///
 80 | /// An image is created based on the primary camera's viewport size. Then, a [`PortalCamera`] is
 81 | /// created, with [`Camera::target`] set to render the [`PortalCamera`]'s view to the image.
 82 | ///
 83 | /// # Notes
 84 | ///
 85 | /// * The [`PortalCamera`] will inherit any properties currently present on the primary camera.
 86 | fn setup_portal_camera(
 87 |     trigger: On<Add, Portal>,
 88 |     mut commands: Commands,
 89 |     mut portal_query: Query<&mut Portal>,
 90 |     primary_camera_query: Query<(
 91 |         &Camera,
 92 |         Option<&Camera3d>,
 93 |         Option<&DebandDither>,
 94 |         Option<&Tonemapping>,
 95 |         Option<&ColorGrading>,
 96 |         Option<&Exposure>,
 97 |     )>,
 98 |     global_transform_query: Query<&GlobalTransform>,
 99 |     mut portal_images: PortalImages,
100 | ) {
101 |     let entity = trigger.event_target();
102 | 
103 |     let mut portal = portal_query.get_mut(entity).unwrap();
104 | 
105 |     let Ok((primary_camera, camera_3d, tonemapping, deband_dither, color_grading, exposure)) =
106 |         primary_camera_query.get(portal.primary_camera)
107 |     else {
108 |         error!(
109 |             "could not setup portal camera {entity}: primary_camera does not contain a Camera component"
110 |         );
111 |         return;
112 |     };
113 | 
114 |     let Some(image_handle) = portal_images.with_camera(primary_camera) else {
115 |         error!("could not create portal image for {entity}");
116 |         return;
117 |     };
118 | 
119 |     let Ok(global_transform) = global_transform_query.get(portal.target).copied() else {
120 |         error!("portal target is missing a GlobalTransform");
121 |         return;
122 |     };
123 |     portal.linked_camera = Some(
124 |         commands
125 |             .spawn((
126 |                 Name::new("Portal Camera"),
127 |                 Camera {
128 |                     order: 100,
129 |                     target: RenderTarget::Image(ImageRenderTarget {
130 |                         handle: image_handle.clone(),
131 |                         scale_factor: FloatOrd(1.0),
132 |                     }),
133 |                     ..primary_camera.clone()
134 |                 },
135 |                 global_transform.compute_transform(),
136 |                 global_transform,
137 |                 camera_3d.cloned().unwrap_or_default(),
138 |                 tonemapping.copied().unwrap_or_default(),
139 |                 deband_dither.copied().unwrap_or_default(),
140 |                 color_grading.cloned().unwrap_or_default(),
141 |                 exposure.copied().unwrap_or_default(),
142 |                 PortalCamera(entity),
143 |             ))
144 |             .id(),
145 |     );
146 | 
147 |     commands
148 |         .entity(entity)
149 |         .insert(PortalImage(image_handle.clone()));
150 | }
151 | 
152 | /// System that despawns a [`Portal::linked_camera`] when the [`Portal`] component is removed from
153 | /// a triggered entity.
154 | fn despawn_portal_camera(
155 |     trigger: On<Remove, Portal>,
156 |     portal_query: Query<&Portal>,
157 |     mut commands: Commands,
158 | ) {
159 |     let portal = portal_query.get(trigger.event_target()).unwrap();
160 | 
161 |     if let Some(linked_camera) = portal.linked_camera {
162 |         commands.entity(linked_camera).despawn();
163 |     }
164 | }
165 | 
166 | /// System that updates a [`PortalCamera`]s [`Transform`] and [`GlobalTransform`] based on the
167 | /// primary camera.
168 | fn update_portal_camera_transform(
169 |     portal_query: Query<(&GlobalTransform, &Portal), (Without<Camera3d>, Without<PortalCamera>)>,
170 |     mut portal_camera_transform_query: Query<
171 |         (&mut GlobalTransform, &mut Transform),
172 |         With<PortalCamera>,
173 |     >,
174 |     global_transform_query: Query<&GlobalTransform, Without<PortalCamera>>,
175 | ) {
176 |     for (portal_transform, portal) in &portal_query {
177 |         let Ok([primary_camera_transform, target_transform]) =
178 |             global_transform_query.get_many([portal.primary_camera, portal.target])
179 |         else {
180 |             continue;
181 |         };
182 | 
183 |         let Some((mut portal_camera_global_transform, mut portal_camera_transform)) = portal
184 |             .linked_camera
185 |             .and_then(|camera| portal_camera_transform_query.get_mut(camera).ok())
186 |         else {
187 |             continue;
188 |         };
189 | 
190 |         // Transform the camera's translation from world space to the portal's space
191 |         let relative_translation = portal_transform
192 |             .affine()
193 |             .inverse()
194 |             .transform_point3(primary_camera_transform.translation());
195 |         // Now transform it back to world space using the target's transform
196 |         let translation = target_transform.transform_point(relative_translation);
197 | 
198 |         let relative_rotation =
199 |             portal_transform.rotation().inverse() * primary_camera_transform.rotation();
200 |         let rotation = target_transform.rotation() * relative_rotation;
201 | 
202 |         portal_camera_transform.translation = translation;
203 |         portal_camera_transform.rotation = rotation;
204 | 
205 |         *portal_camera_global_transform = GlobalTransform::from(*portal_camera_transform);
206 |     }
207 | }
208 | 
209 | /// System that updates [`Frustum`] for [`PortalCamera`]s.
210 | fn update_portal_camera_frusta(
211 |     portal_query: Query<(&Portal, &GlobalTransform)>,
212 |     mut frustum_query: Query<&mut Frustum, With<PortalCamera>>,
213 |     global_transform_query: Query<&GlobalTransform>,
214 | ) {
215 |     for (portal, portal_transform) in &portal_query {
216 |         let Some(linked_camera) = portal.linked_camera else {
217 |             continue;
218 |         };
219 | 
220 |         let Ok(mut frustum) = frustum_query.get_mut(linked_camera) else {
221 |             continue;
222 |         };
223 | 
224 |         let Ok([primary_camera_transform, target_transform]) =
225 |             global_transform_query.get_many([portal.primary_camera, portal.target])
226 |         else {
227 |             continue;
228 |         };
229 | 
230 |         let mut normal = target_transform.forward();
231 | 
232 |         if portal.flip_near_plane_normal {
233 |             let camera_to_portal =
234 |                 portal_transform.translation() - primary_camera_transform.translation();
235 |             if camera_to_portal.dot(*portal_transform.forward()) <= 0.0 {
236 |                 normal = -normal;
237 |             }
238 |         }
239 | 
240 |         let distance = -target_transform
241 |             .translation()
242 |             .dot(normal.normalize_or_zero());
243 |         frustum.half_spaces[4] = HalfSpace::new(normal.extend(distance));
244 |     }
245 | }
246 | 
247 | /// System that resizes [`PortalImage`]s when the [`WindowResized`] message is fired.
248 | fn resize_portal_images(
249 |     mut resized_reader: MessageReader<WindowResized>,
250 |     window_query: Query<&Window>,
251 |     portal_image_query: Query<&PortalImage>,
252 |     mut images: ResMut<Assets<Image>>,
253 | ) {
254 |     for message in resized_reader.read() {
255 |         let window_size = window_query.get(message.window).unwrap().physical_size();
256 |         let size = Extent3d {
257 |             width: window_size.x,
258 |             height: window_size.y,
259 |             ..default()
260 |         };
261 | 
262 |         for portal_image in &portal_image_query {
263 |             let Some(image) = images.get_mut(&portal_image.0) else {
264 |                 continue;
265 |             };
266 | 
267 |             image.resize(size);
268 |         }
269 |     }
270 | }
271 | 
272 | #[derive(SystemParam)]
273 | struct PortalImages<'w, 's> {
274 |     primary_window_query: Query<'w, 's, &'static Window, With<PrimaryWindow>>,
275 |     window_query: Query<'w, 's, &'static Window>,
276 |     images: ResMut<'w, Assets<Image>>,
277 |     manual_texture_views: Res<'w, ManualTextureViews>,
278 | }
279 | 
280 | impl PortalImages<'_, '_> {
281 |     /// Creates a new [`Image`] with size matching the given `camera`.
282 |     ///
283 |     /// Returns `None` if no viewport size could be obtained.
284 |     fn with_camera(&mut self, camera: &Camera) -> Option<Handle<Image>> {
285 |         let size = self.get_viewport_size(camera)?;
286 |         let format = TextureFormat::Bgra8UnormSrgb;
287 |         let image = Image {
288 |             data: Some(vec![0; size.volume() * format.pixel_size().ok()?]),
289 |             texture_descriptor: TextureDescriptor {
290 |                 label: None,
291 |                 size,
292 |                 dimension: TextureDimension::D2,
293 |                 format,
294 |                 mip_level_count: 1,
295 |                 sample_count: 1,
296 |                 usage: TextureUsages::TEXTURE_BINDING
297 |                     | TextureUsages::COPY_DST
298 |                     | TextureUsages::RENDER_ATTACHMENT,
299 |                 view_formats: &[],
300 |             },
301 |             ..default()
302 |         };
303 |         let handle = self.images.add(image);
304 |         Some(handle)
305 |     }
306 | 
307 |     /// Retrieves the size of the viewport of a given `camera`.
308 |     ///
309 |     /// Returns `None` if no sizing could be obtained.
310 |     fn get_viewport_size(&self, camera: &Camera) -> Option<Extent3d> {
311 |         match camera.viewport.as_ref() {
312 |             Some(viewport) => Some(viewport.physical_size),
313 |             None => match &camera.target {
314 |                 RenderTarget::Window(window_ref) => (match window_ref {
315 |                     WindowRef::Primary => self.primary_window_query.single().ok(),
316 |                     WindowRef::Entity(entity) => self.window_query.get(*entity).ok(),
317 |                 })
318 |                 .map(Window::physical_size),
319 |                 RenderTarget::Image(img_render_handle) => {
320 |                     self.images.get(&img_render_handle.handle).map(Image::size)
321 |                 }
322 |                 RenderTarget::TextureView(handle) => self
323 |                     .manual_texture_views
324 |                     .get(handle)
325 |                     .map(|texture| texture.size),
326 |                 RenderTarget::None { size } => Some(*size),
327 |             },
328 |         }
329 |         .map(|size| Extent3d {
330 |             width: size.x,
331 |             height: size.y,
332 |             ..default()
333 |         })
334 |     }
335 | }
336 | 


--------------------------------------------------------------------------------