Add Read/WriteMappedRange (#494)

* Add Read/WriteMappedRange, and disallow ALL map overlaps

* performance docs

* Partial revert so that overlaps are unvalidated in native

* WriteMappedRange const pointer

* clarify that WGPU_WHOLE_MAP_SIZE is not used here

* fix lint

Author: kainino0x

doc/articles/BufferMapping.md

@@ -1,17 +1,21 @@
 # Buffer Mapping {#BufferMapping}
 
-## GetMappedRange/GetConstMappedRange Behavior {#GetMappedRangeBehavior}
+## Mapped Range Behavior {#MappedRangeBehavior}
 
-@ref wgpuBufferGetMappedRange and @ref wgpuBufferGetConstMappedRange...:
+The @ref wgpuBufferGetMappedRange, @ref wgpuBufferGetConstMappedRange, @ref wgpuBufferReadMappedRange, and @ref wgpuBufferWriteMappedRange methods:
 
-- 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.)
+- Fail (return `NULL` or `WGPUStatus_Error`) with @ref ImplementationDefinedLogging if:
+    - There is any content-timeline error, as defined in the WebGPU specification for `getMappedRange()`, given the same buffer, offset, and size (buffer is not mapped, alignment constraints, overlaps, etc.)
         - **Except** for overlaps between *const* ranges, which are allowed in C *in non-Wasm targets only*.
-            (Wasm does not allow this because const ranges do not exist in JS.)
-    - @ref wgpuBufferGetMappedRange is called, but the buffer is not mapped with @ref WGPUMapMode_Write.
+            (Wasm does not allow this because const ranges do not exist in JS.
+            All of these calls are implemented on top of `getMappedRange()`.)
+    - @ref wgpuBufferGetMappedRange or @ref wgpuBufferWriteMappedRange is called, but the buffer is not mapped with @ref WGPUMapMode_Write.
+
+@ref wgpuBufferGetMappedRange, @ref wgpuBufferGetConstMappedRange additionally:
+
 - 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).
+    - Implementations **should** try to guarantee better alignments (as large as 256 bytes), if they can do so without significant runtime overhead (i.e. without allocating new memory and copying data).

webgpu.h

@@ -4554,6 +4554,11 @@ typedef WGPUBufferUsage (*WGPUProcBufferGetUsage)(WGPUBuffer buffer) WGPU_FUNCTI
  * > @copydoc wgpuBufferMapAsync
  */
 typedef WGPUFuture (*WGPUProcBufferMapAsync)(WGPUBuffer buffer, WGPUMapMode mode, size_t offset, size_t size, WGPUBufferMapCallbackInfo callbackInfo) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Proc pointer type for @ref wgpuBufferReadMappedRange:
+ * > @copydoc wgpuBufferReadMappedRange
+ */
+typedef WGPUStatus (*WGPUProcBufferReadMappedRange)(WGPUBuffer buffer, size_t offset, void * data, size_t size) WGPU_FUNCTION_ATTRIBUTE;
 /**
  * Proc pointer type for @ref wgpuBufferSetLabel:
  * > @copydoc wgpuBufferSetLabel
@@ -4564,6 +4569,11 @@ typedef void (*WGPUProcBufferSetLabel)(WGPUBuffer buffer, WGPUStringView label)
  * > @copydoc wgpuBufferUnmap
  */
 typedef void (*WGPUProcBufferUnmap)(WGPUBuffer buffer) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Proc pointer type for @ref wgpuBufferWriteMappedRange:
