1use alloc::{sync::Arc, vec::Vec};
13use core::mem::ManuallyDrop;
14
15#[cfg(feature = "trace")]
16use crate::device::trace::Action;
17use crate::{
18 conv,
19 device::{Device, DeviceError, MissingDownlevelFlags, WaitIdleError},
20 global::Global,
21 hal_label, id,
22 instance::Surface,
23 resource,
24};
25
26use thiserror::Error;
27use wgt::{
28 error::{ErrorType, WebGpuError},
29 SurfaceStatus as Status,
30};
31
32const FRAME_TIMEOUT_MS: u32 = 1000;
33
34#[derive(Debug)]
35pub(crate) struct Presentation {
36 pub(crate) device: Arc<Device>,
37 pub(crate) config: wgt::SurfaceConfiguration<Vec<wgt::TextureFormat>>,
38 pub(crate) acquired_texture: Option<Arc<resource::Texture>>,
39}
40
41#[derive(Clone, Debug, Error)]
42#[non_exhaustive]
43pub enum SurfaceError {
44 #[error("Surface is invalid")]
45 Invalid,
46 #[error("Surface is not configured for presentation")]
47 NotConfigured,
48 #[error(transparent)]
49 Device(#[from] DeviceError),
50 #[error("Surface image is already acquired")]
51 AlreadyAcquired,
52 #[error("Texture has been destroyed")]
53 TextureDestroyed,
54}
55
56impl WebGpuError for SurfaceError {
57 fn webgpu_error_type(&self) -> ErrorType {
58 let e: &dyn WebGpuError = match self {
59 Self::Device(e) => e,
60 Self::Invalid
61 | Self::NotConfigured
62 | Self::AlreadyAcquired
63 | Self::TextureDestroyed => return ErrorType::Validation,
64 };
65 e.webgpu_error_type()
66 }
67}
68
69#[derive(Clone, Debug, Error)]
70#[non_exhaustive]
71pub enum ConfigureSurfaceError {
72 #[error(transparent)]
73 Device(#[from] DeviceError),
74 #[error("Invalid surface")]
75 InvalidSurface,
76 #[error("The view format {0:?} is not compatible with texture format {1:?}, only changing srgb-ness is allowed.")]
77 InvalidViewFormat(wgt::TextureFormat, wgt::TextureFormat),
78 #[error(transparent)]
79 MissingDownlevelFlags(#[from] MissingDownlevelFlags),
80 #[error("`SurfaceOutput` must be dropped before a new `Surface` is made")]
81 PreviousOutputExists,
82 #[error("Failed to wait for GPU to come idle before reconfiguring the Surface")]
83 GpuWaitTimeout,
84 #[error("Both `Surface` width and height must be non-zero. Wait to recreate the `Surface` until the window has non-zero area.")]
85 ZeroArea,
86 #[error("`Surface` width and height must be within the maximum supported texture size. Requested was ({width}, {height}), maximum extent for either dimension is {max_texture_dimension_2d}.")]
87 TooLarge {
88 width: u32,
89 height: u32,
90 max_texture_dimension_2d: u32,
91 },
92 #[error("Surface does not support the adapter's queue family")]
93 UnsupportedQueueFamily,
94 #[error("Requested format {requested:?} is not in list of supported formats: {available:?}")]
95 UnsupportedFormat {
96 requested: wgt::TextureFormat,
97 available: Vec<wgt::TextureFormat>,
98 },
99 #[error("Requested present mode {requested:?} is not in the list of supported present modes: {available:?}")]
100 UnsupportedPresentMode {
101 requested: wgt::PresentMode,
102 available: Vec<wgt::PresentMode>,
103 },
104 #[error("Requested alpha mode {requested:?} is not in the list of supported alpha modes: {available:?}")]
105 UnsupportedAlphaMode {
106 requested: wgt::CompositeAlphaMode,
107 available: Vec<wgt::CompositeAlphaMode>,
108 },
109 #[error("Requested usage {requested:?} is not in the list of supported usages: {available:?}")]
110 UnsupportedUsage {
111 requested: wgt::TextureUses,
112 available: wgt::TextureUses,
113 },
114}
115
116impl From<WaitIdleError> for ConfigureSurfaceError {
117 fn from(e: WaitIdleError) -> Self {
118 match e {
119 WaitIdleError::Device(d) => ConfigureSurfaceError::Device(d),
120 WaitIdleError::WrongSubmissionIndex(..) => unreachable!(),
121 WaitIdleError::Timeout => ConfigureSurfaceError::GpuWaitTimeout,
122 }
123 }
124}
125
126impl WebGpuError for ConfigureSurfaceError {
127 fn webgpu_error_type(&self) -> ErrorType {
128 let e: &dyn WebGpuError = match self {
129 Self::Device(e) => e,
130 Self::MissingDownlevelFlags(e) => e,
131 Self::InvalidSurface
132 | Self::InvalidViewFormat(..)
133 | Self::PreviousOutputExists
134 | Self::GpuWaitTimeout
135 | Self::ZeroArea
136 | Self::TooLarge { .. }
137 | Self::UnsupportedQueueFamily
138 | Self::UnsupportedFormat { .. }
139 | Self::UnsupportedPresentMode { .. }
140 | Self::UnsupportedAlphaMode { .. }
141 | Self::UnsupportedUsage { .. } => return ErrorType::Validation,
142 };
143 e.webgpu_error_type()
144 }
145}
146
147pub type ResolvedSurfaceOutput = SurfaceOutput<Arc<resource::Texture>>;
148
149#[repr(C)]
150#[derive(Debug)]
151pub struct SurfaceOutput<T = id::TextureId> {
152 pub status: Status,
153 pub texture: Option<T>,
154}
155
156impl Surface {
157 pub fn get_current_texture(&self) -> Result<ResolvedSurfaceOutput, SurfaceError> {
158 profiling::scope!("Surface::get_current_texture");
159
160 let (device, config) = if let Some(ref present) = *self.presentation.lock() {
161 present.device.check_is_valid()?;
162 (present.device.clone(), present.config.clone())
163 } else {
164 return Err(SurfaceError::NotConfigured);
165 };
166
167 let fence = device.fence.read();
168
169 let suf = self.raw(device.backend()).unwrap();
170 let (texture, status) = match unsafe {
171 suf.acquire_texture(
172 Some(core::time::Duration::from_millis(FRAME_TIMEOUT_MS as u64)),
173 fence.as_ref(),
174 )
175 } {
176 Ok(Some(ast)) => {
177 drop(fence);
178
179 let texture_desc = wgt::TextureDescriptor {
180 label: Some(alloc::borrow::Cow::Borrowed("<Surface Texture>")),
181 size: wgt::Extent3d {
182 width: config.width,
183 height: config.height,
184 depth_or_array_layers: 1,
185 },
186 sample_count: 1,
187 mip_level_count: 1,
188 format: config.format,
189 dimension: wgt::TextureDimension::D2,
190 usage: config.usage,
191 view_formats: config.view_formats,
192 };
193 let format_features = wgt::TextureFormatFeatures {
194 allowed_usages: wgt::TextureUsages::RENDER_ATTACHMENT,
195 flags: wgt::TextureFormatFeatureFlags::MULTISAMPLE_X4
196 | wgt::TextureFormatFeatureFlags::MULTISAMPLE_RESOLVE,
197 };
198 let hal_usage = conv::map_texture_usage(
199 config.usage,
200 config.format.into(),
201 format_features.flags,
202 );
203 let clear_view_desc = hal::TextureViewDescriptor {
204 label: hal_label(
205 Some("(wgpu internal) clear surface texture view"),
206 device.instance_flags,
207 ),
208 format: config.format,
209 dimension: wgt::TextureViewDimension::D2,
210 usage: wgt::TextureUses::COLOR_TARGET,
211 range: wgt::ImageSubresourceRange::default(),
212 };
213 let clear_view = unsafe {
214 device
215 .raw()
216 .create_texture_view(ast.texture.as_ref().borrow(), &clear_view_desc)
217 }
218 .map_err(|e| device.handle_hal_error(e))?;
219
220 let mut presentation = self.presentation.lock();
221 let present = presentation.as_mut().unwrap();
222 let texture = resource::Texture::new(
223 &device,
224 resource::TextureInner::Surface { raw: ast.texture },
225 hal_usage,
226 &texture_desc,
227 format_features,
228 resource::TextureClearMode::Surface {
229 clear_view: ManuallyDrop::new(clear_view),
230 },
231 true,
232 );
233
234 let texture = Arc::new(texture);
235
236 device
237 .trackers
238 .lock()
239 .textures
240 .insert_single(&texture, wgt::TextureUses::UNINITIALIZED);
241
242 if present.acquired_texture.is_some() {
243 return Err(SurfaceError::AlreadyAcquired);
244 }
245 present.acquired_texture = Some(texture.clone());
246
247 let status = if ast.suboptimal {
248 Status::Suboptimal
249 } else {
250 Status::Good
251 };
252 (Some(texture), status)
253 }
254 Ok(None) => (None, Status::Timeout),
255 Err(err) => (
256 None,
257 match err {
258 hal::SurfaceError::Lost => Status::Lost,
259 hal::SurfaceError::Device(err) => {
260 return Err(device.handle_hal_error(err).into());
261 }
262 hal::SurfaceError::Outdated => Status::Outdated,
263 hal::SurfaceError::Other(msg) => {
264 log::error!("acquire error: {}", msg);
265 Status::Lost
266 }
267 },
268 ),
269 };
270
271 Ok(ResolvedSurfaceOutput { status, texture })
272 }
273
274 pub fn present(&self) -> Result<Status, SurfaceError> {
275 profiling::scope!("Surface::present");
276
277 let mut presentation = self.presentation.lock();
278 let present = match presentation.as_mut() {
279 Some(present) => present,
280 None => return Err(SurfaceError::NotConfigured),
281 };
282
283 let device = &present.device;
284
285 device.check_is_valid()?;
286 let queue = device.get_queue().unwrap();
287
288 let texture = present
289 .acquired_texture
290 .take()
291 .ok_or(SurfaceError::AlreadyAcquired)?;
292
293 let result = match texture.inner.snatch(&mut device.snatchable_lock.write()) {
294 None => return Err(SurfaceError::TextureDestroyed),
295 Some(resource::TextureInner::Surface { raw }) => {
296 let raw_surface = self.raw(device.backend()).unwrap();
297 let raw_queue = queue.raw();
298 unsafe { raw_queue.present(raw_surface, raw) }
299 }
300 _ => unreachable!(),
301 };
302
303 match result {
304 Ok(()) => Ok(Status::Good),
305 Err(err) => match err {
306 hal::SurfaceError::Lost => Ok(Status::Lost),
307 hal::SurfaceError::Device(err) => {
308 Err(SurfaceError::from(device.handle_hal_error(err)))
309 }
310 hal::SurfaceError::Outdated => Ok(Status::Outdated),
311 hal::SurfaceError::Other(msg) => {
312 log::error!("acquire error: {}", msg);
313 Err(SurfaceError::Invalid)
314 }
315 },
316 }
317 }
318
319 pub fn discard(&self) -> Result<(), SurfaceError> {
320 profiling::scope!("Surface::discard");
321
322 let mut presentation = self.presentation.lock();
323 let present = match presentation.as_mut() {
324 Some(present) => present,
325 None => return Err(SurfaceError::NotConfigured),
326 };
327
328 let device = &present.device;
329
330 device.check_is_valid()?;
331
332 let texture = present
333 .acquired_texture
334 .take()
335 .ok_or(SurfaceError::AlreadyAcquired)?;
336
337 match texture.inner.snatch(&mut device.snatchable_lock.write()) {
338 None => return Err(SurfaceError::TextureDestroyed),
339 Some(resource::TextureInner::Surface { raw }) => {
340 let raw_surface = self.raw(device.backend()).unwrap();
341 unsafe { raw_surface.discard_texture(raw) };
342 }
343 _ => unreachable!(),
344 }
345
346 Ok(())
347 }
348}
349
350impl Global {
351 pub fn surface_get_current_texture(
352 &self,
353 surface_id: id::SurfaceId,
354 texture_id_in: Option<id::TextureId>,
355 ) -> Result<SurfaceOutput, SurfaceError> {
356 let surface = self.surfaces.get(surface_id);
357
358 let fid = self.hub.textures.prepare(texture_id_in);
359
360 #[cfg(feature = "trace")]
361 if let Some(present) = surface.presentation.lock().as_ref() {
362 if let Some(ref mut trace) = *present.device.trace.lock() {
363 trace.add(Action::GetSurfaceTexture {
364 id: fid.id(),
365 parent_id: surface_id,
366 });
367 }
368 }
369
370 let output = surface.get_current_texture()?;
371
372 let status = output.status;
373 let texture_id = output
374 .texture
375 .map(|texture| fid.assign(resource::Fallible::Valid(texture)));
376
377 Ok(SurfaceOutput {
378 status,
379 texture: texture_id,
380 })
381 }
382
383 pub fn surface_present(&self, surface_id: id::SurfaceId) -> Result<Status, SurfaceError> {
384 let surface = self.surfaces.get(surface_id);
385
386 #[cfg(feature = "trace")]
387 if let Some(present) = surface.presentation.lock().as_ref() {
388 if let Some(ref mut trace) = *present.device.trace.lock() {
389 trace.add(Action::Present(surface_id));
390 }
391 }
392
393 surface.present()
394 }
395
396 pub fn surface_texture_discard(&self, surface_id: id::SurfaceId) -> Result<(), SurfaceError> {
397 let surface = self.surfaces.get(surface_id);
398
399 #[cfg(feature = "trace")]
400 if let Some(present) = surface.presentation.lock().as_ref() {
401 if let Some(ref mut trace) = *present.device.trace.lock() {
402 trace.add(Action::DiscardSurfaceTexture(surface_id));
403 }
404 }
405
406 surface.discard()
407 }
408}