v0.17.1

This release includes the crate wgpu, wgpu-core, and wgpu-hal. The crate wgpu-types is still at 0.17.0.

Added/New Features

• Add get_mapped_range_as_array_buffer for faster buffer read-backs in wasm builds. By @ryankaplan in #4042.

Bug Fixes

DX12

• Fix panic on resize when using DX12. By @cwfitzgerald in #4106

Vulkan

• Suppress validation error caused by OBS layer. This was also fixed upstream. By @cwfitzgerald in #4002
• Work around bug in nvidia's vkCmdFillBuffer implementation. By @cwfitzgerald in #4132.

v0.17.0

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.

Major Changes

This release was fairly minor as breaking changes go.

wgpu types now !Send !Sync on wasm

Up 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

Power Preference is now optional

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 changes

Removed 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

Misc Breaking Changes

• Change AdapterInfo::{device,vendor} to be u32 instead of usize. By @ameknite in #3760

Changes

• Added support for importing external buffers using buffer_from_raw (Dx12, Metal, Vulkan) and create_buffer_from_hal. By @AdrianEddy in #3355

Vulkan

• Work around Vulkan-ValidationLayers#5671 by ignoring reports of violations of VUID-vkCmdEndDebugUtilsLabelEXT-commandBuffer-01912. By @jimblandy in #3809.

Added/New Features

• Empty scissor rects are allowed now, matching the specification. by @PJB3005 in #3863.
• Add back components info to TextureFormats. By @teoxoy in #3843.

Documentation

• Better documentation for draw, draw_indexed, set_viewport and set_scissor_rect. By @genusistimelord in #3860
• Fix link to GPUVertexBufferLayout. By @fornwall in #3906
• Document feature requirements for DEPTH32FLOAT_STENCIL8 by @ErichDonGubler in #3734.
• Flesh out docs. for AdapterInfo::{device,vendor} by @ErichDonGubler in #3763.
• Spell out which sizes are in bytes. By @jimblandy in #3773.
• Validate that descriptor.usage is not empty in create_buffer by @nical in #3928
• Update max_bindings_per_bind_group limit to reflect spec changes by @ErichDonGubler and @nical in #3943 #3942

Bug Fixes

General

• Fix order of arguments to glPolygonOffset by @komadori in #3783.
• Fix OpenGL/EGL backend not respecting non-sRGB texture formats in SurfaceConfiguration. by @liquidev in #3817
• Make write- and read-only marked buffers match non-readonly layouts. by @fornwall in #3893
• Fix leaking X11 connections. by @wez in #3924
• Fix ASTC feature selection in the webgl backend. by @expenses in #3934
• Fix Multiview to disable validation of TextureViewDimension and ArrayLayerCount. By @MalekiRe in #3779.

Vulkan

• Fix incorrect aspect in barriers when using emulated Stencil8 textures. By @cwfitzgerald in #3833.
• Implement depth-clip-control using depthClamp instead of VK_EXT_depth_clip_enable. By @AlbinBernhardssonARM #3892.

Metal

• Fix renderpasses being used inside of renderpasses. By @cwfitzgerald in #3828
• Support (simulated) visionOS. By @jinleili in #3883

DX12

• Disable suballocation on Intel Iris(R) Xe. By @xiaopengli89 in #3668

WebGPU

• Use get_preferred_canvas_format() to fill formats of SurfaceCapabilities. By @jinleili in #3744

Examples

• Publish examples to wgpu.rs on updates to trunk branch instead of gecko. By @paul-hansen in #3750
• Ignore the exception values generated by the winit resize event. By @jinleili in #3916

v0.16.3

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.

Changes

General

• Make the 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.

v0.16.2

This release includes wgpu, wgpu-hal, and wgpu-types. The crate wgpu-core are still at 0.16.1.

Changes

DX12

