Skip to main content

redjs_webgpu/
backend.rs

1//! Native GPU ownership, shared-device injection and per-client isolation.
2//!
3//! This layer contains no JSC values. An embedder can supply its renderer's
4//! device through `GpuHost`; a JavaScript client's `destroy()` never destroys
5//! that physical device or replaces the embedder's error/loss callbacks.
6
7use std::future::Future;
8use std::pin::Pin;
9use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
10use std::sync::{Arc, Mutex, OnceLock, RwLock, Weak};
11
12#[derive(Clone, Copy, Debug, Default)]
13pub struct AdapterOptions {
14    pub power_preference: wgpu::PowerPreference,
15    pub force_fallback_adapter: bool,
16}
17
18#[derive(Clone)]
19pub struct Adapter {
20    pub raw: Arc<wgpu::Adapter>,
21    pub shared: Option<Arc<Context>>,
22}
23
24/// A loss notification owned by the host rather than by any one JS client.
25#[derive(Clone, Debug)]
26pub struct DeviceLoss {
27    pub reason: &'static str,
28    pub message: String,
29}
30
31/// The physical device and queue, potentially also owned by GPUI.
32///
33/// Construct with `from_shared` when importing a renderer's existing device.
34/// That constructor does not change either of wgpu's process/device callbacks.
35/// Forward a renderer-owned loss callback into `notify_lost` so all logical
36/// clients observe the same device generation becoming unusable.
37pub struct Context {
38    pub device: Arc<wgpu::Device>,
39    pub queue: Arc<wgpu::Queue>,
40    pub adapter: Arc<wgpu::Adapter>,
41    loss: Arc<Mutex<Option<DeviceLoss>>>,
42    // Declared last so a host generation outlives the wgpu wrappers above.
43    _owner: Option<Arc<dyn std::any::Any + Send + Sync>>,
44}
45
46impl Context {
47    pub fn from_shared(
48        adapter: Arc<wgpu::Adapter>,
49        device: Arc<wgpu::Device>,
50        queue: Arc<wgpu::Queue>,
51    ) -> Self {
52        Self {
53            adapter,
54            device,
55            queue,
56            loss: Arc::new(Mutex::new(None)),
57            _owner: None,
58        }
59    }
60
61    /// Retains the renderer generation whose physical device backs these
62    /// wrappers. Logical clients may outlive the window which requested them.
63    pub fn from_shared_with_owner(
64        adapter: Arc<wgpu::Adapter>,
65        device: Arc<wgpu::Device>,
66        queue: Arc<wgpu::Queue>,
67        owner: Arc<dyn std::any::Any + Send + Sync>,
68    ) -> Self {
69        Self {
70            _owner: Some(owner),
71            ..Self::from_shared(adapter, device, queue)
72        }
73    }
74
75    pub fn notify_lost(&self, reason: &'static str, message: impl Into<String>) {
76        let mut loss = self.loss.lock().unwrap();
77        if loss.is_none() {
78            *loss = Some(DeviceLoss {
79                reason,
80                message: message.into(),
81            });
82        }
83    }
84
85    pub fn loss(&self) -> Option<DeviceLoss> {
86        self.loss.lock().unwrap().clone()
87    }
88}
89
90pub type AdapterFuture =
91    Pin<Box<dyn Future<Output = Result<Option<Adapter>, String>> + Send + 'static>>;
92
93pub trait GpuHost: Send + Sync {
94    /// A shared adapter must pair `raw` with the adapter used to create its
95    /// `shared` context. A host controls feature/limit negotiation on that
96    /// physical device before handing it to redjs.
97    fn request_adapter(&self, options: AdapterOptions) -> AdapterFuture;
98}
99
100fn host_slot() -> &'static RwLock<Option<Arc<dyn GpuHost>>> {
101    static HOST: OnceLock<RwLock<Option<Arc<dyn GpuHost>>>> = OnceLock::new();
102    HOST.get_or_init(|| RwLock::new(None))
103}
104
105/// Changes the provider for future requests. Existing adapters/devices retain
106/// their original provider's resources and continue to work.
107pub fn set_host(host: Option<Arc<dyn GpuHost>>) {
108    *host_slot().write().unwrap() = host;
109}
110
111pub async fn request_adapter(options: AdapterOptions) -> Result<Option<Adapter>, String> {
112    let host = host_slot().read().unwrap().clone();
113    if let Some(host) = host {
114        return host.request_adapter(options).await;
115    }
116    // No work is done at JS-global installation time. Windows deliberately
117    // selects D3D12, the backend that can eventually share GPUI's device;
118    // D3D11 is not a wgpu backend.
119    let mut descriptor = wgpu::InstanceDescriptor::new_without_display_handle();
120    descriptor.backends = if cfg!(target_os = "windows") {
121        wgpu::Backends::DX12
122    } else {
123        wgpu::Backends::PRIMARY
124    };
125    descriptor.flags |= wgpu::InstanceFlags::AUTOMATIC_TIMESTAMP_NORMALIZATION;
126    let instance = wgpu::Instance::new(descriptor);
127    match instance
128        .request_adapter(&wgpu::RequestAdapterOptions {
129            power_preference: options.power_preference,
130            force_fallback_adapter: options.force_fallback_adapter,
131            compatible_surface: None,
132            ..Default::default()
133        })
134        .await
135    {
136        Ok(raw) => Ok(Some(Adapter {
137            raw: Arc::new(raw),
138            shared: None,
139        })),
140        // The WebGPU result for an unavailable matching adapter is null.
141        Err(_) => Ok(None),
142    }
143}
144
145/// Physical capabilities a shared client may lack: redjs validates every JS
146/// path to them against the client's own features and limits.
147pub const VIRTUALIZED_FEATURES: wgpu::Features =
148    wgpu::Features::TIMESTAMP_QUERY.union(wgpu::Features::IMMEDIATES);
149
150/// What a physical device needs for JS clients to get every feature and the
151/// immediate-data limit the adapter can expose. Hosts creating a shared device
152/// should request these, on an instance with
153/// `InstanceFlags::AUTOMATIC_TIMESTAMP_NORMALIZATION`.
154pub fn shareable_capabilities(adapter: &wgpu::Adapter) -> (wgpu::Features, wgpu::Limits) {
155    let features = adapter.features() & VIRTUALIZED_FEATURES;
156    let mut limits = wgpu::Limits::default();
157    if features.contains(wgpu::Features::IMMEDIATES) {
158        limits.max_immediate_size = adapter.limits().max_immediate_size;
159    }
160    (features, limits)
161}
162
163impl Adapter {
164    pub fn features(&self) -> wgpu::Features {
165        match &self.shared {
166            // WebGPU resolves timestamps in nanoseconds; an unnormalized
167            // device period cannot honour that.
168            Some(c) if c.queue.get_timestamp_period() != 1.0 => {
169                c.device.features() - wgpu::Features::TIMESTAMP_QUERY
170            }
171            Some(c) => c.device.features(),
172            None => self.raw.features(),
173        }
174    }
175
176    pub fn limits(&self) -> wgpu::Limits {
177        self.shared
178            .as_ref()
179            .map_or_else(|| self.raw.limits(), |c| c.device.limits())
180    }
181
182    pub async fn request_device(
183        &self,
184        features: wgpu::Features,
185        limits: wgpu::Limits,
186    ) -> Result<Arc<Context>, String> {
187        let available_features = self.features();
188        if !available_features.contains(features) {
189            return Err(format!(
190                "Unsupported requiredFeatures: {:?}",
191                features - available_features
192            ));
193        }
194        let available_limits = self.limits();
195        if !limits.check_limits(&available_limits) {
196            let mut failures = Vec::new();
197            limits.check_limits_with_fail_fn(
198                &available_limits,
199                false,
200                |name, requested, allowed| {
201                    failures.push(format!(
202                        "{name}: requested {requested}, available {allowed}"
203                    ));
204                },
205            );
206            return Err(format!(
207                "Unsupported requiredLimits: {}",
208                failures.join(", ")
209            ));
210        }
211        if let Some(context) = &self.shared {
212            // Until every shader/pipeline limit is virtualized per client,
213            // refuse capability subsets rather than silently validating them
214            // against stronger physical capabilities.
215            let physical = context.device.limits();
216            let comparable = wgpu::Limits {
217                max_immediate_size: physical.max_immediate_size,
218                ..limits.clone()
219            };
220            if !VIRTUALIZED_FEATURES.contains(context.device.features() - features)
221                || comparable != physical
222            {
223                return Err(
224                    "Shared WebGPU clients currently require matching physical capabilities".into(),
225                );
226            }
227            if context.adapter.as_ref() != self.raw.as_ref() {
228                return Err("Shared GPU context belongs to a different adapter".into());
229            }
230            if let Some(loss) = context.loss() {
231                return Err(format!("Shared GPU device is lost: {}", loss.message));
232            }
233            return Ok(context.clone());
234        }
235        let features = if limits.max_immediate_size > 0 {
236            features | wgpu::Features::IMMEDIATES
237        } else {
238            features
239        };
240        let (device, queue) = self
241            .raw
242            .request_device(&wgpu::DeviceDescriptor {
243                label: Some("redjs WebGPU"),
244                required_features: features,
245                required_limits: limits,
246                memory_hints: wgpu::MemoryHints::MemoryUsage,
247                ..Default::default()
248            })
249            .await
250            .map_err(|e| e.to_string())?;
251        let context = Arc::new(Context::from_shared(
252            self.raw.clone(),
253            Arc::new(device),
254            Arc::new(queue),
255        ));
256        // This is our standalone device: there is no embedder callback to
257        // replace. Shared-device hosts forward their own callback instead.
258        let loss = context.loss.clone();
259        context
260            .device
261            .set_device_lost_callback(move |reason, message| {
262                let mut state = loss.lock().unwrap();
263                if state.is_none() {
264                    *state = Some(DeviceLoss {
265                        reason: if reason == wgpu::DeviceLostReason::Destroyed {
266                            "destroyed"
267                        } else {
268                            "unknown"
269                        },
270                        message,
271                    });
272                }
273            });
274        Ok(context)
275    }
276}
277
278/// Runs `operation` inside this thread's own error scopes and returns the
279/// first error it raised, instead of recording it on a client.
280pub fn scoped<T>(device: &wgpu::Device, operation: impl FnOnce() -> T) -> (T, Option<wgpu::Error>) {
281    let internal = device.push_error_scope(wgpu::ErrorFilter::Internal);
282    let oom = device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
283    let validation = device.push_error_scope(wgpu::ErrorFilter::Validation);
284    let result = operation();
285    let error = [
286        pollster::block_on(validation.pop()),
287        pollster::block_on(oom.pop()),
288        pollster::block_on(internal.pop()),
289    ]
290    .into_iter()
291    .flatten()
292    .next();
293    (result, error)
294}
295
296/// One step of waiting for `device`'s callbacks: a pause, growing from none to 1 ms, then a
297/// non-blocking poll. Never a timed `PollType::Wait`: wgpu-core panics when such a wait times
298/// out and another thread's poll meanwhile retires every submission in flight.
299pub(crate) fn pump(
300    device: &wgpu::Device,
301    pause: &mut std::time::Duration,
302) -> Result<wgpu::PollStatus, wgpu::PollError> {
303    std::thread::sleep(*pause);
304    *pause = (*pause * 2).clamp(
305        std::time::Duration::from_micros(50),
306        std::time::Duration::from_millis(1),
307    );
308    device.poll(wgpu::PollType::Poll)
309}
310
311#[derive(Clone, Debug)]
312pub struct GpuError {
313    /// WebGPU filter spelling: validation / out-of-memory / internal.
314    pub kind: &'static str,
315    pub message: String,
316}
317
318#[derive(Default)]
319struct Resources {
320    buffers: Vec<Weak<wgpu::Buffer>>,
321    textures: Vec<Weak<wgpu::Texture>>,
322}
323
324/// One logical JavaScript GPUDevice. Resource brands use this id even when
325/// two clients share an identical physical device.
326pub struct Client {
327    pub context: Arc<Context>,
328    pub id: u64,
329    pub features: wgpu::Features,
330    pub limits: wgpu::Limits,
331    pub destroyed: AtomicBool,
332    resources: Mutex<Resources>,
333    errors: Mutex<Vec<GpuError>>,
334}
335
336impl Client {
337    pub fn new(context: Arc<Context>) -> Arc<Self> {
338        let features = context.device.features();
339        let limits = context.device.limits();
340        Self::new_with_capabilities(context, features, limits)
341    }
342
343    pub fn new_with_capabilities(
344        context: Arc<Context>,
345        features: wgpu::Features,
346        limits: wgpu::Limits,
347    ) -> Arc<Self> {
348        static NEXT: AtomicU64 = AtomicU64::new(1);
349        Arc::new(Self {
350            context,
351            id: NEXT.fetch_add(1, Ordering::Relaxed),
352            features,
353            limits,
354            destroyed: AtomicBool::new(false),
355            resources: Mutex::new(Resources::default()),
356            errors: Mutex::new(Vec::new()),
357        })
358    }
359
360    pub fn check(&self) -> Result<(), String> {
361        if self.destroyed.load(Ordering::Acquire) {
362            return Err("GPUDevice has been destroyed".into());
363        }
364        if let Some(loss) = self.context.loss() {
365            return Err(format!("GPUDevice is lost: {}", loss.message));
366        }
367        Ok(())
368    }
369
370    pub fn track_buffer(&self, buffer: &Arc<wgpu::Buffer>) {
371        let mut resources = self.resources.lock().unwrap();
372        if self.destroyed.load(Ordering::Acquire) {
373            drop(resources);
374            buffer.destroy();
375        } else {
376            resources.buffers.retain(|b| b.strong_count() != 0);
377            resources.buffers.push(Arc::downgrade(buffer));
378        }
379    }
380
381    pub fn track_texture(&self, texture: &Arc<wgpu::Texture>) {
382        let mut resources = self.resources.lock().unwrap();
383        if self.destroyed.load(Ordering::Acquire) {
384            drop(resources);
385            texture.destroy();
386        } else {
387            resources.textures.retain(|t| t.strong_count() != 0);
388            resources.textures.push(Arc::downgrade(texture));
389        }
390    }
391
392    /// Transfers an expired canvas buffer to a host presentation owner. Its JS
393    /// wrapper is already invalid; physical destruction now follows that owner.
394    pub(super) fn release_presented_texture(&self, texture: &Arc<wgpu::Texture>) -> bool {
395        let mut resources = self.resources.lock().unwrap();
396        if self.destroyed.load(Ordering::Acquire) {
397            return false;
398        }
399        resources.textures.retain(|weak| {
400            weak.upgrade()
401                .is_some_and(|raw| !Arc::ptr_eq(&raw, texture))
402        });
403        true
404    }
405
406    /// Explicit logical destruction. Never calls wgpu::Device::destroy.
407    pub fn destroy(&self) {
408        let resources = {
409            let mut resources = self.resources.lock().unwrap();
410            if self.destroyed.swap(true, Ordering::AcqRel) {
411                return;
412            }
413            std::mem::take(&mut *resources)
414        };
415        for buffer in resources.buffers.into_iter().filter_map(|b| b.upgrade()) {
416            buffer.destroy();
417        }
418        for texture in resources.textures.into_iter().filter_map(|t| t.upgrade()) {
419            texture.destroy();
420        }
421    }
422
423    pub fn record_error(&self, kind: &'static str, message: impl Into<String>) {
424        self.errors.lock().unwrap().push(GpuError {
425            kind,
426            message: message.into(),
427        });
428    }
429
430    pub fn has_errors(&self) -> bool {
431        !self.errors.lock().unwrap().is_empty()
432    }
433
434    pub fn take_errors(&self) -> Vec<GpuError> {
435        std::mem::take(&mut *self.errors.lock().unwrap())
436    }
437
438    /// Every native operation gets its own short-lived, thread-local scopes.
439    /// It cannot steal GPUI's errors or another JS client's scope. The native
440    /// wgpu-core backend's pop futures are already-ready (no GPU queue wait).
441    /// Logical JS error scopes are managed by the binding above this layer.
442    pub fn checked<T>(&self, operation: impl FnOnce() -> T) -> T {
443        let device = &self.context.device;
444        let internal = device.push_error_scope(wgpu::ErrorFilter::Internal);
445        let oom = device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
446        let validation = device.push_error_scope(wgpu::ErrorFilter::Validation);
447        let result = operation();
448        for error in [
449            pollster::block_on(validation.pop()),
450            pollster::block_on(oom.pop()),
451            pollster::block_on(internal.pop()),
452        ]
453        .into_iter()
454        .flatten()
455        {
456            let kind = match &error {
457                wgpu::Error::Validation { .. } => "validation",
458                wgpu::Error::OutOfMemory { .. } => "out-of-memory",
459                wgpu::Error::Internal { .. } => "internal",
460            };
461            self.record_error(kind, error.to_string());
462        }
463        result
464    }
465}