//! Types for dealing with Instances. use crate::{link_to_wgpu_docs, Backends}; #[cfg(doc)] use crate::{Backend, DownlevelFlags}; /// A [`raw_window_handle::HasDisplayHandle`] that can be shared across threads and has no borrows. /// /// This blanket trait is automatically implemented for all objects that qualify. pub trait WgpuHasDisplayHandle: raw_window_handle::HasDisplayHandle + core::fmt::Debug + Send + Sync + 'static { } impl WgpuHasDisplayHandle for T { } /// Options for creating an instance. /// /// If you want to allow control of instance settings via environment variables, call any of the /// `*from_env()` functions or [`InstanceDescriptor::with_env()`]. Each type within this descriptor /// has its own equivalent methods, so you can select which options you want to expose to influence /// from the environment. #[derive(Debug)] pub struct InstanceDescriptor { /// Which [`Backends`] to enable. /// /// [`Backends::BROWSER_WEBGPU`] has an additional effect: /// If it is set and a [`navigator.gpu`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/gpu) /// object is present, this instance will *only* be able to create WebGPU adapters. /// /// ⚠️ On some browsers this check is insufficient to determine whether WebGPU is supported, /// as the browser may define the `navigator.gpu` object, but be unable to create any WebGPU adapters. /// For targeting _both_ WebGPU & WebGL, it is recommended to use [`crate::util::new_instance_with_webgpu_detection`](../wgpu/util/fn.new_instance_with_webgpu_detection.html). /// /// If you instead want to force use of WebGL, either disable the `webgpu` compile-time feature /// or don't include the [`Backends::BROWSER_WEBGPU`] flag in this field. /// If it is set and WebGPU support is *not* detected, the instance will use `wgpu-core` /// to create adapters, meaning that if the `webgl` feature is enabled, it is able to create /// a WebGL adapter. pub backends: Backends, /// Flags to tune the behavior of the instance. pub flags: InstanceFlags, /// Memory budget thresholds used by some backends. pub memory_budget_thresholds: MemoryBudgetThresholds, /// Options for configuring the behavior of specific backends. pub backend_options: crate::BackendOptions, /// System platform or compositor connection to connect this `Instance` to. /// /// If not [`None`], it is invalid to pass a different [`raw_window_handle::HasDisplayHandle`] to `create_surface()`. /// /// - On GLES, this is required when intending to present on the platform, especially for Wayland. /// - On Vulkan, Metal and Dx12, this is currently unused. /// /// When used with `winit`, callers are expected to pass its [`OwnedDisplayHandle`] (created from /// the `EventLoop`) here. /// /// [`OwnedDisplayHandle`]: https://docs.rs/winit/latest/winit/event_loop/struct.OwnedDisplayHandle.html pub display: Option>, } impl InstanceDescriptor { /// The default instance options, without display handle. #[must_use] pub fn new_without_display_handle() -> Self { Self { backends: Default::default(), flags: Default::default(), memory_budget_thresholds: Default::default(), backend_options: Default::default(), display: None, } } /// The default instance options, with display handle. #[must_use] pub fn new_with_display_handle(display: alloc::boxed::Box) -> Self { Self::new_without_display_handle().with_display_handle(display) } /// Choose instance options entirely from environment variables. /// /// This is equivalent to calling `from_env` on every field. #[must_use] pub fn new_without_display_handle_from_env() -> Self { Self::new_without_display_handle().with_env() } /// Choose instance options entirely from environment variables, while including a display handle. /// /// This is equivalent to calling `from_env` on every field. #[must_use] pub fn new_with_display_handle_from_env( display: alloc::boxed::Box, ) -> Self { // Self::new_without_display_handle_from_env().with_display_handle(display) Self::new_with_display_handle(display).with_env() } /// Takes the given options, modifies them based on the environment variables, and returns the result. /// /// This is equivalent to calling `with_env` on every field. #[must_use] pub fn with_env(self) -> Self { let backends = self.backends.with_env(); let flags = self.flags.with_env(); let backend_options = self.backend_options.with_env(); Self { backends, flags, memory_budget_thresholds: MemoryBudgetThresholds::default(), backend_options, display: self.display, } } /// Appends the given `display` object to the descriptor. #[must_use] pub fn with_display_handle(self, display: alloc::boxed::Box) -> Self { Self { display: Some(display), ..self } } } bitflags::bitflags! { /// Instance debugging flags. /// /// These are not part of the WebGPU standard. /// /// Defaults to enabling debugging-related flags if the build configuration has `debug_assertions`. #[repr(transparent)] #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] pub struct InstanceFlags: u32 { /// Generate debug information in shaders and objects. /// /// When `Self::from_env()` is used takes value from `WGPU_DEBUG` environment variable. const DEBUG = 1 << 0; /// Enable validation in the backend API, if possible: /// /// - On the Direct3D `dx12` backend, this calls [`ID3D12Debug::EnableDebugLayer`][dx12]. /// /// - On the Vulkan backend, this enables the [Vulkan Validation Layer][vvl]. /// /// - On the `gles` backend driving Windows OpenGL, this enables [debug /// output][gl:do], effectively calling `glEnable(GL_DEBUG_OUTPUT)`. /// /// - On non-Windows `gles` backends, this calls /// [`eglDebugMessageControlKHR`][gl:dm] to enable all debugging messages. /// If the GLES implementation is ANGLE running on Vulkan, this also /// enables the Vulkan validation layers by setting /// [`EGL_PLATFORM_ANGLE_DEBUG_LAYERS_ENABLED`][gl:av]. /// /// When `Self::from_env()` is used, this bit is set if the `WGPU_VALIDATION` /// environment variable has any value but "0". /// /// [dx12]: https://learn.microsoft.com/en-us/windows/win32/api/d3d12sdklayers/nf-d3d12sdklayers-id3d12debug-enabledebuglayer /// [vvl]: https://github.com/KhronosGroup/Vulkan-ValidationLayers /// [gl:dm]: https://registry.khronos.org/EGL/extensions/KHR/EGL_KHR_debug.txt /// [gl:do]: https://www.khronos.org/opengl/wiki/Debug_Output /// [gl:av]: https://chromium.googlesource.com/angle/angle/+/HEAD/extensions/EGL_ANGLE_platform_angle.txt const VALIDATION = 1 << 1; /// Don't pass labels to wgpu-hal. /// /// When `Self::from_env()` is used takes value from `WGPU_DISCARD_HAL_LABELS` environment variable. const DISCARD_HAL_LABELS = 1 << 2; /// Whether wgpu should expose adapters that run on top of non-compliant adapters. /// /// Turning this on might mean that some of the functionality provided by the wgpu /// adapter/device is not working or is broken. It could be that all the functionality /// wgpu currently exposes works but we can't tell for sure since we have no additional /// transparency into what is working and what is not on the underlying adapter. /// /// This mainly applies to a Vulkan driver's compliance version. If the major compliance version /// is `0`, then the driver is ignored. This flag allows that driver to be enabled for testing. /// /// This flag controls whether adapters that don't meet the *native* /// API's own compliance requirements are returned, while /// [`Self::STRICT_WEBGPU_COMPLIANCE`] controls whether adapters that /// can't fully satisfy the *WebGPU v1* spec are excluded. /// /// When `Self::from_env()` is used takes value from `WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER` environment variable. const ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER = 1 << 3; /// Enable GPU-based validation. Implies [`Self::VALIDATION`]. Currently, this only changes /// behavior on the DX12 and Vulkan backends. /// /// Supported platforms: /// /// - D3D12; called ["GPU-based validation", or /// "GBV"](https://web.archive.org/web/20230206120404/https://learn.microsoft.com/en-us/windows/win32/direct3d12/using-d3d12-debug-layer-gpu-based-validation) /// - Vulkan, via the `VK_LAYER_KHRONOS_validation` layer; called ["GPU-Assisted /// Validation"](https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/e45aeb85079e0835694cb8f03e6681fd18ae72c9/docs/gpu_validation.md#gpu-assisted-validation) /// /// When `Self::from_env()` is used takes value from `WGPU_GPU_BASED_VALIDATION` environment variable. const GPU_BASED_VALIDATION = 1 << 4; /// Validate indirect buffer content prior to issuing indirect draws/dispatches. /// /// This validation will transform indirect calls into no-ops if they are not valid: /// /// - When calling `dispatch_workgroups_indirect`, all 3 indirect arguments encoded in the buffer /// must be less than the `max_compute_workgroups_per_dimension` device limit. /// - When calling `draw_indirect`/`draw_indexed_indirect`/`multi_draw_indirect`/`multi_draw_indexed_indirect`: /// - If `Features::INDIRECT_FIRST_INSTANCE` is not enabled on the device, the `first_instance` indirect argument must be 0. /// - The `first_instance` & `instance_count` indirect arguments must form a range that fits within all bound vertex buffers with `step_mode` set to `Instance`. /// - When calling `draw_indirect`/`multi_draw_indirect`: /// - The `first_vertex` & `vertex_count` indirect arguments must form a range that fits within all bound vertex buffers with `step_mode` set to `Vertex`. /// - When calling `draw_indexed_indirect`/`multi_draw_indexed_indirect`: /// - The `first_index` & `index_count` indirect arguments must form a range that fits within the bound index buffer. /// /// __Behavior is undefined if this validation is disabled and the rules above are not satisfied.__ /// /// Disabling this will also cause the following built-ins to not report the right values on the D3D12 backend: /// /// - the 3 components of `@builtin(num_workgroups)` will be 0 /// - the value of `@builtin(vertex_index)` will not take into account the value of the `first_vertex`/`base_vertex` argument present in the indirect buffer /// - the value of `@builtin(instance_index)` will not take into account the value of the `first_instance` argument present in the indirect buffer /// /// When `Self::from_env()` is used takes value from `WGPU_VALIDATION_INDIRECT_CALL` environment variable. const VALIDATION_INDIRECT_CALL = 1 << 5; /// Enable automatic timestamp normalization. This means that in [`CommandEncoder::resolve_query_set`][rqs], /// the timestamps will automatically be normalized to be in nanoseconds instead of the raw timestamp values. /// /// This is disabled by default because it introduces a compute shader into the resolution of query sets. /// /// This can be useful for users that need to read timestamps on the gpu, as the normalization /// can be a hassle to do manually. When this is enabled, the timestamp period returned by the queue /// will always be `1.0`. /// #[doc = link_to_wgpu_docs!(["rqs"]: "struct.CommandEncoder.html#method.resolve_query_set")] const AUTOMATIC_TIMESTAMP_NORMALIZATION = 1 << 6; /// Restrict the available feature set to the one defined by the WebGPU specification. /// /// When `Self::from_env()` is used takes value from `WGPU_STRICT_WEBGPU_COMPLIANCE` environment variable. const STRICT_WEBGPU_COMPLIANCE = 1 << 7; } } impl Default for InstanceFlags { fn default() -> Self { Self::from_build_config() } } impl InstanceFlags { /// Enable recommended debugging and validation flags. #[must_use] pub fn debugging() -> Self { InstanceFlags::DEBUG | InstanceFlags::VALIDATION | InstanceFlags::VALIDATION_INDIRECT_CALL } /// Enable advanced debugging and validation flags (potentially very slow). #[must_use] pub fn advanced_debugging() -> Self { Self::debugging() | InstanceFlags::GPU_BASED_VALIDATION } /// Infer decent defaults from the build type. /// /// If `cfg!(debug_assertions)` is true, then this returns [`Self::debugging()`]. /// Otherwise, it returns [`Self::empty()`]. #[must_use] pub fn from_build_config() -> Self { if cfg!(debug_assertions) { return InstanceFlags::debugging(); } InstanceFlags::VALIDATION_INDIRECT_CALL } /// Derive defaults from environment variables. See [`Self::with_env()`] for more information. #[must_use] pub fn from_env_or_default() -> Self { Self::default().with_env() } /// Takes the given flags, modifies them based on the environment variables, and returns the result. /// /// - If an environment variable is set to anything but "0", the corresponding flag is set. /// - If the value is "0", the flag is unset. /// - If the environment variable is not present, then the flag retains its initial value. /// /// For example `let flags = InstanceFlags::debugging().with_env();` with `WGPU_VALIDATION=0` /// does not contain [`InstanceFlags::VALIDATION`]. /// /// The environment variables are named after the flags prefixed with "WGPU_". For example: /// - `WGPU_DEBUG` /// - `WGPU_VALIDATION` /// - `WGPU_DISCARD_HAL_LABELS` /// - `WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER` /// - `WGPU_GPU_BASED_VALIDATION` /// - `WGPU_VALIDATION_INDIRECT_CALL` /// - `WGPU_STRICT_WEBGPU_COMPLIANCE` #[must_use] pub fn with_env(mut self) -> Self { fn env(key: &str) -> Option { crate::env::var(key).map(|s| match s.as_str() { "0" => false, _ => true, }) } if let Some(bit) = env("WGPU_VALIDATION") { self.set(Self::VALIDATION, bit); } if let Some(bit) = env("WGPU_DEBUG") { self.set(Self::DEBUG, bit); } if let Some(bit) = env("WGPU_DISCARD_HAL_LABELS") { self.set(Self::DISCARD_HAL_LABELS, bit); } if let Some(bit) = env("WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER") { self.set(Self::ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER, bit); } if let Some(bit) = env("WGPU_GPU_BASED_VALIDATION") { self.set(Self::GPU_BASED_VALIDATION, bit); } if let Some(bit) = env("WGPU_VALIDATION_INDIRECT_CALL") { self.set(Self::VALIDATION_INDIRECT_CALL, bit); } if let Some(bit) = env("WGPU_STRICT_WEBGPU_COMPLIANCE") { self.set(Self::STRICT_WEBGPU_COMPLIANCE, bit); } self } } /// Memory budget thresholds used by backends to try to avoid high memory pressure situations. /// /// Currently only the D3D12 and (optionally) Vulkan backends support these options. #[derive(Default, Clone, Debug, Copy)] pub struct MemoryBudgetThresholds { /// Threshold at which texture, buffer, query set and acceleration structure creation will start to return OOM errors. /// This is a percent of the memory budget reported by native APIs. /// /// If not specified, resource creation might still return OOM errors. pub for_resource_creation: Option, /// Threshold at which devices will become lost due to memory pressure. /// This is a percent of the memory budget reported by native APIs. /// /// If not specified, devices might still become lost due to memory pressure. pub for_device_loss: Option, }