/* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ // The intra doc links to the wgpu crate in this crate actually succesfully link to the types in the wgpu crate, when built from the wgpu crate. // However when building from both the wgpu crate or this crate cargo doc will claim all the links cannot be resolved // despite the fact that it works fine when it needs to. // So we just disable those warnings. #![allow(broken_intra_doc_links)] #[cfg(feature = "serde")] use serde::{Deserialize, Serialize}; use std::{num::NonZeroU32, ops::Range}; /// Integral type used for buffer offsets. pub type BufferAddress = u64; /// Integral type used for buffer slice sizes. pub type BufferSize = std::num::NonZeroU64; /// Integral type used for binding locations in shaders. pub type ShaderLocation = u32; /// Integral type used for dynamic bind group offsets. pub type DynamicOffset = u32; /// Buffer-Texture copies must have [`bytes_per_row`] aligned to this number. /// /// This doesn't apply to [`Queue::write_texture`]. /// /// [`bytes_per_row`]: TextureDataLayout::bytes_per_row pub const COPY_BYTES_PER_ROW_ALIGNMENT: u32 = 256; /// Bound uniform/storage buffer offsets must be aligned to this number. pub const BIND_BUFFER_ALIGNMENT: BufferAddress = 256; /// Buffer to buffer copy offsets and sizes must be aligned to this number. pub const COPY_BUFFER_ALIGNMENT: BufferAddress = 4; /// Vertex buffer strides have to be aligned to this number. pub const VERTEX_STRIDE_ALIGNMENT: BufferAddress = 4; /// Alignment all push constants need pub const PUSH_CONSTANT_ALIGNMENT: u32 = 4; /// Backends supported by wgpu. #[repr(u8)] #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum Backend { Empty = 0, Vulkan = 1, Metal = 2, Dx12 = 3, Dx11 = 4, Gl = 5, BrowserWebGpu = 6, } /// Power Preference when choosing a physical adapter. #[repr(C)] #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum PowerPreference { /// Adapter that uses the least possible power. This is often an integerated GPU. LowPower = 0, /// Adapter that has the highest performance. This is often a discrete GPU. HighPerformance = 1, } impl Default for PowerPreference { fn default() -> Self { Self::LowPower } } bitflags::bitflags! { /// Represents the backends that wgpu will use. #[repr(transparent)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct BackendBit: u32 { /// Supported on Windows, Linux/Android, and macOS/iOS via Vulkan Portability (with the Vulkan feature enabled) const VULKAN = 1 << Backend::Vulkan as u32; /// Currently unsupported const GL = 1 << Backend::Gl as u32; /// Supported on macOS/iOS const METAL = 1 << Backend::Metal as u32; /// Supported on Windows 10 const DX12 = 1 << Backend::Dx12 as u32; /// Supported on Windows 7+ const DX11 = 1 << Backend::Dx11 as u32; /// Supported when targeting the web through webassembly const BROWSER_WEBGPU = 1 << Backend::BrowserWebGpu as u32; /// All the apis that wgpu offers first tier of support for. /// /// Vulkan + Metal + DX12 + Browser WebGPU const PRIMARY = Self::VULKAN.bits | Self::METAL.bits | Self::DX12.bits | Self::BROWSER_WEBGPU.bits; /// All the apis that wgpu offers second tier of support for. These may /// be unsupported/still experimental. /// /// OpenGL + DX11 const SECONDARY = Self::GL.bits | Self::DX11.bits; } } impl From for BackendBit { fn from(backend: Backend) -> Self { Self::from_bits(1 << backend as u32).unwrap() } } /// Options for requesting adapter. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct RequestAdapterOptions { /// Power preference for the adapter. pub power_preference: PowerPreference, /// Surface that is required to be presentable with the requested adapter. This does not /// create the surface, only guarantees that the adapter can present to said surface. pub compatible_surface: Option, } impl Default for RequestAdapterOptions { fn default() -> Self { Self { power_preference: PowerPreference::default(), compatible_surface: None, } } } bitflags::bitflags! { /// Features that are not guaranteed to be supported. /// /// These are either part of the webgpu standard, or are extension features supported by /// wgpu when targeting native. /// /// If you want to use a feature, you need to first verify that the adapter supports /// the feature. If the adapter does not support the feature, requesting a device with it enabled /// will panic. #[repr(transparent)] #[derive(Default)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct Features: u64 { /// By default, polygon depth is clipped to 0-1 range. Anything outside of that range /// is rejected, and respective fragments are not touched. /// /// With this extension, we can force clamping of the polygon depth to 0-1. That allows /// shadow map occluders to be rendered into a tighter depth range. /// /// Supported platforms: /// - desktops /// - some mobile chips /// /// This is a web and native feature. const DEPTH_CLAMPING = 0x0000_0000_0000_0001; /// Enables BCn family of compressed textures. All BCn textures use 4x4 pixel blocks /// with 8 or 16 bytes per block. /// /// Compressed textures sacrifice some quality in exchange for signifigantly reduced /// bandwidth usage. /// /// Supported Platforms: /// - desktops /// /// This is a web and native feature. const TEXTURE_COMPRESSION_BC = 0x0000_0000_0000_0002; /// Webgpu only allows the MAP_READ and MAP_WRITE buffer usage to be matched with /// COPY_DST and COPY_SRC respectively. This removes this requirement. /// /// This is only beneficial on systems that share memory between CPU and GPU. If enabled /// on a system that doesn't, this can severely hinder performance. Only use if you understand /// the consequences. /// /// Supported platforms: /// - All /// /// This is a native only feature. const MAPPABLE_PRIMARY_BUFFERS = 0x0000_0000_0001_0000; /// Allows the user to create uniform arrays of sampled textures in shaders: /// /// eg. `uniform texture2D textures[10]`. /// /// This capability allows them to exist and to be indexed by compile time constant /// values. /// /// Supported platforms: /// - DX12 /// - Metal (with MSL 2.0+ on macOS 10.13+) /// - Vulkan /// /// This is a native only feature. const SAMPLED_TEXTURE_BINDING_ARRAY = 0x0000_0000_0002_0000; /// Allows shaders to index sampled texture arrays with dynamically uniform values: /// /// eg. `texture_array[uniform_value]` /// /// This capability means the hardware will also support SAMPLED_TEXTURE_BINDING_ARRAY. /// /// Supported platforms: /// - DX12 /// - Metal (with MSL 2.0+ on macOS 10.13+) /// - Vulkan's shaderSampledImageArrayDynamicIndexing feature /// /// This is a native only feature. const SAMPLED_TEXTURE_ARRAY_DYNAMIC_INDEXING = 0x0000_0000_0004_0000; /// Allows shaders to index sampled texture arrays with dynamically non-uniform values: /// /// eg. `texture_array[vertex_data]` /// /// In order to use this capability, the corresponding GLSL extension must be enabled like so: /// /// `#extension GL_EXT_nonuniform_qualifier : require` /// /// and then used either as `nonuniformEXT` qualifier in variable declaration: /// /// eg. `layout(location = 0) nonuniformEXT flat in int vertex_data;` /// /// or as `nonuniformEXT` constructor: /// /// eg. `texture_array[nonuniformEXT(vertex_data)]` /// /// HLSL does not need any extension. /// /// This capability means the hardware will also support SAMPLED_TEXTURE_ARRAY_DYNAMIC_INDEXING /// and SAMPLED_TEXTURE_BINDING_ARRAY. /// /// Supported platforms: /// - DX12 /// - Metal (with MSL 2.0+ on macOS 10.13+) /// - Vulkan 1.2+ (or VK_EXT_descriptor_indexing)'s shaderSampledImageArrayNonUniformIndexing feature) /// /// This is a native only feature. const SAMPLED_TEXTURE_ARRAY_NON_UNIFORM_INDEXING = 0x0000_0000_0008_0000; /// Allows the user to create unsized uniform arrays of bindings: /// /// eg. `uniform texture2D textures[]`. /// /// If this capability is supported, SAMPLED_TEXTURE_ARRAY_NON_UNIFORM_INDEXING is very likely /// to also be supported /// /// Supported platforms: /// - DX12 /// - Vulkan 1.2+ (or VK_EXT_descriptor_indexing)'s runtimeDescriptorArray feature /// /// This is a native only feature. const UNSIZED_BINDING_ARRAY = 0x0000_0000_0010_0000; /// Allows the user to call [`RenderPass::multi_draw_indirect`] and [`RenderPass::multi_draw_indexed_indirect`]. /// /// Allows multiple indirect calls to be dispatched from a single buffer. /// /// Supported platforms: /// - DX12 /// - Metal /// - Vulkan /// /// This is a native only feature. const MULTI_DRAW_INDIRECT = 0x0000_0000_0020_0000; /// Allows the user to call [`RenderPass::multi_draw_indirect_count`] and [`RenderPass::multi_draw_indexed_indirect_count`]. /// /// This allows the use of a buffer containing the actual number of draw calls. /// /// Supported platforms: /// - DX12 /// - Vulkan 1.2+ (or VK_KHR_draw_indirect_count) /// /// This is a native only feature. const MULTI_DRAW_INDIRECT_COUNT = 0x0000_0000_0040_0000; /// Allows the use of push constants: small, fast bits of memory that can be updated /// inside a [`RenderPass`]. /// /// Allows the user to call [`RenderPass::set_push_constants`], provide a non-empty array /// to [`PipelineLayoutDescriptor`], and provide a non-zero limit to [`Limits::max_push_constant_size`]. /// /// A block of push constants can be declared with `layout(push_constant) uniform Name {..}` in shaders. /// /// Supported platforms: /// - DX12 /// - Vulkan /// - Metal /// - DX11 (emulated with uniforms) /// - OpenGL (emulated with uniforms) /// /// This is a native only feature. const PUSH_CONSTANTS = 0x0000_0000_0080_0000; /// Allows the use of [`AddressMode::ClampToBorder`]. /// /// Supported platforms: /// - DX12 /// - Vulkan /// - Metal (macOS 10.12+ only) /// - DX11 /// - OpenGL /// /// This is a web and native feature. const ADDRESS_MODE_CLAMP_TO_BORDER = 0x0000_0000_0100_0000; /// Allows the user to set a non-fill polygon mode in [`RasterizationStateDescriptor::polygon_mode`] /// /// This allows drawing polygons/triangles as lines (wireframe) or points instead of filled /// /// Supported platforms: /// - DX12 /// - Vulkan /// /// This is a native only feature. const NON_FILL_POLYGON_MODE = 0x0000_0000_0200_0000; /// Features which are part of the upstream WebGPU standard. const ALL_WEBGPU = 0x0000_0000_0000_FFFF; /// Features that are only available when targeting native (not web). const ALL_NATIVE = 0xFFFF_FFFF_FFFF_0000; } } /// Represents the sets of limits an adapter/device supports. /// /// Limits "better" than the default must be supported by the adapter and requested when requesting /// a device. If limits "better" than the adapter supports are requested, requesting a device will panic. /// Once a device is requested, you may only use resources up to the limits requested _even_ if the /// adapter supports "better" limits. /// /// Requesting limits that are "better" than you need may cause performance to decrease because the /// implementation needs to support more than is needed. You should ideally only request exactly what /// you need. /// /// See also: https://gpuweb.github.io/gpuweb/#dictdef-gpulimits #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct Limits { /// Amount of bind groups that can be attached to a pipeline at the same time. Defaults to 4. Higher is "better". pub max_bind_groups: u32, /// Amount of uniform buffer bindings that can be dynamic in a single pipeline. Defaults to 8. Higher is "better". pub max_dynamic_uniform_buffers_per_pipeline_layout: u32, /// Amount of storage buffer bindings that can be dynamic in a single pipeline. Defaults to 4. Higher is "better". pub max_dynamic_storage_buffers_per_pipeline_layout: u32, /// Amount of sampled textures visible in a single shader stage. Defaults to 16. Higher is "better". pub max_sampled_textures_per_shader_stage: u32, /// Amount of samplers visible in a single shader stage. Defaults to 16. Higher is "better". pub max_samplers_per_shader_stage: u32, /// Amount of storage buffers visible in a single shader stage. Defaults to 4. Higher is "better". pub max_storage_buffers_per_shader_stage: u32, /// Amount of storage textures visible in a single shader stage. Defaults to 4. Higher is "better". pub max_storage_textures_per_shader_stage: u32, /// Amount of uniform buffers visible in a single shader stage. Defaults to 12. Higher is "better". pub max_uniform_buffers_per_shader_stage: u32, /// Maximum size in bytes of a binding to a uniform buffer. Defaults to 16384. Higher is "better". pub max_uniform_buffer_binding_size: u32, /// Amount of storage available for push constants in bytes. Defaults to 0. Higher is "better". /// Requesting more than 0 during device creation requires [`Features::PUSH_CONSTANTS`] to be enabled. /// /// Expect the size to be: /// - Vulkan: 128-256 bytes /// - DX12: 256 bytes /// - Metal: 4096 bytes /// - DX11 & OpenGL don't natively support push constants, and are emulated with uniforms, /// so this number is less useful. pub max_push_constant_size: u32, } impl Default for Limits { fn default() -> Self { Self { max_bind_groups: 4, max_dynamic_uniform_buffers_per_pipeline_layout: 8, max_dynamic_storage_buffers_per_pipeline_layout: 4, max_sampled_textures_per_shader_stage: 16, max_samplers_per_shader_stage: 16, max_storage_buffers_per_shader_stage: 4, max_storage_textures_per_shader_stage: 4, max_uniform_buffers_per_shader_stage: 12, max_uniform_buffer_binding_size: 16384, max_push_constant_size: 0, } } } /// Describes a [`Device`]. #[repr(C)] #[derive(Clone, Debug, Default)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct DeviceDescriptor { /// Debug label for the device. pub label: L, /// Features that the device should support. If any feature is not supported by /// the adapter, creating a device will panic. pub features: Features, /// Limits that the device should support. If any limit is "better" than the limit exposed by /// the adapter, creating a device will panic. pub limits: Limits, /// Switch shader validation on/off. This is a temporary field /// that will be removed once our validation logic is complete. pub shader_validation: bool, } impl DeviceDescriptor { pub fn map_label(&self, fun: impl FnOnce(&L) -> K) -> DeviceDescriptor { DeviceDescriptor { label: fun(&self.label), features: self.features, limits: self.limits.clone(), shader_validation: self.shader_validation, } } } bitflags::bitflags! { /// Describes the shader stages that a binding will be visible from. /// /// These can be combined so something that is visible from both vertex and fragment shaders can be defined as: /// /// `ShaderStage::VERTEX | ShaderStage::FRAGMENT` #[repr(transparent)] #[cfg_attr(feature = "serde", derive(Deserialize, Serialize))] pub struct ShaderStage: u32 { /// Binding is not visible from any shader stage. const NONE = 0; /// Binding is visible from the vertex shader of a render pipeline. const VERTEX = 1; /// Binding is visible from the fragment shader of a render pipeline. const FRAGMENT = 2; /// Binding is visible from the compute shader of a compute pipeline. const COMPUTE = 4; } } /// Dimensions of a particular texture view. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum TextureViewDimension { /// A one dimensional texture. `texture1D` in glsl shaders. D1, /// A two dimensional texture. `texture2D` in glsl shaders. D2, /// A two dimensional array texture. `texture2DArray` in glsl shaders. D2Array, /// A cubemap texture. `textureCube` in glsl shaders. Cube, /// A cubemap array texture. `textureCubeArray` in glsl shaders. CubeArray, /// A three dimensional texture. `texture3D` in glsl shaders. D3, } impl TextureViewDimension { /// Get the texture dimension required fo this texture view dimension. pub fn compatible_texture_dimension(self) -> TextureDimension { match self { Self::D1 => TextureDimension::D1, Self::D2 | Self::D2Array | Self::Cube | Self::CubeArray => TextureDimension::D2, Self::D3 => TextureDimension::D3, } } } /// Alpha blend factor. /// /// Alpha blending is very complicated: see the OpenGL or Vulkan spec for more information. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum BlendFactor { Zero = 0, One = 1, SrcColor = 2, OneMinusSrcColor = 3, SrcAlpha = 4, OneMinusSrcAlpha = 5, DstColor = 6, OneMinusDstColor = 7, DstAlpha = 8, OneMinusDstAlpha = 9, SrcAlphaSaturated = 10, BlendColor = 11, OneMinusBlendColor = 12, } /// Alpha blend operation. /// /// Alpha blending is very complicated: see the OpenGL or Vulkan spec for more information. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum BlendOperation { Add = 0, Subtract = 1, ReverseSubtract = 2, Min = 3, Max = 4, } impl Default for BlendOperation { fn default() -> Self { Self::Add } } /// Describes the blend state of a pipeline. /// /// Alpha blending is very complicated: see the OpenGL or Vulkan spec for more information. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct BlendDescriptor { pub src_factor: BlendFactor, pub dst_factor: BlendFactor, pub operation: BlendOperation, } impl BlendDescriptor { pub const REPLACE: Self = BlendDescriptor { src_factor: BlendFactor::One, dst_factor: BlendFactor::Zero, operation: BlendOperation::Add, }; pub fn uses_color(&self) -> bool { match (self.src_factor, self.dst_factor) { (BlendFactor::BlendColor, _) | (BlendFactor::OneMinusBlendColor, _) | (_, BlendFactor::BlendColor) | (_, BlendFactor::OneMinusBlendColor) => true, (_, _) => false, } } } impl Default for BlendDescriptor { fn default() -> Self { Self::REPLACE } } /// Describes the color state of a render pipeline. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct ColorStateDescriptor { /// The [`TextureFormat`] of the image that this pipeline will render to. Must match the the format /// of the corresponding color attachment in [`CommandEncoder::begin_render_pass`]. pub format: TextureFormat, /// The alpha blending that is used for this pipeline. pub alpha_blend: BlendDescriptor, /// The color blending that is used for this pipeline. pub color_blend: BlendDescriptor, /// Mask which enables/disables writes to different color/alpha channel. pub write_mask: ColorWrite, } impl From for ColorStateDescriptor { fn from(format: TextureFormat) -> Self { Self { format, alpha_blend: BlendDescriptor::REPLACE, color_blend: BlendDescriptor::REPLACE, write_mask: ColorWrite::ALL, } } } /// Primitive type the input mesh is composed of. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum PrimitiveTopology { /// Vertex data is a list of points. Each vertex is a new point. PointList = 0, /// Vertex data is a list of lines. Each pair of vertices composes a new line. /// /// Vertices `0 1 2 3` create two lines `0 1` and `2 3` LineList = 1, /// Vertex data is a strip of lines. Each set of two adjacent vertices form a line. /// /// Vertices `0 1 2 3` create three lines `0 1`, `1 2`, and `2 3`. LineStrip = 2, /// Vertex data is a list of triangles. Each set of 3 vertices composes a new triangle. /// /// Vertices `0 1 2 3 4 5` create two triangles `0 1 2` and `3 4 5` TriangleList = 3, /// Vertex data is a triangle strip. Each set of three adjacent vertices form a triangle. /// /// Vertices `0 1 2 3 4 5` creates four triangles `0 1 2`, `2 1 3`, `3 2 4`, and `4 3 5` TriangleStrip = 4, } /// Winding order which classifies the "front" face. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum FrontFace { /// Triangles with vertices in counter clockwise order are considered the front face. /// /// This is the default with right handed coordinate spaces. Ccw = 0, /// Triangles with vertices in clockwise order are considered the front face. /// /// This is the default with left handed coordinate spaces. Cw = 1, } impl Default for FrontFace { fn default() -> Self { Self::Ccw } } /// Type of faces to be culled. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum CullMode { /// No faces should be culled None = 0, /// Front faces should be culled Front = 1, /// Back faces should be culled Back = 2, } impl Default for CullMode { fn default() -> Self { Self::None } } /// Type of drawing mode for polygons #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum PolygonMode { /// Polygons are filled Fill = 0, /// Polygons are draw as line segments Line = 1, /// Polygons are draw as points Point = 2, } impl Default for PolygonMode { fn default() -> Self { Self::Fill } } /// Describes the state of the rasterizer in a render pipeline. #[repr(C)] #[derive(Clone, Debug, Default, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct RasterizationStateDescriptor { pub front_face: FrontFace, pub cull_mode: CullMode, /// Controls the way each polygon is rasterized. Can be either `Fill` (default), `Line` or `Point` /// /// Setting this to something other than `Fill` requires `Features::NON_FILL_POLYGON_MODE` to be enabled. pub polygon_mode: PolygonMode, /// If enabled polygon depth is clamped to 0-1 range instead of being clipped. /// /// Requires `Features::DEPTH_CLAMPING` enabled. pub clamp_depth: bool, pub depth_bias: i32, pub depth_bias_slope_scale: f32, pub depth_bias_clamp: f32, } /// Underlying texture data format. /// /// If there is a conversion in the format (such as srgb -> linear), The conversion listed is for /// loading from texture in a shader. When writing to the texture, the opposite conversion takes place. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "serde", derive(Deserialize, Serialize))] pub enum TextureFormat { // Normal 8 bit formats /// Red channel only. 8 bit integer per channel. [0, 255] converted to/from float [0, 1] in shader. R8Unorm = 0, /// Red channel only. 8 bit integer per channel. [-127, 127] converted to/from float [-1, 1] in shader. R8Snorm = 1, /// Red channel only. 8 bit integer per channel. Unsigned in shader. R8Uint = 2, /// Red channel only. 8 bit integer per channel. Signed in shader. R8Sint = 3, // Normal 16 bit formats /// Red channel only. 16 bit integer per channel. Unsigned in shader. R16Uint = 4, /// Red channel only. 16 bit integer per channel. Signed in shader. R16Sint = 5, /// Red channel only. 16 bit float per channel. Float in shader. R16Float = 6, /// Red and green channels. 8 bit integer per channel. [0, 255] converted to/from float [0, 1] in shader. Rg8Unorm = 7, /// Red and green channels. 8 bit integer per channel. [-127, 127] converted to/from float [-1, 1] in shader. Rg8Snorm = 8, /// Red and green channels. 8 bit integer per channel. Unsigned in shader. Rg8Uint = 9, /// Red and green channel s. 8 bit integer per channel. Signed in shader. Rg8Sint = 10, // Normal 32 bit formats /// Red channel only. 32 bit integer per channel. Unsigned in shader. R32Uint = 11, /// Red channel only. 32 bit integer per channel. Signed in shader. R32Sint = 12, /// Red channel only. 32 bit float per channel. Float in shader. R32Float = 13, /// Red and green channels. 16 bit integer per channel. Unsigned in shader. Rg16Uint = 14, /// Red and green channels. 16 bit integer per channel. Signed in shader. Rg16Sint = 15, /// Red and green channels. 16 bit float per channel. Float in shader. Rg16Float = 16, /// Red, green, blue, and alpha channels. 8 bit integer per channel. [0, 255] converted to/from float [0, 1] in shader. Rgba8Unorm = 17, /// Red, green, blue, and alpha channels. 8 bit integer per channel. Srgb-color [0, 255] converted to/from linear-color float [0, 1] in shader. Rgba8UnormSrgb = 18, /// Red, green, blue, and alpha channels. 8 bit integer per channel. [-127, 127] converted to/from float [-1, 1] in shader. Rgba8Snorm = 19, /// Red, green, blue, and alpha channels. 8 bit integer per channel. Unsigned in shader. Rgba8Uint = 20, /// Red, green, blue, and alpha channels. 8 bit integer per channel. Signed in shader. Rgba8Sint = 21, /// Blue, green, red, and alpha channels. 8 bit integer per channel. [0, 255] converted to/from float [0, 1] in shader. Bgra8Unorm = 22, /// Blue, green, red, and alpha channels. 8 bit integer per channel. Srgb-color [0, 255] converted to/from linear-color float [0, 1] in shader. Bgra8UnormSrgb = 23, // Packed 32 bit formats /// Red, green, blue, and alpha channels. 10 bit integer for RGB channels, 2 bit integer for alpha channel. [0, 1023] ([0, 3] for alpha) converted to/from float [0, 1] in shader. Rgb10a2Unorm = 24, /// Red, green, and blue channels. 11 bit float with no sign bit for RG channels. 10 bit float with no sign bit for blue channel. Float in shader. Rg11b10Float = 25, // Normal 64 bit formats /// Red and green channels. 32 bit integer per channel. Unsigned in shader. Rg32Uint = 26, /// Red and green channels. 32 bit integer per channel. Signed in shader. Rg32Sint = 27, /// Red and green channels. 32 bit float per channel. Float in shader. Rg32Float = 28, /// Red, green, blue, and alpha channels. 16 bit integer per channel. Unsigned in shader. Rgba16Uint = 29, /// Red, green, blue, and alpha channels. 16 bit integer per channel. Signed in shader. Rgba16Sint = 30, /// Red, green, blue, and alpha channels. 16 bit float per channel. Float in shader. Rgba16Float = 31, // Normal 128 bit formats /// Red, green, blue, and alpha channels. 32 bit integer per channel. Unsigned in shader. Rgba32Uint = 32, /// Red, green, blue, and alpha channels. 32 bit integer per channel. Signed in shader. Rgba32Sint = 33, /// Red, green, blue, and alpha channels. 32 bit float per channel. Float in shader. Rgba32Float = 34, // Depth and stencil formats /// Special depth format with 32 bit floating point depth. Depth32Float = 35, /// Special depth format with at least 24 bit integer depth. Depth24Plus = 36, /// Special depth/stencil format with at least 24 bit integer depth and 8 bits integer stencil. Depth24PlusStencil8 = 37, // Compressed textures usable with `TEXTURE_COMPRESSION_BC` feature. /// 4x4 block compressed texture. 8 bytes per block (4 bit/px). 4 color + alpha pallet. 5 bit R + 6 bit G + 5 bit B + 1 bit alpha. /// [0, 64] ([0, 1] for alpha) converted to/from float [0, 1] in shader. /// /// Also known as DXT1. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc1RgbaUnorm = 38, /// 4x4 block compressed texture. 8 bytes per block (4 bit/px). 4 color + alpha pallet. 5 bit R + 6 bit G + 5 bit B + 1 bit alpha. /// Srgb-color [0, 64] ([0, 16] for alpha) converted to/from linear-color float [0, 1] in shader. /// /// Also known as DXT1. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc1RgbaUnormSrgb = 39, /// 4x4 block compressed texture. 16 bytes per block (8 bit/px). 4 color pallet. 5 bit R + 6 bit G + 5 bit B + 4 bit alpha. /// [0, 64] ([0, 16] for alpha) converted to/from float [0, 1] in shader. /// /// Also known as DXT3. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc2RgbaUnorm = 40, /// 4x4 block compressed texture. 16 bytes per block (8 bit/px). 4 color pallet. 5 bit R + 6 bit G + 5 bit B + 4 bit alpha. /// Srgb-color [0, 64] ([0, 256] for alpha) converted to/from linear-color float [0, 1] in shader. /// /// Also known as DXT3. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc2RgbaUnormSrgb = 41, /// 4x4 block compressed texture. 16 bytes per block (8 bit/px). 4 color pallet + 8 alpha pallet. 5 bit R + 6 bit G + 5 bit B + 8 bit alpha. /// [0, 64] ([0, 256] for alpha) converted to/from float [0, 1] in shader. /// /// Also known as DXT5. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc3RgbaUnorm = 42, /// 4x4 block compressed texture. 16 bytes per block (8 bit/px). 4 color pallet + 8 alpha pallet. 5 bit R + 6 bit G + 5 bit B + 8 bit alpha. /// Srgb-color [0, 64] ([0, 256] for alpha) converted to/from linear-color float [0, 1] in shader. /// /// Also known as DXT5. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc3RgbaUnormSrgb = 43, /// 4x4 block compressed texture. 8 bytes per block (4 bit/px). 8 color pallet. 8 bit R. /// [0, 256] converted to/from float [0, 1] in shader. /// /// Also known as RGTC1. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc4RUnorm = 44, /// 4x4 block compressed texture. 8 bytes per block (4 bit/px). 8 color pallet. 8 bit R. /// [-127, 127] converted to/from float [-1, 1] in shader. /// /// Also known as RGTC1. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc4RSnorm = 45, /// 4x4 block compressed texture. 16 bytes per block (16 bit/px). 8 color red pallet + 8 color green pallet. 8 bit RG. /// [0, 256] converted to/from float [0, 1] in shader. /// /// Also known as RGTC2. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc5RgUnorm = 46, /// 4x4 block compressed texture. 16 bytes per block (16 bit/px). 8 color red pallet + 8 color green pallet. 8 bit RG. /// [-127, 127] converted to/from float [-1, 1] in shader. /// /// Also known as RGTC2. /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc5RgSnorm = 47, /// 4x4 block compressed texture. 16 bytes per block (16 bit/px). Variable sized pallet. 16 bit unsigned float RGB. Float in shader. /// /// Also known as BPTC (float). /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc6hRgbUfloat = 48, /// 4x4 block compressed texture. 16 bytes per block (16 bit/px). Variable sized pallet. 16 bit signed float RGB. Float in shader. /// /// Also known as BPTC (float). /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc6hRgbSfloat = 49, /// 4x4 block compressed texture. 16 bytes per block (16 bit/px). Variable sized pallet. 8 bit integer RGBA. /// [0, 256] converted to/from float [0, 1] in shader. /// /// Also known as BPTC (unorm). /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc7RgbaUnorm = 50, /// 4x4 block compressed texture. 16 bytes per block (16 bit/px). Variable sized pallet. 8 bit integer RGBA. /// Srgb-color [0, 255] converted to/from linear-color float [0, 1] in shader. /// /// Also known as BPTC (unorm). /// /// [`Features::TEXTURE_COMPRESSION_BC`] must be enabled to use this texture format. Bc7RgbaUnormSrgb = 51, } bitflags::bitflags! { /// Color write mask. Disabled color channels will not be written to. #[repr(transparent)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct ColorWrite: u32 { /// Enable red channel writes const RED = 1; /// Enable green channel writes const GREEN = 2; /// Enable blue channel writes const BLUE = 4; /// Enable alpha channel writes const ALPHA = 8; /// Enable red, green, and blue channel writes const COLOR = 7; /// Enable writes to all channels. const ALL = 15; } } impl Default for ColorWrite { fn default() -> Self { Self::ALL } } #[repr(C)] #[derive(Clone, Debug, Default, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct StencilStateDescriptor { /// Front face mode. pub front: StencilStateFaceDescriptor, /// Back face mode. pub back: StencilStateFaceDescriptor, /// Stencil values are AND'd with this mask when reading and writing from the stencil buffer. Only low 8 bits are used. pub read_mask: u32, /// Stencil values are AND'd with this mask when writing to the stencil buffer. Only low 8 bits are used. pub write_mask: u32, } impl StencilStateDescriptor { pub fn is_enabled(&self) -> bool { (self.front != StencilStateFaceDescriptor::IGNORE || self.back != StencilStateFaceDescriptor::IGNORE) && (self.read_mask != 0 || self.write_mask != 0) } pub fn is_read_only(&self) -> bool { self.write_mask == 0 } pub fn needs_ref_value(&self) -> bool { self.front.compare.needs_ref_value() || self.back.compare.needs_ref_value() } } /// Describes the depth/stencil state in a render pipeline. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct DepthStencilStateDescriptor { /// Format of the depth/stencil buffer, must be special depth format. Must match the the format /// of the depth/stencil attachment in [`CommandEncoder::begin_render_pass`]. pub format: TextureFormat, /// If disabled, depth will not be written to. pub depth_write_enabled: bool, /// Comparison function used to compare depth values in the depth test. pub depth_compare: CompareFunction, pub stencil: StencilStateDescriptor, } impl DepthStencilStateDescriptor { pub fn is_depth_enabled(&self) -> bool { self.depth_compare != CompareFunction::Always || self.depth_write_enabled } pub fn is_read_only(&self) -> bool { !self.depth_write_enabled && self.stencil.is_read_only() } } /// Format of indices used with pipeline. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum IndexFormat { /// Indices are 16 bit unsigned integers. Uint16 = 0, /// Indices are 32 bit unsigned integers. Uint32 = 1, } impl Default for IndexFormat { fn default() -> Self { Self::Uint32 } } /// Operation to perform on the stencil value. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum StencilOperation { /// Keep stencil value unchanged. Keep = 0, /// Set stencil value to zero. Zero = 1, /// Replace stencil value with value provided in most recent call to [`RenderPass::set_stencil_reference`]. Replace = 2, /// Bitwise inverts stencil value. Invert = 3, /// Increments stencil value by one, clamping on overflow. IncrementClamp = 4, /// Decrements stencil value by one, clamping on underflow. DecrementClamp = 5, /// Increments stencil value by one, wrapping on overflow. IncrementWrap = 6, /// Decrements stencil value by one, wrapping on underflow. DecrementWrap = 7, } impl Default for StencilOperation { fn default() -> Self { Self::Keep } } /// Describes stencil state in a render pipeline. /// /// If you are not using stencil state, set this to [`StencilStateFaceDescriptor::IGNORE`]. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct StencilStateFaceDescriptor { /// Comparison function that determines if the fail_op or pass_op is used on the stencil buffer. pub compare: CompareFunction, /// Operation that is preformed when stencil test fails. pub fail_op: StencilOperation, /// Operation that is performed when depth test fails but stencil test succeeds. pub depth_fail_op: StencilOperation, /// Operation that is performed when stencil test success. pub pass_op: StencilOperation, } impl StencilStateFaceDescriptor { pub const IGNORE: Self = StencilStateFaceDescriptor { compare: CompareFunction::Always, fail_op: StencilOperation::Keep, depth_fail_op: StencilOperation::Keep, pass_op: StencilOperation::Keep, }; } impl Default for StencilStateFaceDescriptor { fn default() -> Self { Self::IGNORE } } /// Comparison function used for depth and stencil operations. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum CompareFunction { /// Function never passes Never = 1, /// Function passes if new value less than existing value Less = 2, /// Function passes if new value is equal to existing value Equal = 3, /// Function passes if new value is less than or equal to existing value LessEqual = 4, /// Function passes if new value is greater than existing value Greater = 5, /// Function passes if new value is not equal to existing value NotEqual = 6, /// Function passes if new value is greater than or equal to existing value GreaterEqual = 7, /// Function always passes Always = 8, } impl CompareFunction { pub fn needs_ref_value(self) -> bool { match self { Self::Never | Self::Always => false, _ => true, } } } /// Rate that determines when vertex data is advanced. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum InputStepMode { /// Input data is advanced every vertex. This is the standard value for vertex data. Vertex = 0, /// Input data is advanced every instance. Instance = 1, } /// Vertex inputs (attributes) to shaders. /// /// Arrays of these can be made with the [`vertex_attr_array`] macro. Vertex attributes are assumed to be tightly packed. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct VertexAttributeDescriptor { /// Byte offset of the start of the input pub offset: BufferAddress, /// Format of the input pub format: VertexFormat, /// Location for this input. Must match the location in the shader. pub shader_location: ShaderLocation, } /// Vertex Format for a Vertex Attribute (input). #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum VertexFormat { /// Two unsigned bytes (u8). `uvec2` in shaders. Uchar2 = 0, /// Four unsigned bytes (u8). `uvec4` in shaders. Uchar4 = 1, /// Two signed bytes (i8). `ivec2` in shaders. Char2 = 2, /// Four signed bytes (i8). `ivec4` in shaders. Char4 = 3, /// Two unsigned bytes (u8). [0, 255] converted to float [0, 1] `vec2` in shaders. Uchar2Norm = 4, /// Four unsigned bytes (u8). [0, 255] converted to float [0, 1] `vec4` in shaders. Uchar4Norm = 5, /// Two signed bytes (i8). [-127, 127] converted to float [-1, 1] `vec2` in shaders. Char2Norm = 6, /// Four signed bytes (i8). [-127, 127] converted to float [-1, 1] `vec4` in shaders. Char4Norm = 7, /// Two unsigned shorts (u16). `uvec2` in shaders. Ushort2 = 8, /// Four unsigned shorts (u16). `uvec4` in shaders. Ushort4 = 9, /// Two signed shorts (i16). `ivec2` in shaders. Short2 = 10, /// Four signed shorts (i16). `ivec4` in shaders. Short4 = 11, /// Two unsigned shorts (u16). [0, 65535] converted to float [0, 1] `vec2` in shaders. Ushort2Norm = 12, /// Four unsigned shorts (u16). [0, 65535] converted to float [0, 1] `vec4` in shaders. Ushort4Norm = 13, /// Two signed shorts (i16). [-32767, 32767] converted to float [-1, 1] `vec2` in shaders. Short2Norm = 14, /// Four signed shorts (i16). [-32767, 32767] converted to float [-1, 1] `vec4` in shaders. Short4Norm = 15, /// Two half-precision floats (no Rust equiv). `vec2` in shaders. Half2 = 16, /// Four half-precision floats (no Rust equiv). `vec4` in shaders. Half4 = 17, /// One single-precision float (f32). `float` in shaders. Float = 18, /// Two single-precision floats (f32). `vec2` in shaders. Float2 = 19, /// Three single-precision floats (f32). `vec3` in shaders. Float3 = 20, /// Four single-precision floats (f32). `vec4` in shaders. Float4 = 21, /// One unsigned int (u32). `uint` in shaders. Uint = 22, /// Two unsigned ints (u32). `uvec2` in shaders. Uint2 = 23, /// Three unsigned ints (u32). `uvec3` in shaders. Uint3 = 24, /// Four unsigned ints (u32). `uvec4` in shaders. Uint4 = 25, /// One signed int (i32). `int` in shaders. Int = 26, /// Two signed ints (i32). `ivec2` in shaders. Int2 = 27, /// Three signed ints (i32). `ivec3` in shaders. Int3 = 28, /// Four signed ints (i32). `ivec4` in shaders. Int4 = 29, } impl VertexFormat { pub const fn size(&self) -> u64 { match self { Self::Uchar2 | Self::Char2 | Self::Uchar2Norm | Self::Char2Norm => 2, Self::Uchar4 | Self::Char4 | Self::Uchar4Norm | Self::Char4Norm | Self::Ushort2 | Self::Short2 | Self::Ushort2Norm | Self::Short2Norm | Self::Half2 | Self::Float | Self::Uint | Self::Int => 4, Self::Ushort4 | Self::Short4 | Self::Ushort4Norm | Self::Short4Norm | Self::Half4 | Self::Float2 | Self::Uint2 | Self::Int2 => 8, Self::Float3 | Self::Uint3 | Self::Int3 => 12, Self::Float4 | Self::Uint4 | Self::Int4 => 16, } } } bitflags::bitflags! { /// Different ways that you can use a buffer. /// /// The usages determine what kind of memory the buffer is allocated from and what /// actions the buffer can partake in. #[repr(transparent)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct BufferUsage: u32 { /// Allow a buffer to be mapped for reading using [`Buffer::map_async`] + [`Buffer::get_mapped_range`]. /// This does not include creating a buffer with [`BufferDescriptor::mapped_at_creation`] set. /// /// If [`Features::MAPPABLE_PRIMARY_BUFFERS`] isn't enabled, the only other usage a buffer /// may have is COPY_DST. const MAP_READ = 1; /// Allow a buffer to be mapped for writing using [`Buffer::map_async`] + [`Buffer::get_mapped_range_mut`]. /// This does not include creating a buffer with `mapped_at_creation` set. /// /// If [`Features::MAPPABLE_PRIMARY_BUFFERS`] feature isn't enabled, the only other usage a buffer /// may have is COPY_SRC. const MAP_WRITE = 2; /// Allow a buffer to be the source buffer for a [`CommandEncoder::copy_buffer_to_buffer`] or [`CommandEncoder::copy_buffer_to_texture`] /// operation. const COPY_SRC = 4; /// Allow a buffer to be the destination buffer for a [`CommandEncoder::copy_buffer_to_buffer`], [`CommandEncoder::copy_texture_to_buffer`], /// or [`Queue::write_buffer`] operation. const COPY_DST = 8; /// Allow a buffer to be the index buffer in a draw operation. const INDEX = 16; /// Allow a buffer to be the vertex buffer in a draw operation. const VERTEX = 32; /// Allow a buffer to be a [`BindingType::UniformBuffer`] inside a bind group. const UNIFORM = 64; /// Allow a buffer to be a [`BindingType::StorageBuffer`] inside a bind group. const STORAGE = 128; /// Allow a buffer to be the indirect buffer in an indirect draw call. const INDIRECT = 256; } } /// Describes a [`Buffer`]. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct BufferDescriptor { /// Debug label of a buffer. This will show up in graphics debuggers for easy identification. pub label: L, /// Size of a buffer. pub size: BufferAddress, /// Usages of a buffer. If the buffer is used in any way that isn't specified here, the operation /// will panic. pub usage: BufferUsage, /// Allows a buffer to be mapped immediately after they are made. It does not have to be [`BufferUsage::MAP_READ`] or /// [`BufferUsage::MAP_WRITE`], all buffers are allowed to be mapped at creation. pub mapped_at_creation: bool, } impl BufferDescriptor { pub fn map_label(&self, fun: impl FnOnce(&L) -> K) -> BufferDescriptor { BufferDescriptor { label: fun(&self.label), size: self.size, usage: self.usage, mapped_at_creation: self.mapped_at_creation, } } } /// Describes a [`CommandEncoder`]. #[repr(C)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] #[derive(Clone, Debug, PartialEq, Eq, Hash)] pub struct CommandEncoderDescriptor { /// Debug label for the command encoder. This will show up in graphics debuggers for easy identification. pub label: L, } impl CommandEncoderDescriptor { pub fn map_label(&self, fun: impl FnOnce(&L) -> K) -> CommandEncoderDescriptor { CommandEncoderDescriptor { label: fun(&self.label), } } } impl Default for CommandEncoderDescriptor> { fn default() -> Self { Self { label: None } } } /// Behavior of the presentation engine based on frame rate. #[repr(C)] #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum PresentMode { /// The presentation engine does **not** wait for a vertical blanking period and /// the request is presented immediately. This is a low-latency presentation mode, /// but visible tearing may be observed. Will fallback to `Fifo` if unavailable on the /// selected platform and backend. Not optimal for mobile. Immediate = 0, /// The presentation engine waits for the next vertical blanking period to update /// the current image, but frames may be submitted without delay. This is a low-latency /// presentation mode and visible tearing will **not** be observed. Will fallback to `Fifo` /// if unavailable on the selected platform and backend. Not optimal for mobile. Mailbox = 1, /// The presentation engine waits for the next vertical blanking period to update /// the current image. The framerate will be capped at the display refresh rate, /// corresponding to the `VSync`. Tearing cannot be observed. Optimal for mobile. Fifo = 2, } bitflags::bitflags! { /// Different ways that you can use a texture. /// /// The usages determine what kind of memory the texture is allocated from and what /// actions the texture can partake in. #[repr(transparent)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct TextureUsage: u32 { /// Allows a texture to be the source in a [`CommandEncoder::copy_texture_to_buffer`] or /// [`CommandEncoder::copy_texture_to_texture`] operation. const COPY_SRC = 1; /// Allows a texture to be the destination in a [`CommandEncoder::copy_texture_to_buffer`], /// [`CommandEncoder::copy_texture_to_texture`], or [`Queue::write_texture`] operation. const COPY_DST = 2; /// Allows a texture to be a [`BindingType::SampledTexture`] in a bind group. const SAMPLED = 4; /// Allows a texture to be a [`BindingType::StorageTexture`] in a bind group. const STORAGE = 8; /// Allows a texture to be an output attachment of a renderpass. const RENDER_ATTACHMENT = 16; } } /// Describes a [`SwapChain`]. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct SwapChainDescriptor { /// The usage of the swap chain. The only supported usage is `RENDER_ATTACHMENT`. pub usage: TextureUsage, /// The texture format of the swap chain. The only formats that are guaranteed are /// `Bgra8Unorm` and `Bgra8UnormSrgb` pub format: TextureFormat, /// Width of the swap chain. Must be the same size as the surface. pub width: u32, /// Height of the swap chain. Must be the same size as the surface. pub height: u32, /// Presentation mode of the swap chain. FIFO is the only guaranteed to be supported, though /// other formats will automatically fall back to FIFO. pub present_mode: PresentMode, } /// Status of the recieved swapchain image. #[repr(C)] #[derive(Debug)] pub enum SwapChainStatus { Good, Suboptimal, Timeout, Outdated, Lost, } /// RGBA double precision color. /// /// This is not to be used as a generic color type, only for specific wgpu interfaces. #[repr(C)] #[derive(Clone, Copy, Debug, Default, PartialEq)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct Color { pub r: f64, pub g: f64, pub b: f64, pub a: f64, } impl Color { pub const TRANSPARENT: Self = Self { r: 0.0, g: 0.0, b: 0.0, a: 0.0, }; pub const BLACK: Self = Self { r: 0.0, g: 0.0, b: 0.0, a: 1.0, }; pub const WHITE: Self = Self { r: 1.0, g: 1.0, b: 1.0, a: 1.0, }; pub const RED: Self = Self { r: 1.0, g: 0.0, b: 0.0, a: 1.0, }; pub const GREEN: Self = Self { r: 0.0, g: 1.0, b: 0.0, a: 1.0, }; pub const BLUE: Self = Self { r: 0.0, g: 0.0, b: 1.0, a: 1.0, }; } /// Dimensionality of a texture. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum TextureDimension { /// 1D texture D1, /// 2D texture D2, /// 3D texture D3, } /// Origin of a copy to/from a texture. #[repr(C)] #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct Origin3d { pub x: u32, pub y: u32, pub z: u32, } impl Origin3d { pub const ZERO: Self = Self { x: 0, y: 0, z: 0 }; } impl Default for Origin3d { fn default() -> Self { Self::ZERO } } /// Extent of a texture related operation. #[repr(C)] #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct Extent3d { pub width: u32, pub height: u32, pub depth: u32, } impl Default for Extent3d { fn default() -> Self { Self { width: 1, height: 1, depth: 1, } } } /// Describes a [`Texture`]. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct TextureDescriptor { /// Debug label of the texture. This will show up in graphics debuggers for easy identification. pub label: L, /// Size of the texture. For a regular 1D/2D texture, the unused sizes will be 1. For 2DArray textures, Z is the /// number of 2D textures in that array. pub size: Extent3d, /// Mip count of texture. For a texture with no extra mips, this must be 1. pub mip_level_count: u32, /// Sample count of texture. If this is not 1, texture must have [`BindingType::SampledTexture::multisampled`] set to true. pub sample_count: u32, /// Dimensions of the texture. pub dimension: TextureDimension, /// Format of the texture. pub format: TextureFormat, /// Allowed usages of the texture. If used in other ways, the operation will panic. pub usage: TextureUsage, } impl TextureDescriptor { pub fn map_label(&self, fun: impl FnOnce(&L) -> K) -> TextureDescriptor { TextureDescriptor { label: fun(&self.label), size: self.size, mip_level_count: self.mip_level_count, sample_count: self.sample_count, dimension: self.dimension, format: self.format, usage: self.usage, } } } /// Kind of data the texture holds. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum TextureAspect { /// Depth, Stencil, and Color. All, /// Stencil. StencilOnly, /// Depth. DepthOnly, } impl Default for TextureAspect { fn default() -> Self { Self::All } } /// How edges should be handled in texture addressing. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum AddressMode { /// Clamp the value to the edge of the texture /// /// -0.25 -> 0.0 /// 1.25 -> 1.0 ClampToEdge = 0, /// Repeat the texture in a tiling fashion /// /// -0.25 -> 0.75 /// 1.25 -> 0.25 Repeat = 1, /// Repeat the texture, mirroring it every repeat /// /// -0.25 -> 0.25 /// 1.25 -> 0.75 MirrorRepeat = 2, /// Clamp the value to the border of the texture /// Requires feature [`Features::ADDRESS_MODE_CLAMP_TO_BORDER`] /// /// -0.25 -> border /// 1.25 -> border ClampToBorder = 3, } impl Default for AddressMode { fn default() -> Self { Self::ClampToEdge } } /// Texel mixing mode when sampling between texels. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum FilterMode { /// Nearest neighbor sampling. /// /// This creates a pixelated effect when used as a mag filter Nearest = 0, /// Linear Interpolation /// /// This makes textures smooth but blurry when used as a mag filter. Linear = 1, } impl Default for FilterMode { fn default() -> Self { Self::Nearest } } /// A range of push constant memory to pass to a shader stage. #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct PushConstantRange { /// Stage push constant range is visible from. Each stage can only be served by at most one range. /// One range can serve multiple stages however. pub stages: ShaderStage, /// Range in push constant memory to use for the stage. Must be less than [`Limits::max_push_constant_size`]. /// Start and end must be aligned to the 4s. pub range: Range, } /// Describes a [`CommandBuffer`]. #[repr(C)] #[derive(Clone, Debug, Default, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct CommandBufferDescriptor { pub label: L, } impl CommandBufferDescriptor { pub fn map_label(&self, fun: impl FnOnce(&L) -> K) -> CommandBufferDescriptor { CommandBufferDescriptor { label: fun(&self.label), } } } /// Describes a [`RenderBundle`]. #[repr(C)] #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct RenderBundleDescriptor { /// Debug label of the render bundle encoder. This will show up in graphics debuggers for easy identification. pub label: L, } impl RenderBundleDescriptor { pub fn map_label(&self, fun: impl FnOnce(&L) -> K) -> RenderBundleDescriptor { RenderBundleDescriptor { label: fun(&self.label), } } } impl Default for RenderBundleDescriptor> { fn default() -> Self { Self { label: None } } } /// Type of data shaders will read from a texture. /// /// Only relevant for [`BindingType::SampledTexture`] bindings. See [`TextureFormat`] for more information. #[repr(C)] #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum TextureComponentType { /// They see it as a floating point number `texture1D`, `texture2D` etc Float, /// They see it as a signed integer `itexture1D`, `itexture2D` etc Sint, /// They see it as a unsigned integer `utexture1D`, `utexture2D` etc Uint, /// They see it as a floating point 0-1 result of comparison, i.e. `shadowTexture2D` DepthComparison, } impl From for TextureComponentType { fn from(format: TextureFormat) -> Self { match format { TextureFormat::R8Uint | TextureFormat::R16Uint | TextureFormat::Rg8Uint | TextureFormat::R32Uint | TextureFormat::Rg16Uint | TextureFormat::Rgba8Uint | TextureFormat::Rg32Uint | TextureFormat::Rgba16Uint | TextureFormat::Rgba32Uint => Self::Uint, TextureFormat::R8Sint | TextureFormat::R16Sint | TextureFormat::Rg8Sint | TextureFormat::R32Sint | TextureFormat::Rg16Sint | TextureFormat::Rgba8Sint | TextureFormat::Rg32Sint | TextureFormat::Rgba16Sint | TextureFormat::Rgba32Sint => Self::Sint, TextureFormat::R8Unorm | TextureFormat::R8Snorm | TextureFormat::R16Float | TextureFormat::R32Float | TextureFormat::Rg8Unorm | TextureFormat::Rg8Snorm | TextureFormat::Rg16Float | TextureFormat::Rg11b10Float | TextureFormat::Rg32Float | TextureFormat::Rgba8Snorm | TextureFormat::Rgba16Float | TextureFormat::Rgba32Float | TextureFormat::Rgba8Unorm | TextureFormat::Rgba8UnormSrgb | TextureFormat::Bgra8Unorm | TextureFormat::Bgra8UnormSrgb | TextureFormat::Rgb10a2Unorm | TextureFormat::Depth32Float | TextureFormat::Depth24Plus | TextureFormat::Depth24PlusStencil8 | TextureFormat::Bc1RgbaUnorm | TextureFormat::Bc1RgbaUnormSrgb | TextureFormat::Bc2RgbaUnorm | TextureFormat::Bc2RgbaUnormSrgb | TextureFormat::Bc3RgbaUnorm | TextureFormat::Bc3RgbaUnormSrgb | TextureFormat::Bc4RUnorm | TextureFormat::Bc4RSnorm | TextureFormat::Bc5RgUnorm | TextureFormat::Bc5RgSnorm | TextureFormat::Bc6hRgbSfloat | TextureFormat::Bc6hRgbUfloat | TextureFormat::Bc7RgbaUnorm | TextureFormat::Bc7RgbaUnormSrgb => Self::Float, } } } /// Layout of a texture in a buffer's memory. #[repr(C)] #[derive(Clone, Debug, Default)] #[cfg_attr(feature = "trace", derive(serde::Serialize))] #[cfg_attr(feature = "replay", derive(serde::Deserialize))] pub struct TextureDataLayout { /// Offset into the buffer that is the start of the texture. Must be a multiple of texture block size. /// For non-compressed textures, this is 1. pub offset: BufferAddress, /// Bytes per "row" of the image. This represents one row of pixels in the x direction. Compressed /// textures include multiple rows of pixels in each "row". May be 0 for 1D texture copies. /// /// Must be a multiple of 256 for [`CommandEncoder::copy_buffer_to_texture`] and [`CommandEncoder::copy_texture_to_buffer`]. /// [`Queue::write_texture`] does not have this requirement. /// /// Must be a multiple of the texture block size. For non-compressed textures, this is 1. pub bytes_per_row: u32, /// Rows that make up a single "image". Each "image" is one layer in the z direction of a 3D image. May be larger /// than `copy_size.y`. /// /// May be 0 for 2D texture copies. pub rows_per_image: u32, } /// Specific type of a binding. /// /// WebGPU spec: https://gpuweb.github.io/gpuweb/#dictdef-gpubindgrouplayoutentry #[derive(Clone, Debug, Eq, PartialEq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub enum BindingType { /// A buffer for uniform values. /// /// Example GLSL syntax: /// ```cpp,ignore /// layout(std140, binding = 0) /// uniform Globals { /// vec2 aUniform; /// vec2 anotherUniform; /// }; /// ``` UniformBuffer { /// Indicates that the binding has a dynamic offset. /// One offset must be passed to [`RenderPass::set_bind_group`] for each dynamic binding in increasing order of binding number. dynamic: bool, /// Minimum size of the corresponding `BufferBinding` required to match this entry. /// When pipeline is created, the size has to cover at least the corresponding structure in the shader /// plus one element of the unbound array, which can only be last in the structure. /// If `None`, the check is performed at draw call time instead of pipeline and bind group creation. min_binding_size: Option, }, /// A storage buffer. /// /// Example GLSL syntax: /// ```cpp,ignore /// layout (set=0, binding=0) buffer myStorageBuffer { /// vec4 myElement[]; /// }; /// ``` StorageBuffer { /// Indicates that the binding has a dynamic offset. /// One offset must be passed to [`RenderPass::set_bind_group`] for each dynamic binding in increasing order of binding number. dynamic: bool, /// Minimum size of the corresponding `BufferBinding` required to match this entry. /// When pipeline is created, the size has to cover at least the corresponding structure in the shader /// plus one element of the unbound array, which can only be last in the structure. /// If `None`, the check is performed at draw call time instead of pipeline and bind group creation. min_binding_size: Option, /// The buffer can only be read in the shader and it must be annotated with `readonly`. /// /// Example GLSL syntax: /// ```cpp,ignore /// layout (set=0, binding=0) readonly buffer myStorageBuffer { /// vec4 myElement[]; /// }; /// ``` readonly: bool, }, /// A sampler that can be used to sample a texture. /// /// Example GLSL syntax: /// ```cpp,ignore /// layout(binding = 0) /// uniform sampler s; /// ``` Sampler { /// Use as a comparison sampler instead of a normal sampler. /// For more info take a look at the analogous functionality in OpenGL: https://www.khronos.org/opengl/wiki/Sampler_Object#Comparison_mode. comparison: bool, }, /// A texture. /// /// Example GLSL syntax: /// ```cpp,ignore /// layout(binding = 0) /// uniform texture2D t; /// ``` SampledTexture { /// Dimension of the texture view that is going to be sampled. dimension: TextureViewDimension, /// Component type of the texture. /// This must be compatible with the format of the texture. component_type: TextureComponentType, /// True if the texture has a sample count greater than 1. If this is true, /// the texture must be read from shaders with `texture1DMS`, `texture2DMS`, or `texture3DMS`, /// depending on `dimension`. multisampled: bool, }, /// A storage texture. /// /// Example GLSL syntax: /// ```cpp,ignore /// layout(set=0, binding=0, r32f) uniform image2D myStorageImage; /// ``` /// Note that the texture format must be specified in the shader as well. /// A list of valid formats can be found in the specification here: https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.4.60.html#layout-qualifiers StorageTexture { /// Dimension of the texture view that is going to be sampled. dimension: TextureViewDimension, /// Format of the texture. format: TextureFormat, /// The texture can only be read in the shader and it must be annotated with `readonly`. /// /// Example GLSL syntax: /// ```cpp,ignore /// layout(set=0, binding=0, r32f) readonly uniform image2D myStorageImage; /// ``` readonly: bool, }, } impl BindingType { pub fn has_dynamic_offset(&self) -> bool { match *self { Self::UniformBuffer { dynamic, .. } | Self::StorageBuffer { dynamic, .. } => dynamic, _ => false, } } } /// Describes a single binding inside a bind group. #[derive(Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "trace", derive(Serialize))] #[cfg_attr(feature = "replay", derive(Deserialize))] pub struct BindGroupLayoutEntry { /// Binding index. Must match shader index and be unique inside a BindGroupLayout. A binding /// of index 1, would be described as `layout(set = 0, binding = 1) uniform` in shaders. pub binding: u32, /// Which shader stages can see this binding. pub visibility: ShaderStage, /// The type of the binding pub ty: BindingType, /// If this value is Some, indicates this entry is an array. Array size must be 1 or greater. /// /// If this value is Some and `ty` is `BindingType::SampledTexture`, [`Capabilities::SAMPLED_TEXTURE_BINDING_ARRAY`] must be supported. /// /// If this value is Some and `ty` is any other variant, bind group creation will fail. pub count: Option, } /// View of a buffer which can be used to copy to/from a texture. #[repr(C)] #[derive(Clone, Debug)] #[cfg_attr(feature = "trace", derive(serde::Serialize))] #[cfg_attr(feature = "replay", derive(serde::Deserialize))] pub struct BufferCopyView { /// The buffer to be copied to/from. pub buffer: B, /// The layout of the texture data in this buffer. pub layout: TextureDataLayout, } /// View of a texture which can be used to copy to/from a buffer/texture. #[repr(C)] #[derive(Clone, Debug)] #[cfg_attr(feature = "trace", derive(serde::Serialize))] #[cfg_attr(feature = "replay", derive(serde::Deserialize))] pub struct TextureCopyView { /// The texture to be copied to/from. pub texture: T, /// The target mip level of the texture. pub mip_level: u32, /// The base texel of the texture in the selected `mip_level`. #[cfg_attr(any(feature = "replay", feature = "trace"), serde(default))] pub origin: Origin3d, } /// Color variation to use when sampler addressing mode is [`AddressMode::ClampToBorder`] #[repr(C)] #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)] #[cfg_attr(feature = "trace", derive(serde::Serialize))] #[cfg_attr(feature = "replay", derive(serde::Deserialize))] pub enum SamplerBorderColor { TransparentBlack, OpaqueBlack, OpaqueWhite, }