• Increase the max_storage_buffers_per_shader_stage and max_storage_textures_per_shader_stage limits based on what the hardware supports. by @Elabajaba in [#3798]#3798

v0.16.1

This release includes wgpu, wgpu-core, and wgpu-hal. The crate wgpu-types are still at 0.16.0.

General

• Fix crash on dropping wgpu::CommandBuffer. By @Wumpf in #3726.
• Use u32s internally for bind group indices, rather than u8. By @ErichDonGubler in #3743.

GLES

• Fix missing 4X MSAA support on some OpenGL backends. By @emilk in #3780

WebGPU

• Fix crash when calling create_surface_from_canvas. By @grovesNL in #3718

v0.16.0

Major changes

Shader Changes

type has been replaced with alias to match with upstream WebGPU.

- type MyType = vec4<u32>;
+ alias MyType = vec4<u32>;

TextureFormat info API

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

BufferUsages::QUERY_RESOLVE

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

Renamed features

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

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.

TextureFormat Names

Some texture format names have changed to get back in line with the spec.

- TextureFormat::Bc6hRgbSfloat
+ TextureFormat::Bc6hRgbFloat

By @cwfitzgerald in #3671.

Misc Breaking Changes

• Change type of mip_level_count and array_layer_count (members of TextureViewDescriptor and ImageSubresourceRange) from Option<NonZeroU32> to Option<u32>. By @teoxoy in #3445
• Change type of bytes_per_row and rows_per_image (members of ImageDataLayout) from Option<NonZeroU32> to Option<u32>. By @teoxoy in #3529
• On Web, Instance::create_surface_from_canvas() and create_surface_from_offscreen_canvas() now take the canvas by value. By @daxpedda in #3690

Changes

General

• Added TextureFormatFeatureFlags::MULTISAMPLE_X16. By @Dinnerbone in #3454
• Added BufferUsages::QUERY_RESOLVE. By @JolifantoBambla in #3489
• Support stencil-only views and copying to/from combined depth-stencil textures. By @teoxoy in #3436
• Added Features::SHADER_EARLY_DEPTH_TEST. By @teoxoy in #3494
• All fxhash dependencies have been replaced with rustc-hash. By @james7132 in #3502
• Allow copying of textures with copy-compatible formats. By @teoxoy in #3528
• Improve attachment related errors. By @cwfitzgerald in #3549
• Make error descriptions all upper case. By @cwfitzgerald in #3549
• Don't include ANSI terminal color escape sequences in shader module validation error messages. By @jimblandy in #3591
• Report error messages from DXC compile. By @Davidster in #3632
• Error in native when using a filterable TextureSampleType::Float on a multisample BindingType::Texture. By @mockersf in #3686
• On Web, the size of the canvas is adjusted when using 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

WebGPU

• Implement the new checks for readonly stencils. By @JCapucho in #3443
• Reimplement adapter|device_features. By @jinleili in #3428
• Implement command_encoder_resolve_query_set. By @JolifantoBambla in #3489
• Add support for Features::RG11B10UFLOAT_RENDERABLE. By @mockersf in #3689

Vulkan

• Set max_memory_allocation_size via PhysicalDeviceMaintenance3Properties. By @jinleili in #3567
• Silence false-positive validation error about surface resizing. By @seabassjh in #3627

Bug Fixes

General

• copyTextureToTexture src/dst aspects must both refer to all aspects of src/dst format. By @teoxoy in #3431
• Validate before extracting texture selectors. By @teoxoy in #3487
• Fix fatal errors (those which panic even if an error handler is set) not including all of the details. By @kpreid in #3563
• Validate shader location clashes. By @emilk in #3613
• Fix surfaces not being dropped until exit. By @BenjaminSchaaf in #3647

WebGPU

• Fix handling of None values for depth_ops and stencil_ops in RenderPassDescriptor::depth_stencil_attachment. By @niklaskorz in #3660
• Avoid using WasmAbi functions for WebGPU backend. By @grovesNL in #3657

DX12

• Use typeless formats for textures that might be viewed as srgb or non-srgb. By @teoxoy in #3555

GLES

• Set FORCE_POINT_SIZE if it is vertex shader with mesh consist of point list. By @REASY in 3440
• Remove unwraps inside surface.configure. By @cwfitzgerald in #3585
• Fix 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
• Fix disabling of vertex attributes with non-consecutive locations. By @Azorlogh in #3706

Metal

• Fix metal erroring on an array_stride of 0. By @teoxoy in #3538
• create_texture returns an error if new_texture returns NULL. By @jinleili in #3554
• Fix shader bounds checking being ignored. By @FL33TW00D in #3603

Vulkan

• Treat VK_SUBOPTIMAL_KHR as VK_SUCCESS on Android due to rotation issues. By @James2022-rgb in #3525

Examples

• Use BufferUsages::QUERY_RESOLVE instead of BufferUsages::COPY_DST for buffers used in CommandEncoder::resolve_query_set calls in mipmap example. By @JolifantoBambla in #3489

v0.15.3

This was released as wgpu-hal version 0.15.4 due to a previous publishing issue. All other crates remain unbumped

Bug Fixes

Metal

• Fix incorrect mipmap being sampled when using MinLod <= 0.0 and MaxLod >= 32.0 or when the fragment shader samples different Lods in the same quad. By @cwfitzgerald in #3610.

GLES

• Fix 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
• Reset all queue state between command buffers in a submit. By @jleibs #3589
• Reset the state of SAMPLE_ALPHA_TO_COVERAGE on queue reset. By @jleibs #3589

v0.15.2

Bug Fixes

Metal

• Fix definition of NSOperatingSystemVersion to avoid potential crashes. By @grovesNL in #3557

GLES

• Enable WEBGL_debug_renderer_info before querying unmasked vendor/renderer to avoid crashing on emscripten by @coderedart in #3519

v0.15.1

Changes

General

• Fix for some minor issues in comments on some features. By @Wumpf in #3455

Vulkan

• Improve format MSAA capabilities detection. By @jinleili in #3429

DX12

• Update gpu allocator to 0.22. By @Elabajaba in #3447

WebGPU

• Implement CommandEncoder::clear_buffer. By @raphlinus in #3426

Bug Fixes

General

• Re-sort supported surface formats based on srgb-ness. By @cwfitzgerald in #3444

Vulkan

• Fix surface view formats validation error. By @jinleili in #3432

DX12

• Fix DXC validation issues when using a custom dxil_path. By @Elabajaba in #3434

GLES

• Unbind vertex buffers at end of renderpass. By @cwfitzgerald in #3459

WebGPU

• Reimplement {adapter|device}_features. By @jinleili in #3428

Documentation

General

• Build for WASM on docs.rs. By @daxpedda in #3462

v0.15.0

Major Changes

WGSL Top-Level let is now const

All 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.

Surface Capabilities API

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");

Fallible surface creation

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 WebAssembly

A 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

Instance creation now takes InstanceDescriptor instead of Backends

Instance::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

Texture Format Reinterpretation

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);

