Docs: GetMappedRange relative addresses and alignments

doc/articles/BufferMapping.md

@@ -0,0 +1,17 @@
+# Buffer Mapping {#BufferMapping}
+
+## GetMappedRange/GetConstMappedRange Behavior {#GetMappedRangeBehavior}
+
+@ref wgpuGetMappedRange and @ref wgpuGetConstMappedRange:
+
+- Return `NULL` with @ref ImplementationDefinedLogging if:
+    - There is any content-timeline error, as defined in the WebGPU specification for `getMappedRange()` (buffer is not mapped, alignment constraints, overlaps, etc.)
+        - **Except** for overlaps between *const* ranges, which are allowed in C.
+            (JS does not allow this because const ranges do not exist.)
+    - @ref wgpuGetMappedRange is called, but the buffer is not mapped with @ref WGPUMapMode_Write.
+- Do not guarantee they will return any particular address value relative to another GetMappedRange call.
+- Guarantee that the mapped pointer will be aligned to 16 bytes if the `MapAsync` and `GetMappedRange` offsets are also aligned to 16 bytes.
+
+    More specifically: `GetMappedRange pointer` and `MapAsync offset + GetMappedRange offset` must be _congruent modulo_ `16`.
+
+    - Implementations **should** try to guarantee better alignments (as large as 256 bytes) if possible without significant runtime overhead (e.g. allocating new memory and copying data).

doc/articles/index.md

@@ -1,6 +1,7 @@
 \page articles Articles
 
 - \subpage Asynchronous-Operations
+- \subpage BufferMapping
 - \subpage Errors
 - \subpage Ownership
 - \subpage Surfaces

webgpu.h

@@ -5503,10 +5503,7 @@ WGPU_EXPORT void wgpuBufferDestroy(WGPUBuffer buffer) WGPU_FUNCTION_ATTRIBUTE;
  * @returns
  * Returns a const pointer to beginning of the mapped range.
  * It must not be written; writing to this range causes undefined behavior.
- * Returns `NULL` with @ref ImplementationDefinedLogging if:
- * - There is any content-timeline error as defined in the WebGPU specification for `getMappedRange()` (alignments, overlaps, etc.)
- *   **except** for overlaps with other *const* ranges, which are allowed in C.
- *   (JS does not allow this because const ranges do not exist.)
+ * See @ref GetMappedRangeBehavior for error conditions and guarantees.
  */
 WGPU_EXPORT void const * wgpuBufferGetConstMappedRange(WGPUBuffer buffer, size_t offset, size_t size) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT WGPUBufferMapState wgpuBufferGetMapState(WGPUBuffer buffer) WGPU_FUNCTION_ATTRIBUTE;
@@ -5519,9 +5516,7 @@ WGPU_EXPORT WGPUBufferMapState wgpuBufferGetMapState(WGPUBuffer buffer) WGPU_FUN
  *
  * @returns
  * Returns a mutable pointer to beginning of the mapped range.
- * Returns `NULL` with @ref ImplementationDefinedLogging if:
- * - There is any content-timeline error as defined in the WebGPU specification for `getMappedRange()` (alignments, overlaps, etc.)
- * - The buffer is not mapped with @ref WGPUMapMode_Write.
+ * See @ref GetMappedRangeBehavior for error conditions and guarantees.
  */
 WGPU_EXPORT void * wgpuBufferGetMappedRange(WGPUBuffer buffer, size_t offset, size_t size) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT uint64_t wgpuBufferGetSize(WGPUBuffer buffer) WGPU_FUNCTION_ATTRIBUTE;

webgpu.yml

@@ -3538,9 +3538,7 @@ objects:
         returns:
           doc: |
             Returns a mutable pointer to beginning of the mapped range.
-            Returns `NULL` with @ref ImplementationDefinedLogging if:
-            - There is any content-timeline error as defined in the WebGPU specification for `getMappedRange()` (alignments, overlaps, etc.)
-            - The buffer is not mapped with @ref WGPUMapMode_Write.
+            See @ref GetMappedRangeBehavior for error conditions and guarantees.
           type: c_void
           pointer: mutable
         args:
@@ -3559,10 +3557,7 @@ objects:
           doc: |
             Returns a const pointer to beginning of the mapped range.
             It must not be written; writing to this range causes undefined behavior.
-            Returns `NULL` with @ref ImplementationDefinedLogging if:
-            - There is any content-timeline error as defined in the WebGPU specification for `getMappedRange()` (alignments, overlaps, etc.)
-              **except** for overlaps with other *const* ranges, which are allowed in C.
-              (JS does not allow this because const ranges do not exist.)
+            See @ref GetMappedRangeBehavior for error conditions and guarantees.
           type: c_void
           pointer: immutable
         args: