[naga spv-out] Consolidate explanation of global wrapping.

Consolidate the explanation of why and how we wrap Naga global
variables in structs to satisfy Vulkan's requirements, and include it
in the documentation for `back::spv::GlobalVariable`.

Clarify `GlobalVariable`'s members documentation.

Author: jimblandy

naga/src/back/spv/helpers.rs

@@ -85,22 +85,9 @@ impl crate::AddressSpace {
 
 /// Return true if the global requires a type decorated with `Block`.
 ///
-/// In the Vulkan spec 1.3.296, the section [Descriptor Set Interface][dsi] says:
+/// See [`back::spv::GlobalVariable`] for details.
 ///
-/// > Variables identified with the `Uniform` storage class are used to
-/// > access transparent buffer backed resources. Such variables must
-/// > be:
-/// >
-/// > -   typed as `OpTypeStruct`, or an array of this type,
-/// >
-/// > -   identified with a `Block` or `BufferBlock` decoration, and
-/// >
-/// > -   laid out explicitly using the `Offset`, `ArrayStride`, and
-/// >     `MatrixStride` decorations as specified in §15.6.4, "Offset
-/// >     and Stride Assignment."
-///
-/// [dsi]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#interfaces-resources-descset
-// See `back::spv::GlobalVariable::access_id` for details.
+/// [`back::spv::GlobalVariable`]: super::GlobalVariable
 pub fn global_needs_wrapper(ir_module: &crate::Module, var: &crate::GlobalVariable) -> bool {
     match var.space {
         crate::AddressSpace::Uniform

naga/src/back/spv/index.rs

@@ -52,13 +52,14 @@ impl<'w> BlockContext<'w> {
     /// - An optional [`Access`] or [`AccessIndex`], for case 3, applied to...
     /// - A [`naga::GlobalVariable`].
     ///
-    /// The SPIR-V generated takes into account wrapped globals; see
-    /// [`global_needs_wrapper`].
+    /// The generated SPIR-V takes into account wrapped globals; see
+    /// [`back::spv::GlobalVariable`] for details.
     ///
     /// [`naga::GlobalVariable`]: crate::Expression::GlobalVariable
     /// [`AccessIndex`]: crate::Expression::AccessIndex
     /// [`Access`]: crate::Expression::Access
     /// [`base`]: crate::Expression::Access::base
+    /// [`back::spv::GlobalVariable`]: super::GlobalVariable
     pub(super) fn write_runtime_array_length(
         &mut self,
         array: Handle<crate::Expression>,

naga/src/back/spv/mod.rs

@@ -466,38 +466,75 @@ enum CachedConstant {
     ZeroValue(Word),
 }
 
+/// How a Naga global variable is represented in SPIR-V.
+///
+/// In the Vulkan spec 1.3.296, the section [Descriptor Set Interface][dsi] says:
+///
+/// > Variables identified with the `Uniform` storage class are used to access
+/// > transparent buffer backed resources. Such variables *must* be:
+/// >
+/// > -   typed as `OpTypeStruct`, or an array of this type,
+/// >
+/// > -   identified with a `Block` or `BufferBlock` decoration, and
+/// >
+/// > -   laid out explicitly using the `Offset`, `ArrayStride`, and `MatrixStride`
+/// >     decorations as specified in "Offset and Stride Assignment".
+///
+/// This is followed by identical language for the `StorageBuffer`,
+/// except that a `BufferBlock` decoration is not allowed.
+///
+/// When we encounter a global variable in the [`Storage`] or [`Uniform`]
+/// address spaces whose type is not already [`Struct`], this backend implicitly
+/// wraps the global variable in a struct: we generate a SPIR-V global variable
+/// holding an `OpTypeStruct` with a single member, whose type is what the Naga
+/// global's type would suggest, decorated as required above.
+///
+/// The [`helpers::global_needs_wrapper`] function determines whether a given
+/// [`crate::GlobalVariable`] needs to be wrapped.
+///
+/// [dsi]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#interfaces-resources-descset
+/// [`Storage`]: crate::AddressSpace::Storage
+/// [`Uniform`]: crate::AddressSpace::Uniform
+/// [`Struct`]: crate::TypeInner::Struct
 #[derive(Clone)]
 struct GlobalVariable {
-    /// ID of the OpVariable that declares the global.
+    /// The SPIR-V id of the `OpVariable` that declares the global.
+    ///
+    /// If this global has been implicitly wrapped in an `OpTypeStruct`, this id
+    /// refers to the wrapper, not the original Naga value it contains. If you
+    /// need the Naga value, use [`access_id`] instead of this field.
     ///
-    /// If you need the variable's value, use [`access_id`] instead of this
-    /// field. If we wrapped the Naga IR `GlobalVariable`'s type in a struct to
-    /// comply with Vulkan's requirements, then this points to the `OpVariable`
-    /// with the synthesized struct type, whereas `access_id` points to the
-    /// field of said struct that holds the variable's actual value.
+    /// If this global is not implicitly wrapped, this is the same as
+    /// [`access_id`].
     ///
     /// This is used to compute the `access_id` pointer in function prologues,
-    /// and used for `ArrayLength` expressions, which do need the struct.
+    /// and used for `ArrayLength` expressions, which need to pass the wrapper
+    /// struct.
     ///
     /// [`access_id`]: GlobalVariable::access_id
     var_id: Word,
 
-    /// For `AddressSpace::Handle` variables, this ID is recorded in the function
-    /// prelude block (and reset before every function) as `OpLoad` of the variable.
-    /// It is then used for all the global ops, such as `OpImageSample`.
+    /// The loaded value of a `AddressSpace::Handle` global variable.
+    ///
+    /// If the current function uses this global variable, this is the id of an
+    /// `OpLoad` instruction in the function's prologue that loads its value.
+    /// (This value is assigned as we write the prologue code of each function.)
+    /// It is then used for all operations on the global, such as `OpImageSample`.
     handle_id: Word,
 
-    /// Actual ID used to access this variable.
-    /// For wrapped buffer variables, this ID is `OpAccessChain` into the
-    /// wrapper. Otherwise, the same as `var_id`.
+    /// The SPIR-V id of a pointer to this variable's Naga IR value.
+    ///
+    /// If the current function uses this global variable, and it has been
+    /// implicitly wrapped in an `OpTypeStruct`, this is the id of an
+    /// `OpAccessChain` instruction in the function's prologue that refers to
+    /// the wrapped value inside the struct. (This value is assigned as we write
+    /// the prologue code of each function.) If you need the wrapper struct
+    /// itself, use [`var_id`] instead of this field.
+    ///
+    /// If this global is not implicitly wrapped, this is the same as
+    /// [`var_id`].
     ///
-    /// Vulkan requires that globals in the `StorageBuffer` and `Uniform` storage
-    /// classes must be structs with the `Block` decoration, but WGSL and Naga IR
-    /// make no such requirement. So for such variables, we generate a wrapper struct
-    /// type with a single element of the type given by Naga, generate an
-    /// `OpAccessChain` for that member in the function prelude, and use that pointer
-    /// to refer to the global in the function body. This is the id of that access,
-    /// updated for each function in `write_function`.
+    /// [`var_id`]: GlobalVariable::var_id
     access_id: Word,
 }