Add resource chapter documenting buffers and bindings #344

pow2clk · 2024-10-22T16:48:31Z

This adds a resource chapter that documents typed and raw buffers including their methods and compatible operators along with short descriptions of their functionality. It also adds a description of binding annotations for all types. Stub sections are included for constant buffers and samplers, but no information is provided as yet.

Fixes llvm/wg-hlsl#55
Fixes llvm/wg-hlsl#56

This adds a resource chapter that documents typed and raw buffers including their methods and compatible operators along with short descriptions of their functionality. It also adds a description of binding annotations for all types. Stub sections are included for constant buffers and samplers, but no information is provided as yet. Fixes llvm/wg-hlsl#55 Fixes llvm/wg-hlsl#56

damyanp

Some initial thoughts.

damyanp · 2024-10-22T20:40:56Z

specs/language/resources.tex

+Read-only buffers and textures types constitute Shader Resource Views (SRVs) of the external memory.
+Writable buffers and textures types constitute Unordered Access Views (UAVs) of the external memory.


I think SRV and UAV are DirectX-isms that we probably want to avoid directly using in the spec language. Maybe just qualifying this as "in DirectX read-only buffers.....SRVs" would help my uneasiness here.

Removed them.

damyanp · 2024-10-22T20:43:56Z

specs/language/resources.tex

+All typed buffers can be read through subscript operators or Load methods.
+Writable typed buffers can be written through subscript operators.
+
+Typed Buffers are declared with the built-in templates:


Tripped up a little reading this as I expected the templates: to be immediatelly followed by a list of templates.

Dunno if that's me overthinking while reviewing or worth changing though.

Should have been removed

damyanp · 2024-10-22T20:46:55Z

specs/language/resources.tex

+void GetDimensions(out uint size);
+\end{HLSL}
+
+This returns the full size of the buffer in bytes through the \texttt{width} out parameter.


width

The method definition calls this param size.

damyanp · 2024-10-22T20:53:36Z

specs/language/resources.tex

+The \texttt{status} parameter returns an indication of whether the value retrieved accessed a mapped tile
+resource on tile-based platforms. This parameter is interpretted using the \texttt{CheckAccessFullyMapped}
+built-in function. If tiled resources are enabled, it returns true if the value was accessed from a mapped
+tile resource and false otherwise. If tiled resourced are not enabled, it will return true.


"tile-based platform" is a different thing to tiled resources. Tiled resources aren't really a thing that you enable per se, it's more a property of the underlying resource.

I wonder if we can define this without talking about tiled resources at all?

Maybe just talking about it indicating if the value returned was from mapped memory or not - and as an example referring to D3D12's reserved resources or Vulkan's sparse resources?

Left over from when I didn't follow this clearly. removed

damyanp · 2024-10-22T20:55:27Z

specs/language/resources.tex

+  RWBuffer<float4> buf;
+\end{HLSL}
+
+When defined at global scope, RWBuffers are bound to externally-defined backing stores


Is there some way we can avoid repeating ourselves here? RWBuffer's are exactly like Buffers with some extensions?

Or are there some subtle differences between Load on a Buffer vs RWBuffer? If so then it'd be great if they could more clearly be called out.

I think the main difference between RWBuffer and Buffer is that RWBuffer has a non-const operator[] that returns a T&.

That isn't captured here, but we should capture it and probably describe RWBuffer in terms of additions to Buffer. In the Work Graph's spec, I had described the record types with base classes that didn't actually exist as a way of describing the composition of interfaces. That could be a useful tool for resources too.

I went back and forth on this. I think we've tied ourselves in knots trying to consolidate common sections of documentation in the past and I noted that the C++ spec repeats a lot of things. Merging information between read-only and writable types might be manageable though. I'll take a pass at it.

Initially, I'm more inclined to merge the sections and just annotated cases where it applies to RW buffers only. Does that sound okay?

damyanp · 2024-10-22T20:57:58Z

specs/language/resources.tex

+Raw buffers are either ByteAddressBuffers or StructuredBuffers.
+ByteAddressBuffers enable per-byte access to the raw data while
+StructuredBuffers have an associated structure type that determines how they are
+indexed. This type can be a scalar, vector, matrix, or user-defined struct.


I like this summary - I missed having one for typed buffers above.

I added something there that I hope is equivalent.

damyanp · 2024-10-22T20:58:52Z

specs/language/resources.tex

+but partial writes aren't allowed.
+Though structured buffers can contain vectors,
+assignment to individual vector elements will result in an error.
+I HAVE BEEN UNABLE TO VERIFY THIS, THOUGH I WAS SURE IT WAS TRUE!


Could this be something that the frontend makes work for you but this restriction remains at the DXIL level?

This probably needs to be cleaned up before completing the PR.

I didn't mean to leave this comment in. Removed.

damyanp · 2024-10-22T21:00:03Z

specs/language/resources.tex

