Skip to main content

servo_webxr_api/
session.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5use std::thread;
6use std::time::Duration;
7
8use euclid::{Point2D, Rect, RigidTransform3D, Size2D};
9use log::warn;
10use malloc_size_of_derive::MallocSizeOf;
11use profile_traits::generic_callback::GenericCallback as ProfileGenericCallback;
12use serde::{Deserialize, Serialize};
13use servo_base::generic_channel::{self, GenericReceiver, GenericSender};
14use servo_base::id::PainterId;
15
16use crate::{
17    ContextId, DeviceAPI, Error, Event, Floor, Frame, FrameUpdateEvent, HitTestId, HitTestSource,
18    InputSource, LayerGrandManager, LayerId, LayerInit, Native, Viewport, Viewports,
19};
20
21// How long to wait for an rAF.
22static TIMEOUT: Duration = Duration::from_millis(5);
23
24/// <https://www.w3.org/TR/webxr/#xrsessionmode-enum>
25#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
26pub enum SessionMode {
27    Inline,
28    ImmersiveVR,
29    ImmersiveAR,
30}
31
32/// <https://immersive-web.github.io/webxr/#dictdef-xrsessioninit>
33#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
34pub struct SessionInit {
35    pub required_features: Vec<String>,
36    pub optional_features: Vec<String>,
37    /// Secondary views are enabled with the `secondary-view` feature
38    /// but for performance reasons we also ask users to enable this pref
39    /// for now.
40    pub first_person_observer_view: bool,
41    pub painter_id: PainterId,
42}
43
44impl SessionInit {
45    /// Helper function for validating a list of requested features against
46    /// a list of supported features for a given mode
47    pub fn validate(&self, mode: SessionMode, supported: &[String]) -> Result<Vec<String>, Error> {
48        for f in &self.required_features {
49            // viewer and local in immersive are granted by default
50            // https://immersive-web.github.io/webxr/#default-features
51            if f == "viewer" || (f == "local" && mode != SessionMode::Inline) {
52                continue;
53            }
54
55            if !supported.contains(f) {
56                return Err(Error::UnsupportedFeature(f.into()));
57            }
58        }
59        let mut granted = self.required_features.clone();
60        for f in &self.optional_features {
61            if f == "viewer" ||
62                (f == "local" && mode != SessionMode::Inline) ||
63                supported.contains(f)
64            {
65                granted.push(f.clone());
66            }
67        }
68
69        Ok(granted)
70    }
71
72    pub fn feature_requested(&self, f: &str) -> bool {
73        self.required_features
74            .iter()
75            .chain(self.optional_features.iter())
76            .any(|x| *x == f)
77    }
78}
79
80/// <https://immersive-web.github.io/webxr-ar-module/#xrenvironmentblendmode-enum>
81#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize, MallocSizeOf)]
82pub enum EnvironmentBlendMode {
83    Opaque,
84    AlphaBlend,
85    Additive,
86}
87
88// The messages that are sent from the content thread to the session thread.
89#[derive(Debug, Serialize, Deserialize)]
90enum SessionMsg {
91    CreateLayer(ContextId, LayerInit, GenericSender<Result<LayerId, Error>>),
92    DestroyLayer(ContextId, LayerId),
93    SetLayers(Vec<(ContextId, LayerId)>),
94    SetEventDest(ProfileGenericCallback<Event>),
95    SetFrameDest(ProfileGenericCallback<Frame>),
96    UpdateClipPlanes(/* near */ f32, /* far */ f32),
97    StartRenderLoop,
98    RenderAnimationFrame,
99    RequestHitTest(HitTestSource),
100    CancelHitTest(HitTestId),
101    UpdateFrameRate(f32, ProfileGenericCallback<f32>),
102    Quit,
103    GetBoundsGeometry(GenericSender<Option<Vec<Point2D<f32, Floor>>>>),
104}
105
106#[derive(Serialize, Deserialize, Clone)]
107pub struct Quitter {
108    sender: GenericSender<SessionMsg>,
109}
110
111impl Quitter {
112    pub fn quit(&self) {
113        let _ = self.sender.send(SessionMsg::Quit);
114    }
115}
116
117/// An object that represents an XR session.
118/// This is owned by the content thread.
119/// <https://www.w3.org/TR/webxr/#xrsession-interface>
120#[derive(Serialize, Deserialize, MallocSizeOf)]
121pub struct Session {
122    floor_transform: Option<RigidTransform3D<f32, Native, Floor>>,
123    viewports: Viewports,
124    sender: GenericSender<SessionMsg>,
125    environment_blend_mode: EnvironmentBlendMode,
126    initial_inputs: Vec<InputSource>,
127    granted_features: Vec<String>,
128    id: SessionId,
129    supported_frame_rates: Vec<f32>,
130}
131
132#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Deserialize, Serialize, MallocSizeOf)]
133pub struct SessionId(pub(crate) u32);
134
135impl Session {
136    pub fn id(&self) -> SessionId {
137        self.id
138    }
139
140    pub fn floor_transform(&self) -> Option<RigidTransform3D<f32, Native, Floor>> {
141        self.floor_transform
142    }
143
144    pub fn reference_space_bounds(&self) -> Option<Vec<Point2D<f32, Floor>>> {
145        let (sender, receiver) = generic_channel::channel()?;
146        let _ = self.sender.send(SessionMsg::GetBoundsGeometry(sender));
147        receiver.recv().ok()?
148    }
149
150    pub fn initial_inputs(&self) -> &[InputSource] {
151        &self.initial_inputs
152    }
153
154    pub fn environment_blend_mode(&self) -> EnvironmentBlendMode {
155        self.environment_blend_mode
156    }
157
158    pub fn viewports(&self) -> &[Rect<i32, Viewport>] {
159        &self.viewports.viewports
160    }
161
162    /// A resolution large enough to contain all the viewports.
163    /// <https://immersive-web.github.io/webxr/#recommended-webgl-framebuffer-resolution>
164    ///
165    /// Returns None if the session is inline
166    pub fn recommended_framebuffer_resolution(&self) -> Option<Size2D<i32, Viewport>> {
167        self.viewports()
168            .iter()
169            .fold(None::<Rect<_, _>>, |acc, vp| {
170                Some(acc.map(|a| a.union(vp)).unwrap_or(*vp))
171            })
172            .map(|rect| Size2D::new(rect.max_x(), rect.max_y()))
173    }
174
175    pub fn create_layer(&self, context_id: ContextId, init: LayerInit) -> Result<LayerId, Error> {
176        let Some((sender, receiver)) = generic_channel::channel() else {
177            return Err(Error::CommunicationError);
178        };
179        let _ = self
180            .sender
181            .send(SessionMsg::CreateLayer(context_id, init, sender));
182        receiver.recv().map_err(|_| Error::CommunicationError)?
183    }
184
185    /// Destroy a layer
186    pub fn destroy_layer(&self, context_id: ContextId, layer_id: LayerId) {
187        let _ = self
188            .sender
189            .send(SessionMsg::DestroyLayer(context_id, layer_id));
190    }
191
192    pub fn set_layers(&self, layers: Vec<(ContextId, LayerId)>) {
193        let _ = self.sender.send(SessionMsg::SetLayers(layers));
194    }
195
196    pub fn start_render_loop(&mut self) {
197        let _ = self.sender.send(SessionMsg::StartRenderLoop);
198    }
199
200    pub fn update_clip_planes(&mut self, near: f32, far: f32) {
201        let _ = self.sender.send(SessionMsg::UpdateClipPlanes(near, far));
202    }
203
204    pub fn set_event_dest(&mut self, dest: ProfileGenericCallback<Event>) {
205        let _ = self.sender.send(SessionMsg::SetEventDest(dest));
206    }
207
208    pub fn set_frame_dest(&mut self, dest: ProfileGenericCallback<Frame>) {
209        let _ = self.sender.send(SessionMsg::SetFrameDest(dest));
210    }
211
212    pub fn render_animation_frame(&mut self) {
213        let _ = self.sender.send(SessionMsg::RenderAnimationFrame);
214    }
215
216    pub fn end_session(&mut self) {
217        let _ = self.sender.send(SessionMsg::Quit);
218    }
219
220    pub fn apply_event(&mut self, event: FrameUpdateEvent) {
221        match event {
222            FrameUpdateEvent::UpdateFloorTransform(floor) => self.floor_transform = floor,
223            FrameUpdateEvent::UpdateViewports(vp) => self.viewports = vp,
224            FrameUpdateEvent::HitTestSourceAdded(_) => (),
225        }
226    }
227
228    pub fn granted_features(&self) -> &[String] {
229        &self.granted_features
230    }
231
232    pub fn request_hit_test(&self, source: HitTestSource) {
233        let _ = self.sender.send(SessionMsg::RequestHitTest(source));
234    }
235
236    pub fn cancel_hit_test(&self, id: HitTestId) {
237        let _ = self.sender.send(SessionMsg::CancelHitTest(id));
238    }
239
240    pub fn update_frame_rate(&mut self, rate: f32, sender: ProfileGenericCallback<f32>) {
241        let _ = self.sender.send(SessionMsg::UpdateFrameRate(rate, sender));
242    }
243
244    pub fn supported_frame_rates(&self) -> &[f32] {
245        &self.supported_frame_rates
246    }
247}
248
249#[derive(PartialEq)]
250enum RenderState {
251    NotInRenderLoop,
252    InRenderLoop,
253    PendingQuit,
254}
255
256/// For devices that want to do their own thread management, the `SessionThread` type is exposed.
257pub struct SessionThread<Device> {
258    receiver: GenericReceiver<SessionMsg>,
259    sender: GenericSender<SessionMsg>,
260    layers: Vec<(ContextId, LayerId)>,
261    pending_layers: Option<Vec<(ContextId, LayerId)>>,
262    frame_count: u64,
263    frame_sender: Option<ProfileGenericCallback<Frame>>,
264    running: bool,
265    device: Device,
266    id: SessionId,
267    render_state: RenderState,
268}
269
270impl<Device> SessionThread<Device>
271where
272    Device: DeviceAPI,
273{
274    pub fn new(mut device: Device, id: SessionId) -> Result<Self, Error> {
275        let Some((sender, receiver)) = generic_channel::channel() else {
276            return Err(Error::CommunicationError);
277        };
278        device.set_quitter(Quitter {
279            sender: sender.clone(),
280        });
281        let frame_count = 0;
282        let running = true;
283        let layers = Vec::new();
284        let pending_layers = None;
285        Ok(SessionThread {
286            sender,
287            receiver,
288            device,
289            layers,
290            pending_layers,
291            frame_count,
292            frame_sender: None,
293            running,
294            id,
295            render_state: RenderState::NotInRenderLoop,
296        })
297    }
298
299    pub fn new_session(&mut self) -> Session {
300        let floor_transform = self.device.floor_transform();
301        let viewports = self.device.viewports();
302        let sender = self.sender.clone();
303        let initial_inputs = self.device.initial_inputs();
304        let environment_blend_mode = self.device.environment_blend_mode();
305        let granted_features = self.device.granted_features().into();
306        let supported_frame_rates = self.device.supported_frame_rates();
307        Session {
308            floor_transform,
309            viewports,
310            sender,
311            initial_inputs,
312            environment_blend_mode,
313            granted_features,
314            id: self.id,
315            supported_frame_rates,
316        }
317    }
318
319    pub fn run(&mut self) {
320        while let Ok(msg) = self.receiver.recv() {
321            if !self.handle_msg(msg) {
322                self.running = false;
323                break;
324            }
325        }
326    }
327
328    fn handle_msg(&mut self, msg: SessionMsg) -> bool {
329        log::debug!("processing {:?}", msg);
330        match msg {
331            SessionMsg::SetEventDest(dest) => {
332                self.device.set_event_dest(dest);
333            },
334            SessionMsg::SetFrameDest(dest) => {
335                self.frame_sender = Some(dest);
336            },
337            SessionMsg::RequestHitTest(source) => {
338                self.device.request_hit_test(source);
339            },
340            SessionMsg::CancelHitTest(id) => {
341                self.device.cancel_hit_test(id);
342            },
343            SessionMsg::CreateLayer(context_id, layer_init, sender) => {
344                let result = self.device.create_layer(context_id, layer_init);
345                let _ = sender.send(result);
346            },
347            SessionMsg::DestroyLayer(context_id, layer_id) => {
348                self.layers.retain(|&(_, other_id)| layer_id != other_id);
349                self.device.destroy_layer(context_id, layer_id);
350            },
351            SessionMsg::SetLayers(layers) => {
352                self.pending_layers = Some(layers);
353            },
354            SessionMsg::StartRenderLoop => {
355                if let Some(layers) = self.pending_layers.take() {
356                    self.layers = layers;
357                }
358                let frame = match self.device.begin_animation_frame(&self.layers[..]) {
359                    Some(frame) => frame,
360                    None => {
361                        warn!("Device stopped providing frames, exiting");
362                        return false;
363                    },
364                };
365                self.render_state = RenderState::InRenderLoop;
366                self.send_frame(frame);
367            },
368            SessionMsg::UpdateClipPlanes(near, far) => self.device.update_clip_planes(near, far),
369            SessionMsg::RenderAnimationFrame => {
370                self.frame_count += 1;
371
372                self.device.end_animation_frame(&self.layers[..]);
373
374                if self.render_state == RenderState::PendingQuit {
375                    self.quit();
376                    return false;
377                }
378
379                if let Some(layers) = self.pending_layers.take() {
380                    self.layers = layers;
381                }
382                #[expect(unused_mut)]
383                let mut frame = match self.device.begin_animation_frame(&self.layers[..]) {
384                    Some(frame) => frame,
385                    None => {
386                        warn!("Device stopped providing frames, exiting");
387                        return false;
388                    },
389                };
390
391                self.send_frame(frame);
392            },
393            SessionMsg::UpdateFrameRate(rate, sender) => {
394                let new_framerate = self.device.update_frame_rate(rate);
395                let _ = sender.send(new_framerate);
396            },
397            SessionMsg::Quit => {
398                if self.render_state == RenderState::NotInRenderLoop {
399                    self.quit();
400                    return false;
401                } else {
402                    self.render_state = RenderState::PendingQuit;
403                }
404            },
405            SessionMsg::GetBoundsGeometry(sender) => {
406                let bounds = self.device.reference_space_bounds();
407                let _ = sender.send(bounds);
408            },
409        }
410        true
411    }
412
413    fn send_frame(&self, frame: Frame) {
414        if let Some(frame_sender) = &self.frame_sender {
415            let _ = frame_sender.send(frame);
416        }
417    }
418
419    fn quit(&mut self) {
420        self.render_state = RenderState::NotInRenderLoop;
421        self.device.quit();
422    }
423}
424
425/// Devices that need to can run sessions on the main thread.
426pub trait MainThreadSession: 'static {
427    fn run_one_frame(&mut self);
428    fn running(&self) -> bool;
429}
430
431impl<Device> MainThreadSession for SessionThread<Device>
432where
433    Device: DeviceAPI,
434{
435    fn run_one_frame(&mut self) {
436        let frame_count = self.frame_count;
437        while frame_count == self.frame_count && self.running {
438            if let Ok(msg) = self.receiver.try_recv_timeout(TIMEOUT) {
439                self.running = self.handle_msg(msg);
440            } else {
441                break;
442            }
443        }
444    }
445
446    fn running(&self) -> bool {
447        self.running
448    }
449}
450
451/// A type for building XR sessions
452pub struct SessionBuilder<'a, GL> {
453    sessions: &'a mut Vec<Box<dyn MainThreadSession>>,
454    layer_grand_manager: LayerGrandManager<GL>,
455    id: SessionId,
456}
457
458impl<'a, GL: 'static> SessionBuilder<'a, GL> {
459    pub fn id(&self) -> SessionId {
460        self.id
461    }
462
463    pub(crate) fn new(
464        sessions: &'a mut Vec<Box<dyn MainThreadSession>>,
465        layer_grand_manager: LayerGrandManager<GL>,
466        id: SessionId,
467    ) -> Self {
468        SessionBuilder {
469            sessions,
470            layer_grand_manager,
471            id,
472        }
473    }
474
475    /// For devices which are happy to hand over thread management to webxr.
476    pub fn spawn<Device, Factory>(self, factory: Factory) -> Result<Session, Error>
477    where
478        Factory: 'static + FnOnce(LayerGrandManager<GL>) -> Result<Device, Error> + Send,
479        Device: DeviceAPI,
480    {
481        let Some((acks, ackr)) = generic_channel::channel() else {
482            return Err(Error::CommunicationError);
483        };
484        let layer_grand_manager = self.layer_grand_manager;
485        let id = self.id;
486        thread::spawn(move || {
487            match factory(layer_grand_manager).and_then(|device| SessionThread::new(device, id)) {
488                Ok(mut thread) => {
489                    let session = thread.new_session();
490                    let _ = acks.send(Ok(session));
491                    thread.run();
492                },
493                Err(err) => {
494                    let _ = acks.send(Err(err));
495                },
496            }
497        });
498        ackr.recv().unwrap_or(Err(Error::CommunicationError))
499    }
500
501    /// For devices that need to run on the main thread.
502    pub fn run_on_main_thread<Device, Factory>(self, factory: Factory) -> Result<Session, Error>
503    where
504        Factory: 'static + FnOnce(LayerGrandManager<GL>) -> Result<Device, Error>,
505        Device: DeviceAPI,
506    {
507        let device = factory(self.layer_grand_manager)?;
508        let mut session_thread = SessionThread::new(device, self.id)?;
509        let session = session_thread.new_session();
510        self.sessions.push(Box::new(session_thread));
511        Ok(session)
512    }
513}