A cross-platform, safe, pure-Rust graphics API.
This release includes the crate wgpu, wgpu-core, and wgpu-hal. The crate wgpu-types is still at 0.17.0.
get_mapped_range_as_array_buffer for faster buffer read-backs in wasm builds. By @ryankaplan in #4042.This is the first release that featured wgpu-info as a binary crate for getting information about what devices wgpu sees in your system. It can dump the information in both human readable format and json.
This release was fairly minor as breaking changes go.
wgpu types now !Send !Sync on wasmUp until this point, wgpu has made the assumption that threads do not exist on wasm. With the rise of libraries like wasm_thread making it easier and easier to do wasm multithreading this assumption is no longer sound. As all wgpu objects contain references into the JS heap, they cannot leave the thread they started on.
As we understand that this change might be very inconvenient for users who don't care about wasm threading, there is a crate feature which re-enables the old behavior: fragile-send-sync-non-atomic-wasm. So long as you don't compile your code with -Ctarget-feature=+atomics, Send and Sync will be implemented again on wgpu types on wasm. As the name implies, especially for libraries, this is very fragile, as you don't know if a user will want to compile with atomics (and therefore threads) or not.
By @daxpedda in #3691
The power_preference field of RequestAdapterOptions is now optional. If it is PowerPreference::None, we will choose the first available adapter, preferring GPU adapters over CPU adapters.
By @Aaron1011 in #3903
initialize_adapter_from_env argument changesRemoved the backend_bits parameter from initialize_adapter_from_env and initialize_adapter_from_env_or_default. If you want to limit the backends used by this function, only enable the watned backends in the instance.
Added a compatible surface parameter, to ensure the given device is able to be presented onto the given surface.
- wgpu::util::initialize_adapter_from_env(instance, backend_bits);
+ wgpu::util::initialize_adapter_from_env(instance, Some(&compatible_surface));
By @fornwall in #3904 and #3905
AdapterInfo::{device,vendor} to be u32 instead of usize. By @ameknite in #3760
buffer_from_raw (Dx12, Metal, Vulkan) and create_buffer_from_hal. By @AdrianEddy in #3355
TextureFormats. By @teoxoy in #3843.GPUVertexBufferLayout. By @fornwall in #3906
DEPTH32FLOAT_STENCIL8 by @ErichDonGubler in #3734.AdapterInfo::{device,vendor} by @ErichDonGubler in #3763.descriptor.usage is not empty in create_buffer by @nical in #3928
max_bindings_per_bind_group limit to reflect spec changes by @ErichDonGubler and @nical in #3943 #3942
SurfaceConfiguration. by @liquidev in #3817
get_preferred_canvas_format() to fill formats of SurfaceCapabilities. By @jinleili in #3744
This release includes the crate wgpu. The crate wgpu-core is still at 0.16.1, wgpu-types and wgpu-hal are still at 0.16.2.
Id type that is exposed when using the expose-ids feature implement Send and Sync again. This was unintentionally changed by the v0.16.0 release and is now fixed.This release includes wgpu, wgpu-hal, and wgpu-types. The crate wgpu-core are still at 0.16.1.
max_storage_buffers_per_shader_stage and max_storage_textures_per_shader_stage limits based on what the hardware supports. by @Elabajaba in [#3798]https://github.com/gfx-rs/wgpu/pull/3798This release includes wgpu, wgpu-core, and wgpu-hal. The crate wgpu-types are still at 0.16.0.
wgpu::CommandBuffer. By @wumpf in #3726.u32s internally for bind group indices, rather than u8. By @ErichDonGubler in #3743.create_surface_from_canvas. By @grovesNL in #3718
type has been replaced with alias to match with upstream WebGPU.
- type MyType = vec4<u32>;
+ alias MyType = vec4<u32>;
The TextureFormat::describe function was removed in favor of separate functions: block_dimensions, is_compressed, is_srgb, required_features, guaranteed_format_features, sample_type and block_size.
- let block_dimensions = format.describe().block_dimensions;
+ let block_dimensions = format.block_dimensions();
- let is_compressed = format.describe().is_compressed();
+ let is_compressed = format.is_compressed();
- let is_srgb = format.describe().srgb;
+ let is_srgb = format.is_srgb();
- let required_features = format.describe().required_features;
+ let required_features = format.required_features();
Additionally guaranteed_format_features now takes a set of features to assume are enabled.
- let guaranteed_format_features = format.describe().guaranteed_format_features;
+ let guaranteed_format_features = format.guaranteed_format_features(device.features());
Additionally sample_type and block_size now take an optional TextureAspect and return Options.
- let sample_type = format.describe().sample_type;
+ let sample_type = format.sample_type(None).expect("combined depth-stencil format requires specifying a TextureAspect");
- let block_size = format.describe().block_size;
+ let block_size = format.block_size(None).expect("combined depth-stencil format requires specifying a TextureAspect");
By @teoxoy in #3436
Buffers used as the destination argument of CommandEncoder::resolve_query_set now have to contain the QUERY_RESOLVE usage instead of the COPY_DST usage.
let destination = device.create_buffer(&wgpu::BufferDescriptor {
// ...
- usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
+ usage: wgpu::BufferUsages::QUERY_RESOLVE | wgpu::BufferUsages::MAP_READ,
mapped_at_creation: false,
});
command_encoder.resolve_query_set(&query_set, query_range, &destination, destination_offset);
By @JolifantoBambla in #3489
The following Features have been renamed.
SHADER_FLOAT16 -> SHADER_F16
SHADER_FLOAT64 -> SHADER_F64
SHADER_INT16 -> SHADER_I16
TEXTURE_COMPRESSION_ASTC_LDR -> TEXTURE_COMPRESSION_ASTC
WRITE_TIMESTAMP_INSIDE_PASSES -> TIMESTAMP_QUERY_INSIDE_PASSES
By @teoxoy in #3534
Anisotropic filtering has been brought in line with the spec. The anisotropic clamp is now a u16 (was a Option<u8>) which must be at least 1.
If the anisotropy clamp is not 1, all the filters in a sampler must be Linear.
SamplerDescriptor {
- anisotropic_clamp: None,
+ anisotropic_clamp: 1,
}
By @cwfitzgerald in #3610.
Some texture format names have changed to get back in line with the spec.
- TextureFormat::Bc6hRgbSfloat
+ TextureFormat::Bc6hRgbFloat
By @cwfitzgerald in #3671.
mip_level_count and array_layer_count (members of TextureViewDescriptor and ImageSubresourceRange) from Option<NonZeroU32> to Option<u32>. By @teoxoy in #3445
bytes_per_row and rows_per_image (members of ImageDataLayout) from Option<NonZeroU32> to Option<u32>. By @teoxoy in #3529
Instance::create_surface_from_canvas() and create_surface_from_offscreen_canvas() now take the canvas by value. By @daxpedda in #3690
TextureFormatFeatureFlags::MULTISAMPLE_X16. By @Dinnerbone in #3454
BufferUsages::QUERY_RESOLVE. By @JolifantoBambla in #3489
Features::SHADER_EARLY_DEPTH_TEST. By @teoxoy in #3494
fxhash dependencies have been replaced with rustc-hash. By @james7132 in #3502
TextureSampleType::Float on a multisample BindingType::Texture. By @mockersf in #3686
Surface::configure(). If the canvas was given an explicit size (via CSS), this will not affect the visual size of the canvas. By @daxpedda in #3690
adapter|device_features. By @jinleili in #3428
command_encoder_resolve_query_set. By @JolifantoBambla in #3489
Features::RG11B10UFLOAT_RENDERABLE. By @mockersf in #3689
max_memory_allocation_size via PhysicalDeviceMaintenance3Properties. By @jinleili in #3567
copyTextureToTexture src/dst aspects must both refer to all aspects of src/dst format. By @teoxoy in #3431
None values for depth_ops and stencil_ops in RenderPassDescriptor::depth_stencil_attachment. By @niklaskorz in #3660
WasmAbi functions for WebGPU backend. By @grovesNL in #3657
surface.configure. By @cwfitzgerald in #3585
copy_external_image_to_texture, copy_texture_to_texture and copy_buffer_to_texture not taking the specified index into account if the target texture is a cube map, 2D texture array or cube map array. By @daxpedda #3641
array_stride of 0. By @teoxoy in #3538
create_texture returns an error if new_texture returns NULL. By @jinleili in #3554
VK_SUBOPTIMAL_KHR as VK_SUCCESS on Android due to rotation issues. By @James2022-rgb in #3525
BufferUsages::QUERY_RESOLVE instead of BufferUsages::COPY_DST for buffers used in CommandEncoder::resolve_query_set calls in mipmap example. By @JolifantoBambla in #3489
This was released as wgpu-hal version 0.15.4 due to a previous publishing issue. All other crates remain unbumped
MinLod <= 0.0 and MaxLod >= 32.0 or when the fragment shader samples different Lods in the same quad. By @cwfitzgerald in #3610.Vertex buffer is not big enough for the draw call. for ANGLE/Web when rendering with instance attributes on a single instance. By @wumpf in #3596
SAMPLE_ALPHA_TO_COVERAGE on queue reset. By @jleibs #3589
CommandEncoder::clear_buffer. By @raphlinus in #3426
dxil_path. By @Elabajaba in #3434
{adapter|device}_features. By @jinleili in #3428
let is now constAll top level constants are now declared with const, catching up with the wgsl spec.
let is no longer allowed at the global scope, only within functions.
-let SOME_CONSTANT = 12.0;
+const SOME_CONSTANT = 12.0;
See https://github.com/gfx-rs/naga/blob/master/CHANGELOG.md#v011-2023-01-25 for smaller shader improvements.
The various surface capability functions were combined into a single call that gives you all the capabilities.
- let formats = surface.get_supported_formats(&adapter);
- let present_modes = surface.get_supported_present_modes(&adapter);
- let alpha_modes = surface.get_supported_alpha_modes(&adapter);
+ let caps = surface.get_capabilities(&adapter);
+ let formats = caps.formats;
+ let present_modes = caps.present_modes;
+ let alpha_modes = caps.alpha_modes;
Additionally Surface::get_default_config now returns an Option and returns None if the surface isn't supported by the adapter.
- let config = surface.get_default_config(&adapter);
+ let config = surface.get_default_config(&adapter).expect("Surface unsupported by adapter");
Instance::create_surface() now returns Result<Surface, CreateSurfaceError> instead of Surface. This allows an error to be returned if the given window is a HTML canvas and obtaining a WebGPU or WebGL 2 context fails. (No other platforms currently report any errors through this path.) By @kpreid in #3052
Queue::copy_external_image_to_texture on WebAssemblyA new api, Queue::copy_external_image_to_texture, allows you to create wgpu textures from various web image primitives. Specificically from HtmlVideoElement, HtmlCanvasElement, OffscreenCanvas, and ImageBitmap. This provides multiple low-copy ways of interacting with the browser. WebGL is also supported, though WebGL has some additional restrictions, represented by the UNRESTRICTED_EXTERNAL_IMAGE_COPIES downlevel flag. By @cwfitzgerald in #3288
InstanceDescriptor instead of BackendsInstance::new() and hub::Global::new() now take an InstanceDescriptor struct which cointains both the existing Backends selection as well as a new Dx12Compiler field for selecting which Dx12 shader compiler to use.
- let instance = Instance::new(wgpu::Backends::all());
+ let instance = Instance::new(wgpu::InstanceDescriptor {
+ backends: wgpu::Backends::all(),
+ dx12_shader_compiler: wgpu::Dx12Compiler::Fxc,
+ });
Instance now also also implements Default, which uses wgpu::Backends::all() and wgpu::Dx12Compiler::Fxc for InstanceDescriptor
- let instance = Instance::new(wgpu::InstanceDescriptor {
- backends: wgpu::Backends::all(),
- dx12_shader_compiler: wgpu::Dx12Compiler::Fxc,
- });
+ let instance = Instance::default();
By @Elabajaba in #3356
The new view_formats field in the TextureDescriptor is used to specify a list of formats the texture can be re-interpreted to in a texture view. Currently only changing srgb-ness is allowed (ex. Rgba8Unorm <=> Rgba8UnormSrgb).
let texture = device.create_texture(&wgpu::TextureDescriptor {
// ...
format: TextureFormat::Rgba8UnormSrgb,
+ view_formats: &[TextureFormat::Rgba8Unorm],
});
let config = wgpu::SurfaceConfiguration {
// ...
format: TextureFormat::Rgba8Unorm,
+ view_formats: vec![wgpu::TextureFormat::Rgba8UnormSrgb],
};
surface.configure(&device, &config);
Via the TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES feature, MSAA x2 and x8 are now supported on textures. To query for x2 or x8 support, enable the feature and look at the texture format flags for the texture format of your choice.
By @39ali in 3140
You can now choose to use the DXC compiler for DX12 instead of FXC. The DXC compiler is faster, less buggy, and allows for new features compared to the old, unmaintained FXC compiler.
You can choose which compiler to use at Instance creation using the dx12_shader_compiler field in the InstanceDescriptor struct. Note that DXC requires both dxcompiler.dll and dxil.dll, which can be downloaded from https://github.com/microsoft/DirectXShaderCompiler/releases. Both .dlls need to be shipped with your application when targeting DX12 and using the DXC compiler. If the .dlls can't be loaded, then it will fall back to the FXC compiler. By @39ali and @Elabajaba in #3356
The DX12 backend can now suballocate buffers and textures from larger chunks of memory, which can give a significant increase in performance (in testing a 100x improvement has been seen in a simple scene with 200 write_buffer calls per frame, and a 1.4x improvement in Bistro using Bevy).
Previously wgpu-hal's DX12 backend created a new heap on the GPU every time you called write_buffer (by calling CreateCommittedResource), whereas now it uses gpu_allocator to manage GPU memory (and calls CreatePlacedResource with a suballocated heap). By @Elabajaba in #3163
Whereas wgpu-core used to automatically select backends to enable
based on the target OS and architecture, it now has separate features
to enable each backend:
None are enabled by default, but the wgpu crate automatically
selects these features based on the target operating system and
architecture, using the same rules that wgpu-core used to, so users
of wgpu should be unaffected by this change. However, other crates
using wgpu-core directly will need to copy wgpu's logic or write
their own. See the [target] section of wgpu/Cargo.toml for
details.
Similarly, wgpu-core now has emscripten and renderdoc features
that wgpu enables on appropriate platforms.
In previous releases, the wgpu-core crate decided which backends to
support. However, this left wgpu-core's users with no way to
override those choices. (Firefox doesn't want the GLES back end, for
example.) There doesn't seem to be any way to have a crate select
backends based on target OS and architecture that users of that crate
can still override. Default features can't be selected based on the
target, for example. That implies that we should do the selection as
late in the dependency DAG as feasible. Having wgpu (and
wgpu-core's other dependents) choose backends seems like the best
option.
By @jimblandy in #3254.
Default Implementations on Enums to derive(Default)
Default for CompositeAlphaMode
UNRESTRICTED_INDEX_BUFFER to indicate support for using INDEX together with other non-copy/map usages (unsupported on WebGL). By @Wumpf in #3157
DEPTH_BIAS_CLAMP and FULL_DRAW_INDEX_UINT32 downlevel flags. By @teoxoy in #3316
Surface::get_supported_formats, Surface::get_supported_present_modes, and Surface::get_supported_alpha_modes into Surface::get_capabilities and SurfaceCapabilities. By @cwfitzgerald in #3157
Surface::get_default_config return an Option to prevent panics. By @cwfitzgerald in #3157
max_buffer_size limit value for compatibility with Apple2 and WebGPU compliance. By @jinleili in #3255
min_uniform_buffer_offset_alignment and min_storage_buffer_offset_alignment is now always at least 32. By @wumpf #3262
strict_assert family of macros was moved to wgpu-types. By @i509VCB in #3051
ObjectId structure and invariants idiomatic. By @teoxoy in #3347
GPUSamplerDescriptor valid usage for lodMinClamp and lodMaxClamp. By @James2022-rgb in #3353
Deref implementations for QueueWriteBufferView and BufferViewMut. Instead, warnings are logged, since reading from these types is not recommended. By @botahamec in [#3336]view_formats in the TextureDescriptor to match the WebGPU spec. By @jinleili in #3237
TextureView validation according to the WebGPU spec. By @teoxoy in #3410
view_formats in the SurfaceConfiguration to match the WebGPU spec. By @jinleili in #3409
WEBGPU_TEXTURE_FORMAT_SUPPORT downlevel flag depending on the proper format support by @teoxoy in #3367.COPY_SRC/COPY_DST only based on Vulkan's TRANSFER_SRC/TRANSFER_DST by @teoxoy in #3366.OVR_multiview2 now report the MULTIVIEW feature by @expenses in #3121.Limits::max_push_constant_size on GLES is now 256 by @Dinnerbone in #3374.queue_validate_write_buffer by @jinleili in #3098
Hash for DepthStencilState and DepthBiasState
"wgsl" feature, to enable WGSL shaders in wgpu-core and wgpu. Enabled by default in wgpu. By @daxpedda in #2890.Clone for ShaderSource and ShaderModuleDescriptor in wgpu. By @daxpedda in #3086.get_default_config for Surface to simplify user creation of SurfaceConfiguration. By @jinleili in #3034
Adapter::get_presentation_timestamp]. By @cwfitzgerald in #3240
Features::SHADER_PRIMITIVE_INDEX on all backends. By @cwfitzgerald in #3272
TextureFormat::Stencil8, allowing for stencil testing without depth components. By @Dinnerbone in #3343
add_srgb_suffix() for TextureFormat for converting linear formats to sRGB. By @Elabajaba in #3419
TextureFormat::Rgba8Unorm and (non-web only) TextureFormat::Bgra8Unorm. By @Wumpf in #3070
MULTISAMPLE_X2, MULTISAMPLE_X4 and MULTISAMPLE_X8 to TextureFormatFeatureFlags. By @39ali in 3140
TextureFormat.describe with the spec. By @teoxoy in 3312
hal::Api::CommandBuffer when a wgpu_core::command::CommandEncoder is dropped. By @jimblandy in #3069.copy_texture_to_texture by @nical #3090
wgpu_types::Features::DEPTH24PLUS_STENCIL8, making wgpu::TextureFormat::Depth24PlusStencil8 available on all backends. By @Healthire in (#3151)[https://github.com/gfx-rs/wgpu/pull/3151]queue_write_texture by @nical in (#3146)[https://github.com/gfx-rs/wgpu/pull/3146]RenderPassCompatibilityError and CreateShaderModuleError not so huge. By @jimblandy in (#3226)[https://github.com/gfx-rs/wgpu/pull/3226]gfx_select!'s #[cfg] conditions at the right time. By @jimblandy in #3253
Global::queue_texture_write. By @jimblandy in #3378.make_spirv_raw and make_spirv handle big-endian binaries. By @1e1001 in #3411.debug_utils_set_object_name() function to set_debug_utils_object_name() by @elabajaba in #3273
PhysicalDeviceDriverProperties struct after it has gone out of scope. In fact, don't make a local copy at all. Introduce a helper function for building CStrs from C character arrays, and remove some unsafe blocks. By @jimblandy in #3076.depth16Unorm formats by @teoxoy in #3313
GraphicsCommandList when close or reset fails. By @xiaopengli89 in #3204
mip_level_count or array_layer_count. By @cwfitzgerald in #3323
log instead of println in hello example by @JolifantoBambla in #2858
setVertexBuffer and setIndexBuffer calls on
GPURenderBundleEncoder throw an error if the size argument is
zero, rather than treating that as "until the end of the buffer".
By @jimblandy in #3171
framework.rs compile again under Emscripten. By @jimblandy in #3246
stencil-triangles to show basic use of stencil testing. By @Dinnerbone in #3343