+
+\begin{HLSL}
+  ByteAddressBuffer gbuf;
+  void doit(bool b) {


void doit(bool b)

Wondering why there's the boolean argument in this example?

In error from when I had a more involved example. Removed.

damyanp · 2024-10-22T21:01:15Z

specs/language/resources.tex

+
+\Sub{Constructors}{Resources.rwbabufs.ctrs}
+
+Since their contents are viewed as raw bytes, RWByteAddressBuffers are defined as a simple variable definition.


Wonder if "without any type parameters" might be more specific than "simple variable definition".

damyanp · 2024-10-22T21:03:20Z

specs/language/resources.tex

+\Sec{Samplers}{Resources.samp}
+
+
+\Sec{Resource Binding}{Resources.binding}


This needs to have a discussion about bindings on UDT's.

Strip mention of UAVs and SRVs Remove some legacy text mistakenly left in as notes, mischaracterization of tiled memory, leftover sentences from moved or deleted segments, and elements of code examples. Better summarize typed buffers upfront. Add description of UDT register annotations.

llvm-beanz · 2024-10-30T15:46:45Z

specs/language/expressions.tex

-\texttt{T[]}, or an object of type \texttt{T} where \texttt{T} provides an
+the form \texttt{E1[E2]}, \texttt{E1} must either be a variable of array,
+vector, matrix, typed buffer (\ref{Resources.tybuf}), or structured buffer
+(\ref{Resources.stbufs}), with elements of type \texttt{T[]} or an


Resource types have overloads for operator[] even in DXC. The original language did miss vector and matrix types, but the addition of resources is redundant.

llvm-beanz · 2024-10-30T15:48:13Z

specs/language/resources.tex

+   // element access
+   T operator[](uint pos);
+   T Load(in int pos);
+   T Load(in int pos, out uint status);


Some (maybe all) of these methods should probably be const.

llvm-beanz · 2024-10-30T15:49:14Z

specs/language/resources.tex

+\begin{HLSL}
+template <typename T = float4>
+ class Buffer {
+   Buffer();


We also need a copy constructor.

llvm-beanz · 2024-10-30T15:53:55Z

specs/language/resources.tex

+  RWBuffer<float4> buf;
+\end{HLSL}
+
+When defined at global scope, RWBuffers are bound to externally-defined backing stores


I think the main difference between RWBuffer and Buffer is that RWBuffer has a non-const operator[] that returns a T&.

That isn't captured here, but we should capture it and probably describe RWBuffer in terms of additions to Buffer. In the Work Graph's spec, I had described the record types with base classes that didn't actually exist as a way of describing the composition of interfaces. That could be a useful tool for resources too.

pow2clk

Responded to Damyan's comments

pow2clk · 2024-10-30T16:10:55Z

specs/language/resources.tex

+ T Load(in int pos);
+ T operator[](uint pos);


That's what the documentation says, but it turns out that a -1 makes it through for the subscript in DXC. I don't know how that would be useful though.

pow2clk · 2024-10-30T16:12:55Z

specs/language/resources.tex

+  RWBuffer<float4> buf;
+\end{HLSL}
+
+When defined at global scope, RWBuffers are bound to externally-defined backing stores


I went back and forth on this. I think we've tied ourselves in knots trying to consolidate common sections of documentation in the past and I noted that the C++ spec repeats a lot of things. Merging information between read-only and writable types might be manageable though. I'll take a pass at it.

Initially, I'm more inclined to merge the sections and just annotated cases where it applies to RW buffers only. Does that sound okay?

pow2clk · 2024-10-30T16:13:09Z

specs/language/resources.tex

+
+\Sub{Constructors}{Resources.rwbabufs.ctrs}
+
+Since their contents are viewed as raw bytes, RWByteAddressBuffers are defined as a simple variable definition.


pow2clk · 2024-10-30T16:13:22Z

specs/language/resources.tex

+\Sec{Samplers}{Resources.samp}
+
+
+\Sec{Resource Binding}{Resources.binding}


damyanp requested a review from llvm-beanz October 22, 2024 16:56

damyanp reviewed Oct 22, 2024

View reviewed changes

llvm-beanz reviewed Oct 30, 2024

View reviewed changes

pow2clk commented Oct 30, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add resource chapter documenting buffers and bindings #344

Add resource chapter documenting buffers and bindings #344

pow2clk commented Oct 22, 2024

damyanp left a comment

damyanp Oct 22, 2024

pow2clk Oct 30, 2024

damyanp Oct 22, 2024

pow2clk Oct 30, 2024

damyanp Oct 22, 2024

pow2clk Oct 30, 2024

damyanp Oct 22, 2024

pow2clk Oct 30, 2024

damyanp Oct 22, 2024

llvm-beanz Oct 30, 2024

pow2clk Oct 30, 2024

damyanp Oct 22, 2024

pow2clk Oct 30, 2024

damyanp Oct 22, 2024

pow2clk Oct 30, 2024

damyanp Oct 22, 2024

pow2clk Oct 30, 2024

damyanp Oct 22, 2024

pow2clk Oct 30, 2024

damyanp Oct 22, 2024

pow2clk Oct 30, 2024

llvm-beanz Oct 30, 2024

llvm-beanz Oct 30, 2024

llvm-beanz Oct 30, 2024

llvm-beanz Oct 30, 2024

pow2clk left a comment

pow2clk Oct 30, 2024

pow2clk Oct 30, 2024

pow2clk Oct 30, 2024

pow2clk Oct 30, 2024

		Read-only buffers and textures types constitute Shader Resource Views (SRVs) of the external memory.
		Writable buffers and textures types constitute Unordered Access Views (UAVs) of the external memory.


		\Sub{Constructors}{Resources.rwbabufs.ctrs}

		Since their contents are viewed as raw bytes, RWByteAddressBuffers are defined as a simple variable definition.

		\Sec{Samplers}{Resources.samp}


		\Sec{Resource Binding}{Resources.binding}

Add resource chapter documenting buffers and bindings #344

Are you sure you want to change the base?

Add resource chapter documenting buffers and bindings #344

Conversation

pow2clk commented Oct 22, 2024

damyanp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pow2clk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment