From 33d313cba91041852d02b5e382ddec358014b4d9 Mon Sep 17 00:00:00 2001
From: Jim Blandy <jimb@red-bean.com>
Date: Sat, 13 Aug 2022 17:35:57 -0700
Subject: [PATCH] Document some wgpu-core resource tracking types (#2960)

---
 wgpu-core/src/device/queue.rs | 28 ++++++++++++++++++++++++++++
 wgpu-core/src/resource.rs     | 19 +++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/wgpu-core/src/device/queue.rs b/wgpu-core/src/device/queue.rs
index 4bfcd3fa28..102f59fdaa 100644
--- a/wgpu-core/src/device/queue.rs
+++ b/wgpu-core/src/device/queue.rs
@@ -86,6 +86,19 @@ pub struct WrappedSubmissionIndex {
     pub index: SubmissionIndex,
 }
 
+/// A texture or buffer to be freed soon.
+///
+/// This is just a tagged raw texture or buffer, generally about to be added to
+/// some other more specific container like:
+///
+/// - `PendingWrites::temp_resources`: resources used by queue writes and
+///   unmaps, waiting to be folded in with the next queue submission
+///
+/// - `ActiveSubmission::last_resources`: temporary resources used by a queue
+///   submission, to be freed when it completes
+///
+/// - `LifetimeTracker::free_resources`: resources to be freed in the next
+///   `maintain` call, no longer used anywhere
 #[derive(Debug)]
 pub enum TempResource<A: hal::Api> {
     Buffer(A::Buffer),
@@ -105,6 +118,19 @@ impl<A: hal::Api> EncoderInFlight<A> {
     }
 }
 
+/// Writes made directly on the device or queue, not as part of a wgpu command buffer.
+///
+/// Operations like `buffer_unmap`, `queue_write_buffer`, and
+/// `queue_write_texture` need to copy data to the GPU. This must be
+/// done by encoding and submitting commands at the hal level, but these
+/// operations are not associated with any specific wgpu command buffer.
+///
+/// Instead, `Device::pending_writes` owns one of these values, which has its
+/// own hal command encoder and resource lists. The commands accumulated here
+/// are automatically submitted to the queue the next time the user submits a
+/// wgpu command buffer, ahead of the user's commands.
+///
+/// All uses of [`StagingBuffer`]s end up here.
 #[derive(Debug)]
 pub(crate) struct PendingWrites<A: hal::Api> {
     pub command_encoder: A::CommandEncoder,
@@ -1082,6 +1108,8 @@ impl<G: GlobalIdentityHandlerFactory> Global<G> {
                 Err(WaitIdleError::WrongSubmissionIndex(..)) => unreachable!(),
             };
 
+            // pending_write_resources has been drained, so it's empty, but we
+            // want to retain its heap allocation.
             device.pending_writes.temp_resources = pending_write_resources;
             device.temp_suspected.clear();
             device.lock_life(&mut token).post_submit();
diff --git a/wgpu-core/src/resource.rs b/wgpu-core/src/resource.rs
index 0c574d7665..1721d41de2 100644
--- a/wgpu-core/src/resource.rs
+++ b/wgpu-core/src/resource.rs
@@ -224,6 +224,25 @@ impl<A: hal::Api> Resource for Buffer<A> {
     }
 }
 
+/// A temporary buffer, consumed by the command that uses it.
+///
+/// A [`StagingBuffer`] is designed for one-shot uploads of data to the GPU. It
+/// is always created mapped, and the command that uses it destroys the buffer
+/// when it is done.
+///
+/// [`StagingBuffer`]s can be created with [`queue_create_staging_buffer`] and
+/// used with [`queue_write_staging_buffer`]. They are also used internally by
+/// operations like [`queue_write_texture`] that need to upload data to the GPU,
+/// but that don't belong to any particular wgpu command buffer.
+///
+/// Used `StagingBuffer`s are accumulated in [`Device::pending_writes`], to be
+/// freed once their associated operation's queue submission has finished
+/// execution.
+///
+/// [`queue_create_staging_buffer`]: Global::queue_create_staging_buffer
+/// [`queue_write_staging_buffer`]: Global::queue_write_staging_buffer
+/// [`queue_write_texture`]: Global::queue_write_texture
+/// [`Device::pending_writes`]: crate::device::Device
 pub struct StagingBuffer<A: hal::Api> {
     pub(crate) raw: A::Buffer,
     pub(crate) size: wgt::BufferAddress,