Document DXC handling of resources in non-global structs (#374)

Includes examples where a struct with resource is:
- declared as static
- declared as local variable
- used as a function arguments
- initialized with an initializer list

Part 2 of #175

Author: hekota

proposals/0038-resources-in-structs.md

@@ -312,21 +312,24 @@ https://godbolt.org/z/3TW565acT
 #### Example 8
 
 For resources declared at global scope, DXC validates that they fit within the
-specified register slots. If they do not fit, an error is reported during
-validation, though the error message is cryptic and the source location points
+specified register slots. If they do not fit, errors are reported, though the
+error messages are not clear and the source location points
 to where the resource is first used rather than where it is declared.
 
 ```
 RWBuffer<float> Buf[10] : register(u4294967293);
 
 [numthreads(4,1,1)]
 void main() {
-  Buf[0][0] = 0;
+  Buf[0][0] = 0; // line 5
 }
 ```
 https://godbolt.org/z/93d317Ej4
 ```
-<source>:12:3: error: Constant values must be in-range for operation.
+<source>:5:3: error: Constant values must be in-range for operation.
+<source>:5:3: error: Resource handle should returned by createHandle.
+<source>:5:13: error: store should be on uav resource.
+<source>:5:13: error: buffer load/store only works on Raw/Typed/StructuredBuffer.
 ```
 
 #### Example 9
@@ -386,6 +389,113 @@ https://godbolt.org/z/Mo8Paoq7G
 <source>:5:7: error: register space cannot be specified on global constants.
 ```
 
+### Static Structs with Resources
+
+Structs with resources can be declared as static. Same as other statically
+declared resources, these struct resource members are not automatically bound.
+Instead, the user must explicitly initialize them by assigning an existing
+resource to the struct member.
+
+#### Example 11
+
+```
+struct M {
+  RWBuffer<float> Bufs[10];
+};
+
+RWBuffer<float> GlobalBufs[10];
+
+static M m = { GlobalBufs };
+
+[numthreads(4,4,4)]
+void main(uint3 ID : SV_GroupID) {
+  m.Bufs[ID.y][1] = m.Bufs[ID.x][0];
+}
+```
+https://godbolt.org/z/8fcTfz6d8
+
+Unlike resource arrays in non-static global struct instances, resource arrays
+inside static or local struct variables may be dynamically indexable. This is
+possible when all resource elements are initialized from a range of the same
+dynamically indexable global resource array, as shown in the example above where
+`m.Bufs` is initialized from `GlobalBufs`.
+
+### Local variables and Function Parameters
+
+Structs with resources can also be declared as local variables or used as function parameters.
+
+#### Example 12
+
+```
+struct N {
+  RWBuffer<float> Buf;
+};
+
+N n : register(u2);
+
+void foo(N paramN, uint i) {
+  paramN.Buf[i] = 10;
+}
+
+[numthreads(4,4,4)]
+void main(uint3 ID : SV_GroupID) {
+  N localN = n;
+  localN.Buf[10] = 0.13;
+  foo(localN, ID.x);
+}
+```
+https://godbolt.org/z/eKq3jzM5r
+
+### Initialization list
+
+Local or static declarations of structs with resources can be initialized using
+initialized lists.
+
+#### Example 13
+
+```
+struct P {
+  RWBuffer<float> Bufs[4];
+};
+
+RWBuffer<float> GlobalBufs[4];
+
+static P p1 = { GlobalBufs };
+
+[numthreads(4,4,4)]
+void main(uint3 ID : SV_GroupID) {
+  P p2 = { GlobalBufs[3], GlobalBufs[2],
+           GlobalBufs[1], GlobalBufs[0]};
+
+  p1.Bufs[ID.y][0] = p2.Bufs[ID.x][0];
+}
+```
+https://godbolt.org/z/zzKe8bjff
+
+### Assignments
+
+Assignment to resource or resource array members of a global non-static structs
+is not allowed.
+
+```c++
+struct P {
+  RWBuffer<float> Buf;
+};
+
+P p : register(u2);
+
+RWBuffer<float> GlobalBuf;
+
+[numthreads(4,4,4)]
+void main(uint3 ID : SV_GroupID) {
+  p.Buf = GlobalBuf; // error
+  p.Buf[0] = 10;
+}
+```
+https://godbolt.org/z/f9dd4GYWq
+
+DXC reports an error `cast<X>() argument of incompatible type!`.
+
 ### Summary
 
 - DXC supports resources as members of structs, generating global resources
@@ -409,9 +519,15 @@ https://godbolt.org/z/Mo8Paoq7G
 - DXC validates register ranges for global resources but does not check for
   overflow in struct members, which may result in silently overflow.
 
+- Structs with resources can be declared as static or local variables, used as
+  function parameters, and initialized with initializer lists.
+
 ## Motivation
 
-We need to support resources in structs in Clang.
+While resources in structs may not be a widely used HLSL feature, DXC does
+support them, and so should the Clang implementation. This also presents an
+opportunity to address usability issues, such as the unpredictable implicit
+binding order, to make the feature more robust and user-friendly.
 
 ## Proposed solution