more comments about buffer sizes

Author: andyleiserson

wgpu-core/src/device/resource.rs

@@ -1253,7 +1253,8 @@ impl Device {
             .map_err(|e| self.handle_hal_error_with_nonfatal_oom(e))?;
 
         let timestamp_normalization_bind_group = Snatchable::new(unsafe {
-            // SAFETY: The size passed here must not overflow the buffer.
+            // SAFETY: The size passed here must be 4B aligned, >= the application size, and
+            // <= the buffer size.
             self.timestamp_normalizer
                 .get()
                 .unwrap()
@@ -1592,7 +1593,8 @@ impl Device {
     /// # Safety
     ///
     /// - `hal_buffer` must have been created on this device.
-    /// - `hal_buffer` must have been created respecting `desc` (in particular, the size).
+    /// - `hal_buffer` must have been created respecting `desc` (in particular, the size,
+    ///   which must always be a multiple of 4, and may be subject to other requirements).
     /// - `hal_buffer` must be initialized.
     /// - `hal_buffer` must not have zero size.
     pub(crate) unsafe fn create_buffer_from_hal_inner(
@@ -1601,6 +1603,8 @@ impl Device {
         desc: &resource::BufferDescriptor,
     ) -> Result<Arc<Buffer>, resource::CreateBufferError> {
         let timestamp_normalization_bind_group = Snatchable::new(unsafe {
+            // SAFETY: The size passed here must be 4B aligned, >= the application size, and
+            // <= the buffer size.
             self.timestamp_normalizer
                 .get()
                 .unwrap()
@@ -1650,6 +1654,10 @@ impl Device {
         Ok(buffer)
     }
 
+    /// If needed, creates the bind groups for indirect validation shaders to read
+    /// from `raw_buffer`.
+    ///
+    /// `buffer_size` is the user-requested size of the buffer.
     fn create_indirect_validation_bind_groups(
         &self,
         raw_buffer: &dyn hal::DynBuffer,

wgpu-core/src/indirect_validation/mod.rs

@@ -74,6 +74,10 @@ pub(crate) struct BindGroups {
 }
 
 impl BindGroups {
+    /// Creates the bind groups for indirect validation shaders to read from `buffer`.
+    ///
+    /// `buffer_size` is the user-requested size of the buffer.
+    ///
     /// `Ok(None)` will only be returned if `buffer_size` is `0`.
     pub(crate) fn new(
         indirect_validation: &IndirectValidation,

wgpu-core/src/timestamp_normalization/mod.rs

@@ -253,8 +253,16 @@ impl TimestampNormalizer {
 
     /// Create a bind group for normalizing timestamps in `buffer`.
     ///
-    /// This function is unsafe because it does not know that `buffer_size` is
-    /// the true size of the buffer.
+    /// `buffer_size` must be 4B-aligned, so that it is valid as a storage binding,
+    /// must be the same or more than the application-visible buffer size, and must
+    /// not overrun the buffer. This function is unsafe because it does not know and
+    /// cannot check whether `buffer_size` meets these requirements.
+    ///
+    /// The buffer size passed here is used to construct a binding that must be
+    /// able to access the full application-visible range of the buffer. It is
+    /// not used to check the destination range of query resolution requests. That
+    /// uses the application-requested buffer size, obtained from the `wgpu_core`
+    /// `Buffer`.
     pub unsafe fn create_normalization_bind_group(
         &self,
         device: &Device,