MSAA x2 and x8 Support

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

DXC Shader Compiler Support for DX12

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

Suballocate DX12 buffers and textures

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

Backend selection by features in wgpu-core

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:

• "metal", for the Metal API on macOS and iOS
• "vulkan", for the Vulkan API (Linux, some Android, and occasionally Windows)
• "dx12", for Microsoft's Direct3D 12 API
• "gles", OpenGL ES, available on many systems
• "dx11", for Microsoft's Direct3D 11 API

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.

Changes

General

• Convert all Default Implementations on Enums to derive(Default)
• Implement Default for CompositeAlphaMode
• New downlevel feature UNRESTRICTED_INDEX_BUFFER to indicate support for using INDEX together with other non-copy/map usages (unsupported on WebGL). By @Wumpf in #3157
• Add missing DEPTH_BIAS_CLAMP and FULL_DRAW_INDEX_UINT32 downlevel flags. By @teoxoy in #3316
• Combine 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
• Make Surface::get_default_config return an Option to prevent panics. By @cwfitzgerald in #3157
• Lower the max_buffer_size limit value for compatibility with Apple2 and WebGPU compliance. By @jinleili in #3255
• Limits min_uniform_buffer_offset_alignment and min_storage_buffer_offset_alignment is now always at least 32. By @Wumpf #3262
• Dereferencing a buffer view is now marked inline. By @Wumpf in #3307
• The strict_assert family of macros was moved to wgpu-types. By @i509VCB in #3051
• Make ObjectId structure and invariants idiomatic. By @teoxoy in #3347
• Add validation in accordance with WebGPU GPUSamplerDescriptor valid usage for lodMinClamp and lodMaxClamp. By @James2022-rgb in #3353
• Remove panics in Deref implementations for QueueWriteBufferView and BufferViewMut. Instead, warnings are logged, since reading from these types is not recommended. By @botahamec in [#3336]
• Implement view_formats in the TextureDescriptor to match the WebGPU spec. By @jinleili in #3237
• Show more information in error message for non-aligned buffer bindings in WebGL #3414
• Update TextureView validation according to the WebGPU spec. By @teoxoy in #3410
• Implement view_formats in the SurfaceConfiguration to match the WebGPU spec. By @jinleili in #3409

Vulkan

• Set `WE...