+ * > @copydoc wgpuBufferWriteMappedRange
+ */
+typedef WGPUStatus (*WGPUProcBufferWriteMappedRange)(WGPUBuffer buffer, size_t offset, void const * data, size_t size) WGPU_FUNCTION_ATTRIBUTE;
 /**
  * Proc pointer type for @ref wgpuBufferAddRef.
  * > @copydoc wgpuBufferAddRef
@@ -5553,34 +5563,94 @@ WGPU_EXPORT void wgpuBufferDestroy(WGPUBuffer buffer) WGPU_FUNCTION_ATTRIBUTE;
 /**
  * Returns a const pointer to beginning of the mapped range.
  * It must not be written; writing to this range causes undefined behavior.
- * See @ref GetMappedRangeBehavior for error conditions and guarantees.
+ * See @ref MappedRangeBehavior for error conditions and guarantees.
  * This function is safe to call inside spontaneous callbacks (see @ref CallbackReentrancy).
  *
+ * In Wasm, if `memcpy`ing from this range, prefer using @ref wgpuBufferReadMappedRange
+ * instead for better performance.
+ *
  * @param offset
  * Byte offset relative to the beginning of the buffer.
  *
  * @param size
- * Byte size of the range to get. The returned pointer is valid for exactly this many bytes.
+ * Byte size of the range to get.
+ * If this is @ref WGPU_WHOLE_MAP_SIZE, it defaults to `buffer.size - offset`.
+ * The returned pointer is valid for exactly this many bytes.
  */
 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;
 /**
  * Returns a mutable pointer to beginning of the mapped range.
- * See @ref GetMappedRangeBehavior for error conditions and guarantees.
+ * See @ref MappedRangeBehavior for error conditions and guarantees.
  * This function is safe to call inside spontaneous callbacks (see @ref CallbackReentrancy).
  *
+ * In Wasm, if `memcpy`ing into this range, prefer using @ref wgpuBufferWriteMappedRange
+ * instead for better performance.
+ *
  * @param offset
  * Byte offset relative to the beginning of the buffer.
  *
  * @param size
- * Byte size of the range to get. The returned pointer is valid for exactly this many bytes.
+ * Byte size of the range to get.
+ * If this is @ref WGPU_WHOLE_MAP_SIZE, it defaults to `buffer.size - offset`.
+ * The returned pointer is valid for exactly this many bytes.
  */
 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;
 WGPU_EXPORT WGPUBufferUsage wgpuBufferGetUsage(WGPUBuffer buffer) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * @param offset
+ * Byte offset relative to beginning of the buffer.
+ *
+ * @param size
+ * Byte size of the region to map.
+ * If this is @ref WGPU_WHOLE_MAP_SIZE, it defaults to `buffer.size - offset`.
+ */
 WGPU_EXPORT WGPUFuture wgpuBufferMapAsync(WGPUBuffer buffer, WGPUMapMode mode, size_t offset, size_t size, WGPUBufferMapCallbackInfo callbackInfo) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Copies a range of data from the buffer mapping into the provided destination pointer.
+ * See @ref MappedRangeBehavior for error conditions and guarantees.
+ * This function is safe to call inside spontaneous callbacks (see @ref CallbackReentrancy).
+ *
+ * In Wasm, this is more efficient than copying from a mapped range into a `malloc`'d range.
+ *
+ * @param offset
+ * Byte offset relative to the beginning of the buffer.
+ *
+ * @param data
+ * Destination, to read buffer data into.
+ *
+ * @param size
+ * Number of bytes of data to read from the buffer.
+ * (Note @ref WGPU_WHOLE_MAP_SIZE is *not* accepted here.)
+ *
+ * @returns
+ * @ref WGPUStatus_Error if the copy did not occur.
+ */
+WGPU_EXPORT WGPUStatus wgpuBufferReadMappedRange(WGPUBuffer buffer, size_t offset, void * data, size_t size) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuBufferSetLabel(WGPUBuffer buffer, WGPUStringView label) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuBufferUnmap(WGPUBuffer buffer) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Copies a range of data from the provided source pointer into the buffer mapping.
+ * See @ref MappedRangeBehavior for error conditions and guarantees.
+ * This function is safe to call inside spontaneous callbacks (see @ref CallbackReentrancy).
+ *
+ * In Wasm, this is more efficient than copying from a `malloc`'d range into a mapped range.
+ *
+ * @param offset
+ * Byte offset relative to the beginning of the buffer.
+ *
+ * @param data
+ * Source, to write buffer data from.
+ *
+ * @param size
+ * Number of bytes of data to write to the buffer.
+ * (Note @ref WGPU_WHOLE_MAP_SIZE is *not* accepted here.)
+ *
+ * @returns
+ * @ref WGPUStatus_Error if the copy did not occur.
+ */
+WGPU_EXPORT WGPUStatus wgpuBufferWriteMappedRange(WGPUBuffer buffer, size_t offset, void const * data, size_t size) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuBufferAddRef(WGPUBuffer buffer) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuBufferRelease(WGPUBuffer buffer) WGPU_FUNCTION_ATTRIBUTE;
 /** @} */

