CLEAR_COMMANDS extension is now more of a window into wgpu zero-init

Wumpf · Wumpf · commit 127cbab6bdbb · 2021-11-09T21:34:08.000+01:00
this has mostly implications on the constraints, but also allows a more leaky documentation which makes sense for this non-standard function as there is no other place to look it up
diff --git a/wgpu-core/src/command/clear.rs b/wgpu-core/src/command/clear.rs
@@ -41,7 +41,7 @@ pub enum ClearError {
         end_offset: BufferAddress,
         buffer_size: BufferAddress,
     },
-    #[error("destination buffer/texture is missing the `COPY_DST` usage flag")]
+    #[error("destination buffer is missing the `COPY_DST` usage flag")]
     MissingCopyDstUsageFlag(Option<BufferId>, Option<TextureId>),
     #[error("texture lacks the aspects that were specified in the image subresource range. Texture with format {texture_format:?}, specified was {subresource_range_aspects:?}")]
     MissingTextureAspect {
@@ -250,9 +250,6 @@ impl<G: GlobalIdentityHandlerFactory> Global<G> {
             .inner
             .as_raw()
             .ok_or(ClearError::InvalidTexture(dst))?;
-        if !dst_texture.desc.usage.contains(TextureUsages::COPY_DST) {
-            return Err(ClearError::MissingCopyDstUsageFlag(None, Some(dst)));
-        }
 
         // actual hal barrier & operation
         let dst_barrier = dst_pending.map(|pending| pending.into_hal(dst_texture));
diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs
@@ -2337,12 +2337,16 @@ impl CommandEncoder {
 
     /// Clears texture to zero.
     ///
-    /// Where possible it may be significantly more efficient to perform clears via render passes!
+    /// Note that unlike with clear_buffer, `COPY_DST` usage is not required.
+    ///
+    /// # Implementation notes
+    ///
+    /// - implemented either via buffer copies, render/depth target clear
+    /// - behaves like texture zero init, but is performed immediately (clearing is *not* delayed via marking it as uninitialized)
     ///
     /// # Panics
     ///
     /// - `CLEAR_COMMANDS` extension not enabled
-    /// - Texture does not have `COPY_DST` usage.
     /// - Range is out of bounds
     pub fn clear_texture(&mut self, texture: &Texture, subresource_range: &ImageSubresourceRange) {
         Context::command_encoder_clear_texture(
@@ -2355,6 +2359,12 @@ impl CommandEncoder {
 
     /// Clears buffer to zero.
     ///
+    /// # Implementation notes
+    ///
+    /// - implemented via backend specific function which may be emulated with buffer copies
+    /// - behaves like delayed buffer zero init (i.e. lazy zero init for buffers that weren't mapped at creation),
+    ///   but is performed immediately (clearing is *not* delayed via marking it as uninitialized)
+    ///
     /// # Panics
     ///
     /// - `CLEAR_COMMANDS` extension not enabled
diff --git a/wgpu/tests/clear_texture.rs b/wgpu/tests/clear_texture.rs
@@ -131,7 +131,9 @@ fn single_texture_clear_test(
         sample_count: 1, // multisampling is not supported for clear
         dimension,
         format,
-        usage: wgpu::TextureUsages::COPY_DST,
+        // Forces internally the required usages to be able to clear it.
+        // This is not visible on the API level.
+        usage: wgpu::TextureUsages::TEXTURE_BINDING,
     });
     let mut encoder = ctx
         .device
