Resource constructors proposal (#197)

Proposal for resource classes constructors.

Closes #209

Author: hekota

proposals/0025-resource-constructors.md

@@ -0,0 +1,222 @@
+* Proposal: [0025 - Resource Constructors](0025-resource-constructors.md)
+* Author(s): [Helena Kotas](https://github.com/hekota)
+* Status: **Design In Progress**
+
+## Introduction
+
+HLSL resource classes are represented in Clang as struct types, or template
+struct types with the resource element type as the template argument. The
+resource structs have a member field `__handle` of type `__hlsl_resource_t` that
+is decorated with type attributes specifying the resource class, contained type,
+whether it is a handle for a raw buffer or ROV, and other properties. These
+builtin types are constructed in `HLSLExternalSemaSource`.
+
+For example, the source code for `RWBuffer<T>` would look like this:
+
+```c++
+template <typename T> struct RWBuffer {
+private:
+  using handle_t = __hlsl_resource_t
+      [[hlsl::contained_type(T)]] [[hlsl::resource_class(UAV)]];
+  handle_t __handle;
+};
+```
+_* The resource declaration also includes element type validation via C++20
+concepts which I have not included here for readability._
+
+Depending on the resource type its definition will include methods for accessing
+or manipulating the resource, such as subscript operators, `Load` and `Store`
+methods, etc.
+
+Note that while the HLSL resources are defined as structs, they are often
+referred to as _resource classes_ or _resource records_. These terms can be used
+interchangebly.
+
+The record classes can be declared at the global scope, used as function in/out
+parameters, or as local variables. They need to be properly initialized
+depending on the declaration scope, and this should be done by resource class
+constructors.
+
+## Proposed solution
+
+Each resource class should have a set of constructors that will initialize its
+`__handle` based on the scope where the resource was declared, its binding, or
+whether it is a dynamically bound resource. Each resource class should also have
+a copy constructor and/or assignment operator that will take care of copying the
+resource handle, for example when an existing resource is assigned to a local
+resource variable.
+
+### Default constructor
+
+Default constructor does not take any arguments and will initialize the
+`__handle` member to `poison` value, which means that its value is undefined.
+This constructor will be used for resources that are declared as local
+variables.
+
+```c++
+template <typename T> struct RWBuffer {
+  ...
+public:
+  // For uninitialized handles
+  RWBuffer() {
+    __handle = __builtin_hlsl_resource_createpoisonhandle(__handle);
+  }
+  ...
+};
+```
+
+The `__handle` argument of the `__builtin_hlsl_resource_createpoisonhandle` Clang
+builtin function will be used to infer the return type of that function. This is
+the same way we infer return types for HLSL intrinsic builtins based on their
+arguments, except in the case only the type of the argument is used and not its
+(uninitialized) value.
+
+There might be a way of encoding the handle type into the
+builtin call without explicitly passing in the `__handle`. If that is the case
+and it is not overly complicated, we should use that instead.
+
+A call to the default resource constructor is automatically generated by Clang
+for any uninitialized resource class. For resources declared at global scope
+Sema analysis will set the initialization expression to use a different
+constructor based on whether the resource has an explicit binding or not.
+
+### Constructor for resources with explicit binding
+
+Resources declared at the global scope can have an explicit binding and will be
+initialized by the following constructor.
+
+```c++
+template <typename T> struct RWBuffer {
+  ...
+private:
+  // For resources with explicit binding
+  RWBuffer(unsigned register, unsigned space, int range, unsigned index) {
+    __handle = __builtin_hlsl_resource_createhandlefrombinding(__handle, register, space, range, index);
+  }
+  ...
+};
+```
+
+The `__handle` argument passed into the
+`__builtin_hlsl_resource_createhandlefrombinding` Clang builtin function will be used
+to infer the return type of the that function (the same way as for the default
+construtor).
+
+A call to this constructor will be created by Sema as part of uninitialized
+variable declaration processing (`Sema::ActOnUninitializedDecl`). It will
+work as if it would replace:
+
+`RWBuffer<float> A : register(u3);`
+
+with
+
+`RWBuffer<float> A(3,0,1,0);`.
+
+### Constructor for resources with implicit binding
+
+If a resource does not have an explicit binding annotation, or if it has one but
+it only specifies the virtual register space, it has _implicit binding_. The
+actual binding will be assigned later on by the compiler.
+
+The constructor for resources with implicit binding looks like this:
+
+```c++
+template <typename T> struct RWBuffer {
+  ...
+private:
+  // For resources with implicit binding
+  RWBuffer(unsigned space, int range, unsigned index) {
+    __handle = __builtin_hlsl_resource_createhandlefromimplicitbinding(__handle, space, range, index);
+  }
+  ...
+};
+```
+
+The `__handle` argument passed into the
+`__builtin_hlsl_resource_createhandlefromimplicitbinding` Clang builtin function will
+be used to infer the return type of the that function (the same way as for the
+default construtor).
+
+A call to this constructor will be created by Sema as part of uninitialized
+variable declaration processing (`Sema::ActOnUninitializedDecl`). It will
+work as if it would replace:
+
+`RWBuffer<float> A;`
+
+with
+
+`RWBuffer<float> A(0,1,0);`.
+
+Or if the resource has a space-only binding annotation, it will work as if it
+would replace:
+
+`RWBuffer<float> A : register(space13);`
+
+with
+
+`RWBuffer<float> A(13,1,0);`.
+
+### Copy constructor and assignment operator
+
+The copy constructor and/or the assignment operator will take care of copying the
+resource handle between resource class instances.
+
+```c++
+template <typename T> struct RWBuffer {
+  ...
+public:
+  // Resources are copyable.
+  RWBuffer(RWBuffer &LHS) = default;
+
+  // Resources are assignable.
+  RWBuffer &operator=(RWBuffer &LHS) = default;
+  ...
+};
+```
+
+### Dynamically-bound resources
+
+TBD
+
+### Summary
+
+```c++
+template <typename T> struct RWBuffer {
+private:
+  // resource handle
+  using handle_t = __hlsl_resource_t
+      [[hlsl::contained_type(T)]] [[hlsl::resource_class(UAV)]];
+  handle_t __handle;
+
+  // For resources with explicit binding
+  RWBuffer(unsigned register, unsigned space, int rage, unsigned index) {
+    __handle = __builtin_hlsl_resource_createhandlefrombinding(__handle, register, space, range, index);
+  }
+
+  // For resources with implicit binding
+  RWBuffer(unsigned space, int rage, unsigned index) {
+    __handle = __builtin_hlsl_resource_createhandlefromimplicitbinding(__handle, space, range, index);
+  }
+
+public:
+  // For uninitialized handles
+  RWBuffer() {
+    __handle = __builtin_hlsl_resource_createpoisonhandle(__handle);
+  }
+
+  // Resources are copyable.
+  RWBuffer(RWBuffer &LHS) = default;
+
+  // Resources are assignable.
+  RWBuffer &operator=(RWBuffer &LHS) = default;
+  ...
+};
+```
+
+## Alternatives considered (Optional)
+
+## Acknowledgments (Optional)
+
+Chris Bieneman
+
+<!-- {% endraw %} -->