webgpu.yml

@@ -3572,17 +3572,21 @@ objects:
             type: bitflag.map_mode
           - name: offset
             doc: |
-              TODO
+              Byte offset relative to beginning of the buffer.
             type: usize
           - name: size
             doc: |
-              TODO
+              Byte size of the region to map.
+              If this is @ref WGPU_WHOLE_MAP_SIZE, it defaults to `buffer.size - offset`.
             type: usize
       - name: get_mapped_range
         doc: |
           Returns a mutable pointer to beginning of the mapped range.
-          See @ref GetMappedRangeBehavior for error conditions and guarantees.
+          See @ref MappedRangeBehavior for error conditions and guarantees.
           This function is safe to call inside spontaneous callbacks (see @ref CallbackReentrancy).
+
+          In Wasm, if `memcpy`ing into this range, prefer using @ref wgpuBufferWriteMappedRange
+          instead for better performance.
         returns:
           doc: ""
           type: c_void
@@ -3594,14 +3598,19 @@ objects:
             type: usize
           - name: size
             doc: |
-              Byte size of the range to get. The returned pointer is valid for exactly this many bytes.
+              Byte size of the range to get.
+              If this is @ref WGPU_WHOLE_MAP_SIZE, it defaults to `buffer.size - offset`.
+              The returned pointer is valid for exactly this many bytes.
             type: usize
       - name: get_const_mapped_range
         doc: |
           Returns a const pointer to beginning of the mapped range.
           It must not be written; writing to this range causes undefined behavior.
-          See @ref GetMappedRangeBehavior for error conditions and guarantees.
+          See @ref MappedRangeBehavior for error conditions and guarantees.
           This function is safe to call inside spontaneous callbacks (see @ref CallbackReentrancy).
+
+          In Wasm, if `memcpy`ing from this range, prefer using @ref wgpuBufferReadMappedRange
+          instead for better performance.
         returns:
           doc: ""
           type: c_void
@@ -3613,7 +3622,61 @@ objects:
             type: usize
           - name: size
             doc: |
-              Byte size of the range to get. The returned pointer is valid for exactly this many bytes.
+              Byte size of the range to get.
+              If this is @ref WGPU_WHOLE_MAP_SIZE, it defaults to `buffer.size - offset`.
+              The returned pointer is valid for exactly this many bytes.
+            type: usize
+      - name: read_mapped_range
+        doc: |
+          Copies a range of data from the buffer mapping into the provided destination pointer.
+          See @ref MappedRangeBehavior for error conditions and guarantees.
+          This function is safe to call inside spontaneous callbacks (see @ref CallbackReentrancy).
+
+          In Wasm, this is more efficient than copying from a mapped range into a `malloc`'d range.
+        returns:
+          doc: |
+            @ref WGPUStatus_Error if the copy did not occur.
+          type: enum.status
+        args:
+          - name: offset
+            doc: |
+              Byte offset relative to the beginning of the buffer.
+            type: usize
+          - name: data
+            doc: |
+              Destination, to read buffer data into.
+            type: c_void
+            pointer: mutable
+          - name: size
+            doc: |
+              Number of bytes of data to read from the buffer.
+              (Note @ref WGPU_WHOLE_MAP_SIZE is *not* accepted here.)
+            type: usize
+      - name: write_mapped_range
+        doc: |
+          Copies a range of data from the provided source pointer into the buffer mapping.
+          See @ref MappedRangeBehavior for error conditions and guarantees.
+          This function is safe to call inside spontaneous callbacks (see @ref CallbackReentrancy).
+
+          In Wasm, this is more efficient than copying from a `malloc`'d range into a mapped range.
+        returns:
+          doc: |
+            @ref WGPUStatus_Error if the copy did not occur.
+          type: enum.status
+        args:
+          - name: offset
+            doc: |
+              Byte offset relative to the beginning of the buffer.
+            type: usize
+          - name: data
+            doc: |
+              Source, to write buffer data from.
+            type: c_void
+            pointer: immutable
+          - name: size
+            doc: |
+              Number of bytes of data to write to the buffer.
+              (Note @ref WGPU_WHOLE_MAP_SIZE is *not* accepted here.)
             type: usize
       - name: set_label
         doc: |