Skip to main content

sui_render_wgpu/
interop.rs

1use std::collections::HashMap;
2use std::fmt;
3use std::sync::Arc;
4use std::sync::Condvar;
5use std::sync::Mutex;
6use std::sync::atomic::AtomicU64;
7use std::sync::atomic::Ordering;
8use std::time::Duration;
9use sui_core::Error;
10use sui_core::ImageHandle;
11use sui_core::Result;
12use sui_scene::RegisteredExternalImage;
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
15pub struct RendererInterop {
16    pub raw_wgpu_enabled: bool,
17}
18
19/// Cloneable access to the renderer-owned WGPU device and queue.
20///
21/// The handles refer to the exact device used by SUI. Applications can use
22/// them to populate textures or run conversion passes, then register the
23/// resulting sampled texture through [`WgpuExternalTextureRegistry`].
24#[derive(Debug, Clone)]
25pub struct WgpuExternalTextureContext {
26    pub(crate) device: wgpu::Device,
27    pub(crate) queue: wgpu::Queue,
28    pub(crate) adapter_info: wgpu::AdapterInfo,
29}
30
31impl WgpuExternalTextureContext {
32    pub fn device(&self) -> &wgpu::Device {
33        &self.device
34    }
35
36    pub fn queue(&self) -> &wgpu::Queue {
37        &self.queue
38    }
39
40    /// Identifies the physical/logical adapter backing the shared device.
41    ///
42    /// External renderers can persist the backend, adapter, and driver fields
43    /// alongside captures produced through SUI's device.
44    pub fn adapter_info(&self) -> &wgpu::AdapterInfo {
45        &self.adapter_info
46    }
47}
48
49#[derive(Debug, Clone)]
50pub(crate) struct WgpuExternalTextureEntry {
51    pub(crate) texture: wgpu::Texture,
52    pub(crate) view: wgpu::TextureView,
53    pub(crate) descriptor: RegisteredExternalImage,
54    pub(crate) binding_revision: u64,
55    pub(crate) content_revision: Option<u64>,
56}
57
58#[derive(Default)]
59pub(crate) struct WgpuExternalTextureRegistryInner {
60    pub(crate) context: Mutex<Option<WgpuExternalTextureContext>>,
61    pub(crate) context_ready: Condvar,
62    pub(crate) textures: Mutex<HashMap<ImageHandle, WgpuExternalTextureEntry>>,
63    pub(crate) next_binding_revision: AtomicU64,
64}
65
66/// Shared registry for app-owned textures sampled by SUI's normal image draw
67/// path.
68///
69/// This contract is intentionally media-agnostic. The application owns the
70/// producer, update cadence, pixel conversion, and texture contents. SUI owns
71/// only the renderer device handoff and sampled-texture lifetime needed to
72/// compose the resource with ordinary scene transforms and clips.
73#[derive(Clone, Default)]
74pub struct WgpuExternalTextureRegistry {
75    pub(crate) inner: Arc<WgpuExternalTextureRegistryInner>,
76}
77
78impl fmt::Debug for WgpuExternalTextureRegistry {
79    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
80        formatter
81            .debug_struct("WgpuExternalTextureRegistry")
82            .field("attached", &self.context().is_some())
83            .field("len", &self.len())
84            .finish()
85    }
86}
87
88impl WgpuExternalTextureRegistry {
89    pub fn new() -> Self {
90        Self::default()
91    }
92
93    /// Returns the renderer device once the first render target initializes.
94    pub fn context(&self) -> Option<WgpuExternalTextureContext> {
95        self.inner
96            .context
97            .lock()
98            .unwrap_or_else(|poisoned| poisoned.into_inner())
99            .clone()
100    }
101
102    /// Wait for renderer initialization without tying the registry to a
103    /// platform event-loop type.
104    pub fn wait_for_context(&self, timeout: Duration) -> Option<WgpuExternalTextureContext> {
105        let context = self
106            .inner
107            .context
108            .lock()
109            .unwrap_or_else(|poisoned| poisoned.into_inner());
110        let (context, _) = self
111            .inner
112            .context_ready
113            .wait_timeout_while(context, timeout, |context| context.is_none())
114            .unwrap_or_else(|poisoned| poisoned.into_inner());
115        context.clone()
116    }
117
118    /// Upload tightly packed sRGB RGBA8 pixels into a persistent texture.
119    /// Reusing `handle` and dimensions updates the existing allocation.
120    pub fn upload_rgba8(
121        &self,
122        handle: ImageHandle,
123        width: u32,
124        height: u32,
125        pixels: Arc<[u8]>,
126        revision: u64,
127    ) -> Result<RegisteredExternalImage> {
128        let context = self.context().ok_or_else(|| {
129            Error::new("external texture registry is not attached to an initialized renderer")
130        })?;
131        let descriptor = RegisteredExternalImage::new(width, height)?;
132        let row_bytes = width
133            .checked_mul(4)
134            .ok_or_else(|| Error::new("external RGBA8 image row size overflow"))?;
135        let expected_len = row_bytes
136            .checked_mul(height)
137            .map(|len| len as usize)
138            .ok_or_else(|| Error::new("external RGBA8 image byte size overflow"))?;
139        if pixels.len() != expected_len {
140            return Err(Error::new(format!(
141                "external RGBA8 image data length {} does not match expected size {} for a {}x{} image",
142                pixels.len(),
143                expected_len,
144                width,
145                height
146            )));
147        }
148
149        let mut textures = self
150            .inner
151            .textures
152            .lock()
153            .unwrap_or_else(|poisoned| poisoned.into_inner());
154        let reusable = textures.get_mut(&handle).filter(|entry| {
155            entry.descriptor == descriptor
156                && entry.texture.format() == wgpu::TextureFormat::Rgba8UnormSrgb
157                && entry
158                    .texture
159                    .usage()
160                    .contains(wgpu::TextureUsages::COPY_DST)
161        });
162        if let Some(entry) = reusable {
163            if entry.content_revision == Some(revision) {
164                return Ok(entry.descriptor);
165            }
166            Self::write_rgba8(&context.queue, &entry.texture, width, height, &pixels);
167            entry.content_revision = Some(revision);
168            return Ok(entry.descriptor);
169        }
170
171        let texture = context.device.create_texture(&wgpu::TextureDescriptor {
172            label: Some("SUI external RGBA8 texture"),
173            size: wgpu::Extent3d {
174                width,
175                height,
176                depth_or_array_layers: 1,
177            },
178            mip_level_count: 1,
179            sample_count: 1,
180            dimension: wgpu::TextureDimension::D2,
181            format: wgpu::TextureFormat::Rgba8UnormSrgb,
182            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
183            view_formats: &[],
184        });
185        Self::write_rgba8(&context.queue, &texture, width, height, &pixels);
186        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
187        let binding_revision = self.next_binding_revision();
188        textures.insert(
189            handle,
190            WgpuExternalTextureEntry {
191                texture,
192                view,
193                descriptor,
194                binding_revision,
195                content_revision: Some(revision),
196            },
197        );
198        Ok(descriptor)
199    }
200
201    /// Register a sampled texture created from this registry's renderer
202    /// context. This supports app-owned GPU conversion/render passes without
203    /// exposing backend-native shared-handle policy in SUI.
204    pub fn register_texture(
205        &self,
206        handle: ImageHandle,
207        texture: wgpu::Texture,
208    ) -> Result<RegisteredExternalImage> {
209        let context = self.context().ok_or_else(|| {
210            Error::new("external texture registry is not attached to an initialized renderer")
211        })?;
212        if texture.dimension() != wgpu::TextureDimension::D2
213            || texture.depth_or_array_layers() != 1
214            || texture.sample_count() != 1
215        {
216            return Err(Error::new(
217                "external texture must be a single-sampled two-dimensional texture",
218            ));
219        }
220        if !texture
221            .usage()
222            .contains(wgpu::TextureUsages::TEXTURE_BINDING)
223        {
224            return Err(Error::new(
225                "external texture must include TEXTURE_BINDING usage",
226            ));
227        }
228        if texture.format().sample_type(
229            Some(wgpu::TextureAspect::All),
230            Some(context.device.features()),
231        ) != Some(wgpu::TextureSampleType::Float { filterable: true })
232        {
233            return Err(Error::new(
234                "external texture format must support filterable float sampling",
235            ));
236        }
237
238        let descriptor = RegisteredExternalImage::new(texture.width(), texture.height())?;
239        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
240        let entry = WgpuExternalTextureEntry {
241            texture,
242            view,
243            descriptor,
244            binding_revision: self.next_binding_revision(),
245            content_revision: None,
246        };
247        self.inner
248            .textures
249            .lock()
250            .unwrap_or_else(|poisoned| poisoned.into_inner())
251            .insert(handle, entry);
252        Ok(descriptor)
253    }
254
255    pub fn unregister(&self, handle: ImageHandle) -> bool {
256        self.inner
257            .textures
258            .lock()
259            .unwrap_or_else(|poisoned| poisoned.into_inner())
260            .remove(&handle)
261            .is_some()
262    }
263
264    pub fn contains(&self, handle: ImageHandle) -> bool {
265        self.inner
266            .textures
267            .lock()
268            .unwrap_or_else(|poisoned| poisoned.into_inner())
269            .contains_key(&handle)
270    }
271
272    pub fn len(&self) -> usize {
273        self.inner
274            .textures
275            .lock()
276            .unwrap_or_else(|poisoned| poisoned.into_inner())
277            .len()
278    }
279
280    pub fn is_empty(&self) -> bool {
281        self.len() == 0
282    }
283
284    pub(crate) fn attach(
285        &self,
286        device: wgpu::Device,
287        queue: wgpu::Queue,
288        adapter_info: wgpu::AdapterInfo,
289    ) {
290        let mut context = self
291            .inner
292            .context
293            .lock()
294            .unwrap_or_else(|poisoned| poisoned.into_inner());
295        if context.is_none() {
296            *context = Some(WgpuExternalTextureContext {
297                device,
298                queue,
299                adapter_info,
300            });
301            self.inner.context_ready.notify_all();
302        }
303    }
304
305    pub(crate) fn resolve(&self, handle: ImageHandle) -> Option<WgpuExternalTextureEntry> {
306        self.inner
307            .textures
308            .lock()
309            .unwrap_or_else(|poisoned| poisoned.into_inner())
310            .get(&handle)
311            .cloned()
312    }
313
314    pub(crate) fn next_binding_revision(&self) -> u64 {
315        self.inner
316            .next_binding_revision
317            .fetch_add(1, Ordering::Relaxed)
318            .wrapping_add(1)
319    }
320
321    pub(crate) fn write_rgba8(
322        queue: &wgpu::Queue,
323        texture: &wgpu::Texture,
324        width: u32,
325        height: u32,
326        pixels: &[u8],
327    ) {
328        queue.write_texture(
329            wgpu::TexelCopyTextureInfo {
330                texture,
331                mip_level: 0,
332                origin: wgpu::Origin3d::ZERO,
333                aspect: wgpu::TextureAspect::All,
334            },
335            pixels,
336            wgpu::TexelCopyBufferLayout {
337                offset: 0,
338                bytes_per_row: Some(width * 4),
339                rows_per_image: Some(height),
340            },
341            wgpu::Extent3d {
342                width,
343                height,
344                depth_or_array_layers: 1,
345            },
346        );
347    }
348}