Transition resources

CHANGELOG.md

@@ -120,6 +120,7 @@ By @ErichDonGubler in [#6456](https://github.com/gfx-rs/wgpu/pull/6456), [#6148]
 - Return submission index in `map_async` and `on_submitted_work_done` to track down completion of async callbacks. By @eliemichel in [#6360](https://github.com/gfx-rs/wgpu/pull/6360).
 - Move raytracing alignments into HAL instead of in core. By @Vecvec in [#6563](https://github.com/gfx-rs/wgpu/pull/6563).
 - Allow for statically linking DXC rather than including separate `.dll` files. By @DouglasDwyer in [#6574](https://github.com/gfx-rs/wgpu/pull/6574).
+- Added `CommandEncoder::transition_resources()` for native API interop, and allowing users to slightly optimize barriers. By @JMS55 in [6678](https://github.com/gfx-rs/wgpu/pull/6678).
 
 ### Changes
 

tests/tests/root.rs

@@ -49,6 +49,8 @@ mod subgroup_operations;
 mod texture_bounds;
 mod texture_view_creation;
 mod transfer;
+#[cfg(all(feature = "wgc", feature = "hal"))]
+mod transition_resources;
 mod vertex_formats;
 mod vertex_indices;
 mod write_texture;

tests/tests/transition_resources.rs

@@ -0,0 +1,39 @@
+use wgpu::{hal::TextureUses, TextureTransition};
+use wgpu_test::{gpu_test, GpuTestConfiguration};
+use wgt::{
+    CommandEncoderDescriptor, Extent3d, TextureDescriptor, TextureDimension, TextureFormat,
+    TextureUsages,
+};
+
+#[gpu_test]
+static TRANSITION_RESOURCES: GpuTestConfiguration = GpuTestConfiguration::new().run_sync(|ctx| {
+    let texture = ctx.device.create_texture(&TextureDescriptor {
+        label: None,
+        size: Extent3d {
+            width: 32,
+            height: 32,
+            depth_or_array_layers: 1,
+        },
+        mip_level_count: 1,
+        sample_count: 1,
+        dimension: TextureDimension::D2,
+        format: TextureFormat::Rgba8Unorm,
+        usage: TextureUsages::RENDER_ATTACHMENT | TextureUsages::TEXTURE_BINDING,
+        view_formats: &[],
+    });
+
+    let mut encoder = ctx
+        .device
+        .create_command_encoder(&CommandEncoderDescriptor { label: None });
+
+    encoder.transition_resources(
+        &[],
+        &[TextureTransition {
+            texture: &texture,
+            selector: None,
+            state: TextureUses::COLOR_TARGET,
+        }],
+    );
+
+    ctx.queue.submit([encoder.finish()]);
+});

wgpu-core/src/command/mod.rs

@@ -12,6 +12,7 @@ mod render;
 mod render_command;
 mod timestamp_writes;
 mod transfer;
+mod transition_resources;
 
 use std::mem::{self, ManuallyDrop};
 use std::sync::Arc;

wgpu-core/src/command/transition_resources.rs

@@ -0,0 +1,87 @@
+use hal::{BufferUses, TextureUses};
+use thiserror::Error;
+
+use crate::{
+    command::CommandBuffer,
+    device::DeviceError,
+    global::Global,
+    id::{BufferId, CommandEncoderId, TextureId},
+    resource::{InvalidResourceError, ParentDevice},
+    track::{ResourceUsageCompatibilityError, TextureSelector},
+};
+
+use super::CommandEncoderError;
+
+impl Global {
+    pub fn command_encoder_transition_resources(
+        &self,
+        command_encoder_id: CommandEncoderId,
+        buffer_transitions: impl Iterator<Item = (BufferId, BufferUses)>,
+        texture_transitions: impl Iterator<Item = (TextureId, Option<TextureSelector>, TextureUses)>,
+    ) -> Result<(), TransitionResourcesError> {
+        profiling::scope!("CommandEncoder::transition_resources");
+
+        let hub = &self.hub;
+
+        // Lock command encoder for recording
+        let cmd_buf = hub
+            .command_buffers
+            .get(command_encoder_id.into_command_buffer_id());
+        let mut cmd_buf_data = cmd_buf.data.lock();
+        let mut cmd_buf_data_guard = cmd_buf_data.record()?;
+        let cmd_buf_data = &mut *cmd_buf_data_guard;
+
+        // Get and lock device
+        let device = &cmd_buf.device;
+        device.check_is_valid()?;
+        let snatch_guard = &device.snatchable_lock.read();
+
+        let mut usage_scope = device.new_usage_scope();
+
+        // Process buffer transitions
+        for (buffer_id, state) in buffer_transitions {
+            let buffer = hub.buffers.get(buffer_id).get()?;
+            buffer.same_device_as(cmd_buf.as_ref())?;
+
+            usage_scope.buffers.merge_single(&buffer, state)?;
+        }
+
+        // Process texture transitions
+        for (texture_id, selector, state) in texture_transitions {
+            let texture = hub.textures.get(texture_id).get()?;
+            texture.same_device_as(cmd_buf.as_ref())?;
+
+            unsafe {
+                usage_scope
+                    .textures
+                    .merge_single(&texture, selector.clone(), state)
+            }?;
+        }
+
+        // Record any needed barriers based on tracker data
+        let cmd_buf_raw = cmd_buf_data.encoder.open(device)?;
+        CommandBuffer::insert_barriers_from_scope(
+            cmd_buf_raw,
+            &mut cmd_buf_data.trackers,
+            &usage_scope,
+            snatch_guard,
+        );
+        cmd_buf_data_guard.mark_successful();
+
+        Ok(())
+    }
+}
+
+/// Error encountered while attempting to perform [`Global::command_encoder_transition_resources`].
+#[derive(Clone, Debug, Error)]
+#[non_exhaustive]
+pub enum TransitionResourcesError {
+    #[error(transparent)]
+    Device(#[from] DeviceError),
+    #[error(transparent)]
+    Encoder(#[from] CommandEncoderError),
+    #[error(transparent)]
+    InvalidResource(#[from] InvalidResourceError),
+    #[error(transparent)]
+    ResourceUsage(#[from] ResourceUsageCompatibilityError),
+}

wgpu-core/src/lib.rs

@@ -92,6 +92,7 @@ pub mod validation;
 
 pub use hal::{api, MAX_BIND_GROUPS, MAX_COLOR_ATTACHMENTS, MAX_VERTEX_BUFFERS};
 pub use naga;
+pub use track::texture::TextureSelector;
 
 use std::{borrow::Cow, os::raw::c_char};
 

wgpu-core/src/track/mod.rs

@@ -100,7 +100,7 @@ mod metadata;
 mod range;
 mod ray_tracing;
 mod stateless;
-mod texture;
+pub(crate) mod texture;
 
 use crate::{
     binding_model, command,
@@ -643,7 +643,7 @@ impl Tracker {
     /// bind group as a source of which IDs to look at. The bind groups
     /// must have first been added to the usage scope.
     ///
-    /// Only stateful things are merged in herell other resources are owned
+    /// Only stateful things are merged in here, all other resources are owned
     /// indirectly by the bind group.
     ///
     /// # Safety

wgpu/src/api/command_encoder.rs

@@ -346,4 +346,86 @@ impl CommandEncoder {
             &mut tlas.into_iter(),
         );
     }
+
+    /// Transition resources to an underlying hal resource state.
+    ///
+    /// This is an advanced, native-only API that has two main use cases:
+    ///
+    /// # Batching Barriers
+    ///
+    /// Wgpu does not have a global view of the frame when recording command buffers. When you submit multiple command buffers in a single queue submission, wgpu may need to record and
+    /// insert new command buffers (holding 1 or more barrier commands) in between the user-supplied command buffers in order to ensure that resources are transitioned to the correct state
+    /// for the start of the next user-supplied command buffer.
+    ///
+    /// Wgpu does not currently attempt to batch multiple of these generated command buffers/barriers together, which may lead to suboptimal barrier placement.
+    ///
+    /// Consider the following scenario, where the user does `queue.submit(&[a, b, c])`:
+    /// * CommandBuffer A: Use resource X as a render pass attachment
+    /// * CommandBuffer B: Use resource Y as a render pass attachment
+    /// * CommandBuffer C: Use resources X and Y in a bind group
+    ///
+    /// At submission time, wgpu will record and insert some new command buffers, resulting in a submission that looks like `queue.submit(&[0, a, 1, b, 2, c])`:
+    /// * CommandBuffer 0: Barrier to transition resource X from TextureUses::RESOURCE (from last frame) to TextureUses::COLOR_TARGET
+    /// * CommandBuffer A: Use resource X as a render pass attachment
+    /// * CommandBuffer 1: Barrier to transition resource Y from TextureUses::RESOURCE (from last frame) to TextureUses::COLOR_TARGET
+    /// * CommandBuffer B: Use resource Y as a render pass attachment
+    /// * CommandBuffer 2: Barrier to transition resources X and Y from TextureUses::COLOR_TARGET to TextureUses::RESOURCE
+    /// * CommandBuffer C: Use resources X and Y in a bind group
+    ///
+    /// To prevent this, after profiling their app, an advanced user might choose to instead do `queue.submit(&[a, b, c])`:
+    /// * CommandBuffer A:
+    ///     * Use [`CommandEncoder::transition_resources`] to transition resources X and Y from TextureUses::RESOURCE (from last frame) to TextureUses::COLOR_TARGET
+    ///     * Use resource X as a render pass attachment
+    /// * CommandBuffer B: Use resource Y as a render pass attachment
+    /// * CommandBuffer C:
+    ///     * Use [`CommandEncoder::transition_resources`] to transition resources X and Y from TextureUses::COLOR_TARGET to TextureUses::RESOURCE
+    ///     * Use resources X and Y in a bind group
+    ///
+    /// At submission time, wgpu will record and insert some new command buffers, resulting in a submission that looks like `queue.submit(&[0, a, b, 1, c])`:
+    /// * CommandBuffer 0: Barrier to transition resources X and Y from TextureUses::RESOURCE (from last frame) to TextureUses::COLOR_TARGET
+    /// * CommandBuffer A: Use resource X as a render pass attachment
+    /// * CommandBuffer B: Use resource Y as a render pass attachment
+    /// * CommandBuffer 1: Barrier to transition resources X and Y from TextureUses::COLOR_TARGET to TextureUses::RESOURCE
+    /// * CommandBuffer C: Use resources X and Y in a bind group
+    ///
+    /// Which eliminates the extra command buffer and barrier between command buffers A and B.
+    ///
+    /// # Native Interoperability
+    ///
+    /// A user wanting to interoperate with the underlying native graphics APIs (Vulkan, DirectX12, Metal, etc) can use this API to generate barriers between wgpu commands and
+    /// the native API commands, for synchronization and resource state transition purposes.
+    #[cfg(wgpu_core)]
+    pub fn transition_resources(
+        &mut self,
+        buffer_transitions: &[BufferTransition<'_>],
+        texture_transitions: &[TextureTransition<'_>],
+    ) {
+        if let Some(encoder) = self.inner.as_core_mut_opt() {
+            encoder.transition_resources(buffer_transitions, texture_transitions);
+        }
+    }
+}
+
+/// A buffer transition for use with [`CommandEncoder::transition_resources`].
+#[cfg(wgpu_core)]
+#[derive(Debug)]
+pub struct BufferTransition<'a> {
+    /// The buffer to transition.
+    pub buffer: &'a Buffer,
+    /// The new state to transition to.
+    pub state: hal::BufferUses,
+}
+
+/// A texture transition for use with [`CommandEncoder::transition_resources`].
+#[cfg(wgpu_core)]
+#[derive(Debug)]
+pub struct TextureTransition<'a> {
+    /// The texture to transition.
+    pub texture: &'a Texture,
+    /// An optional selector to transition only part of the texture.
+    ///
+    /// If None, the entire texture will be transitioned.
+    pub selector: Option<wgc::TextureSelector>,
+    /// The new state to transition to.
+    pub state: hal::TextureUses,
 }

wgpu/src/backend/wgpu_core.rs

@@ -2551,6 +2551,32 @@ impl dispatch::CommandEncoderInterface for CoreCommandEncoder {
     }
 }
 
+impl CoreCommandEncoder {
+    pub fn transition_resources(
+        &mut self,
+        buffer_transitions: &[crate::BufferTransition<'_>],
+        texture_transitions: &[crate::TextureTransition<'_>],
+    ) {
+        let result = self.context.0.command_encoder_transition_resources(
+            self.id,
+            buffer_transitions
+                .iter()
+                .map(|t| (t.buffer.inner.as_core().id, t.state)),
+            texture_transitions
+                .iter()
+                .map(|t| (t.texture.inner.as_core().id, t.selector.clone(), t.state)),
+        );
+
+        if let Err(cause) = result {
+            self.context.handle_error_nolabel(
+                &self.error_sink,
+                cause,
+                "CommandEncoder::transition_resources",
+            );
+        }
+    }
+}
+
 impl Drop for CoreCommandEncoder {
     fn drop(&mut self) {
         if self.open {