fixup! [naga hlsl-out] Implement external texture support

Author: jamienicol

naga/src/back/hlsl/mod.rs

@@ -106,6 +106,37 @@ index buffer for each bind group. This buffer is accessed in the shader to get t
 sampler index within the heap. See the wgpu_hal dx12 backend documentation for more
 information.
 
+# External textures
+
+Support for [`crate::ImageClass::External`] textures is implemented by lowering
+each external texture global variable to 3 `Texture2D<float4>`s, and a `cbuffer`
+of type `NagaExternalTextureParams`. This provides up to 3 planes of texture
+data (for example single planar RGBA, or separate Y, Cb, and Cr planes), and the
+parameters buffer containing information describing how to handle these
+correctly. The bind target to use for each of these globals is specified via
+[`Options::external_texture_binding_map`].
+
+External textures are supported by WGSL's `textureDimensions()`,
+`textureLoad()`, and `textureSampleBaseClampToEdge()` built-in functions. These
+are implemented using helper functions. See the following functions for how
+these are generated:
+ * [`Writer::write_wrapped_image_query_function`]
+ * [`Writer::write_wrapped_image_load_function`]
+ * [`Writer::write_wrapped_image_sample_function`]
+
+Ideally the set of global variables could be wrapped in a single struct that
+could conveniently be passed around. But, alas, HLSL does not allow structs to
+have `Texture2D` members. Fortunately, however, external textures can only be
+used as arguments to either built-in or user-defined functions. We therefore
+expand any external texture function argument to four consecutive arguments (3
+textures and the params struct) when declaring user-defined functions, and
+ensure our built-in function implementations take the same arguments. Then,
+whenever we need to emit an external texture in [`Writer::write_expr`], which
+fortunately can only ever be for a global variable or function argument, we
+simply emit the variable name of each of the three textures and the parameters
+struct in a comma-separated list. This won't win any awards for elegance, but
+it works for our purposes.
+
 [hlsl]: https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl
 [ilov]: https://gpuweb.github.io/gpuweb/wgsl/#internal-value-layout
 [16bb]: https://github.com/microsoft/DirectXShaderCompiler/wiki/Buffer-Packing#constant-buffer-packing