From 90eb399d4344a73ed723a9a4ab0249fde7bfa3c7 Mon Sep 17 00:00:00 2001 From: Jim Blandy Date: Fri, 2 Sep 2022 20:56:27 -0700 Subject: [PATCH] Fill in Adapter::as_hal and Device::as_hal documentation. (#2992) In particular, explain why a callback is needed, rather than just having these functions return an `Option<&A::Mumble>`. --- CHANGELOG.md | 2 ++ wgpu/src/lib.rs | 38 ++++++++++++++++++++++++++++++++------ 2 files changed, 34 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0255460545..3555702a5a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -90,6 +90,7 @@ the same every time it is rendered, we now warn if it is missing. - Update Winit to version 0.27 and raw-window-handle to 0.5 by @wyatt-herkamp in [#2918](https://github.com/gfx-rs/wgpu/pull/2918) - Address Clippy 0.1.63 complaints. By @jimblandy in [#2977](https://github.com/gfx-rs/wgpu/pull/2977) - Don't use `PhantomData` for `IdentityManager`'s `Input` type. By @jimblandy in [#2972](https://github.com/gfx-rs/wgpu/pull/2972) + #### Metal - Extract the generic code into `get_metal_layer` by @jinleili in [#2826](https://github.com/gfx-rs/wgpu/pull/2826) @@ -110,6 +111,7 @@ the same every time it is rendered, we now warn if it is missing. `Instance::create_surface_from_offscreen_canvas` regarding their safety contract. These functions are not unsafe. By @jimblandy [#2990](https://github.com/gfx-rs/wgpu/pull/2990) - Document that `write_buffer_with()` is sound but unwise to read from by @kpreid in [#3006](https://github.com/gfx-rs/wgpu/pull/3006) +- Explain why `Adapter::as_hal` and `Device::as_hal` have to take callback functions. By @jimblandy in [#2992](https://github.com/gfx-rs/wgpu/pull/2992) ### Build Configuration diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index 234165cdf2..541fa3566e 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -1916,12 +1916,25 @@ impl Adapter { }) } - /// Returns the inner hal Adapter using a callback. The hal adapter will be `None` if the - /// backend type argument does not match with this wgpu Adapter + /// Apply a callback to this `Adapter`'s underlying backend adapter. + /// + /// If this `Adapter` is implemented by the backend API given by `A` (Vulkan, + /// Dx12, etc.), then apply `hal_adapter_callback` to `Some(&adapter)`, where + /// `adapter` is the underlying backend adapter type, [`A::Adapter`]. + /// + /// If this `Adapter` uses a different backend, apply `hal_adapter_callback` + /// to `None`. + /// + /// The adapter is locked for reading while `hal_adapter_callback` runs. If + /// the callback attempts to perform any `wgpu` operations that require + /// write access to the adapter, deadlock will occur. The locks are + /// automatically released when the callback returns. /// /// # Safety /// - /// - The raw handle obtained from the hal Adapter must not be manually destroyed + /// - The raw handle passed to the callback must not be manually destroyed. + /// + /// [`A::Adapter`]: hal::Api::Adapter #[cfg(any(not(target_arch = "wasm32"), feature = "webgl"))] pub unsafe fn as_hal) -> R, R>( &self, @@ -2211,12 +2224,25 @@ impl Device { Context::device_stop_capture(&*self.context, &self.id) } - /// Returns the inner hal Device using a callback. The hal device will be `None` if the - /// backend type argument does not match with this wgpu Device + /// Apply a callback to this `Device`'s underlying backend device. + /// + /// If this `Device` is implemented by the backend API given by `A` (Vulkan, + /// Dx12, etc.), then apply `hal_device_callback` to `Some(&device)`, where + /// `device` is the underlying backend device type, [`A::Device`]. + /// + /// If this `Device` uses a different backend, apply `hal_device_callback` + /// to `None`. + /// + /// The device is locked for reading while `hal_device_callback` runs. If + /// the callback attempts to perform any `wgpu` operations that require + /// write access to the device (destroying a buffer, say), deadlock will + /// occur. The locks are automatically released when the callback returns. /// /// # Safety /// - /// - The raw handle obtained from the hal Device must not be manually destroyed + /// - The raw handle passed to the callback must not be manually destroyed. + /// + /// [`A::Device`]: hal::Api::Device #[cfg(any(not(target_arch = "wasm32"), feature = "emscripten"))] pub unsafe fn as_hal) -> R, R>( &self,