From b4d36b3efe0bb58fe8d69ccd85cfc756937dd822 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cle=CC=81ment=20Foucault?= <foucault.clem@gmail.com>
Date: Sun, 5 Mar 2023 18:12:31 +0100
Subject: [PATCH] GPU: Compute: Document and cleanup header

No fonctional changes.
---
 source/blender/gpu/GPU_compute.h | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/source/blender/gpu/GPU_compute.h b/source/blender/gpu/GPU_compute.h
index ff94620f186..8829e83cedc 100644
--- a/source/blender/gpu/GPU_compute.h
+++ b/source/blender/gpu/GPU_compute.h
@@ -2,6 +2,11 @@
 
 /** \file
  * \ingroup gpu
+ *
+ * GPU Compute Pipeline
+ *
+ * Allows to dispatch compute shader tasks on the GPU.
+ * Every dispatch is sent to the active `GPUContext`.
  */
 
 #pragma once
@@ -15,12 +20,34 @@
 extern "C" {
 #endif
 
+/**
+ * Dispatch a compute shader task.
+ * The number of work groups (aka thread groups) is bounded by `GPU_max_work_group_count()` which
+ * might be different in each of the 3 dimensions.
+ */
 void GPU_compute_dispatch(GPUShader *shader,
                           uint groups_x_len,
                           uint groups_y_len,
                           uint groups_z_len);
 
-void GPU_compute_dispatch_indirect(GPUShader *shader, GPUStorageBuf *indirect_buf_);
+/**
+ * Dispatch a compute shader task. The size of the dispatch is sourced from a \a indirect_buf
+ * which must follow this layout:
+ * \code{.c}
+ * typedef struct {
+ *   uint groups_x_len;
+ *   uint groups_y_len;
+ *   uint groups_z_len;
+ * } DispatchIndirectCommand;
+ * \encode
+ *
+ * \note The writes to the \a indirect_buf do not need to be synchronized as a memory barrier is
+ * emitted internally.
+ *
+ * The number of work groups (aka thread groups) is bounded by `GPU_max_work_group_count()` which
+ * might be different in each of the 3 dimensions.
+ */
+void GPU_compute_dispatch_indirect(GPUShader *shader, GPUStorageBuf *indirect_buf);
 
 #ifdef __cplusplus
 }