Documentation for the compute system

Docs/APIChanges.md

@@ -4,6 +4,10 @@ This document lists all breaking API changes by date and by release tag. Note th
 
 Changes that make some state saved through SaveBinaryState from a prior version of the library unreadable by the new version is marked as *SBS*. See [Saving Shapes](https://jrouwe.github.io/JoltPhysics/#saving-shapes) for further information.
 
+## Changes between v5.5.0 and latest
+
+* 20253012 - Added interface to run compute shaders on the GPU with implementations for DX12, Vulkan and Metal. These interfaces can be disabled by setting JPH_USE_DX12, JPH_USE_VK and JPH_USE_MTL to OFF. To build on macOS, you'll need to have dxc and spirv-cross installed. The easiest way to install them is by installing the Vulkan SDK. (5ac132df689fbf88da618181b0f1f73fca8bb1b4)
+
 ## Changes between v5.4.0 and v5.5.0
 
 * 20251206 - Renamed `JPH_CPU_ADDRESS_BITS` to `JPH_CPU_ARCH_BITS` because the size of a pointer can be different from the number of bits used by the architecture. (db654de2a6098fd1ad78cb9a3e70f6a8a61c00b5)

Docs/ReleaseNotes.md

@@ -4,6 +4,10 @@ For breaking API changes see [this document](https://github.com/jrouwe/JoltPhysi
 
 ## Unreleased changes
 
+### New functionality
+
+* Added interface to run compute shaders on the GPU with implementations for DX12, Vulkan and Metal. These interfaces can be disabled by setting JPH_USE_DX12, JPH_USE_VK and JPH_USE_MTL to OFF. To build on macOS, you'll need to have dxc and spirv-cross installed. The easiest way to install them is by installing the Vulkan SDK.
+
 ### Bug Fixes
 
 * Made it possible to make a class outside the JPH namespace serializable.

Jolt/Compute/ComputeQueue.h

@@ -13,6 +13,8 @@ class ComputeShader;
 class ComputeBuffer;
 
 /// A command queue for executing compute workloads on the GPU.
+///
+/// Note that only a single thread should be using a ComputeQueue at any time (although an implementation could be made that is thread safe).
 class JPH_EXPORT ComputeQueue : public RefTarget<ComputeQueue>, public NonCopyable
 {
 public:
@@ -33,12 +35,19 @@ public:
 	};
 
 	/// Bind a constant buffer to the shader. Note that the contents of the buffer cannot be modified until execution finishes.
+	/// A reference to the buffer is added to make sure it stays alive until execution finishes.
+	/// @param inName Name of the buffer as specified in the shader.
+	/// @param inBuffer The buffer to bind.
 	virtual void			SetConstantBuffer(const char *inName, const ComputeBuffer *inBuffer) = 0;
 
 	/// Bind a read only buffer to the shader. Note that the contents of the buffer cannot be modified on CPU until execution finishes (only relevant for buffers of type UploadBuffer).
+	/// A reference to the buffer is added to make sure it stays alive until execution finishes.
+	/// @param inName Name of the buffer as specified in the shader.
+	/// @param inBuffer The buffer to bind.
 	virtual void			SetBuffer(const char *inName, const ComputeBuffer *inBuffer) = 0;
 
 	/// Bind a read/write buffer to the shader.
+	/// A reference to the buffer is added to make sure it stays alive until execution finishes.
 	/// @param inName Name of the buffer as specified in the shader.
 	/// @param inBuffer The buffer to bind.
 	/// @param inBarrier If set to Yes, a barrier will be placed before accessing the buffer to ensure all previous writes to the buffer are visible.
@@ -47,16 +56,20 @@ public:
 	/// Dispatch a compute shader with the specified number of thread groups
 	virtual void			Dispatch(uint inThreadGroupsX, uint inThreadGroupsY = 1, uint inThreadGroupsZ = 1) = 0;
 
-	/// Schedule buffer to be copied from GPU to CPU
+	/// Schedule buffer to be copied from GPU to CPU.
+	/// A reference to the buffers is added to make sure they stay alive until execution finishes.
 	virtual void			ScheduleReadback(ComputeBuffer *inDst, const ComputeBuffer *inSrc) = 0;
 
-	/// Execute accumulated command list
+	/// Execute accumulated command list.
+	/// No more commands can be added until Wait is called.
 	virtual void			Execute() = 0;
 
-	/// After executing, this waits until execution is done
+	/// After executing, this waits until execution is done.
+	/// This also makes sure that any readback operations have completed and the data is available on CPU.
 	virtual void			Wait() = 0;
 
 	/// Execute and wait for the command list to finish
+	/// @see Execute, Wait
 	void					ExecuteAndWait()
 	{
 		Execute();