Add support for transient textures on Vulkan and Metal

CHANGELOG.md

@@ -238,6 +238,8 @@ By @wumpf in [#8282](https://github.com/gfx-rs/wgpu/pull/8282), [#8285](https://
 
 - Expose `naga::front::wgsl::UnimplementedEnableExtension`. By @ErichDonGubler in [#8237](https://github.com/gfx-rs/wgpu/pull/8237).
 
+- Added support for transient textures on Vulkan and Metal. By @opstic in [#8247](https://github.com/gfx-rs/wgpu/pull/8247)
+
 ### Changes
 
 #### General

examples/features/src/msaa_line/mod.rs

@@ -112,7 +112,7 @@ impl Example {
             sample_count,
             dimension: wgpu::TextureDimension::D2,
             format: config.view_formats[0],
-            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
+            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TRANSIENT,
             label: None,
             view_formats: &[],
         };

examples/features/src/shadow/mod.rs

@@ -192,7 +192,7 @@ impl Example {
             sample_count: 1,
             dimension: wgpu::TextureDimension::D2,
             format: Self::DEPTH_FORMAT,
-            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
+            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TRANSIENT,
             label: None,
             view_formats: &[],
         });

examples/features/src/skybox/mod.rs

@@ -80,7 +80,7 @@ impl Example {
             sample_count: 1,
             dimension: wgpu::TextureDimension::D2,
             format: Self::DEPTH_FORMAT,
-            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
+            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TRANSIENT,
             label: None,
             view_formats: &[],
         });

tests/tests/wgpu-gpu/main.rs

@@ -64,6 +64,7 @@ mod texture_view_creation;
 mod timestamp_normalization;
 mod timestamp_query;
 mod transfer;
+mod transient;
 mod transition_resources;
 mod vertex_formats;
 mod vertex_indices;
@@ -135,6 +136,7 @@ fn all_tests() -> Vec<wgpu_test::GpuTestInitializer> {
     timestamp_normalization::all_tests(&mut tests);
     timestamp_query::all_tests(&mut tests);
     transfer::all_tests(&mut tests);
+    transient::all_tests(&mut tests);
     transition_resources::all_tests(&mut tests);
     vertex_formats::all_tests(&mut tests);
     vertex_indices::all_tests(&mut tests);

tests/tests/wgpu-gpu/transient.rs

@@ -0,0 +1,158 @@
+use wgpu_test::{gpu_test, GpuTestConfiguration, GpuTestInitializer, TestParameters};
+
+pub fn all_tests(vec: &mut Vec<GpuTestInitializer>) {
+    vec.push(RESOLVE_WITH_TRANSIENT);
+}
+
+#[gpu_test]
+static RESOLVE_WITH_TRANSIENT: GpuTestConfiguration = GpuTestConfiguration::new()
+    .parameters(TestParameters::default())
+    .run_async(|ctx| async move {
+        const SIZE: wgpu::Extent3d = wgpu::Extent3d {
+            width: 256,
+            height: 256,
+            depth_or_array_layers: 1,
+        };
+
+        let shader_src = "
+            @vertex
+            fn vs_main(@builtin(vertex_index) index: u32) -> @builtin(position) vec4f {
+                let positions: array<vec2f, 3> = array<vec2f, 3>(
+                    vec2f(-1.0, -1.0),
+                    vec2f(-1.0, 3.0),
+                    vec2f(3.0, -1.0)
+                );
+                return vec4f(positions[index], 0.0, 1.0);
+            }
+
+            @fragment
+            fn fs_main() -> @location(0) vec4f {
+                return vec4f(1.0);
+            }
+        ";
+
+        let shader = ctx
+            .device
+            .create_shader_module(wgpu::ShaderModuleDescriptor {
+                label: None,
+                source: wgpu::ShaderSource::Wgsl(shader_src.into()),
+            });
+
+        let pipeline_desc = wgpu::RenderPipelineDescriptor {
+            label: None,
+            layout: None,
+            vertex: wgpu::VertexState {
+                buffers: &[],
+                module: &shader,
+                entry_point: Some("vs_main"),
+                compilation_options: Default::default(),
+            },
+            primitive: wgpu::PrimitiveState::default(),
+            depth_stencil: None,
+            multisample: wgpu::MultisampleState {
+                count: 4,
+                mask: !0,
+                alpha_to_coverage_enabled: false,
+            },
+            fragment: Some(wgpu::FragmentState {
+                module: &shader,
+                entry_point: Some("fs_main"),
+                compilation_options: Default::default(),
+                targets: &[Some(wgpu::ColorTargetState {
+                    format: wgpu::TextureFormat::Rgba8Unorm,
+                    blend: None,
+                    write_mask: wgpu::ColorWrites::ALL,
+                })],
+            }),
+            multiview: None,
+            cache: None,
+        };
+        let pipeline = ctx.device.create_render_pipeline(&pipeline_desc);
+
+        let transient_texture = ctx.device.create_texture(&wgpu::TextureDescriptor {
+            label: None,
+            size: SIZE,
+            mip_level_count: 1,
+            sample_count: 4,
+            dimension: wgpu::TextureDimension::D2,
+            format: wgpu::TextureFormat::Rgba8Unorm,
+            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TRANSIENT,
+            view_formats: &[],
+        });
+
+        let target_texture = ctx.device.create_texture(&wgpu::TextureDescriptor {
+            label: None,
+            size: SIZE,
+            mip_level_count: 1,
+            sample_count: 1,
+            dimension: wgpu::TextureDimension::D2,
+            format: wgpu::TextureFormat::Rgba8Unorm,
+            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
+            view_formats: &[],
+        });
+
+        let readback_buffer = ctx.device.create_buffer(&wgpu::BufferDescriptor {
+            label: None,
+            size: 256 * 256 * 4,
+            usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
+            mapped_at_creation: false,
+        });
+
+        let mut encoder = ctx
+            .device
+            .create_command_encoder(&wgpu::CommandEncoderDescriptor::default());
+
+        {
+            let mut rpass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+                label: None,
+                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
+                    view: &transient_texture.create_view(&wgpu::TextureViewDescriptor::default()),
+                    depth_slice: None,
+                    resolve_target: Some(
+                        &target_texture.create_view(&wgpu::TextureViewDescriptor::default()),
+                    ),
+                    ops: wgpu::Operations {
+                        load: wgpu::LoadOp::Clear(wgpu::Color::TRANSPARENT),
+                        store: wgpu::StoreOp::Discard,
+                    },
+                })],
+                depth_stencil_attachment: None,
+                timestamp_writes: None,
+                occlusion_query_set: None,
+            });
+
+            rpass.set_pipeline(&pipeline);
+            rpass.draw(0..3, 0..1);
+        }
+
+        encoder.copy_texture_to_buffer(
+            wgpu::TexelCopyTextureInfo {
+                texture: &target_texture,
+                mip_level: 0,
+                origin: wgpu::Origin3d { x: 0, y: 0, z: 0 },
+                aspect: wgpu::TextureAspect::All,
+            },
+            wgpu::TexelCopyBufferInfo {
+                buffer: &readback_buffer,
+                layout: wgpu::TexelCopyBufferLayout {
+                    offset: 0,
+                    bytes_per_row: Some(256 * 4),
+                    rows_per_image: Some(256),
+                },
+            },
+            SIZE,
+        );
+
+        ctx.queue.submit([encoder.finish()]);
+
+        let slice = readback_buffer.slice(..);
+        slice.map_async(wgpu::MapMode::Read, |_| ());
+
+        ctx.async_poll(wgpu::PollType::wait_indefinitely())
+            .await
+            .unwrap();
+
+        let data = slice.get_mapped_range();
+        let succeeded = data.iter().all(|b| *b == u8::MAX);
+        assert!(succeeded);
+    });

