diff --git a/CHANGELOG.md b/CHANGELOG.md index 6af62698e..eccf6abe9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -182,7 +182,6 @@ By @sagudev in [#10307](https://github.com/gfx-rs/wgpu/pull/10307). - [`immediate_address_space`](https://www.w3.org/TR/WGSL/#language_extension-immediate_address_space) WGSL language extension is implemented. By @beicause in [#9711](https://github.com/gfx-rs/wgpu/pull/9711). - `TextureFormat::is_srgb()` has been renamed to `TextureFormat::has_srgb_suffix()` to clarify its function. By @kpreid in [#9758](https://github.com/gfx-rs/wgpu/pull/9758). - Remove the never-constructed `CreateBlasError::InvalidAabbStride` variant. `create_blas` takes no stride, so it could never be produced; AABB stride is validated at build time as `BuildAccelerationStructureError::InvalidAabbStride`. By @mstampfli in [#9935](https://github.com/gfx-rs/wgpu/pull/9935). - - Added `DownlevelFlags::LINEAR_INTERPOLATION`, indicating that the adapter supports `@interpolate(linear)`. It is absent on GLES/WebGL2, since GLSL ES has no `noperspective` qualifier. By @emilk in [#9972](https://github.com/gfx-rs/wgpu/pull/9972). - `Buffer::unmap` will not raise any validation errors anymore per specification. By @sagudev in [#10242](https://github.com/gfx-rs/wgpu/pull/10242). - `wgpu::Error::Validation::description` from `Device::create_shader_module` no longer include the shader source text and detailed compiler messages, per the WebGPU specification. These details remain accessible via `ShaderModule::get_compilation_info`. By @beicause and @sagudev in [#10173](https://github.com/gfx-rs/wgpu/pull/10173). @@ -190,6 +189,7 @@ By @sagudev in [#10307](https://github.com/gfx-rs/wgpu/pull/10307). - `ShaderStages` is now composed of `ShaderStagesWebGPU` and `ShaderStagesWGPU`, similarly to `Features`. In most cases this is not expected to be a breaking change, but changes might be required for converting `ShaderStages` to/from `u32`. By @sagudev in [#10313](https://github.com/gfx-rs/wgpu/pull/10313). - `request_adapter` will return error on `InstanceFlags::STRICT_WEBGPU_COMPLIANCE` if the adapter has already been consumed by a previous `request_device`. By @sagudev in [#10444](https://github.com/gfx-rs/wgpu/pull/10444). - The variants of `wgpu_core::validation::StageError` related to entry point selection have been reorganized. By @jimblandy in [#10544](https://github.com/gfx-rs/wgpu/pull/10544). +- `clear_texture` now rejects a request to clear only some aspects of a texture. Previously such a request would clear all aspects of the texture. By @andyleiserson in [#10684](https://github.com/gfx-rs/wgpu/pull/10684). #### naga diff --git a/wgpu-core/src/command/clear.rs b/wgpu-core/src/command/clear.rs index f5ec54719..3426d83f7 100644 --- a/wgpu-core/src/command/clear.rs +++ b/wgpu-core/src/command/clear.rs @@ -55,6 +55,11 @@ pub enum ClearError { texture_format: wgt::TextureFormat, subresource_range_aspects: TextureAspect, }, + #[error("Unable to selectively clear aspect {aspect:?} of format {format:?}. All aspects must be cleared.")] + InvalidClearAspect { + format: wgt::TextureFormat, + aspect: TextureAspect, + }, #[error("Image subresource level range is outside of the texture's level range. texture range is {texture_level_range:?}, \ whereas subesource range specified start {subresource_base_mip_level} and count {subresource_mip_level_count:?}")] InvalidTextureLevelRange { @@ -101,6 +106,7 @@ impl WebGpuError for ClearError { | Self::OffsetPlusSizeExceeds64BitBounds { .. } | Self::BufferOverrun { .. } | Self::MissingTextureAspect { .. } + | Self::InvalidClearAspect { .. } | Self::InvalidTextureLevelRange { .. } | Self::InvalidTextureLayerRange { .. } => ErrorType::Validation, } @@ -251,14 +257,21 @@ pub(super) fn clear_texture_cmd( .device .require_features(wgt::Features::CLEAR_TEXTURE)?; - // Check if subresource aspects are valid. + // Check that the clear targets all aspects, and no invalid aspects. let clear_aspects = hal::FormatAspects::new(dst_texture.desc.format, subresource_range.aspect); + let all_aspects = hal::FormatAspects::new(dst_texture.desc.format, TextureAspect::All); if clear_aspects.is_empty() { return Err(ClearError::MissingTextureAspect { texture_format: dst_texture.desc.format, subresource_range_aspects: subresource_range.aspect, }); - }; + } + if clear_aspects != all_aspects { + return Err(ClearError::InvalidClearAspect { + format: dst_texture.desc.format, + aspect: subresource_range.aspect, + }); + } // Check if subresource level range is valid let subresource_mip_range = subresource_range.mip_range(dst_texture.full_range.mips.end); diff --git a/wgpu/src/api/command_encoder.rs b/wgpu/src/api/command_encoder.rs index 112e11bad..c701ac92b 100644 --- a/wgpu/src/api/command_encoder.rs +++ b/wgpu/src/api/command_encoder.rs @@ -172,17 +172,21 @@ impl CommandEncoder { /// Clears texture to zero. /// - /// Note that unlike with clear_buffer, `COPY_DST` usage is not required. + /// Requires [`Features::CLEAR_TEXTURE`]. /// - /// # Implementation notes + /// Unlike [`Self::clear_buffer`], `COPY_DST` usage is not required. The + /// texture will be cleared either by buffer copies or by a render pass with + /// [`LoadOp::Clear`], depending on the texture format and enabled usages. /// - /// - implemented either via buffer copies and render/depth target clear, path depends on texture usages - /// - behaves like texture zero init, but is performed immediately (clearing is *not* delayed via marking it as uninitialized) + /// Unlike when `wgpu` internally marks a texture as uninitialized, the + /// clear will always occur at the point in the command stream where + /// `clear_texture` is called. It will not be deferred until a subsequent + /// operation reads data from the texture. /// - /// # Panics - /// - /// - `CLEAR_TEXTURE` extension not enabled - /// - Range is out of bounds + /// Although [`ImageSubresourceRange`] contains an `aspect` member, it must + /// either be [`wgt::TextureAspect::All`], or it must select all aspects of + /// the texture. Requesting to selectively clear only some aspects is an + /// error. pub fn clear_texture(&mut self, texture: &Texture, subresource_range: &ImageSubresourceRange) { self.inner.clear_texture(&texture.inner, subresource_range); }