Skip to main content

wgpu_hal/
lib.rs

1//! A cross-platform unsafe graphics abstraction.
2//!
3//! This crate defines a set of traits abstracting over modern graphics APIs,
4//! with implementations ("backends") for Vulkan, Metal, Direct3D, and GL.
5//!
6//! `wgpu-hal` is a spiritual successor to
7//! [gfx-hal](https://github.com/gfx-rs/gfx), but with reduced scope, and
8//! oriented towards WebGPU implementation goals. It has no overhead for
9//! validation or tracking, and the API translation overhead is kept to the bare
10//! minimum by the design of WebGPU. This API can be used for resource-demanding
11//! applications and engines.
12//!
13//! The `wgpu-hal` crate's main design choices:
14//!
15//! - Our traits are meant to be *portable*: proper use
16//!   should get equivalent results regardless of the backend.
17//!
18//! - Our traits' contracts are *unsafe*: implementations perform minimal
19//!   validation, if any, and incorrect use will often cause undefined behavior.
20//!   This allows us to minimize the overhead we impose over the underlying
21//!   graphics system. If you need safety, the [`wgpu-core`] crate provides a
22//!   safe API for driving `wgpu-hal`, implementing all necessary validation,
23//!   resource state tracking, and so on. (Note that `wgpu-core` is designed for
24//!   use via FFI; the [`wgpu`] crate provides more idiomatic Rust bindings for
25//!   `wgpu-core`.) Or, you can do your own validation.
26//!
27//! - In the same vein, returned errors *only cover cases the user can't
28//!   anticipate*, like running out of memory or losing the device. Any errors
29//!   that the user could reasonably anticipate are their responsibility to
30//!   avoid. For example, `wgpu-hal` returns no error for mapping a buffer that's
31//!   not mappable: as the buffer creator, the user should already know if they
32//!   can map it.
33//!
34//! - We use *static dispatch*. The traits are not
35//!   generally object-safe. You must select a specific backend type
36//!   like [`vulkan::Api`] or [`metal::Api`], and then use that
37//!   according to the main traits, or call backend-specific methods.
38//!
39//! - We use *idiomatic Rust parameter passing*,
40//!   taking objects by reference, returning them by value, and so on,
41//!   unlike `wgpu-core`, which refers to objects by ID.
42//!
43//! - We map buffer contents *persistently*. This means that the buffer can
44//!   remain mapped on the CPU while the GPU reads or writes to it. You must
45//!   explicitly indicate when data might need to be transferred between CPU and
46//!   GPU, if [`Device::map_buffer`] indicates that this is necessary.
47//!
48//! - You must record *explicit barriers* between different usages of a
49//!   resource. For example, if a buffer is written to by a compute
50//!   shader, and then used as and index buffer to a draw call, you
51//!   must use [`CommandEncoder::transition_buffers`] between those two
52//!   operations.
53//!
54//! - Pipeline layouts are *explicitly specified* when setting bind groups.
55//!   Incompatible layouts disturb groups bound at higher indices.
56//!
57//! - The API *accepts collections as iterators*, to avoid forcing the user to
58//!   store data in particular containers. The implementation doesn't guarantee
59//!   that any of the iterators are drained, unless stated otherwise by the
60//!   function documentation. For this reason, we recommend that iterators don't
61//!   do any mutating work.
62//!
63//! Unfortunately, `wgpu-hal`'s safety requirements are not fully documented.
64//! Ideally, all trait methods would have doc comments setting out the
65//! requirements users must meet to ensure correct and portable behavior. If you
66//! are aware of a specific requirement that a backend imposes that is not
67//! ensured by the traits' documented rules, please file an issue. Or, if you are
68//! a capable technical writer, please file a pull request!
69//!
70//! [`wgpu-core`]: https://crates.io/crates/wgpu-core
71//! [`wgpu`]: https://crates.io/crates/wgpu
72//! [`vulkan::Api`]: vulkan/struct.Api.html
73//! [`metal::Api`]: metal/struct.Api.html
74//!
75//! ## Primary backends
76//!
77//! The `wgpu-hal` crate has full-featured backends implemented on the following
78//! platform graphics APIs:
79//!
80//! - Vulkan, available on Linux, Android, and Windows, using the [`ash`] crate's
81//!   Vulkan bindings. It's also available on macOS, if you install [MoltenVK].
82//!
83//! - Metal on macOS, using the [`metal`] crate's bindings.
84//!
85//! - Direct3D 12 on Windows, using the [`windows`] crate's bindings.
86//!
87//! [`ash`]: https://crates.io/crates/ash
88//! [MoltenVK]: https://github.com/KhronosGroup/MoltenVK
89//! [`metal`]: https://crates.io/crates/metal
90//! [`windows`]: https://crates.io/crates/windows
91//!
92//! ## Secondary backends
93//!
94//! The `wgpu-hal` crate has a partial implementation based on the following
95//! platform graphics API:
96//!
97//! - The GL backend is available anywhere OpenGL, OpenGL ES, or WebGL are
98//!   available. See the [`gles`] module documentation for details.
99//!
100//! [`gles`]: gles/index.html
101//!
102//! You can see what capabilities an adapter is missing by checking the
103//! [`DownlevelCapabilities`][tdc] in [`ExposedAdapter::capabilities`], available
104//! from [`Instance::enumerate_adapters`].
105//!
106//! The API is generally designed to fit the primary backends better than the
107//! secondary backends, so the latter may impose more overhead.
108//!
109//! [tdc]: wgt::DownlevelCapabilities
110//!
111//! ## Traits
112//!
113//! The `wgpu-hal` crate defines a handful of traits that together
114//! represent a cross-platform abstraction for modern GPU APIs.
115//!
116//! - The [`Api`] trait represents a `wgpu-hal` backend. It has no methods of its
117//!   own, only a collection of associated types.
118//!
119//! - [`Api::Instance`] implements the [`Instance`] trait. [`Instance::init`]
120//!   creates an instance value, which you can use to enumerate the adapters
121//!   available on the system. For example, [`vulkan::Api::Instance::init`][Ii]
122//!   returns an instance that can enumerate the Vulkan physical devices on your
123//!   system.
124//!
125//! - [`Api::Adapter`] implements the [`Adapter`] trait, representing a
126//!   particular device from a particular backend. For example, a Vulkan instance
127//!   might have a Lavapipe software adapter and a GPU-based adapter.
128//!
129//! - [`Api::Device`] implements the [`Device`] trait, representing an active
130//!   link to a device. You get a device value by calling [`Adapter::open`], and
131//!   then use it to create buffers, textures, shader modules, and so on.
132//!
133//! - [`Api::Queue`] implements the [`Queue`] trait, which you use to submit
134//!   command buffers to a given device.
135//!
136//! - [`Api::CommandEncoder`] implements the [`CommandEncoder`] trait, which you
137//!   use to build buffers of commands to submit to a queue. This has all the
138//!   methods for drawing and running compute shaders, which is presumably what
139//!   you're here for.
140//!
141//! - [`Api::Surface`] implements the [`Surface`] trait, which represents a
142//!   swapchain for presenting images on the screen, via interaction with the
143//!   system's window manager.
144//!
145//! The [`Api`] trait has various other associated types like [`Api::Buffer`] and
146//! [`Api::Texture`] that represent resources the rest of the interface can
147//! operate on, but these generally do not have their own traits.
148//!
149//! [Ii]: Instance::init
150//!
151//! ## Validation is the calling code's responsibility, not `wgpu-hal`'s
152//!
153//! As much as possible, `wgpu-hal` traits place the burden of validation,
154//! resource tracking, and state tracking on the caller, not on the trait
155//! implementations themselves. Anything which can reasonably be handled in
156//! backend-independent code should be. A `wgpu_hal` backend's sole obligation is
157//! to provide portable behavior, and report conditions that the calling code
158//! can't reasonably anticipate, like device loss or running out of memory.
159//!
160//! The `wgpu` crate collection is intended for use in security-sensitive
161//! applications, like web browsers, where the API is available to untrusted
162//! code. This means that `wgpu-core`'s validation is not simply a service to
163//! developers, to be provided opportunistically when the performance costs are
164//! acceptable and the necessary data is ready at hand. Rather, `wgpu-core`'s
165//! validation must be exhaustive, to ensure that even malicious content cannot
166//! provoke and exploit undefined behavior in the platform's graphics API.
167//!
168//! Because graphics APIs' requirements are complex, the only practical way for
169//! `wgpu` to provide exhaustive validation is to comprehensively track the
170//! lifetime and state of all the resources in the system. Implementing this
171//! separately for each backend is infeasible; effort would be better spent
172//! making the cross-platform validation in `wgpu-core` legible and trustworthy.
173//! Fortunately, the requirements are largely similar across the various
174//! platforms, so cross-platform validation is practical.
175//!
176//! Some backends have specific requirements that aren't practical to foist off
177//! on the `wgpu-hal` user. For example, properly managing macOS Objective-C or
178//! Microsoft COM reference counts is best handled by using appropriate pointer
179//! types within the backend.
180//!
181//! A desire for "defense in depth" may suggest performing additional validation
182//! in `wgpu-hal` when the opportunity arises, but this must be done with
183//! caution. Even experienced contributors infer the expectations their changes
184//! must meet by considering not just requirements made explicit in types, tests,
185//! assertions, and comments, but also those implicit in the surrounding code.
186//! When one sees validation or state-tracking code in `wgpu-hal`, it is tempting
187//! to conclude, "Oh, `wgpu-hal` checks for this, so `wgpu-core` needn't worry
188//! about it - that would be redundant!" The responsibility for exhaustive
189//! validation always rests with `wgpu-core`, regardless of what may or may not
190//! be checked in `wgpu-hal`.
191//!
192//! To this end, any "defense in depth" validation that does appear in `wgpu-hal`
193//! for requirements that `wgpu-core` should have enforced should report failure
194//! via the `unreachable!` macro, because problems detected at this stage always
195//! indicate a bug in `wgpu-core`.
196//!
197//! ## Debugging
198//!
199//! Most of the information on the wiki [Debugging wgpu Applications][wiki-debug]
200//! page still applies to this API, with the exception of API tracing/replay
201//! functionality, which is only available in `wgpu-core`.
202//!
203//! [wiki-debug]: https://github.com/gfx-rs/wgpu/wiki/Debugging-wgpu-Applications
204
205#![no_std]
206#![cfg_attr(docsrs, feature(doc_cfg))]
207#![allow(
208    // this happens on the GL backend, where it is both thread safe and non-thread safe in the same code.
209    clippy::arc_with_non_send_sync,
210    // We don't use syntax sugar where it's not necessary.
211    clippy::match_like_matches_macro,
212    // Redundant matching is more explicit.
213    clippy::redundant_pattern_matching,
214    // Explicit lifetimes are often easier to reason about.
215    clippy::needless_lifetimes,
216    // No need for defaults in the internal types.
217    clippy::new_without_default,
218    // Matches are good and extendable, no need to make an exception here.
219    clippy::single_match,
220    // Push commands are more regular than macros.
221    clippy::vec_init_then_push,
222    // TODO!
223    clippy::missing_safety_doc,
224    // It gets in the way a lot and does not prevent bugs in practice.
225    clippy::pattern_type_mismatch,
226    // We should investigate these.
227    clippy::large_enum_variant
228)]
229#![warn(
230    clippy::alloc_instead_of_core,
231    clippy::ptr_as_ptr,
232    clippy::std_instead_of_alloc,
233    clippy::std_instead_of_core,
234    trivial_casts,
235    trivial_numeric_casts,
236    unsafe_op_in_unsafe_fn,
237    unused_extern_crates,
238    unused_qualifications
239)]
240
241extern crate alloc;
242#[allow(unused_extern_crates)]
243extern crate naga_types as nt;
244extern crate wgpu_types as wgt;
245// Each of these backends needs `std` in some fashion; usually `std::thread` functions.
246#[cfg(any(dx12, gles_with_std, metal, vulkan))]
247#[macro_use]
248extern crate std;
249
250/// DirectX12 API internals.
251#[cfg(dx12)]
252pub mod dx12;
253/// GLES API internals.
254#[cfg(gles)]
255pub mod gles;
256/// Metal API internals.
257#[cfg(metal)]
258pub mod metal;
259/// A dummy API implementation.
260// TODO(https://github.com/gfx-rs/wgpu/issues/7120): this should have a cfg
261pub mod noop;
262/// Vulkan API internals.
263#[cfg(vulkan)]
264pub mod vulkan;
265
266pub mod auxil;
267mod glsl_template;
268pub use glsl_template::{GlslBlock, GlslMacro, GlslMacroKind, GlslTemplate, GlslTexture};
269pub mod api {
270    #[cfg(dx12)]
271    pub use super::dx12::Api as Dx12;
272    #[cfg(gles)]
273    pub use super::gles::Api as Gles;
274    #[cfg(metal)]
275    pub use super::metal::Api as Metal;
276    pub use super::noop::Api as Noop;
277    #[cfg(vulkan)]
278    pub use super::vulkan::Api as Vulkan;
279}
280
281mod dynamic;
282#[cfg(feature = "validation_canary")]
283mod validation_canary;
284
285#[cfg(feature = "validation_canary")]
286pub use validation_canary::{ValidationCanary, VALIDATION_CANARY};
287
288pub(crate) use dynamic::impl_dyn_resource;
289pub use dynamic::{
290    DynAccelerationStructure, DynAcquiredSurfaceTexture, DynAdapter, DynBindGroup,
291    DynBindGroupLayout, DynBuffer, DynCommandBuffer, DynCommandEncoder, DynComputePipeline,
292    DynDevice, DynExposedAdapter, DynFence, DynInstance, DynOpenDevice, DynPipelineCache,
293    DynPipelineLayout, DynQuerySet, DynQueue, DynRayTracingPipeline, DynRenderPipeline,
294    DynResource, DynSampler, DynShaderModule, DynSurface, DynSurfaceTexture, DynTexture,
295    DynTextureView,
296};
297
298#[allow(unused)]
299use alloc::boxed::Box;
300use alloc::{borrow::Cow, string::String, vec::Vec};
301use core::{
302    borrow::Borrow,
303    error::Error,
304    fmt,
305    num::{NonZeroU32, NonZeroU64},
306    ops::{Range, RangeInclusive},
307    ptr::NonNull,
308};
309
310use bitflags::bitflags;
311use raw_window_handle::DisplayHandle;
312use thiserror::Error;
313use wgt::WasmNotSendSync;
314
315cfg_if::cfg_if! {
316    if #[cfg(supports_ptr_atomics)] {
317        use alloc::sync::Arc;
318    } else if #[cfg(feature = "portable-atomic")] {
319        use portable_atomic_util::Arc;
320    }
321}
322
323// - Vertex + Fragment
324// - Compute
325// Task + Mesh + Fragment
326pub const MAX_CONCURRENT_SHADER_STAGES: usize = 3;
327pub const MAX_ANISOTROPY: u8 = 16;
328pub const MAX_BIND_GROUPS: usize = 8;
329pub const MAX_VERTEX_BUFFERS: usize = 16;
330pub const MAX_COLOR_ATTACHMENTS: usize = 8;
331pub const MAX_MIP_LEVELS: u32 = 16;
332/// Size of a single occlusion/timestamp query, when copied into a buffer, in bytes.
333/// cbindgen:ignore
334pub const QUERY_SIZE: wgt::BufferAddress = 8;
335
336pub type Label<'a> = Option<&'a str>;
337pub type MemoryRange = Range<wgt::BufferAddress>;
338pub type FenceValue = u64;
339#[cfg(supports_64bit_atomics)]
340pub type AtomicFenceValue = core::sync::atomic::AtomicU64;
341#[cfg(not(supports_64bit_atomics))]
342pub type AtomicFenceValue = portable_atomic::AtomicU64;
343
344/// A callback to signal that wgpu is no longer using a resource.
345#[cfg(any(gles, vulkan, metal))]
346pub type DropCallback = Box<dyn FnOnce() + Send + Sync + 'static>;
347
348#[cfg(any(gles, vulkan, metal))]
349pub struct DropGuard {
350    callback: Option<DropCallback>,
351}
352
353#[cfg(all(any(gles, vulkan, metal), any(native, Emscripten)))]
354impl DropGuard {
355    fn from_option(callback: Option<DropCallback>) -> Option<Self> {
356        callback.map(Self::new)
357    }
358
359    fn new(callback: DropCallback) -> Self {
360        Self {
361            callback: Some(callback),
362        }
363    }
364}
365
366#[cfg(any(gles, vulkan, metal))]
367impl Drop for DropGuard {
368    fn drop(&mut self) {
369        if let Some(cb) = self.callback.take() {
370            (cb)();
371        }
372    }
373}
374
375#[cfg(any(gles, vulkan, metal))]
376impl fmt::Debug for DropGuard {
377    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
378        f.debug_struct("DropGuard").finish()
379    }
380}
381
382#[derive(Clone, Debug, PartialEq, Eq, Error)]
383pub enum DeviceError {
384    #[error("Out of memory")]
385    OutOfMemory,
386    #[error("Device is lost")]
387    Lost,
388    #[error("Unexpected error variant (driver implementation is at fault)")]
389    Unexpected,
390}
391
392#[cfg(any(dx12, vulkan))]
393impl From<gpu_allocator::AllocationError> for DeviceError {
394    fn from(result: gpu_allocator::AllocationError) -> Self {
395        match result {
396            gpu_allocator::AllocationError::OutOfMemory => Self::OutOfMemory,
397            gpu_allocator::AllocationError::FailedToMap(e) => {
398                log::error!("gpu-allocator: Failed to map: {e}");
399                Self::Lost
400            }
401            gpu_allocator::AllocationError::NoCompatibleMemoryTypeFound => {
402                log::error!("gpu-allocator: No Compatible Memory Type Found");
403                Self::Lost
404            }
405            gpu_allocator::AllocationError::InvalidAllocationCreateDesc => {
406                log::error!("gpu-allocator: Invalid Allocation Creation Description");
407                Self::Lost
408            }
409            gpu_allocator::AllocationError::InvalidAllocatorCreateDesc(e) => {
410                log::error!("gpu-allocator: Invalid Allocator Creation Description: {e}");
411                Self::Lost
412            }
413
414            gpu_allocator::AllocationError::Internal(e) => {
415                log::error!("gpu-allocator: Internal Error: {e}");
416                Self::Lost
417            }
418            gpu_allocator::AllocationError::BarrierLayoutNeedsDevice10
419            | gpu_allocator::AllocationError::CastableFormatsRequiresEnhancedBarriers
420            | gpu_allocator::AllocationError::CastableFormatsRequiresAtLeastDevice12 => {
421                unreachable!()
422            }
423        }
424    }
425}
426
427// A copy of gpu_allocator::AllocationSizes, allowing to read the configured value for
428// the dx12 backend, we should instead add getters to gpu_allocator::AllocationSizes
429// and remove this type.
430// https://github.com/Traverse-Research/gpu-allocator/issues/295
431#[cfg_attr(not(any(dx12, vulkan)), expect(dead_code))]
432pub(crate) struct AllocationSizes {
433    pub(crate) min_device_memblock_size: u64,
434    pub(crate) max_device_memblock_size: u64,
435    pub(crate) min_host_memblock_size: u64,
436    pub(crate) max_host_memblock_size: u64,
437}
438
439impl AllocationSizes {
440    #[allow(dead_code, reason = "may be unused on some platforms")]
441    pub(crate) fn from_memory_hints(memory_hints: &wgt::MemoryHints) -> Self {
442        // TODO: the allocator's configuration should take hardware capability into
443        // account.
444        const MB: u64 = 1024 * 1024;
445
446        match memory_hints {
447            wgt::MemoryHints::Performance => Self {
448                min_device_memblock_size: 128 * MB,
449                max_device_memblock_size: 256 * MB,
450                min_host_memblock_size: 64 * MB,
451                max_host_memblock_size: 128 * MB,
452            },
453            wgt::MemoryHints::MemoryUsage => Self {
454                min_device_memblock_size: 8 * MB,
455                max_device_memblock_size: 64 * MB,
456                min_host_memblock_size: 4 * MB,
457                max_host_memblock_size: 32 * MB,
458            },
459            wgt::MemoryHints::Manual {
460                suballocated_device_memory_block_size,
461            } => {
462                // TODO: https://github.com/gfx-rs/wgpu/issues/8625
463                // Would it be useful to expose the host size in memory hints
464                // instead of always using half of the device size?
465                let device_size = suballocated_device_memory_block_size;
466                let host_size = device_size.start / 2..device_size.end / 2;
467
468                // gpu_allocator clamps the sizes between 4MiB and 256MiB, but we clamp them ourselves since we use
469                // the sizes when detecting high memory pressure and there is no way to query the values otherwise.
470                Self {
471                    min_device_memblock_size: device_size.start.clamp(4 * MB, 256 * MB),
472                    max_device_memblock_size: device_size.end.clamp(4 * MB, 256 * MB),
473                    min_host_memblock_size: host_size.start.clamp(4 * MB, 256 * MB),
474                    max_host_memblock_size: host_size.end.clamp(4 * MB, 256 * MB),
475                }
476            }
477        }
478    }
479}
480
481#[cfg(any(dx12, vulkan))]
482impl From<AllocationSizes> for gpu_allocator::AllocationSizes {
483    fn from(value: AllocationSizes) -> gpu_allocator::AllocationSizes {
484        gpu_allocator::AllocationSizes::new(
485            value.min_device_memblock_size,
486            value.min_host_memblock_size,
487        )
488        .with_max_device_memblock_size(value.max_device_memblock_size)
489        .with_max_host_memblock_size(value.max_host_memblock_size)
490    }
491}
492
493#[allow(dead_code, reason = "may be unused on some platforms")]
494#[cold]
495fn hal_usage_error<T: fmt::Display>(txt: T) -> ! {
496    panic!("wgpu-hal invariant was violated (usage error): {txt}")
497}
498
499#[allow(dead_code, reason = "may be unused on some platforms")]
500#[cold]
501fn hal_internal_error<T: fmt::Display>(txt: T) -> ! {
502    panic!("wgpu-hal ran into a preventable internal error: {txt}")
503}
504
505#[derive(Clone, Debug, Eq, PartialEq, Error)]
506pub enum ShaderError {
507    #[error("Compilation failed: {0:?}")]
508    Compilation(String),
509    #[error(transparent)]
510    Device(#[from] DeviceError),
511}
512
513#[derive(Clone, Debug, Eq, PartialEq, Error)]
514pub enum PipelineError {
515    #[error("Linkage failed for stage {0:?}: {1}")]
516    Linkage(wgt::ShaderStages, String),
517    #[error("Entry point for stage {0:?} is invalid")]
518    EntryPoint(naga::ShaderStage),
519    #[error(transparent)]
520    Device(#[from] DeviceError),
521    #[error("Pipeline constant error for stage {0:?}: {1}")]
522    PipelineConstants(wgt::ShaderStages, String),
523}
524
525#[derive(Clone, Debug, Eq, PartialEq, Error)]
526pub enum PipelineCacheError {
527    #[error(transparent)]
528    Device(#[from] DeviceError),
529}
530
531#[derive(Clone, Debug, Eq, PartialEq, Error)]
532pub enum SurfaceError {
533    #[error("Surface is lost")]
534    Lost,
535    #[error("Surface is outdated, needs to be re-created")]
536    Outdated,
537    #[error("Timed out waiting for a surface texture")]
538    Timeout,
539    #[error("The window is occluded (e.g. minimized or behind another window). Try again once the window is no longer occluded.")]
540    Occluded,
541    #[error(transparent)]
542    Device(#[from] DeviceError),
543    #[error("Other reason: {0}")]
544    Other(&'static str),
545}
546
547/// Error occurring while trying to create an instance, or create a surface from an instance;
548/// typically relating to the state of the underlying graphics API or hardware.
549#[derive(Clone, Debug, Error)]
550#[error("{message}")]
551pub struct InstanceError {
552    /// These errors are very platform specific, so do not attempt to encode them as an enum.
553    ///
554    /// This message should describe the problem in sufficient detail to be useful for a
555    /// user-to-developer “why won't this work on my machine” bug report, and otherwise follow
556    /// <https://rust-lang.github.io/api-guidelines/interoperability.html#error-types-are-meaningful-and-well-behaved-c-good-err>.
557    message: String,
558
559    /// Underlying error value, if any is available.
560    #[source]
561    source: Option<Arc<dyn Error + Send + Sync + 'static>>,
562}
563
564impl InstanceError {
565    #[allow(dead_code, reason = "may be unused on some platforms")]
566    pub(crate) fn new(message: String) -> Self {
567        Self {
568            message,
569            source: None,
570        }
571    }
572    #[allow(dead_code, reason = "may be unused on some platforms")]
573    pub(crate) fn with_source(message: String, source: impl Error + Send + Sync + 'static) -> Self {
574        cfg_if::cfg_if! {
575            if #[cfg(supports_ptr_atomics)] {
576                let source = Arc::new(source);
577            } else {
578                // TODO(https://github.com/rust-lang/rust/issues/18598): avoid indirection via Box once arbitrary types support unsized coercion
579                let source: Box<dyn Error + Send + Sync + 'static> = Box::new(source);
580                let source = Arc::from(source);
581            }
582        }
583        Self {
584            message,
585            source: Some(source),
586        }
587    }
588}
589
590/// All the types and methods that make up a implementation on top of a backend.
591///
592/// Only the types that have non-dyn trait bounds have methods on them. Most methods
593/// are either on [`CommandEncoder`] or [`Device`].
594///
595/// The api can either be used through generics (through use of this trait and associated
596/// types) or dynamically through using the `Dyn*` traits.
597pub trait Api: Clone + fmt::Debug + Sized + WasmNotSendSync + 'static {
598    const VARIANT: wgt::Backend;
599
600    type Instance: DynInstance + Instance<A = Self>;
601    type Surface: DynSurface + Surface<A = Self>;
602    type Adapter: DynAdapter + Adapter<A = Self>;
603    type Device: DynDevice + Device<A = Self>;
604
605    type Queue: DynQueue + Queue<A = Self>;
606    type CommandEncoder: DynCommandEncoder + CommandEncoder<A = Self>;
607
608    /// This API's command buffer type.
609    ///
610    /// The only thing you can do with `CommandBuffer`s is build them
611    /// with a [`CommandEncoder`] and then pass them to
612    /// [`Queue::submit`] for execution, or destroy them by passing
613    /// them to [`CommandEncoder::reset_all`].
614    ///
615    /// [`CommandEncoder`]: Api::CommandEncoder
616    type CommandBuffer: DynCommandBuffer;
617
618    type Buffer: DynBuffer;
619    type Texture: DynTexture;
620    type SurfaceTexture: DynSurfaceTexture + Borrow<Self::Texture>;
621    type TextureView: DynTextureView;
622    type Sampler: DynSampler;
623    type QuerySet: DynQuerySet;
624
625    /// A value you can block on to wait for something to finish.
626    ///
627    /// A `Fence` holds a monotonically increasing [`FenceValue`]. You can call
628    /// [`Device::wait`] to block until a fence reaches or passes a value you
629    /// choose. [`Queue::submit`] can take a `Fence` and a [`FenceValue`] to
630    /// store in it when the submitted work is complete.
631    ///
632    /// Attempting to set a fence to a value less than its current value has no
633    /// effect.
634    ///
635    /// Waiting on a fence returns as soon as the fence reaches *or passes* the
636    /// requested value. This implies that, in order to reliably determine when
637    /// an operation has completed, operations must finish in order of
638    /// increasing fence values: if a higher-valued operation were to finish
639    /// before a lower-valued operation, then waiting for the fence to reach the
640    /// lower value could return before the lower-valued operation has actually
641    /// finished.
642    ///
643    /// Fences are internally synchronised by the hal, and so should not need to be
644    /// contained in external synchronisation primitives.
645    type Fence: DynFence;
646
647    type BindGroupLayout: DynBindGroupLayout;
648    type BindGroup: DynBindGroup;
649    type PipelineLayout: DynPipelineLayout;
650    type ShaderModule: DynShaderModule;
651    type RenderPipeline: DynRenderPipeline;
652    type ComputePipeline: DynComputePipeline;
653    type RayTracingPipeline: DynRayTracingPipeline;
654    type PipelineCache: DynPipelineCache;
655
656    type AccelerationStructure: DynAccelerationStructure + 'static;
657}
658
659pub trait Instance: Sized + WasmNotSendSync {
660    type A: Api;
661
662    unsafe fn init(desc: &InstanceDescriptor<'_>) -> Result<Self, InstanceError>;
663    unsafe fn create_surface(
664        &self,
665        display_handle: raw_window_handle::RawDisplayHandle,
666        window_handle: raw_window_handle::RawWindowHandle,
667    ) -> Result<<Self::A as Api>::Surface, InstanceError>;
668    /// `surface_hint` is only used by the GLES backend targeting WebGL2
669    unsafe fn enumerate_adapters(
670        &self,
671        surface_hint: Option<&<Self::A as Api>::Surface>,
672    ) -> Vec<ExposedAdapter<Self::A>>;
673}
674
675pub trait Surface: WasmNotSendSync {
676    type A: Api;
677
678    /// Configure `self` to use `device`.
679    ///
680    /// # Safety
681    ///
682    /// - All GPU work using `self` must have been completed.
683    /// - All [`AcquiredSurfaceTexture`]s must have been destroyed.
684    /// - All [`Api::TextureView`]s derived from the [`AcquiredSurfaceTexture`]s must have been destroyed.
685    /// - The surface `self` must not currently be configured to use any other [`Device`].
686    unsafe fn configure(
687        &self,
688        device: &<Self::A as Api>::Device,
689        config: &SurfaceConfiguration,
690    ) -> Result<(), SurfaceError>;
691
692    /// Unconfigure `self` on `device`.
693    ///
694    /// # Safety
695    ///
696    /// - All GPU work that uses `surface` must have been completed.
697    /// - All [`AcquiredSurfaceTexture`]s must have been destroyed.
698    /// - All [`Api::TextureView`]s derived from the [`AcquiredSurfaceTexture`]s must have been destroyed.
699    /// - The surface `self` must have been configured on `device`.
700    unsafe fn unconfigure(&self, device: &<Self::A as Api>::Device);
701
702    /// Return the next texture to be presented by `self`, for the caller to draw on.
703    ///
704    /// On success, return an [`AcquiredSurfaceTexture`] representing the
705    /// texture into which the caller should draw the image to be displayed on
706    /// `self`.
707    ///
708    /// If `timeout` elapses before `self` has a texture ready to be acquired,
709    /// return `Err(SurfaceError::Timeout)`. If `timeout` is `None`, wait
710    /// indefinitely, with no timeout.
711    ///
712    /// # Using an [`AcquiredSurfaceTexture`]
713    ///
714    /// On success, this function returns an [`AcquiredSurfaceTexture`] whose
715    /// [`texture`] field is a [`SurfaceTexture`] from which the caller can
716    /// [`borrow`] a [`Texture`] to draw on. The [`AcquiredSurfaceTexture`] also
717    /// carries some metadata about that [`SurfaceTexture`].
718    ///
719    /// All calls to [`Queue::submit`] that draw on that [`Texture`] must also
720    /// include the [`SurfaceTexture`] in the `surface_textures` argument.
721    ///
722    /// When you are done drawing on the texture, you can display it on `self`
723    /// by passing the [`SurfaceTexture`] and `self` to [`Queue::present`].
724    ///
725    /// If you do not wish to display the texture, you must pass the
726    /// [`SurfaceTexture`] to [`self.discard_texture`], so that it can be reused
727    /// by future acquisitions.
728    ///
729    /// The fence is internally synchronised by the hal.
730    ///
731    /// # Portability
732    ///
733    /// Some backends can't support a timeout when acquiring a texture. On these
734    /// backends, `timeout` is ignored.
735    ///
736    /// On macOS, this returns `Err(SurfaceError::Timeout)` when the window is
737    /// not visible (minimized, fully occluded, or on another virtual desktop)
738    /// to avoid blocking in `CAMetalLayer.nextDrawable()`.
739    ///
740    /// # Safety
741    ///
742    /// - The surface `self` must currently be configured on some [`Device`].
743    ///
744    /// - The `fence` argument must be the same [`Fence`] passed to all calls to
745    ///   [`Queue::submit`] that used [`Texture`]s acquired from this surface.
746    ///
747    /// - You may only have one texture acquired from `self` at a time. When
748    ///   `acquire_texture` returns `Ok(ast)`, you must pass the returned
749    ///   [`SurfaceTexture`] `ast.texture` to either [`Queue::present`] or
750    ///   [`Surface::discard_texture`] before calling `acquire_texture` again.
751    ///
752    /// [`texture`]: AcquiredSurfaceTexture::texture
753    /// [`SurfaceTexture`]: Api::SurfaceTexture
754    /// [`borrow`]: alloc::borrow::Borrow::borrow
755    /// [`Texture`]: Api::Texture
756    /// [`Fence`]: Api::Fence
757    /// [`self.discard_texture`]: Surface::discard_texture
758    unsafe fn acquire_texture(
759        &self,
760        timeout: Option<core::time::Duration>,
761        fence: &<Self::A as Api>::Fence,
762    ) -> Result<AcquiredSurfaceTexture<Self::A>, SurfaceError>;
763
764    /// Relinquish an acquired texture without presenting it.
765    ///
766    /// After this call, the texture underlying [`SurfaceTexture`] may be
767    /// returned by subsequent calls to [`self.acquire_texture`].
768    ///
769    /// # Safety
770    ///
771    /// - The surface `self` must currently be configured on some [`Device`].
772    ///
773    /// - `texture` must be a [`SurfaceTexture`] returned by a call to
774    ///   [`self.acquire_texture`] that has not yet been passed to
775    ///   [`Queue::present`].
776    ///
777    /// [`SurfaceTexture`]: Api::SurfaceTexture
778    /// [`self.acquire_texture`]: Surface::acquire_texture
779    unsafe fn discard_texture(&self, texture: <Self::A as Api>::SurfaceTexture);
780}
781
782pub trait Adapter: WasmNotSendSync {
783    type A: Api;
784
785    unsafe fn open(
786        &self,
787        features: wgt::Features,
788        limits: &wgt::Limits,
789        memory_hints: &wgt::MemoryHints,
790    ) -> Result<OpenDevice<Self::A>, DeviceError>;
791
792    /// Return the set of supported capabilities for a texture format.
793    unsafe fn texture_format_capabilities(
794        &self,
795        format: wgt::TextureFormat,
796    ) -> TextureFormatCapabilities;
797
798    /// Returns the capabilities of working with a specified surface.
799    ///
800    /// `None` means presentation is not supported for it.
801    unsafe fn surface_capabilities(
802        &self,
803        surface: &<Self::A as Api>::Surface,
804    ) -> Option<SurfaceCapabilities>;
805
806    /// Returns the HDR / luminance characteristics of the display backing
807    /// `surface`, queried from the OS on each call.
808    ///
809    /// `None` means no information is available; wgpu-core maps it to
810    /// [`wgt::DisplayHdrInfo::default`]. Implementors must not panic; degrade any
811    /// OS-query failure to `None`. The default implementation returns `None`.
812    ///
813    /// Implemented by Metal (macOS only, and only from the main thread), DX12, and
814    /// Vulkan (Win32 `HWND` surfaces only); GLES and noop keep the default `None`.
815    unsafe fn surface_display_hdr_info(
816        &self,
817        surface: &<Self::A as Api>::Surface,
818    ) -> Option<wgt::DisplayHdrInfo> {
819        let _ = surface;
820        None
821    }
822
823    /// Creates a [`PresentationTimestamp`] using the adapter's WSI.
824    ///
825    /// [`PresentationTimestamp`]: wgt::PresentationTimestamp
826    unsafe fn get_presentation_timestamp(&self) -> wgt::PresentationTimestamp;
827
828    /// The combination of all usages that the are guaranteed to be be ordered by the hardware.
829    /// If a usage is ordered, then if the buffer state doesn't change between draw calls,
830    /// there are no barriers needed for synchronization.
831    fn get_ordered_buffer_usages(&self) -> wgt::BufferUses;
832
833    /// The combination of all usages that the are guaranteed to be be ordered by the hardware.
834    /// If a usage is ordered, then if the buffer state doesn't change between draw calls,
835    /// there are no barriers needed for synchronization.
836    fn get_ordered_texture_usages(&self) -> wgt::TextureUses;
837}
838
839/// A connection to a GPU and a pool of resources to use with it.
840///
841/// A `wgpu-hal` `Device` represents an open connection to a specific graphics
842/// processor, controlled via the backend [`Device::A`]. A `Device` is mostly
843/// used for creating resources. Each `Device` has an associated [`Queue`] used
844/// for command submission.
845///
846/// On Vulkan a `Device` corresponds to a logical device ([`VkDevice`]). Other
847/// backends don't have an exact analog: for example, [`ID3D12Device`]s and
848/// [`MTLDevice`]s are owned by the backends' [`wgpu_hal::Adapter`]
849/// implementations, and shared by all [`wgpu_hal::Device`]s created from that
850/// `Adapter`.
851///
852/// A `Device`'s life cycle is generally:
853///
854/// 1)  Obtain a `Device` and its associated [`Queue`] by calling
855///     [`Adapter::open`].
856///
857///     Alternatively, the backend-specific types that implement [`Adapter`] often
858///     have methods for creating a `wgpu-hal` `Device` from a platform-specific
859///     handle. For example, [`vulkan::Adapter::device_from_raw`] can create a
860///     [`vulkan::Device`] from an [`ash::Device`].
861///
862/// 1)  Create resources to use on the device by calling methods like
863///     [`Device::create_texture`] or [`Device::create_shader_module`].
864///
865/// 1)  Call [`Device::create_command_encoder`] to obtain a [`CommandEncoder`],
866///     which you can use to build [`CommandBuffer`]s holding commands to be
867///     executed on the GPU.
868///
869/// 1)  Call [`Queue::submit`] on the `Device`'s associated [`Queue`] to submit
870///     [`CommandBuffer`]s for execution on the GPU. If needed, call
871///     [`Device::wait`] to wait for them to finish execution.
872///
873/// 1)  Free resources with methods like [`Device::destroy_texture`] or
874///     [`Device::destroy_shader_module`].
875///
876/// 1)  Drop the device.
877///
878/// [`vkDevice`]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#VkDevice
879/// [`ID3D12Device`]: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nn-d3d12-id3d12device
880/// [`MTLDevice`]: https://developer.apple.com/documentation/metal/mtldevice
881/// [`wgpu_hal::Adapter`]: Adapter
882/// [`wgpu_hal::Device`]: Device
883/// [`vulkan::Adapter::device_from_raw`]: vulkan/struct.Adapter.html#method.device_from_raw
884/// [`vulkan::Device`]: vulkan/struct.Device.html
885/// [`ash::Device`]: https://docs.rs/ash/latest/ash/struct.Device.html
886/// [`CommandBuffer`]: Api::CommandBuffer
887///
888/// # Safety
889///
890/// As with other `wgpu-hal` APIs, [validation] is the caller's
891/// responsibility. Here are the general requirements for all `Device`
892/// methods:
893///
894/// - Any resource passed to a `Device` method must have been created by that
895///   `Device`. For example, a [`Texture`] passed to [`Device::destroy_texture`] must
896///   have been created with the `Device` passed as `self`.
897///
898/// - Resources may not be destroyed if they are used by any submitted command
899///   buffers that have not yet finished execution.
900///
901/// [validation]: index.html#validation-is-the-calling-codes-responsibility-not-wgpu-hals
902/// [`Texture`]: Api::Texture
903pub trait Device: WasmNotSendSync {
904    type A: Api;
905
906    /// Creates a new buffer.
907    ///
908    /// The initial usage is `wgt::BufferUses::empty()`.
909    unsafe fn create_buffer(
910        &self,
911        desc: &BufferDescriptor,
912    ) -> Result<<Self::A as Api>::Buffer, DeviceError>;
913
914    /// Free `buffer` and any GPU resources it owns.
915    ///
916    /// Note that backends are allowed to allocate GPU memory for buffers from
917    /// allocation pools, and this call is permitted to simply return `buffer`'s
918    /// storage to that pool, without making it available to other applications.
919    ///
920    /// # Safety
921    ///
922    /// - The given `buffer` must not currently be mapped.
923    unsafe fn destroy_buffer(&self, buffer: <Self::A as Api>::Buffer);
924
925    /// A hook for when a wgpu-core buffer is created from a raw wgpu-hal buffer.
926    unsafe fn add_raw_buffer(&self, buffer: &<Self::A as Api>::Buffer);
927
928    /// Return a pointer to CPU memory mapping the contents of `buffer`.
929    ///
930    /// Buffer mappings are persistent: the buffer may remain mapped on the CPU
931    /// while the GPU reads or writes to it. (Note that `wgpu_core` does not use
932    /// this feature: when a `wgpu_core::Buffer` is unmapped, the underlying
933    /// `wgpu_hal` buffer is also unmapped.)
934    ///
935    /// If this function returns `Ok(mapping)`, then:
936    ///
937    /// - `mapping.ptr` is the CPU address of the start of the mapped memory.
938    ///
939    /// - If `mapping.is_coherent` is `true`, then CPU writes to the mapped
940    ///   memory are immediately visible on the GPU, and vice versa.
941    ///
942    /// # Safety
943    ///
944    /// - The given `buffer` must have been created with the [`MAP_READ`] or
945    ///   [`MAP_WRITE`] flags set in [`BufferDescriptor::usage`].
946    ///
947    /// - The given `range` must fall within the size of `buffer`.
948    ///
949    /// - The caller must avoid data races between the CPU and the GPU. A data
950    ///   race is any pair of accesses to a particular byte, one of which is a
951    ///   write, that are not ordered with respect to each other by some sort of
952    ///   synchronization operation.
953    ///
954    /// - If this function returns `Ok(mapping)` and `mapping.is_coherent` is
955    ///   `false`, then:
956    ///
957    ///   - Every CPU write to a mapped byte followed by a GPU read of that byte
958    ///     must have at least one call to [`Device::flush_mapped_ranges`]
959    ///     covering that byte that occurs between those two accesses.
960    ///
961    ///   - Every GPU write to a mapped byte followed by a CPU read of that byte
962    ///     must have at least one call to [`Device::invalidate_mapped_ranges`]
963    ///     covering that byte that occurs between those two accesses.
964    ///
965    ///   Note that the data race rule above requires that all such access pairs
966    ///   be ordered, so it is meaningful to talk about what must occur
967    ///   "between" them.
968    ///
969    /// - Zero-sized mappings are not allowed.
970    ///
971    /// - The returned [`BufferMapping::ptr`] must not be used after a call to
972    ///   [`Device::unmap_buffer`].
973    ///
974    /// [`MAP_READ`]: wgt::BufferUses::MAP_READ
975    /// [`MAP_WRITE`]: wgt::BufferUses::MAP_WRITE
976    unsafe fn map_buffer(
977        &self,
978        buffer: &<Self::A as Api>::Buffer,
979        range: MemoryRange,
980    ) -> Result<BufferMapping, DeviceError>;
981
982    /// Remove the mapping established by the last call to [`Device::map_buffer`].
983    ///
984    /// # Safety
985    ///
986    /// - The given `buffer` must be currently mapped.
987    unsafe fn unmap_buffer(&self, buffer: &<Self::A as Api>::Buffer);
988
989    /// Indicate that CPU writes to mapped buffer memory should be made visible to the GPU.
990    ///
991    /// # Safety
992    ///
993    /// - The given `buffer` must be currently mapped.
994    ///
995    /// - All ranges produced by `ranges` must fall within `buffer`'s size.
996    unsafe fn flush_mapped_ranges<I>(&self, buffer: &<Self::A as Api>::Buffer, ranges: I)
997    where
998        I: Iterator<Item = MemoryRange>;
999
1000    /// Indicate that GPU writes to mapped buffer memory should be made visible to the CPU.
1001    ///
1002    /// # Safety
1003    ///
1004    /// - The given `buffer` must be currently mapped.
1005    ///
1006    /// - All ranges produced by `ranges` must fall within `buffer`'s size.
1007    unsafe fn invalidate_mapped_ranges<I>(&self, buffer: &<Self::A as Api>::Buffer, ranges: I)
1008    where
1009        I: Iterator<Item = MemoryRange>;
1010
1011    /// Creates a new texture.
1012    ///
1013    /// The initial usage for all subresources is `wgt::TextureUses::UNINITIALIZED`.
1014    unsafe fn create_texture(
1015        &self,
1016        desc: &TextureDescriptor,
1017    ) -> Result<<Self::A as Api>::Texture, DeviceError>;
1018    unsafe fn destroy_texture(&self, texture: <Self::A as Api>::Texture);
1019
1020    /// A hook for when a wgpu-core texture is created from a raw wgpu-hal texture.
1021    unsafe fn add_raw_texture(&self, texture: &<Self::A as Api>::Texture);
1022
1023    unsafe fn create_texture_view(
1024        &self,
1025        texture: &<Self::A as Api>::Texture,
1026        desc: &TextureViewDescriptor,
1027    ) -> Result<<Self::A as Api>::TextureView, DeviceError>;
1028    unsafe fn destroy_texture_view(&self, view: <Self::A as Api>::TextureView);
1029    unsafe fn create_sampler(
1030        &self,
1031        desc: &SamplerDescriptor,
1032    ) -> Result<<Self::A as Api>::Sampler, DeviceError>;
1033    unsafe fn destroy_sampler(&self, sampler: <Self::A as Api>::Sampler);
1034
1035    /// Create a fresh [`CommandEncoder`].
1036    ///
1037    /// The new `CommandEncoder` is in the "closed" state.
1038    unsafe fn create_command_encoder(
1039        &self,
1040        desc: &CommandEncoderDescriptor<<Self::A as Api>::Queue>,
1041    ) -> Result<<Self::A as Api>::CommandEncoder, DeviceError>;
1042
1043    /// Creates a bind group layout.
1044    unsafe fn create_bind_group_layout(
1045        &self,
1046        desc: &BindGroupLayoutDescriptor,
1047    ) -> Result<<Self::A as Api>::BindGroupLayout, DeviceError>;
1048    unsafe fn destroy_bind_group_layout(&self, bg_layout: <Self::A as Api>::BindGroupLayout);
1049    unsafe fn create_pipeline_layout(
1050        &self,
1051        desc: &PipelineLayoutDescriptor<<Self::A as Api>::BindGroupLayout>,
1052    ) -> Result<<Self::A as Api>::PipelineLayout, DeviceError>;
1053    unsafe fn destroy_pipeline_layout(&self, pipeline_layout: <Self::A as Api>::PipelineLayout);
1054
1055    #[allow(clippy::type_complexity)]
1056    unsafe fn create_bind_group(
1057        &self,
1058        desc: &BindGroupDescriptor<
1059            <Self::A as Api>::BindGroupLayout,
1060            <Self::A as Api>::Buffer,
1061            <Self::A as Api>::Sampler,
1062            <Self::A as Api>::TextureView,
1063            <Self::A as Api>::AccelerationStructure,
1064        >,
1065    ) -> Result<<Self::A as Api>::BindGroup, DeviceError>;
1066    unsafe fn destroy_bind_group(&self, group: <Self::A as Api>::BindGroup);
1067
1068    unsafe fn create_shader_module(
1069        &self,
1070        desc: &ShaderModuleDescriptor,
1071        shader: ShaderInput,
1072    ) -> Result<<Self::A as Api>::ShaderModule, ShaderError>;
1073    unsafe fn destroy_shader_module(&self, module: <Self::A as Api>::ShaderModule);
1074
1075    #[allow(clippy::type_complexity)]
1076    unsafe fn create_render_pipeline(
1077        &self,
1078        desc: &RenderPipelineDescriptor<
1079            <Self::A as Api>::PipelineLayout,
1080            <Self::A as Api>::ShaderModule,
1081            <Self::A as Api>::PipelineCache,
1082        >,
1083    ) -> Result<<Self::A as Api>::RenderPipeline, PipelineError>;
1084    unsafe fn destroy_render_pipeline(&self, pipeline: <Self::A as Api>::RenderPipeline);
1085
1086    #[allow(clippy::type_complexity)]
1087    unsafe fn create_compute_pipeline(
1088        &self,
1089        desc: &ComputePipelineDescriptor<
1090            <Self::A as Api>::PipelineLayout,
1091            <Self::A as Api>::ShaderModule,
1092            <Self::A as Api>::PipelineCache,
1093        >,
1094    ) -> Result<<Self::A as Api>::ComputePipeline, PipelineError>;
1095    unsafe fn destroy_compute_pipeline(&self, pipeline: <Self::A as Api>::ComputePipeline);
1096
1097    #[allow(clippy::type_complexity)]
1098    unsafe fn create_ray_tracing_pipeline(
1099        &self,
1100        desc: &RayTracingPipelineDescriptor<
1101            <Self::A as Api>::PipelineLayout,
1102            <Self::A as Api>::ShaderModule,
1103            <Self::A as Api>::PipelineCache,
1104        >,
1105    ) -> Result<<Self::A as Api>::RayTracingPipeline, PipelineError>;
1106    unsafe fn destroy_ray_tracing_pipeline(&self, pipeline: <Self::A as Api>::RayTracingPipeline);
1107    /// Obtain the opaque data from each group, behaves as if group 0 is the ray generation, group 1
1108    /// is the miss shader, and group 2.. are the intersection groups.
1109    unsafe fn get_raytracing_pipeline_group_data(
1110        &self,
1111        pipeline: &<Self::A as Api>::RayTracingPipeline,
1112        groups: Range<u32>,
1113    ) -> Result<Vec<u8>, DeviceError>;
1114
1115    unsafe fn create_pipeline_cache(
1116        &self,
1117        desc: &PipelineCacheDescriptor<'_>,
1118    ) -> Result<<Self::A as Api>::PipelineCache, PipelineCacheError>;
1119    fn pipeline_cache_validation_key(&self) -> Option<[u8; 16]> {
1120        None
1121    }
1122    unsafe fn destroy_pipeline_cache(&self, cache: <Self::A as Api>::PipelineCache);
1123
1124    unsafe fn create_query_set(
1125        &self,
1126        desc: &wgt::QuerySetDescriptor<Label>,
1127    ) -> Result<<Self::A as Api>::QuerySet, DeviceError>;
1128    unsafe fn destroy_query_set(&self, set: <Self::A as Api>::QuerySet);
1129    unsafe fn create_fence(&self) -> Result<<Self::A as Api>::Fence, DeviceError>;
1130    unsafe fn destroy_fence(&self, fence: <Self::A as Api>::Fence);
1131    unsafe fn get_fence_value(
1132        &self,
1133        fence: &<Self::A as Api>::Fence,
1134    ) -> Result<FenceValue, DeviceError>;
1135
1136    /// Wait for `fence` to reach `value`.
1137    ///
1138    /// Operations like [`Queue::submit`] can accept a [`Fence`] and a
1139    /// [`FenceValue`] to store in it, so you can use this `wait` function
1140    /// to wait for a given queue submission to finish execution.
1141    ///
1142    /// The `value` argument must not exceed the highest value that an actual
1143    /// operation you have already presented to the device is going to store in
1144    /// `fence`. You cannot wait for values yet to be submitted. (This
1145    /// restriction accommodates implementations like the `vulkan` backend's
1146    /// [`FencePool`] that must allocate a distinct synchronization object for
1147    /// each fence value one is able to wait for.)
1148    ///
1149    /// Calling `wait` with a lower [`FenceValue`] than `fence`'s current value
1150    /// returns immediately.
1151    ///
1152    /// If `timeout` is not provided, the function will block indefinitely or until
1153    /// an error is encountered.
1154    ///
1155    /// Returns `Ok(true)` on success and `Ok(false)` on timeout.
1156    ///
1157    /// [`Fence`]: Api::Fence
1158    /// [`FencePool`]: vulkan/enum.Fence.html#variant.FencePool
1159    unsafe fn wait(
1160        &self,
1161        fence: &<Self::A as Api>::Fence,
1162        value: FenceValue,
1163        timeout: Option<core::time::Duration>,
1164    ) -> Result<bool, DeviceError>;
1165
1166    /// Start a graphics debugger capture.
1167    ///
1168    /// # Safety
1169    ///
1170    /// See [`wgpu::Device::start_graphics_debugger_capture`][api] for more details.
1171    ///
1172    /// [api]: ../wgpu/struct.Device.html#method.start_graphics_debugger_capture
1173    unsafe fn start_graphics_debugger_capture(&self) -> bool;
1174
1175    /// Stop a graphics debugger capture.
1176    ///
1177    /// # Safety
1178    ///
1179    /// See [`wgpu::Device::stop_graphics_debugger_capture`][api] for more details.
1180    ///
1181    /// [api]: ../wgpu/struct.Device.html#method.stop_graphics_debugger_capture
1182    unsafe fn stop_graphics_debugger_capture(&self);
1183
1184    #[allow(unused_variables)]
1185    unsafe fn pipeline_cache_get_data(
1186        &self,
1187        cache: &<Self::A as Api>::PipelineCache,
1188    ) -> Option<Vec<u8>> {
1189        None
1190    }
1191
1192    unsafe fn create_acceleration_structure(
1193        &self,
1194        desc: &AccelerationStructureDescriptor,
1195    ) -> Result<<Self::A as Api>::AccelerationStructure, DeviceError>;
1196    unsafe fn get_acceleration_structure_build_sizes(
1197        &self,
1198        desc: &GetAccelerationStructureBuildSizesDescriptor<<Self::A as Api>::Buffer>,
1199    ) -> AccelerationStructureBuildSizes;
1200    unsafe fn get_acceleration_structure_device_address(
1201        &self,
1202        acceleration_structure: &<Self::A as Api>::AccelerationStructure,
1203    ) -> wgt::BufferAddress;
1204    unsafe fn destroy_acceleration_structure(
1205        &self,
1206        acceleration_structure: <Self::A as Api>::AccelerationStructure,
1207    );
1208    fn tlas_instance_to_bytes(&self, instance: TlasInstance) -> Vec<u8>;
1209
1210    fn get_internal_counters(&self) -> wgt::HalCounters;
1211
1212    fn generate_allocator_report(&self) -> Option<wgt::AllocatorReport> {
1213        None
1214    }
1215
1216    fn check_if_oom(&self) -> Result<(), DeviceError>;
1217}
1218
1219pub trait Queue: WasmNotSendSync {
1220    type A: Api;
1221
1222    /// Submit `command_buffers` for execution on GPU.
1223    ///
1224    /// Update `fence` to `value` when the operation is complete. See
1225    /// [`Fence`] for details.
1226    ///
1227    /// All command buffers submitted to a `wgpu_hal` queue are executed in the
1228    /// order they're submitted, with each buffer able to observe the effects of
1229    /// previous buffers' execution. Specifically:
1230    ///
1231    /// - If two calls to `submit` on a single `Queue` occur in a particular
1232    ///   order (that is, they happen on the same thread, or on two threads that
1233    ///   have synchronized to establish an ordering), then the first
1234    ///   submission's commands all complete execution before any of the second
1235    ///   submission's commands begin. All results produced by one submission
1236    ///   are visible to the next.
1237    ///
1238    /// - Within a submission, command buffers execute in the order in which they
1239    ///   appear in `command_buffers`. All results produced by one buffer are
1240    ///   visible to the next.
1241    ///
1242    /// If two calls to `submit` on a single `Queue` from different threads are
1243    /// not synchronized to occur in a particular order, they must pass distinct
1244    /// [`Fence`]s. As explained in the [`Fence`] documentation, waiting for
1245    /// operations to complete is only trustworthy when operations finish in
1246    /// order of increasing fence value, but submissions from different threads
1247    /// cannot determine how to order the fence values if the submissions
1248    /// themselves are unordered. If each thread uses a separate [`Fence`], this
1249    /// problem does not arise.
1250    ///
1251    /// # Safety
1252    ///
1253    /// - Each [`CommandBuffer`][cb] in `command_buffers` must have been created
1254    ///   from a [`CommandEncoder`][ce] that was constructed from the
1255    ///   [`Device`][d] associated with this [`Queue`].
1256    ///
1257    /// - Each [`CommandBuffer`][cb] must remain alive until the submitted
1258    ///   commands have finished execution. Since command buffers must not
1259    ///   outlive their encoders, this implies that the encoders must remain
1260    ///   alive as well.
1261    ///
1262    /// - All resources used by a submitted [`CommandBuffer`][cb]
1263    ///   ([`Texture`][t]s, [`BindGroup`][bg]s, [`RenderPipeline`][rp]s, and so
1264    ///   on) must remain alive until the command buffer finishes execution.
1265    ///
1266    /// - Every [`SurfaceTexture`][st] that any command in `command_buffers`
1267    ///   writes to must appear in the `surface_textures` argument.
1268    ///
1269    /// - No [`SurfaceTexture`][st] may appear in the `surface_textures`
1270    ///   argument more than once.
1271    ///
1272    /// - Each [`SurfaceTexture`][st] in `surface_textures` must be configured
1273    ///   for use with the [`Device`][d] associated with this [`Queue`],
1274    ///   typically by calling [`Surface::configure`].
1275    ///
1276    /// - All calls to this function that include a given [`SurfaceTexture`][st]
1277    ///   in `surface_textures` must use the same [`Fence`].
1278    ///
1279    /// - The [`Fence`] passed as `signal_fence.0` must remain alive until
1280    ///   all submissions that will signal it have completed.
1281    ///
1282    /// [`Fence`]: Api::Fence
1283    /// [cb]: Api::CommandBuffer
1284    /// [ce]: Api::CommandEncoder
1285    /// [d]: Api::Device
1286    /// [t]: Api::Texture
1287    /// [bg]: Api::BindGroup
1288    /// [rp]: Api::RenderPipeline
1289    /// [st]: Api::SurfaceTexture
1290    unsafe fn submit(
1291        &self,
1292        command_buffers: &[&<Self::A as Api>::CommandBuffer],
1293        surface_textures: &[&<Self::A as Api>::SurfaceTexture],
1294        signal_fence: (&<Self::A as Api>::Fence, FenceValue),
1295    ) -> Result<(), DeviceError>;
1296    /// Present a surface texture to the screen.
1297    ///
1298    /// This consumes the surface texture, returning it to the swapchain.
1299    ///
1300    /// # Safety
1301    ///
1302    /// - `texture` must have been acquired from `surface` via
1303    ///   [`Surface::acquire_texture`] and not yet presented or discarded.
1304    /// - `surface` must be configured for use with the [`Device`][d] associated
1305    ///   with this [`Queue`].
1306    /// - `texture` must be in the "present" state. Either:
1307    ///   - It was passed in [`submit`][s]'s `surface_textures` argument
1308    ///     (which transitions it to the present state), or
1309    ///   - The caller has otherwise transitioned it (e.g. via a clear +
1310    ///     barrier to `PRESENT` for textures that were never rendered to).
1311    /// - Any command buffers that write to `texture` must have been submitted
1312    ///   via [`submit`][s] before this call. The submissions do not need to
1313    ///   have completed on the GPU; platform-level synchronization handles the
1314    ///   ordering between rendering and display.
1315    /// - Must be externally synchronized with all other queue operations
1316    ///   ([`submit`][s], [`present`][Queue::present],
1317    ///   [`wait_for_idle`][Queue::wait_for_idle]) on the same queue.
1318    ///
1319    /// [d]: Api::Device
1320    /// [s]: Queue::submit
1321    unsafe fn present(
1322        &self,
1323        surface: &<Self::A as Api>::Surface,
1324        texture: <Self::A as Api>::SurfaceTexture,
1325    ) -> Result<(), SurfaceError>;
1326    /// Block until all previously submitted work on this queue has completed,
1327    /// including any pending presentations.
1328    ///
1329    /// # Safety
1330    ///
1331    /// - Must be externally synchronized with all other queue operations
1332    ///   ([`submit`][Queue::submit], [`present`][Queue::present],
1333    ///   [`wait_for_idle`][Queue::wait_for_idle]) on the same queue.
1334    unsafe fn wait_for_idle(&self) -> Result<(), DeviceError>;
1335    unsafe fn get_timestamp_period(&self) -> f32;
1336}
1337
1338/// Encoder and allocation pool for `CommandBuffer`s.
1339///
1340/// A `CommandEncoder` not only constructs `CommandBuffer`s but also
1341/// acts as the allocation pool that owns the buffers' underlying
1342/// storage. Thus, `CommandBuffer`s must not outlive the
1343/// `CommandEncoder` that created them.
1344///
1345/// The life cycle of a `CommandBuffer` is as follows:
1346///
1347/// - Call [`Device::create_command_encoder`] to create a new
1348///   `CommandEncoder`, in the "closed" state.
1349///
1350/// - Call `begin_encoding` on a closed `CommandEncoder` to begin
1351///   recording commands. This puts the `CommandEncoder` in the
1352///   "recording" state.
1353///
1354/// - Call methods like `copy_buffer_to_buffer`, `begin_render_pass`,
1355///   etc. on a "recording" `CommandEncoder` to add commands to the
1356///   list. (If an error occurs, you must call `discard_encoding`; see
1357///   below.)
1358///
1359/// - Call `end_encoding` on a recording `CommandEncoder` to close the
1360///   encoder and construct a fresh `CommandBuffer` consisting of the
1361///   list of commands recorded up to that point.
1362///
1363/// - Call `discard_encoding` on a recording `CommandEncoder` to drop
1364///   the commands recorded thus far and close the encoder. This is
1365///   the only safe thing to do on a `CommandEncoder` if an error has
1366///   occurred while recording commands.
1367///
1368/// - Call `reset_all` on a closed `CommandEncoder`, passing all the
1369///   live `CommandBuffers` built from it. All the `CommandBuffer`s
1370///   are destroyed, and their resources are freed.
1371///
1372/// # Safety
1373///
1374/// - The `CommandEncoder` must be in the states described above to
1375///   make the given calls.
1376///
1377/// - A `CommandBuffer` that has been submitted for execution on the
1378///   GPU must live until its execution is complete.
1379///
1380/// - A `CommandBuffer` must not outlive the `CommandEncoder` that
1381///   built it.
1382///
1383/// It is the user's responsibility to meet this requirements. This
1384/// allows `CommandEncoder` implementations to keep their state
1385/// tracking to a minimum.
1386pub trait CommandEncoder: WasmNotSendSync + fmt::Debug {
1387    type A: Api;
1388
1389    /// Begin encoding a new command buffer.
1390    ///
1391    /// This puts this `CommandEncoder` in the "recording" state.
1392    ///
1393    /// # Safety
1394    ///
1395    /// This `CommandEncoder` must be in the "closed" state.
1396    unsafe fn begin_encoding(&mut self, label: Label) -> Result<(), DeviceError>;
1397
1398    /// Discard the command list under construction.
1399    ///
1400    /// If an error has occurred while recording commands, this
1401    /// is the only safe thing to do with the encoder.
1402    ///
1403    /// This puts this `CommandEncoder` in the "closed" state.
1404    ///
1405    /// # Safety
1406    ///
1407    /// This `CommandEncoder` must be in the "recording" state.
1408    ///
1409    /// Callers must not assume that implementations of this
1410    /// function are idempotent, and thus should not call it
1411    /// multiple times in a row.
1412    unsafe fn discard_encoding(&mut self);
1413
1414    /// Return a fresh [`CommandBuffer`] holding the recorded commands.
1415    ///
1416    /// The returned [`CommandBuffer`] holds all the commands recorded
1417    /// on this `CommandEncoder` since the last call to
1418    /// [`begin_encoding`].
1419    ///
1420    /// This puts this `CommandEncoder` in the "closed" state.
1421    ///
1422    /// # Safety
1423    ///
1424    /// This `CommandEncoder` must be in the "recording" state.
1425    ///
1426    /// The returned [`CommandBuffer`] must not outlive this
1427    /// `CommandEncoder`. Implementations are allowed to build
1428    /// `CommandBuffer`s that depend on storage owned by this
1429    /// `CommandEncoder`.
1430    ///
1431    /// [`CommandBuffer`]: Api::CommandBuffer
1432    /// [`begin_encoding`]: CommandEncoder::begin_encoding
1433    unsafe fn end_encoding(&mut self) -> Result<<Self::A as Api>::CommandBuffer, DeviceError>;
1434
1435    /// Reclaim all resources belonging to this `CommandEncoder`.
1436    ///
1437    /// # Safety
1438    ///
1439    /// This `CommandEncoder` must be in the "closed" state.
1440    ///
1441    /// The `command_buffers` iterator must produce all the live
1442    /// [`CommandBuffer`]s built using this `CommandEncoder` --- that
1443    /// is, every extant `CommandBuffer` returned from `end_encoding`.
1444    ///
1445    /// [`CommandBuffer`]: Api::CommandBuffer
1446    unsafe fn reset_all<I>(&mut self, command_buffers: I)
1447    where
1448        I: Iterator<Item = <Self::A as Api>::CommandBuffer>;
1449
1450    unsafe fn transition_buffers<'a, T>(&mut self, barriers: T)
1451    where
1452        T: Iterator<Item = BufferBarrier<'a, <Self::A as Api>::Buffer>>;
1453
1454    unsafe fn transition_textures<'a, T>(&mut self, barriers: T)
1455    where
1456        T: Iterator<Item = TextureBarrier<'a, <Self::A as Api>::Texture>>;
1457
1458    // copy operations
1459
1460    unsafe fn clear_buffer(&mut self, buffer: &<Self::A as Api>::Buffer, range: MemoryRange);
1461
1462    unsafe fn copy_buffer_to_buffer<T>(
1463        &mut self,
1464        src: &<Self::A as Api>::Buffer,
1465        dst: &<Self::A as Api>::Buffer,
1466        regions: T,
1467    ) where
1468        T: Iterator<Item = BufferCopy>;
1469
1470    /// Copy from an external image to an internal texture.
1471    /// Works with a single array layer.
1472    /// Note: `dst` current usage has to be `wgt::TextureUses::COPY_DST`.
1473    /// Note: the copy extent is in physical size (rounded to the block size)
1474    #[cfg(webgl)]
1475    unsafe fn copy_external_image_to_texture<T>(
1476        &mut self,
1477        src: &wgt::CopyExternalImageSourceInfo,
1478        dst: &<Self::A as Api>::Texture,
1479        dst_premultiplication: bool,
1480        regions: T,
1481    ) where
1482        T: Iterator<Item = TextureCopy>;
1483
1484    /// Copy from one texture to another.
1485    /// Works with a single array layer.
1486    /// Note: `dst` current usage has to be `wgt::TextureUses::COPY_DST`.
1487    /// Note: the copy extent is in physical size (rounded to the block size)
1488    unsafe fn copy_texture_to_texture<T>(
1489        &mut self,
1490        src: &<Self::A as Api>::Texture,
1491        src_usage: wgt::TextureUses,
1492        dst: &<Self::A as Api>::Texture,
1493        regions: T,
1494    ) where
1495        T: Iterator<Item = TextureCopy>;
1496
1497    /// Copy from buffer to texture.
1498    /// Works with a single array layer.
1499    /// Note: `dst` current usage has to be `wgt::TextureUses::COPY_DST`.
1500    /// Note: the copy extent is in physical size (rounded to the block size)
1501    unsafe fn copy_buffer_to_texture<T>(
1502        &mut self,
1503        src: &<Self::A as Api>::Buffer,
1504        dst: &<Self::A as Api>::Texture,
1505        regions: T,
1506    ) where
1507        T: Iterator<Item = BufferTextureCopy>;
1508
1509    /// Copy from texture to buffer.
1510    /// Works with a single array layer.
1511    /// Note: the copy extent is in physical size (rounded to the block size)
1512    unsafe fn copy_texture_to_buffer<T>(
1513        &mut self,
1514        src: &<Self::A as Api>::Texture,
1515        src_usage: wgt::TextureUses,
1516        dst: &<Self::A as Api>::Buffer,
1517        regions: T,
1518    ) where
1519        T: Iterator<Item = BufferTextureCopy>;
1520
1521    unsafe fn copy_acceleration_structure_to_acceleration_structure(
1522        &mut self,
1523        src: &<Self::A as Api>::AccelerationStructure,
1524        dst: &<Self::A as Api>::AccelerationStructure,
1525        copy: wgt::AccelerationStructureCopy,
1526    );
1527    // pass common
1528
1529    /// Sets the bind group at `index` to `group`.
1530    ///
1531    /// If this is not the first call to `set_bind_group` within the current
1532    /// render or compute pass:
1533    ///
1534    /// - If `layout` contains `n` bind group layouts, then any previously set
1535    ///   bind groups at indices `n` or higher are cleared.
1536    ///
1537    /// - If the first `m` bind group layouts of `layout` are equal to those of
1538    ///   the previously passed layout, but no more, then any previously set
1539    ///   bind groups at indices `m` or higher are cleared.
1540    ///
1541    /// It follows from the above that passing the same layout as before doesn't
1542    /// clear any bind groups.
1543    ///
1544    /// # Safety
1545    ///
1546    /// - This [`CommandEncoder`] must be within a render or compute pass.
1547    ///
1548    /// - `index` must be the valid index of some bind group layout in `layout`.
1549    ///   Call this the "relevant bind group layout".
1550    ///
1551    /// - The layout of `group` must be equal to the relevant bind group layout.
1552    ///
1553    /// - The length of `dynamic_offsets` must match the number of buffer
1554    ///   bindings [with dynamic offsets][hdo] in the relevant bind group
1555    ///   layout.
1556    ///
1557    /// - If those buffer bindings are ordered by increasing [`binding` number]
1558    ///   and paired with elements from `dynamic_offsets`, then each offset must
1559    ///   be a valid offset for the binding's corresponding buffer in `group`.
1560    ///
1561    /// [hdo]: wgt::BindingType::Buffer::has_dynamic_offset
1562    /// [`binding` number]: wgt::BindGroupLayoutEntry::binding
1563    unsafe fn set_bind_group(
1564        &mut self,
1565        layout: &<Self::A as Api>::PipelineLayout,
1566        index: u32,
1567        group: &<Self::A as Api>::BindGroup,
1568        dynamic_offsets: &[wgt::DynamicOffset],
1569    );
1570
1571    /// Sets a range in immediate data.
1572    ///
1573    /// IMPORTANT: while the data is passed as words, the offset is in bytes!
1574    ///
1575    /// # Safety
1576    ///
1577    /// - `offset_bytes` must be a multiple of 4.
1578    /// - The range of immediates written must be valid for the pipeline layout at draw time.
1579    unsafe fn set_immediates(
1580        &mut self,
1581        layout: &<Self::A as Api>::PipelineLayout,
1582        offset_bytes: u32,
1583        data: &[u32],
1584    );
1585
1586    unsafe fn insert_debug_marker(&mut self, label: &str);
1587    unsafe fn begin_debug_marker(&mut self, group_label: &str);
1588    unsafe fn end_debug_marker(&mut self);
1589
1590    // queries
1591
1592    /// # Safety:
1593    ///
1594    /// - If `set` is an occlusion query set, it must be the same one as used in the [`RenderPassDescriptor::occlusion_query_set`] parameter.
1595    unsafe fn begin_query(&mut self, set: &<Self::A as Api>::QuerySet, index: u32);
1596    /// # Safety:
1597    ///
1598    /// - If `set` is an occlusion query set, it must be the same one as used in the [`RenderPassDescriptor::occlusion_query_set`] parameter.
1599    unsafe fn end_query(&mut self, set: &<Self::A as Api>::QuerySet, index: u32);
1600    unsafe fn write_timestamp(&mut self, set: &<Self::A as Api>::QuerySet, index: u32);
1601    unsafe fn reset_queries(&mut self, set: &<Self::A as Api>::QuerySet, range: Range<u32>);
1602    unsafe fn copy_query_results(
1603        &mut self,
1604        set: &<Self::A as Api>::QuerySet,
1605        range: Range<u32>,
1606        buffer: &<Self::A as Api>::Buffer,
1607        offset: wgt::BufferAddress,
1608        stride: wgt::BufferSize,
1609    );
1610
1611    // render passes
1612
1613    /// Begin a new render pass, clearing all active bindings.
1614    ///
1615    /// This clears any bindings established by the following calls:
1616    ///
1617    /// - [`set_bind_group`](CommandEncoder::set_bind_group)
1618    /// - [`set_immediates`](CommandEncoder::set_immediates)
1619    /// - [`begin_query`](CommandEncoder::begin_query)
1620    /// - [`set_render_pipeline`](CommandEncoder::set_render_pipeline)
1621    /// - [`set_index_buffer`](CommandEncoder::set_index_buffer)
1622    /// - [`set_vertex_buffer`](CommandEncoder::set_vertex_buffer)
1623    ///
1624    /// # Safety
1625    ///
1626    /// - All prior calls to [`begin_render_pass`] on this [`CommandEncoder`] must have been followed
1627    ///   by a call to [`end_render_pass`].
1628    ///
1629    /// - All prior calls to [`begin_compute_pass`] on this [`CommandEncoder`] must have been followed
1630    ///   by a call to [`end_compute_pass`].
1631    ///
1632    /// - All prior calls to [`begin_ray_tracing_pass`] on this [`CommandEncoder`] must have been followed
1633    ///   by a call to [`end_ray_tracing_pass`].
1634    ///
1635    /// [`begin_render_pass`]: CommandEncoder::begin_render_pass
1636    /// [`begin_compute_pass`]: CommandEncoder::begin_compute_pass
1637    /// [`begin_ray_tracing_pass`]: CommandEncoder::begin_ray_tracing_pass
1638    /// [`end_render_pass`]: CommandEncoder::end_render_pass
1639    /// [`end_compute_pass`]: CommandEncoder::end_compute_pass
1640    /// [`end_ray_tracing_pass`]: CommandEncoder::end_ray_tracing_pass
1641    unsafe fn begin_render_pass(
1642        &mut self,
1643        desc: &RenderPassDescriptor<<Self::A as Api>::QuerySet, <Self::A as Api>::TextureView>,
1644    ) -> Result<(), DeviceError>;
1645
1646    /// End the current render pass.
1647    ///
1648    /// # Safety
1649    ///
1650    /// - There must have been a prior call to [`begin_render_pass`] on this [`CommandEncoder`]
1651    ///   that has not been followed by a call to [`end_render_pass`].
1652    ///
1653    /// [`begin_render_pass`]: CommandEncoder::begin_render_pass
1654    /// [`end_render_pass`]: CommandEncoder::end_render_pass
1655    unsafe fn end_render_pass(&mut self);
1656
1657    unsafe fn set_render_pipeline(&mut self, pipeline: &<Self::A as Api>::RenderPipeline);
1658
1659    unsafe fn set_index_buffer<'a>(
1660        &mut self,
1661        binding: BufferBinding<'a, <Self::A as Api>::Buffer>,
1662        format: wgt::IndexFormat,
1663    );
1664    unsafe fn set_vertex_buffer<'a>(
1665        &mut self,
1666        index: u32,
1667        binding: BufferBinding<'a, <Self::A as Api>::Buffer>,
1668    );
1669    unsafe fn set_viewport(&mut self, rect: &Rect<f32>, depth_range: Range<f32>);
1670    unsafe fn set_scissor_rect(&mut self, rect: &Rect<u32>);
1671    unsafe fn set_stencil_reference(&mut self, value: u32);
1672    unsafe fn set_blend_constants(&mut self, color: &[f32; 4]);
1673
1674    unsafe fn draw(
1675        &mut self,
1676        first_vertex: u32,
1677        vertex_count: u32,
1678        first_instance: u32,
1679        instance_count: u32,
1680    );
1681    unsafe fn draw_indexed(
1682        &mut self,
1683        first_index: u32,
1684        index_count: u32,
1685        base_vertex: i32,
1686        first_instance: u32,
1687        instance_count: u32,
1688    );
1689    unsafe fn draw_indirect(
1690        &mut self,
1691        buffer: &<Self::A as Api>::Buffer,
1692        offset: wgt::BufferAddress,
1693        draw_count: u32,
1694    );
1695    unsafe fn draw_indexed_indirect(
1696        &mut self,
1697        buffer: &<Self::A as Api>::Buffer,
1698        offset: wgt::BufferAddress,
1699        draw_count: u32,
1700    );
1701    unsafe fn draw_indirect_count(
1702        &mut self,
1703        buffer: &<Self::A as Api>::Buffer,
1704        offset: wgt::BufferAddress,
1705        count_buffer: &<Self::A as Api>::Buffer,
1706        count_offset: wgt::BufferAddress,
1707        max_count: u32,
1708    );
1709    unsafe fn draw_indexed_indirect_count(
1710        &mut self,
1711        buffer: &<Self::A as Api>::Buffer,
1712        offset: wgt::BufferAddress,
1713        count_buffer: &<Self::A as Api>::Buffer,
1714        count_offset: wgt::BufferAddress,
1715        max_count: u32,
1716    );
1717    unsafe fn draw_mesh_tasks(
1718        &mut self,
1719        group_count_x: u32,
1720        group_count_y: u32,
1721        group_count_z: u32,
1722    );
1723    unsafe fn draw_mesh_tasks_indirect(
1724        &mut self,
1725        buffer: &<Self::A as Api>::Buffer,
1726        offset: wgt::BufferAddress,
1727        draw_count: u32,
1728    );
1729    unsafe fn draw_mesh_tasks_indirect_count(
1730        &mut self,
1731        buffer: &<Self::A as Api>::Buffer,
1732        offset: wgt::BufferAddress,
1733        count_buffer: &<Self::A as Api>::Buffer,
1734        count_offset: wgt::BufferAddress,
1735        max_count: u32,
1736    );
1737
1738    // compute passes
1739
1740    /// Begin a new compute pass, clearing all active bindings.
1741    ///
1742    /// This clears any bindings established by the following calls:
1743    ///
1744    /// - [`set_bind_group`](CommandEncoder::set_bind_group)
1745    /// - [`set_immediates`](CommandEncoder::set_immediates)
1746    /// - [`begin_query`](CommandEncoder::begin_query)
1747    /// - [`set_compute_pipeline`](CommandEncoder::set_compute_pipeline)
1748    ///
1749    /// # Safety
1750    ///
1751    /// - All prior calls to [`begin_render_pass`] on this [`CommandEncoder`] must have been followed
1752    ///   by a call to [`end_render_pass`].
1753    ///
1754    /// - All prior calls to [`begin_compute_pass`] on this [`CommandEncoder`] must have been followed
1755    ///   by a call to [`end_compute_pass`].
1756    ///
1757    /// - All prior calls to [`begin_ray_tracing_pass`] on this [`CommandEncoder`] must have been followed
1758    ///   by a call to [`end_ray_tracing_pass`].
1759    ///
1760    /// [`begin_render_pass`]: CommandEncoder::begin_render_pass
1761    /// [`begin_compute_pass`]: CommandEncoder::begin_compute_pass
1762    /// [`begin_ray_tracing_pass`]: CommandEncoder::begin_ray_tracing_pass
1763    /// [`end_render_pass`]: CommandEncoder::end_render_pass
1764    /// [`end_compute_pass`]: CommandEncoder::end_compute_pass
1765    /// [`end_ray_tracing_pass`]: CommandEncoder::end_ray_tracing_pass
1766    unsafe fn begin_compute_pass(
1767        &mut self,
1768        desc: &ComputePassDescriptor<<Self::A as Api>::QuerySet>,
1769    );
1770
1771    /// End the current compute pass.
1772    ///
1773    /// # Safety
1774    ///
1775    /// - There must have been a prior call to [`begin_compute_pass`] on this [`CommandEncoder`]
1776    ///   that has not been followed by a call to [`end_compute_pass`].
1777    ///
1778    /// [`begin_compute_pass`]: CommandEncoder::begin_compute_pass
1779    /// [`end_compute_pass`]: CommandEncoder::end_compute_pass
1780    unsafe fn end_compute_pass(&mut self);
1781
1782    unsafe fn set_compute_pipeline(&mut self, pipeline: &<Self::A as Api>::ComputePipeline);
1783
1784    unsafe fn dispatch_workgroups(&mut self, count: [u32; 3]);
1785    unsafe fn dispatch_workgroups_indirect(
1786        &mut self,
1787        buffer: &<Self::A as Api>::Buffer,
1788        offset: wgt::BufferAddress,
1789    );
1790
1791    /// Begin a new ray tracing pass, clearing all active bindings.
1792    ///
1793    /// This clears any bindings established by the following calls:
1794    ///
1795    /// - [`set_bind_group`](CommandEncoder::set_bind_group)
1796    /// - [`set_immediates`](CommandEncoder::set_immediates)
1797    /// - [`begin_query`](CommandEncoder::begin_query)
1798    /// - [`set_ray_tracing_pipeline`](CommandEncoder::set_compute_pipeline)
1799    ///
1800    /// # Safety
1801    ///
1802    /// - All prior calls to [`begin_render_pass`] on this [`CommandEncoder`] must have been followed
1803    ///   by a call to [`end_render_pass`].
1804    ///
1805    /// - All prior calls to [`begin_compute_pass`] on this [`CommandEncoder`] must have been followed
1806    ///   by a call to [`end_compute_pass`].
1807    ///
1808    /// - All prior calls to [`begin_ray_tracing_pass`] on this [`CommandEncoder`] must have been followed
1809    ///   by a call to [`end_ray_tracing_pass`].
1810    ///
1811    /// [`begin_render_pass`]: CommandEncoder::begin_render_pass
1812    /// [`begin_compute_pass`]: CommandEncoder::begin_compute_pass
1813    /// [`begin_ray_tracing_pass`]: CommandEncoder::begin_ray_tracing_pass
1814    /// [`end_render_pass`]: CommandEncoder::end_render_pass
1815    /// [`end_compute_pass`]: CommandEncoder::end_compute_pass
1816    /// [`end_ray_tracing_pass`]: CommandEncoder::end_ray_tracing_pass
1817    unsafe fn begin_ray_tracing_pass(&mut self, desc: &RayTracingPassDescriptor);
1818
1819    /// End the current compute pass.
1820    ///
1821    /// # Safety
1822    ///
1823    /// - There must have been a prior call to [`begin_ray_tracing_pass`] on this [`CommandEncoder`]
1824    ///   that has not been followed by a call to [`end_ray_tracing_pass`].
1825    ///
1826    /// [`begin_ray_tracing_pass`]: CommandEncoder::begin_ray_tracing_pass
1827    /// [`end_ray_tracing_pass`]: CommandEncoder::end_ray_tracing_pass
1828    unsafe fn end_ray_tracing_pass(&mut self);
1829
1830    /// # Safety
1831    ///
1832    /// - Pipeline must not be destroyed
1833    unsafe fn set_ray_tracing_pipeline(&mut self, pipeline: &<Self::A as Api>::RayTracingPipeline);
1834
1835    unsafe fn trace_rays<'a>(
1836        &mut self,
1837        count: [u32; 3],
1838        ray_generation_group_data: PipelineGroupData<'a, <Self::A as Api>::Buffer>,
1839        miss_group_data: PipelineGroupData<'a, <Self::A as Api>::Buffer>,
1840        intersection_group_data: PipelineGroupData<'a, <Self::A as Api>::Buffer>,
1841    );
1842
1843    /// To get the required sizes for the buffer allocations use `get_acceleration_structure_build_sizes` per descriptor
1844    /// All buffers must be synchronized externally
1845    /// All buffer regions, which are written to may only be passed once per function call,
1846    /// with the exception of updates in the same descriptor.
1847    /// Consequences of this limitation:
1848    /// - scratch buffers need to be unique
1849    /// - a tlas can't be build in the same call with a blas it contains
1850    unsafe fn build_acceleration_structures<'a, T>(
1851        &mut self,
1852        descriptor_count: u32,
1853        descriptors: T,
1854    ) where
1855        Self::A: 'a,
1856        T: IntoIterator<
1857            Item = BuildAccelerationStructureDescriptor<
1858                'a,
1859                <Self::A as Api>::Buffer,
1860                <Self::A as Api>::AccelerationStructure,
1861            >,
1862        >;
1863    unsafe fn place_acceleration_structure_barrier(
1864        &mut self,
1865        barrier: AccelerationStructureBarrier,
1866    );
1867    // modeled off dx12, because this is able to be polyfilled in vulkan as opposed to the other way round
1868    unsafe fn read_acceleration_structure_compact_size(
1869        &mut self,
1870        acceleration_structure: &<Self::A as Api>::AccelerationStructure,
1871        buf: &<Self::A as Api>::Buffer,
1872    );
1873    unsafe fn set_acceleration_structure_dependencies(
1874        command_buffers: &[&<Self::A as Api>::CommandBuffer],
1875        dependencies: &[&<Self::A as Api>::AccelerationStructure],
1876    );
1877}
1878
1879bitflags!(
1880    /// Pipeline layout creation flags.
1881    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
1882    pub struct PipelineLayoutFlags: u32 {
1883        /// D3D12: Add support for `first_vertex` and `first_instance` builtins
1884        /// via immediates for direct execution.
1885        const FIRST_VERTEX_INSTANCE = 1 << 0;
1886        /// D3D12: Add support for `num_workgroups` builtins via immediates
1887        /// for direct execution.
1888        const NUM_WORK_GROUPS = 1 << 1;
1889        /// D3D12: Add support for the builtins that the other flags enable for
1890        /// indirect execution.
1891        const INDIRECT_BUILTIN_UPDATE = 1 << 2;
1892    }
1893);
1894
1895bitflags!(
1896    /// Pipeline layout creation flags.
1897    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
1898    pub struct BindGroupLayoutFlags: u32 {
1899        /// Allows for bind group binding arrays to be shorter than the array in the BGL.
1900        const PARTIALLY_BOUND = 1 << 0;
1901    }
1902);
1903
1904bitflags!(
1905    /// Texture format capability flags.
1906    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
1907    pub struct TextureFormatCapabilities: u32 {
1908        /// Format can be sampled.
1909        const SAMPLED = 1 << 0;
1910        /// Format can be sampled with a linear sampler.
1911        const SAMPLED_LINEAR = 1 << 1;
1912        /// Format can be sampled with a min/max reduction sampler.
1913        const SAMPLED_MINMAX = 1 << 2;
1914
1915        /// Format can be used as storage with read-only access.
1916        const STORAGE_READ_ONLY = 1 << 3;
1917        /// Format can be used as storage with write-only access.
1918        const STORAGE_WRITE_ONLY = 1 << 4;
1919        /// Format can be used as storage with both read and write access.
1920        const STORAGE_READ_WRITE = 1 << 5;
1921        /// Format can be used as storage with atomics.
1922        const STORAGE_ATOMIC = 1 << 6;
1923
1924        /// Format can be used as color and input attachment.
1925        const COLOR_ATTACHMENT = 1 << 7;
1926        /// Format can be used as color (with blending) and input attachment.
1927        const COLOR_ATTACHMENT_BLEND = 1 << 8;
1928        /// Format can be used as depth-stencil and input attachment.
1929        const DEPTH_STENCIL_ATTACHMENT = 1 << 9;
1930
1931        /// Format can be multisampled by x2.
1932        const MULTISAMPLE_X2   = 1 << 10;
1933        /// Format can be multisampled by x4.
1934        const MULTISAMPLE_X4   = 1 << 11;
1935        /// Format can be multisampled by x8.
1936        const MULTISAMPLE_X8   = 1 << 12;
1937        /// Format can be multisampled by x16.
1938        const MULTISAMPLE_X16  = 1 << 13;
1939
1940        /// Format can be used for render pass resolve targets.
1941        const MULTISAMPLE_RESOLVE = 1 << 14;
1942
1943        /// Format can be copied from.
1944        const COPY_SRC = 1 << 15;
1945        /// Format can be copied to.
1946        const COPY_DST = 1 << 16;
1947    }
1948);
1949
1950bitflags!(
1951    /// Texture format capability flags.
1952    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
1953    pub struct FormatAspects: u8 {
1954        const COLOR = 1 << 0;
1955        const DEPTH = 1 << 1;
1956        const STENCIL = 1 << 2;
1957        const PLANE_0 = 1 << 3;
1958        const PLANE_1 = 1 << 4;
1959        const PLANE_2 = 1 << 5;
1960
1961        const DEPTH_STENCIL = Self::DEPTH.bits() | Self::STENCIL.bits();
1962    }
1963);
1964
1965impl FormatAspects {
1966    pub fn new(format: wgt::TextureFormat, aspect: wgt::TextureAspect) -> Self {
1967        let aspect_mask = match aspect {
1968            wgt::TextureAspect::All => Self::all(),
1969            wgt::TextureAspect::DepthOnly => Self::DEPTH,
1970            wgt::TextureAspect::StencilOnly => Self::STENCIL,
1971            wgt::TextureAspect::Plane0 => Self::PLANE_0,
1972            wgt::TextureAspect::Plane1 => Self::PLANE_1,
1973            wgt::TextureAspect::Plane2 => Self::PLANE_2,
1974        };
1975        Self::from(format) & aspect_mask
1976    }
1977
1978    /// Returns `true` if only one flag is set
1979    pub fn is_one(&self) -> bool {
1980        self.bits().is_power_of_two()
1981    }
1982
1983    pub fn map(&self) -> wgt::TextureAspect {
1984        match *self {
1985            Self::COLOR => wgt::TextureAspect::All,
1986            Self::DEPTH => wgt::TextureAspect::DepthOnly,
1987            Self::STENCIL => wgt::TextureAspect::StencilOnly,
1988            Self::PLANE_0 => wgt::TextureAspect::Plane0,
1989            Self::PLANE_1 => wgt::TextureAspect::Plane1,
1990            Self::PLANE_2 => wgt::TextureAspect::Plane2,
1991            _ => unreachable!(),
1992        }
1993    }
1994}
1995
1996impl From<wgt::TextureFormat> for FormatAspects {
1997    fn from(format: wgt::TextureFormat) -> Self {
1998        match format {
1999            wgt::TextureFormat::Stencil8 => Self::STENCIL,
2000            wgt::TextureFormat::Depth16Unorm
2001            | wgt::TextureFormat::Depth32Float
2002            | wgt::TextureFormat::Depth24Plus => Self::DEPTH,
2003            wgt::TextureFormat::Depth32FloatStencil8 | wgt::TextureFormat::Depth24PlusStencil8 => {
2004                Self::DEPTH_STENCIL
2005            }
2006            wgt::TextureFormat::NV12 | wgt::TextureFormat::P010 => Self::PLANE_0 | Self::PLANE_1,
2007            _ => Self::COLOR,
2008        }
2009    }
2010}
2011
2012bitflags!(
2013    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
2014    pub struct MemoryFlags: u32 {
2015        const TRANSIENT = 1 << 0;
2016        const PREFER_COHERENT = 1 << 1;
2017    }
2018);
2019
2020bitflags!(
2021    /// Attachment load and store operations.
2022    ///
2023    /// There must be at least one flag from the LOAD group and one from the STORE group set.
2024    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
2025    pub struct AttachmentOps: u8 {
2026        /// Load the existing contents of the attachment.
2027        const LOAD = 1 << 0;
2028        /// Clear the attachment to a specified value.
2029        const LOAD_CLEAR = 1 << 1;
2030        /// The contents of the attachment are undefined.
2031        const LOAD_DONT_CARE = 1 << 2;
2032        /// Store the contents of the attachment.
2033        const STORE = 1 << 3;
2034        /// The contents of the attachment are undefined after the pass.
2035        const STORE_DISCARD = 1 << 4;
2036    }
2037);
2038
2039#[derive(Debug)]
2040pub struct InstanceDescriptor<'a> {
2041    pub name: &'a str,
2042    pub flags: wgt::InstanceFlags,
2043    pub memory_budget_thresholds: wgt::MemoryBudgetThresholds,
2044    pub backend_options: wgt::BackendOptions,
2045    pub telemetry: Option<Telemetry>,
2046    /// This is a borrow because the surrounding `core::Instance` keeps the owned display handle
2047    /// alive already.
2048    pub display: Option<DisplayHandle<'a>>,
2049}
2050
2051#[derive(Clone, Debug)]
2052pub struct Alignments {
2053    /// The alignment of the start of the buffer used as a GPU copy source.
2054    pub buffer_copy_offset: wgt::BufferSize,
2055
2056    /// The alignment of the row pitch of the texture data stored in a buffer that is
2057    /// used in a GPU copy operation.
2058    pub buffer_copy_pitch: wgt::BufferSize,
2059
2060    /// The finest alignment of bound range checking for uniform buffers.
2061    ///
2062    /// When `wgpu_hal` restricts shader references to the [accessible
2063    /// region][ar] of a [`Uniform`] buffer, the size of the accessible region
2064    /// is the bind group binding's stated [size], rounded up to the next
2065    /// multiple of this value.
2066    ///
2067    /// We don't need an analogous field for storage buffer bindings, because
2068    /// all our backends promise to enforce the size at least to a four-byte
2069    /// alignment, and `wgpu_hal` requires bound range lengths to be a multiple
2070    /// of four anyway.
2071    ///
2072    /// [ar]: struct.BufferBinding.html#accessible-region
2073    /// [`Uniform`]: wgt::BufferBindingType::Uniform
2074    /// [size]: BufferBinding::size
2075    pub uniform_bounds_check_alignment: wgt::BufferSize,
2076
2077    /// The size of the raw TLAS instance
2078    pub raw_tlas_instance_size: u32,
2079
2080    /// What the scratch buffer for building an acceleration structure must be aligned to
2081    pub ray_tracing_scratch_buffer_alignment: u32,
2082
2083    /// How large a single piece of group data is. That is, how large the vector returned
2084    /// from `device.get_raytracing_pipeline_group_data(&pipeline, n..(n+1))` is.
2085    ///
2086    /// If ray tracing pipelines are implemented, this must be non zero.
2087    pub ray_tracing_pipeline_group_data_size: u32,
2088
2089    /// If ray tracing pipelines are implemented, this must be a power of two (and non zero).
2090    pub ray_tracing_pipeline_group_data_alignment: u32,
2091
2092    /// If ray tracing pipelines are implemented, this must be a power of two (and non zero).
2093    ///
2094    /// The offset within `PipelineGroupData` must be a multiple of this
2095    pub ray_tracing_pipeline_data_offset_alignment: u32,
2096}
2097
2098#[derive(Clone, Debug)]
2099pub struct Capabilities {
2100    pub limits: wgt::Limits,
2101    pub alignments: Alignments,
2102    pub downlevel: wgt::DownlevelCapabilities,
2103    /// Supported cooperative matrix configurations.
2104    ///
2105    /// Empty if cooperative matrices are not supported.
2106    pub cooperative_matrix_properties: Vec<wgt::CooperativeMatrixProperties>,
2107}
2108
2109/// An adapter with all the information needed to reason about its capabilities.
2110///
2111/// These are either made by [`Instance::enumerate_adapters`] or by backend specific
2112/// methods on the backend [`Instance`] or [`Adapter`].
2113#[derive(Debug)]
2114pub struct ExposedAdapter<A: Api> {
2115    pub adapter: A::Adapter,
2116    pub info: wgt::AdapterInfo,
2117    pub features: wgt::Features,
2118    pub capabilities: Capabilities,
2119}
2120
2121/// Describes information about what a `Surface`'s presentation capabilities are.
2122/// Fetch this with [Adapter::surface_capabilities].
2123#[derive(Debug, Clone)]
2124pub struct SurfaceCapabilities {
2125    /// List of supported texture formats together with the color spaces
2126    /// supported for each format.
2127    ///
2128    /// Must be at least one. At most one entry per format, each with a
2129    /// non-empty set of color spaces.
2130    pub formats: Vec<wgt::SurfaceFormatCapabilities>,
2131
2132    /// Range for the number of queued frames.
2133    ///
2134    /// This adjusts either the swapchain frame count to value + 1 - or sets SetMaximumFrameLatency to the value given,
2135    /// or uses a wait-for-present in the acquire method to limit rendering such that it acts like it's a value + 1 swapchain frame set.
2136    ///
2137    /// - `maximum_frame_latency.start` must be at least 1.
2138    /// - `maximum_frame_latency.end` must be larger or equal to `maximum_frame_latency.start`.
2139    pub maximum_frame_latency: RangeInclusive<u32>,
2140
2141    /// Current extent of the surface, if known.
2142    pub current_extent: Option<wgt::Extent3d>,
2143
2144    /// Supported texture usage flags.
2145    ///
2146    /// Must have at least `wgt::TextureUses::COLOR_TARGET`
2147    pub usage: wgt::TextureUses,
2148
2149    /// List of supported V-sync modes.
2150    ///
2151    /// Must be at least one.
2152    pub present_modes: Vec<wgt::PresentMode>,
2153
2154    /// List of supported alpha composition modes.
2155    ///
2156    /// Must be at least one.
2157    pub composite_alpha_modes: Vec<wgt::CompositeAlphaMode>,
2158}
2159
2160impl SurfaceCapabilities {
2161    /// Returns the supported texture formats, dropping the per-format color-space
2162    /// information carried in [`Self::formats`].
2163    pub fn texture_formats(&self) -> impl Iterator<Item = wgt::TextureFormat> + '_ {
2164        self.formats.iter().map(|fc| fc.format)
2165    }
2166}
2167
2168#[derive(Debug)]
2169pub struct AcquiredSurfaceTexture<A: Api> {
2170    pub texture: A::SurfaceTexture,
2171    /// The presentation configuration no longer matches
2172    /// the surface properties exactly, but can still be used to present
2173    /// to the surface successfully.
2174    pub suboptimal: bool,
2175    /// How many presentable images the surface hands out, where the backend
2176    /// tells them apart ([`DynSurfaceTexture::image_id`]): one for a GL
2177    /// surface, which draws every frame into the same texture (Cranpose
2178    /// fork).
2179    pub images: u32,
2180}
2181
2182/// An open connection to a device and a queue.
2183///
2184/// This can be created from [`Adapter::open`] or backend
2185/// specific methods on the backend's [`Instance`] or [`Adapter`].
2186#[derive(Debug)]
2187pub struct OpenDevice<A: Api> {
2188    pub device: A::Device,
2189    pub queue: A::Queue,
2190}
2191
2192#[derive(Clone, Debug)]
2193pub struct BufferMapping {
2194    pub ptr: NonNull<u8>,
2195    pub is_coherent: bool,
2196}
2197
2198#[derive(Clone, Debug)]
2199pub struct BufferDescriptor<'a> {
2200    pub label: Label<'a>,
2201    pub size: wgt::BufferAddress,
2202    pub usage: wgt::BufferUses,
2203    pub memory_flags: MemoryFlags,
2204}
2205
2206#[derive(Clone, Debug)]
2207pub struct TextureDescriptor<'a> {
2208    pub label: Label<'a>,
2209    pub size: wgt::Extent3d,
2210    pub mip_level_count: u32,
2211    pub sample_count: u32,
2212    pub dimension: wgt::TextureDimension,
2213    pub format: wgt::TextureFormat,
2214    pub usage: wgt::TextureUses,
2215    pub memory_flags: MemoryFlags,
2216    /// Allows views of this texture to have a different format
2217    /// than the texture does.
2218    pub view_formats: Vec<wgt::TextureFormat>,
2219}
2220
2221impl TextureDescriptor<'_> {
2222    pub fn copy_extent(&self) -> CopyExtent {
2223        CopyExtent::map_extent_to_copy_size(&self.size, self.dimension)
2224    }
2225
2226    pub fn is_cube_compatible(&self) -> bool {
2227        self.dimension == wgt::TextureDimension::D2
2228            && self.size.depth_or_array_layers.is_multiple_of(6)
2229            && self.sample_count == 1
2230            && self.size.width == self.size.height
2231    }
2232
2233    pub fn array_layer_count(&self) -> u32 {
2234        match self.dimension {
2235            wgt::TextureDimension::D1 | wgt::TextureDimension::D3 => 1,
2236            wgt::TextureDimension::D2 => self.size.depth_or_array_layers,
2237        }
2238    }
2239}
2240
2241/// TextureView descriptor.
2242///
2243/// Valid usage:
2244///. - `format` has to be the same as `TextureDescriptor::format`
2245///. - `dimension` has to be compatible with `TextureDescriptor::dimension`
2246///. - `usage` has to be a subset of `TextureDescriptor::usage`
2247///. - `range` has to be a subset of parent texture
2248#[derive(Clone, Debug)]
2249pub struct TextureViewDescriptor<'a> {
2250    pub label: Label<'a>,
2251    pub format: wgt::TextureFormat,
2252    pub dimension: wgt::TextureViewDimension,
2253    pub usage: wgt::TextureUses,
2254    pub range: wgt::ImageSubresourceRange,
2255}
2256
2257#[derive(Clone, Debug)]
2258pub struct SamplerDescriptor<'a> {
2259    pub label: Label<'a>,
2260    pub address_modes: [wgt::AddressMode; 3],
2261    pub mag_filter: wgt::FilterMode,
2262    pub min_filter: wgt::FilterMode,
2263    pub mipmap_filter: wgt::MipmapFilterMode,
2264    pub lod_clamp: Range<f32>,
2265    pub compare: Option<wgt::CompareFunction>,
2266    // Must in the range [1, 16].
2267    //
2268    // Anisotropic filtering must be supported if this is not 1.
2269    pub anisotropy_clamp: u16,
2270    pub border_color: Option<wgt::SamplerBorderColor>,
2271}
2272
2273/// BindGroupLayout descriptor.
2274///
2275/// Valid usage:
2276/// - `entries` are sorted by ascending `wgt::BindGroupLayoutEntry::binding`
2277#[derive(Clone, Debug)]
2278pub struct BindGroupLayoutDescriptor<'a> {
2279    pub label: Label<'a>,
2280    pub flags: BindGroupLayoutFlags,
2281    pub entries: &'a [wgt::BindGroupLayoutEntry],
2282}
2283
2284#[derive(Clone, Debug)]
2285pub struct PipelineLayoutDescriptor<'a, B: DynBindGroupLayout + ?Sized> {
2286    pub label: Label<'a>,
2287    pub flags: PipelineLayoutFlags,
2288    pub bind_group_layouts: &'a [Option<&'a B>],
2289    pub immediate_size: u32,
2290}
2291
2292/// A region of a buffer made visible to shaders via a [`BindGroup`].
2293///
2294/// [`BindGroup`]: Api::BindGroup
2295///
2296/// ## Construction
2297///
2298/// The recommended way to construct a `BufferBinding` is using the `binding`
2299/// method on a wgpu-core `Buffer`, which will validate the binding size
2300/// against the buffer size. A `new_unchecked` constructor is also provided for
2301/// cases where direct construction is necessary.
2302///
2303/// ## Accessible region
2304///
2305/// `wgpu_hal` guarantees that shaders compiled with
2306/// [`ShaderModuleDescriptor::runtime_checks`] set to `true` cannot read or
2307/// write data via this binding outside the *accessible region* of a buffer:
2308///
2309/// - The accessible region starts at [`offset`].
2310///
2311/// - For [`Storage`] bindings, the size of the accessible region is [`size`],
2312///   which must be a multiple of 4.
2313///
2314/// - For [`Uniform`] bindings, the size of the accessible region is [`size`]
2315///   rounded up to the next multiple of
2316///   [`Alignments::uniform_bounds_check_alignment`].
2317///
2318/// Note that this guarantee is stricter than WGSL's requirements for
2319/// [out-of-bounds accesses][woob], as WGSL allows them to return values from
2320/// elsewhere in the buffer. But this guarantee is necessary anyway, to permit
2321/// `wgpu-core` to avoid clearing uninitialized regions of buffers that will
2322/// never be read by the application before they are overwritten. This
2323/// optimization consults bind group buffer binding regions to determine which
2324/// parts of which buffers shaders might observe. This optimization is only
2325/// sound if shader access is bounds-checked.
2326///
2327/// ## Zero-length bindings
2328///
2329/// Some back ends cannot tolerate zero-length regions; for example, see
2330/// [VUID-VkDescriptorBufferInfo-offset-00340][340] and
2331/// [VUID-VkDescriptorBufferInfo-range-00341][341], or the
2332/// documentation for GLES's [glBindBufferRange][bbr]. This documentation
2333/// previously stated that a `BufferBinding` must have `offset` strictly less
2334/// than the size of the buffer, but this restriction was not honored elsewhere
2335/// in the code, so has been removed. However, it remains the case that
2336/// some backends do not support zero-length bindings, so additional
2337/// logic is needed somewhere to handle this properly. See
2338/// [#3170](https://github.com/gfx-rs/wgpu/issues/3170).
2339///
2340/// [`offset`]: BufferBinding::offset
2341/// [`size`]: BufferBinding::size
2342/// [`Storage`]: wgt::BufferBindingType::Storage
2343/// [`Uniform`]: wgt::BufferBindingType::Uniform
2344/// [340]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#VUID-VkDescriptorBufferInfo-offset-00340
2345/// [341]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#VUID-VkDescriptorBufferInfo-range-00341
2346/// [bbr]: https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glBindBufferRange.xhtml
2347/// [woob]: https://gpuweb.github.io/gpuweb/wgsl/#out-of-bounds-access-sec
2348#[derive(Debug)]
2349pub struct BufferBinding<'a, B: DynBuffer + ?Sized> {
2350    /// The buffer being bound.
2351    ///
2352    /// This is not fully `pub` to prevent direct construction of
2353    /// `BufferBinding`s, while still allowing public read access to the `offset`
2354    /// and `size` properties.
2355    pub(crate) buffer: &'a B,
2356
2357    /// The offset at which the bound region starts.
2358    ///
2359    /// This must be less or equal to the size of the buffer.
2360    pub offset: wgt::BufferAddress,
2361
2362    /// The size of the region bound, in bytes.
2363    ///
2364    /// If `None`, the region extends from `offset` to the end of the
2365    /// buffer. Given the restrictions on `offset`, this means that
2366    /// the size is always greater than zero.
2367    pub size: Option<wgt::BufferSize>,
2368}
2369
2370// We must implement this manually because `B` is not necessarily `Clone`.
2371impl<B: DynBuffer + ?Sized> Clone for BufferBinding<'_, B> {
2372    fn clone(&self) -> Self {
2373        BufferBinding {
2374            buffer: self.buffer,
2375            offset: self.offset,
2376            size: self.size,
2377        }
2378    }
2379}
2380
2381/// Temporary convenience trait to let us call `.get()` on `u64`s in code that
2382/// really wants to be using `NonZeroU64`.
2383/// TODO(<https://github.com/gfx-rs/wgpu/issues/3170>): remove this
2384pub trait ShouldBeNonZeroExt {
2385    fn get(&self) -> u64;
2386}
2387
2388impl ShouldBeNonZeroExt for NonZeroU64 {
2389    fn get(&self) -> u64 {
2390        NonZeroU64::get(*self)
2391    }
2392}
2393
2394impl ShouldBeNonZeroExt for u64 {
2395    fn get(&self) -> u64 {
2396        *self
2397    }
2398}
2399
2400impl ShouldBeNonZeroExt for Option<NonZeroU64> {
2401    fn get(&self) -> u64 {
2402        match *self {
2403            Some(non_zero) => non_zero.get(),
2404            None => 0,
2405        }
2406    }
2407}
2408
2409impl<'a, B: DynBuffer + ?Sized> BufferBinding<'a, B> {
2410    /// Construct a `BufferBinding` with the given contents.
2411    ///
2412    /// When possible, use the `binding` method on a wgpu-core `Buffer` instead
2413    /// of this method. `Buffer::binding` validates the size of the binding
2414    /// against the size of the buffer.
2415    ///
2416    /// It is more difficult to provide a validating constructor here, due to
2417    /// not having direct access to the size of a `DynBuffer`.
2418    ///
2419    /// SAFETY: The caller is responsible for ensuring that a binding of `size`
2420    /// bytes starting at `offset` is contained within the buffer.
2421    ///
2422    /// The `S` type parameter is a temporary convenience to allow callers to
2423    /// pass a zero size. When the zero-size binding issue is resolved, the
2424    /// argument should just match the type of the member.
2425    /// TODO(<https://github.com/gfx-rs/wgpu/issues/3170>): remove the parameter
2426    pub fn new_unchecked<S: Into<Option<NonZeroU64>>>(
2427        buffer: &'a B,
2428        offset: wgt::BufferAddress,
2429        size: S,
2430    ) -> Self {
2431        Self {
2432            buffer,
2433            offset,
2434            size: size.into(),
2435        }
2436    }
2437}
2438
2439#[derive(Debug)]
2440pub struct TextureBinding<'a, T: DynTextureView + ?Sized> {
2441    pub view: &'a T,
2442    pub usage: wgt::TextureUses,
2443}
2444
2445impl<'a, T: DynTextureView + ?Sized> Clone for TextureBinding<'a, T> {
2446    fn clone(&self) -> Self {
2447        TextureBinding {
2448            view: self.view,
2449            usage: self.usage,
2450        }
2451    }
2452}
2453
2454#[derive(Debug)]
2455pub struct ExternalTextureBinding<'a, B: DynBuffer + ?Sized, T: DynTextureView + ?Sized> {
2456    pub planes: [TextureBinding<'a, T>; 3],
2457    pub params: BufferBinding<'a, B>,
2458}
2459
2460impl<'a, B: DynBuffer + ?Sized, T: DynTextureView + ?Sized> Clone
2461    for ExternalTextureBinding<'a, B, T>
2462{
2463    fn clone(&self) -> Self {
2464        ExternalTextureBinding {
2465            planes: self.planes.clone(),
2466            params: self.params.clone(),
2467        }
2468    }
2469}
2470
2471/// cbindgen:ignore
2472#[derive(Clone, Debug)]
2473pub struct BindGroupEntry {
2474    pub binding: u32,
2475    pub resource_index: u32,
2476    pub count: u32,
2477}
2478
2479/// BindGroup descriptor.
2480///
2481/// Valid usage:
2482///. - `entries` has to be sorted by ascending `BindGroupEntry::binding`
2483///. - `entries` has to have the same set of `BindGroupEntry::binding` as `layout`
2484///. - each entry has to be compatible with the `layout`
2485///. - each entry's `BindGroupEntry::resource_index` is within range
2486///    of the corresponding resource array, selected by the relevant
2487///    `BindGroupLayoutEntry`.
2488#[derive(Clone, Debug)]
2489pub struct BindGroupDescriptor<
2490    'a,
2491    Bgl: DynBindGroupLayout + ?Sized,
2492    B: DynBuffer + ?Sized,
2493    S: DynSampler + ?Sized,
2494    T: DynTextureView + ?Sized,
2495    A: DynAccelerationStructure + ?Sized,
2496> {
2497    pub label: Label<'a>,
2498    pub layout: &'a Bgl,
2499    pub buffers: &'a [BufferBinding<'a, B>],
2500    pub samplers: &'a [&'a S],
2501    pub textures: &'a [TextureBinding<'a, T>],
2502    pub entries: &'a [BindGroupEntry],
2503    pub acceleration_structures: &'a [&'a A],
2504    pub external_textures: &'a [ExternalTextureBinding<'a, B, T>],
2505}
2506
2507#[derive(Clone, Debug)]
2508pub struct CommandEncoderDescriptor<'a, Q: DynQueue + ?Sized> {
2509    pub label: Label<'a>,
2510    pub queue: &'a Q,
2511}
2512
2513/// Naga shader module.
2514#[derive(Default)]
2515pub struct NagaShader {
2516    /// Shader module IR.
2517    pub module: Cow<'static, naga::Module>,
2518    /// Analysis information of the module.
2519    pub info: naga::valid::ModuleInfo,
2520    /// Source codes for debug
2521    pub debug_source: Option<DebugSource>,
2522}
2523
2524// Custom implementation avoids the need to generate Debug impl code
2525// for the whole Naga module and info.
2526impl fmt::Debug for NagaShader {
2527    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
2528        write!(formatter, "Naga shader")
2529    }
2530}
2531
2532/// Shader input.
2533pub enum ShaderInput<'a> {
2534    Naga(NagaShader),
2535    MetalLib {
2536        file: &'a [u8],
2537        num_workgroups: hashbrown::HashMap<String, (u32, u32, u32)>,
2538    },
2539    Msl {
2540        shader: &'a str,
2541        num_workgroups: hashbrown::HashMap<String, (u32, u32, u32)>,
2542    },
2543    SpirV(&'a [u32]),
2544    Dxil {
2545        shader: &'a [u8],
2546    },
2547    Hlsl {
2548        shader: &'a str,
2549    },
2550    Glsl {
2551        shader: &'a str,
2552    },
2553    /// One template per entry point, for the GL backend.
2554    GlslTemplates(&'static [GlslTemplate]),
2555}
2556
2557impl fmt::Debug for ShaderInput<'_> {
2558    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2559        match self {
2560            // Don't include the entire shader source, especially for binary formats, because it
2561            // would be spammy.
2562            Self::Naga { .. } => f.debug_tuple("Naga").finish_non_exhaustive(),
2563            Self::MetalLib { .. } => f.debug_tuple("MetalLib").finish_non_exhaustive(),
2564            Self::Msl { .. } => f.debug_tuple("Msl").finish_non_exhaustive(),
2565            Self::SpirV { .. } => f.debug_tuple("SpirV").finish_non_exhaustive(),
2566            Self::Dxil { .. } => f.debug_tuple("Dxil").finish_non_exhaustive(),
2567            Self::Hlsl { .. } => f.debug_tuple("Hlsl").finish_non_exhaustive(),
2568            Self::Glsl { .. } => f.debug_tuple("Glsl").finish_non_exhaustive(),
2569            Self::GlslTemplates(_) => f.debug_tuple("GlslTemplates").finish_non_exhaustive(),
2570        }
2571    }
2572}
2573
2574#[derive(Debug)]
2575pub struct ShaderModuleDescriptor<'a> {
2576    pub label: Label<'a>,
2577
2578    /// # Safety
2579    ///
2580    /// See the documentation for each flag in [`ShaderRuntimeChecks`][src].
2581    ///
2582    /// [src]: wgt::ShaderRuntimeChecks
2583    pub runtime_checks: wgt::ShaderRuntimeChecks,
2584}
2585
2586#[derive(Debug, Clone)]
2587pub struct DebugSource {
2588    pub file_name: Cow<'static, str>,
2589    pub source_code: Cow<'static, str>,
2590}
2591
2592/// Describes a programmable pipeline stage.
2593#[derive(Debug)]
2594pub struct ProgrammableStage<'a, M: DynShaderModule + ?Sized> {
2595    /// The compiled shader module for this stage.
2596    pub module: &'a M,
2597    /// The name of the entry point in the compiled shader. There must be a function with this name
2598    ///  in the shader.
2599    pub entry_point: &'a str,
2600    /// Pipeline constants
2601    pub constants: &'a naga::back::PipelineConstants,
2602    /// Whether workgroup scoped memory will be initialized with zero values for this stage.
2603    ///
2604    /// This is required by the WebGPU spec, but may have overhead which can be avoided
2605    /// for cross-platform applications
2606    pub zero_initialize_workgroup_memory: bool,
2607}
2608
2609impl<M: DynShaderModule + ?Sized> Clone for ProgrammableStage<'_, M> {
2610    fn clone(&self) -> Self {
2611        Self {
2612            module: self.module,
2613            entry_point: self.entry_point,
2614            constants: self.constants,
2615            zero_initialize_workgroup_memory: self.zero_initialize_workgroup_memory,
2616        }
2617    }
2618}
2619
2620/// Describes a compute pipeline.
2621#[derive(Clone, Debug)]
2622pub struct ComputePipelineDescriptor<
2623    'a,
2624    Pl: DynPipelineLayout + ?Sized,
2625    M: DynShaderModule + ?Sized,
2626    Pc: DynPipelineCache + ?Sized,
2627> {
2628    pub label: Label<'a>,
2629    /// The layout of bind groups for this pipeline.
2630    pub layout: &'a Pl,
2631    /// The compiled compute stage and its entry point.
2632    pub stage: ProgrammableStage<'a, M>,
2633    /// The cache which will be used and filled when compiling this pipeline
2634    pub cache: Option<&'a Pc>,
2635}
2636
2637#[derive(Debug)]
2638pub struct PipelineCacheDescriptor<'a> {
2639    pub label: Label<'a>,
2640    pub data: Option<&'a [u8]>,
2641}
2642
2643/// Describes how the vertex buffer is interpreted.
2644#[derive(Clone, Debug)]
2645pub struct VertexBufferLayout<'a> {
2646    /// The stride, in bytes, between elements of this buffer.
2647    pub array_stride: wgt::BufferAddress,
2648    /// How often this vertex buffer is "stepped" forward.
2649    pub step_mode: wgt::VertexStepMode,
2650    /// The list of attributes which comprise a single vertex.
2651    pub attributes: &'a [wgt::VertexAttribute],
2652}
2653
2654#[derive(Clone, Debug)]
2655pub enum VertexProcessor<'a, M: DynShaderModule + ?Sized> {
2656    Standard {
2657        /// The format of any vertex buffers used with this pipeline.
2658        vertex_buffers: &'a [Option<VertexBufferLayout<'a>>],
2659        /// The vertex stage for this pipeline.
2660        vertex_stage: ProgrammableStage<'a, M>,
2661    },
2662    Mesh {
2663        task_stage: Option<ProgrammableStage<'a, M>>,
2664        mesh_stage: ProgrammableStage<'a, M>,
2665    },
2666}
2667
2668/// Describes a render (graphics) pipeline.
2669#[derive(Clone, Debug)]
2670pub struct RenderPipelineDescriptor<
2671    'a,
2672    Pl: DynPipelineLayout + ?Sized,
2673    M: DynShaderModule + ?Sized,
2674    Pc: DynPipelineCache + ?Sized,
2675> {
2676    pub label: Label<'a>,
2677    /// The layout of bind groups for this pipeline.
2678    pub layout: &'a Pl,
2679    /// The vertex processing state(vertex shader + buffers or task + mesh shaders)
2680    pub vertex_processor: VertexProcessor<'a, M>,
2681    /// The properties of the pipeline at the primitive assembly and rasterization level.
2682    pub primitive: wgt::PrimitiveState,
2683    /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
2684    pub depth_stencil: Option<wgt::DepthStencilState>,
2685    /// The multi-sampling properties of the pipeline.
2686    pub multisample: wgt::MultisampleState,
2687    /// The fragment stage for this pipeline.
2688    pub fragment_stage: Option<ProgrammableStage<'a, M>>,
2689    /// The effect of draw calls on the color aspect of the output target.
2690    pub color_targets: &'a [Option<wgt::ColorTargetState>],
2691    /// If the pipeline will be used with a multiview render pass, this indicates how many array
2692    /// layers the attachments will have.
2693    pub multiview_mask: Option<NonZeroU32>,
2694    /// The cache which will be used and filled when compiling this pipeline
2695    pub cache: Option<&'a Pc>,
2696}
2697
2698#[derive(Clone, Debug)]
2699pub struct RayObjectIntersectionState<'a, M: DynShaderModule + ?Sized> {
2700    pub closest_hit: ProgrammableStage<'a, M>,
2701    pub any_hit: Option<ProgrammableStage<'a, M>>,
2702}
2703
2704/// Describes a ray tracing pipeline.
2705#[derive(Clone, Debug)]
2706pub struct RayTracingPipelineDescriptor<
2707    'a,
2708    Pl: DynPipelineLayout + ?Sized,
2709    M: DynShaderModule + ?Sized,
2710    Pc: DynPipelineCache + ?Sized,
2711> {
2712    pub label: Label<'a>,
2713    /// The layout of bind groups for this pipeline.
2714    pub layout: &'a Pl,
2715    /// The ray generation stage.
2716    pub ray_generation: ProgrammableStage<'a, M>,
2717    /// The miss stage.
2718    pub miss: ProgrammableStage<'a, M>,
2719    /// All the object intersection stages.
2720    pub intersection: &'a [RayObjectIntersectionState<'a, M>],
2721    /// The maximum recursion depth allowed for the ray tracing (ray_generation shader counts as depth 0).
2722    pub max_recursion_depth: u32,
2723    /// The cache which will be used and filled when compiling this pipeline
2724    pub cache: Option<&'a Pc>,
2725}
2726
2727#[derive(Debug, Clone)]
2728pub struct SurfaceConfiguration {
2729    /// Maximum number of queued frames. Must be in
2730    /// `SurfaceCapabilities::maximum_frame_latency` range.
2731    pub maximum_frame_latency: u32,
2732    /// Vertical synchronization mode.
2733    pub present_mode: wgt::PresentMode,
2734    /// Alpha composition mode.
2735    pub composite_alpha_mode: wgt::CompositeAlphaMode,
2736    /// Format of the surface textures.
2737    pub format: wgt::TextureFormat,
2738    /// Color space in which the presentation engine interprets the surface
2739    /// textures. Never [`wgt::SurfaceColorSpace::Auto`]; `wgpu-core` resolves
2740    /// `Auto` to a concrete color space before configuring the surface, and
2741    /// the (format, color space) pair must be listed in
2742    /// `SurfaceCapabilities::formats`.
2743    pub color_space: wgt::SurfaceColorSpace,
2744    /// Requested texture extent. Must be in
2745    /// `SurfaceCapabilities::extents` range.
2746    pub extent: wgt::Extent3d,
2747    /// Allowed usage of surface textures,
2748    pub usage: wgt::TextureUses,
2749    /// Allows views of swapchain texture to have a different format
2750    /// than the texture does.
2751    pub view_formats: Vec<wgt::TextureFormat>,
2752    /// Whether an image the surface hands out again must hold every pixel it
2753    /// last presented, so a frame can draw only what changed (Cranpose
2754    /// fork): a Vulkan swapchain then draws the pixels other windows cover
2755    /// too, and a DXGI one keeps its buffers' contents.
2756    pub keep_presented: bool,
2757}
2758
2759#[derive(Debug, Clone)]
2760pub struct Rect<T> {
2761    pub x: T,
2762    pub y: T,
2763    pub w: T,
2764    pub h: T,
2765}
2766
2767#[derive(Debug, Clone, PartialEq)]
2768pub struct StateTransition<T> {
2769    pub from: T,
2770    pub to: T,
2771}
2772
2773#[derive(Debug, Clone)]
2774pub struct BufferBarrier<'a, B: DynBuffer + ?Sized> {
2775    pub buffer: &'a B,
2776    pub usage: StateTransition<wgt::BufferUses>,
2777}
2778
2779#[derive(Debug, Clone)]
2780pub struct TextureBarrier<'a, T: DynTexture + ?Sized> {
2781    pub texture: &'a T,
2782    pub range: wgt::ImageSubresourceRange,
2783    pub usage: StateTransition<wgt::TextureUses>,
2784}
2785
2786#[derive(Clone, Copy, Debug)]
2787pub struct BufferCopy {
2788    pub src_offset: wgt::BufferAddress,
2789    pub dst_offset: wgt::BufferAddress,
2790    pub size: wgt::BufferSize,
2791}
2792
2793#[derive(Clone, Debug)]
2794pub struct TextureCopyBase {
2795    pub mip_level: u32,
2796    pub array_layer: u32,
2797    /// Origin within a texture.
2798    /// Note: for 1D and 2D textures, Z must be 0.
2799    pub origin: wgt::Origin3d,
2800    pub aspect: FormatAspects,
2801}
2802
2803#[derive(Clone, Copy, Debug)]
2804pub struct CopyExtent {
2805    pub width: u32,
2806    pub height: u32,
2807    pub depth: u32,
2808}
2809
2810impl From<wgt::Extent3d> for CopyExtent {
2811    fn from(value: wgt::Extent3d) -> Self {
2812        let wgt::Extent3d {
2813            width,
2814            height,
2815            depth_or_array_layers,
2816        } = value;
2817        Self {
2818            width,
2819            height,
2820            depth: depth_or_array_layers,
2821        }
2822    }
2823}
2824
2825impl From<CopyExtent> for wgt::Extent3d {
2826    fn from(value: CopyExtent) -> Self {
2827        let CopyExtent {
2828            width,
2829            height,
2830            depth,
2831        } = value;
2832        Self {
2833            width,
2834            height,
2835            depth_or_array_layers: depth,
2836        }
2837    }
2838}
2839
2840#[derive(Clone, Debug)]
2841pub struct TextureCopy {
2842    pub src_base: TextureCopyBase,
2843    pub dst_base: TextureCopyBase,
2844    pub size: CopyExtent,
2845}
2846
2847#[derive(Clone, Debug)]
2848pub struct BufferTextureCopy {
2849    pub buffer_layout: wgt::TexelCopyBufferLayout,
2850    pub texture_base: TextureCopyBase,
2851    pub size: CopyExtent,
2852}
2853
2854#[derive(Clone, Debug)]
2855pub struct Attachment<'a, T: DynTextureView + ?Sized> {
2856    pub view: &'a T,
2857    /// Contains either a single mutating usage as a target,
2858    /// or a valid combination of read-only usages.
2859    pub usage: wgt::TextureUses,
2860}
2861
2862#[derive(Clone, Debug)]
2863pub struct ColorAttachment<'a, T: DynTextureView + ?Sized> {
2864    pub target: Attachment<'a, T>,
2865    pub depth_slice: Option<u32>,
2866    pub resolve_target: Option<Attachment<'a, T>>,
2867    pub ops: AttachmentOps,
2868    pub clear_value: wgt::Color,
2869}
2870
2871#[derive(Clone, Debug)]
2872pub struct DepthStencilAttachment<'a, T: DynTextureView + ?Sized> {
2873    pub target: Attachment<'a, T>,
2874    pub depth_ops: AttachmentOps,
2875    pub stencil_ops: AttachmentOps,
2876    pub clear_value: (f32, u32),
2877}
2878
2879#[derive(Clone, Debug)]
2880pub struct PassTimestampWrites<'a, Q: DynQuerySet + ?Sized> {
2881    pub query_set: &'a Q,
2882    pub beginning_of_pass_write_index: Option<u32>,
2883    pub end_of_pass_write_index: Option<u32>,
2884}
2885
2886#[derive(Clone, Debug)]
2887pub struct RenderPassDescriptor<'a, Q: DynQuerySet + ?Sized, T: DynTextureView + ?Sized> {
2888    pub label: Label<'a>,
2889    pub extent: wgt::Extent3d,
2890    pub sample_count: u32,
2891    pub color_attachments: &'a [Option<ColorAttachment<'a, T>>],
2892    pub depth_stencil_attachment: Option<DepthStencilAttachment<'a, T>>,
2893    pub multiview_mask: Option<NonZeroU32>,
2894    pub timestamp_writes: Option<PassTimestampWrites<'a, Q>>,
2895    pub occlusion_query_set: Option<&'a Q>,
2896}
2897
2898#[derive(Clone, Debug)]
2899pub struct ComputePassDescriptor<'a, Q: DynQuerySet + ?Sized> {
2900    pub label: Label<'a>,
2901    pub timestamp_writes: Option<PassTimestampWrites<'a, Q>>,
2902}
2903
2904#[derive(Clone, Debug)]
2905pub struct RayTracingPassDescriptor<'a> {
2906    pub label: Label<'a>,
2907}
2908
2909#[test]
2910fn test_default_limits() {
2911    let limits = wgt::Limits::default();
2912    assert!(limits.max_bind_groups <= MAX_BIND_GROUPS as u32);
2913}
2914
2915#[derive(Clone, Debug)]
2916pub struct AccelerationStructureDescriptor<'a> {
2917    pub label: Label<'a>,
2918    pub size: wgt::BufferAddress,
2919    pub format: AccelerationStructureFormat,
2920    pub allow_compaction: bool,
2921}
2922
2923#[derive(Debug, Clone, Copy, Eq, PartialEq)]
2924pub enum AccelerationStructureFormat {
2925    TopLevel,
2926    BottomLevel,
2927}
2928
2929#[derive(Debug, Clone, Copy, Eq, PartialEq)]
2930pub enum AccelerationStructureBuildMode {
2931    Build,
2932    Update,
2933}
2934
2935/// Information of the required size for a corresponding entries struct (+ flags)
2936#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
2937pub struct AccelerationStructureBuildSizes {
2938    pub acceleration_structure_size: wgt::BufferAddress,
2939    pub update_scratch_size: wgt::BufferAddress,
2940    pub build_scratch_size: wgt::BufferAddress,
2941}
2942
2943/// Updates use source_acceleration_structure if present, else the update will be performed in place.
2944/// For updates, only the data is allowed to change (not the meta data or sizes).
2945#[derive(Clone, Debug)]
2946pub struct BuildAccelerationStructureDescriptor<
2947    'a,
2948    B: DynBuffer + ?Sized,
2949    A: DynAccelerationStructure + ?Sized,
2950> {
2951    pub entries: &'a AccelerationStructureEntries<'a, B>,
2952    pub mode: AccelerationStructureBuildMode,
2953    pub flags: AccelerationStructureBuildFlags,
2954    pub source_acceleration_structure: Option<&'a A>,
2955    pub destination_acceleration_structure: &'a A,
2956    pub scratch_buffer: &'a B,
2957    pub scratch_buffer_offset: wgt::BufferAddress,
2958}
2959
2960/// - All buffers, buffer addresses and offsets will be ignored.
2961/// - The build mode will be ignored.
2962/// - Reducing the amount of Instances, Triangle groups or AABB groups (or the number of Triangles/AABBs in corresponding groups),
2963///   may result in reduced size requirements.
2964/// - Any other change may result in a bigger or smaller size requirement.
2965#[derive(Clone, Debug)]
2966pub struct GetAccelerationStructureBuildSizesDescriptor<'a, B: DynBuffer + ?Sized> {
2967    pub entries: &'a AccelerationStructureEntries<'a, B>,
2968    pub flags: AccelerationStructureBuildFlags,
2969}
2970
2971/// Entries for a single descriptor
2972/// * `Instances` - Multiple instances for a top level acceleration structure
2973/// * `Triangles` - Multiple triangle meshes for a bottom level acceleration structure
2974/// * `AABBs` - List of list of axis aligned bounding boxes for a bottom level acceleration structure
2975#[derive(Debug)]
2976pub enum AccelerationStructureEntries<'a, B: DynBuffer + ?Sized> {
2977    Instances(AccelerationStructureInstances<'a, B>),
2978    Triangles(Vec<AccelerationStructureTriangles<'a, B>>),
2979    AABBs(Vec<AccelerationStructureAABBs<'a, B>>),
2980}
2981
2982/// * `first_vertex` - offset in the vertex buffer (as number of vertices)
2983/// * `indices` - optional index buffer with attributes
2984/// * `transform` - optional transform
2985#[derive(Clone, Debug)]
2986pub struct AccelerationStructureTriangles<'a, B: DynBuffer + ?Sized> {
2987    pub vertex_buffer: Option<&'a B>,
2988    pub vertex_format: wgt::VertexFormat,
2989    pub first_vertex: u32,
2990    pub vertex_count: u32,
2991    pub vertex_stride: wgt::BufferAddress,
2992    pub indices: Option<AccelerationStructureTriangleIndices<'a, B>>,
2993    pub transform: Option<AccelerationStructureTriangleTransform<'a, B>>,
2994    pub flags: AccelerationStructureGeometryFlags,
2995}
2996
2997/// * `offset` - offset in bytes
2998#[derive(Clone, Debug)]
2999pub struct AccelerationStructureAABBs<'a, B: DynBuffer + ?Sized> {
3000    pub buffer: Option<&'a B>,
3001    pub offset: u32,
3002    pub count: u32,
3003    pub stride: wgt::BufferAddress,
3004    pub flags: AccelerationStructureGeometryFlags,
3005}
3006
3007#[derive(Clone, Debug)]
3008pub struct AccelerationStructureCopy {
3009    pub copy_flags: wgt::AccelerationStructureCopy,
3010    pub type_flags: wgt::AccelerationStructureType,
3011}
3012
3013/// * `offset` - offset in bytes
3014#[derive(Clone, Debug)]
3015pub struct AccelerationStructureInstances<'a, B: DynBuffer + ?Sized> {
3016    pub buffer: Option<&'a B>,
3017    pub offset: u32,
3018    pub count: u32,
3019}
3020
3021/// * `offset` - offset in bytes
3022#[derive(Clone, Debug)]
3023pub struct AccelerationStructureTriangleIndices<'a, B: DynBuffer + ?Sized> {
3024    pub format: wgt::IndexFormat,
3025    pub buffer: Option<&'a B>,
3026    pub offset: u32,
3027    pub count: u32,
3028}
3029
3030/// * `offset` - offset in bytes
3031#[derive(Clone, Debug)]
3032pub struct AccelerationStructureTriangleTransform<'a, B: DynBuffer + ?Sized> {
3033    pub buffer: &'a B,
3034    pub offset: u32,
3035}
3036
3037pub use wgt::AccelerationStructureFlags as AccelerationStructureBuildFlags;
3038pub use wgt::AccelerationStructureGeometryFlags;
3039
3040bitflags::bitflags! {
3041    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
3042    pub struct AccelerationStructureUses: u8 {
3043        // For blas used as input for tlas
3044        const BUILD_INPUT = 1 << 0;
3045        // Target for acceleration structure build
3046        const BUILD_OUTPUT = 1 << 1;
3047        // Tlas used in a shader
3048        const SHADER_INPUT = 1 << 2;
3049        // Blas used to query compacted size
3050        const QUERY_INPUT = 1 << 3;
3051        // BLAS used as a src for a copy operation
3052        const COPY_SRC = 1 << 4;
3053        // BLAS used as a dst for a copy operation
3054        const COPY_DST = 1 << 5;
3055    }
3056}
3057
3058#[derive(Debug, Clone)]
3059pub struct AccelerationStructureBarrier {
3060    pub usage: StateTransition<AccelerationStructureUses>,
3061}
3062
3063#[derive(Debug, Copy, Clone)]
3064pub struct TlasInstance {
3065    pub transform: [f32; 12],
3066    pub custom_data: u32,
3067    pub mask: u8,
3068    pub blas_address: u64,
3069    /// The offset for the index into the intersection hit
3070    /// group calculation. Number is in hit groups.
3071    pub pipeline_intersection_data_offset: u32,
3072}
3073
3074#[cfg(dx12)]
3075#[derive(Debug)]
3076pub enum D3D12ExposeAdapterResult {
3077    CreateDeviceError(dx12::CreateDeviceError),
3078    UnknownFeatureLevel(i32),
3079    ResourceBindingTier2Requirement,
3080    ShaderModel6Requirement,
3081    Success(dx12::FeatureLevel, dx12::ShaderModel),
3082}
3083
3084/// Pluggable telemetry, mainly to be used by Firefox.
3085#[derive(Debug, Clone, Copy)]
3086pub struct Telemetry {
3087    #[cfg(dx12)]
3088    pub d3d12_expose_adapter: fn(
3089        desc: &windows::Win32::Graphics::Dxgi::DXGI_ADAPTER_DESC2,
3090        driver_version: Result<[u16; 4], windows_core::HRESULT>,
3091        result: D3D12ExposeAdapterResult,
3092    ),
3093}
3094
3095#[derive(Debug)]
3096pub struct PipelineGroupData<'a, B: DynBuffer + ?Sized> {
3097    pub buffer: &'a B,
3098    pub offset: wgt::BufferAddress,
3099    pub stride: u64,
3100    pub count: u64,
3101}