tests/tests/wgpu-validation/api/texture.rs

@@ -508,3 +508,106 @@ fn copy_buffer_to_texture_forbidden_format_aspect() {
         );
     }
 }
+
+/// Ensures that attempting to create a texture with [`wgpu::TextureUsages::TRANSIENT`]
+/// and its unsupported usages fails validation.
+#[test]
+fn transient_invalid_usage() {
+    let (device, _queue) = wgpu::Device::noop(&wgpu::DeviceDescriptor::default());
+
+    let size = wgpu::Extent3d {
+        width: 256,
+        height: 256,
+        depth_or_array_layers: 1,
+    };
+
+    let invalid_usages = wgpu::TextureUsages::all()
+        - wgpu::TextureUsages::RENDER_ATTACHMENT
+        - wgpu::TextureUsages::TRANSIENT;
+
+    for usage in invalid_usages {
+        let invalid_texture_descriptor = wgpu::TextureDescriptor {
+            label: None,
+            size,
+            mip_level_count: 1,
+            sample_count: 1,
+            dimension: wgpu::TextureDimension::D2,
+            format: wgpu::TextureFormat::Rgba8Unorm,
+            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TRANSIENT | usage,
+            view_formats: &[],
+        };
+        fail(
+            &device,
+            || device.create_texture(&invalid_texture_descriptor),
+            Some(&format!("Texture usage TextureUsages(TRANSIENT) is not compatible with texture usage {usage:?}")),
+        );
+    }
+
+    let invalid_texture_descriptor = wgpu::TextureDescriptor {
+        label: None,
+        size,
+        mip_level_count: 1,
+        sample_count: 1,
+        dimension: wgpu::TextureDimension::D2,
+        format: wgpu::TextureFormat::Rgba8Unorm,
+        usage: wgpu::TextureUsages::TRANSIENT,
+        view_formats: &[],
+    };
+    fail(
+        &device,
+        || device.create_texture(&invalid_texture_descriptor),
+        Some("Invalid usage flags TextureUsages(TRANSIENT)"),
+    );
+}
+
+/// Ensures that attempting to use a texture of [`wgpu::TextureUsages::TRANSIENT`]
+/// with [`wgpu::StoreOp::Store`] fails validation.
+#[test]
+fn transient_invalid_storeop() {
+    let (device, _queue) = wgpu::Device::noop(&wgpu::DeviceDescriptor::default());
+
+    let size = wgpu::Extent3d {
+        width: 256,
+        height: 256,
+        depth_or_array_layers: 1,
+    };
+
+    let transient_texture = device.create_texture(&wgpu::TextureDescriptor {
+        label: None,
+        size,
+        mip_level_count: 1,
+        sample_count: 1,
+        dimension: wgpu::TextureDimension::D2,
+        format: wgpu::TextureFormat::Rgba8Unorm,
+        usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TRANSIENT,
+        view_formats: &[],
+    });
+
+    fail(
+        &device,
+        || {
+            let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: None });
+
+            let invalid_render_pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+                label: None,
+                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
+                    view: &transient_texture.create_view(&wgpu::TextureViewDescriptor::default()),
+                    depth_slice: None,
+                    resolve_target: None,
+                    ops: wgpu::Operations {
+                        load: wgpu::LoadOp::Clear(wgpu::Color::TRANSPARENT),
+                        store: wgpu::StoreOp::Store,
+                    },
+                })],
+                depth_stencil_attachment: None,
+                timestamp_writes: None,
+                occlusion_query_set: None,
+            });
+
+            drop(invalid_render_pass);
+
+            encoder.finish()
+        },
+      Some("Color attachment's usage contains TextureUsages(TRANSIENT). This can only be used with StoreOp::Discard, but StoreOp::Store was provided")
+    );
+}

wgpu-core/src/command/render.rs

@@ -629,6 +629,8 @@ pub enum ColorAttachmentError {
         mip_level: u32,
         depth_or_array_layer: u32,
     },
+    #[error("Color attachment's usage contains {0:?}. This can only be used with StoreOp::{1:?}, but StoreOp::{2:?} was provided")]
+    InvalidUsageForStoreOp(TextureUsages, StoreOp, StoreOp),
 }
 
 impl WebGpuError for ColorAttachmentError {
@@ -1585,6 +1587,18 @@ impl Global {
                     let view = texture_views.get(*view_id).get()?;
                     view.same_device(device)?;
 
+                    if view.desc.usage.contains(TextureUsages::TRANSIENT)
+                        && *store_op != StoreOp::Discard
+                    {
+                        return Err(RenderPassErrorInner::ColorAttachment(
+                            ColorAttachmentError::InvalidUsageForStoreOp(
+                                TextureUsages::TRANSIENT,
+                                StoreOp::Discard,
+                                *store_op,
+                            ),
+                        ));
+                    }
+
                     let resolve_target = if let Some(resolve_target_id) = resolve_target {
                         let rt_arc = texture_views.get(*resolve_target_id).get()?;
                         rt_arc.same_device(device)?;

wgpu-core/src/conv.rs

@@ -124,6 +124,10 @@ pub fn map_texture_usage(
         wgt::TextureUses::STORAGE_ATOMIC,
         usage.contains(wgt::TextureUsages::STORAGE_ATOMIC),
     );
+    u.set(
+        wgt::TextureUses::TRANSIENT,
+        usage.contains(wgt::TextureUsages::TRANSIENT),
+    );
     u
 }
 
@@ -183,6 +187,10 @@ pub fn map_texture_usage_from_hal(uses: wgt::TextureUses) -> wgt::TextureUsages
         wgt::TextureUsages::STORAGE_ATOMIC,
         uses.contains(wgt::TextureUses::STORAGE_ATOMIC),
     );
+    u.set(
+        wgt::TextureUsages::TRANSIENT,
+        uses.contains(wgt::TextureUses::TRANSIENT),
+    );
     u
 }
 

wgpu-core/src/device/resource.rs

@@ -1274,6 +1274,22 @@ impl Device {
             }
         }
 
+        if desc.usage.contains(wgt::TextureUsages::TRANSIENT) {
+            if !desc.usage.contains(wgt::TextureUsages::RENDER_ATTACHMENT) {
+                return Err(CreateTextureError::InvalidUsage(
+                    wgt::TextureUsages::TRANSIENT,
+                ));
+            }
+            let extra_usage =
+                desc.usage - wgt::TextureUsages::TRANSIENT - wgt::TextureUsages::RENDER_ATTACHMENT;
+            if !extra_usage.is_empty() {
+                return Err(CreateTextureError::IncompatibleUsage(
+                    wgt::TextureUsages::TRANSIENT,
+                    extra_usage,
+                ));
+            }
+        }
+
         let format_features = self
             .describe_format_features(desc.format)
             .map_err(|error| CreateTextureError::MissingFeatures(desc.format, error))?;

wgpu-core/src/instance.rs

@@ -699,7 +699,7 @@ impl Adapter {
             ),
         );
         allowed_usages.set(
-            wgt::TextureUsages::RENDER_ATTACHMENT,
+            wgt::TextureUsages::RENDER_ATTACHMENT | wgt::TextureUsages::TRANSIENT,
             caps.intersects(Tfc::COLOR_ATTACHMENT | Tfc::DEPTH_STENCIL_ATTACHMENT),
         );
         allowed_usages.set(