From 6e0150956b59fa0369734d7279d44017b226bee2 Mon Sep 17 00:00:00 2001
From: Elie Michel <elie.michel@exppad.com>
Date: Thu, 1 May 2025 12:38:31 +0200
Subject: [PATCH] Document buffer usage

---
 webgpu.h   | 36 ++++++++++++++++++++++++++++++++++++
 webgpu.yml | 26 +++++++++++++++-----------
 2 files changed, 51 insertions(+), 11 deletions(-)

diff --git a/webgpu.h b/webgpu.h
index 2f51b47..da99a60 100644
--- a/webgpu.h
+++ b/webgpu.h
@@ -1145,15 +1145,47 @@ typedef WGPUFlags WGPUBufferUsage;
  * `0`.
  */
 static const WGPUBufferUsage WGPUBufferUsage_None = 0x0000000000000000;
+/**
+ * The buffer can be *mapped* on the CPU side in *read* mode (using @ref WGPUMapMode_Read).
+ */
 static const WGPUBufferUsage WGPUBufferUsage_MapRead = 0x0000000000000001;
+/**
+ * The buffer can be *mapped* on the CPU side in *write* mode (using @ref WGPUMapMode_Write).
+ *
+ * @note This usage is **not** required to set `mappedAtCreation` to `true` in @ref WGPUBufferDescriptor.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_MapWrite = 0x0000000000000002;
+/**
+ * The buffer can be used as the *source* of a GPU-side copy operation.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_CopySrc = 0x0000000000000004;
+/**
+ * The buffer can be used as the *destination* of a GPU-side copy operation.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_CopyDst = 0x0000000000000008;
+/**
+ * The buffer can be used as an Index buffer when doing indexed drawing in a render pipeline.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Index = 0x0000000000000010;
+/**
+ * The buffer can be used as an Vertex buffer when using a render pipeline.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Vertex = 0x0000000000000020;
+/**
+ * The buffer can be bound to a shader as a uniform buffer.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Uniform = 0x0000000000000040;
+/**
+ * The buffer can be bound to a shader as a storage buffer.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Storage = 0x0000000000000080;
+/**
+ * The buffer can store arguments for an indirect draw call.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_Indirect = 0x0000000000000100;
+/**
+ * The buffer can store the result of a timestamp or occlusion query.
+ */
 static const WGPUBufferUsage WGPUBufferUsage_QueryResolve = 0x0000000000000200;
 
 /**
@@ -1820,6 +1852,10 @@ typedef struct WGPUBufferDescriptor {
      */
     uint64_t size;
     /**
+     * When true, the buffer is mapped in write mode at creation. It should thus be unmapped once its initial data has been written.
+     *
+     * @note Mapping at creation does **not** require the usage @ref WGPUBufferUsage_MapWrite.
+     *
      * The `INIT` macro sets this to `WGPU_FALSE`.
      */
     WGPUBool mappedAtCreation;
diff --git a/webgpu.yml b/webgpu.yml
index 08851e3..60cccd9 100644
--- a/webgpu.yml
+++ b/webgpu.yml
@@ -1419,34 +1419,36 @@ bitflags:
           TODO
       - name: map_read
         doc: |
-          TODO
+          The buffer can be *mapped* on the CPU side in *read* mode (using @ref WGPUMapMode_Read).
       - name: map_write
         doc: |
-          TODO
+          The buffer can be *mapped* on the CPU side in *write* mode (using @ref WGPUMapMode_Write).
+
+          @note This usage is **not** required to set `mappedAtCreation` to `true` in @ref WGPUBufferDescriptor.
       - name: copy_src
         doc: |
-          TODO
+          The buffer can be used as the *source* of a GPU-side copy operation.
       - name: copy_dst
         doc: |
-          TODO
+          The buffer can be used as the *destination* of a GPU-side copy operation.
       - name: index
         doc: |
-          TODO
+          The buffer can be used as an Index buffer when doing indexed drawing in a render pipeline.
       - name: vertex
         doc: |
-          TODO
+          The buffer can be used as an Vertex buffer when using a render pipeline.
       - name: uniform
         doc: |
-          TODO
+          The buffer can be bound to a shader as a uniform buffer.
       - name: storage
         doc: |
-          TODO
+          The buffer can be bound to a shader as a storage buffer.
       - name: indirect
         doc: |
-          TODO
+          The buffer can store arguments for an indirect draw call.
       - name: query_resolve
         doc: |
-          TODO
+          The buffer can store the result of a timestamp or occlusion query.
   - name: color_write_mask
     doc: |
       TODO
@@ -1767,7 +1769,9 @@ structs:
         type: uint64
       - name: mapped_at_creation
         doc: |
-          TODO
+          When true, the buffer is mapped in write mode at creation. It should thus be unmapped once its initial data has been written.
+
+          @note Mapping at creation does **not** require the usage @ref WGPUBufferUsage_MapWrite.
         type: bool
         default: false
   - name: color