GPUBuffer

interface GPUBuffer : GPUBindingResource, GPUObjectBase, AutoCloseable

A GPUBuffer represents a block of memory that can be used in GPU operations. Data is stored in linear layout, meaning that each byte of the allocation can be addressed by its offset from the start of the GPUBuffer, subject to alignment restrictions depending on the operation. Some GPUBuffers can be mapped which makes the block of memory accessible via an ArrayBuffer called its mapping. ## Lifetime A GPUBuffer created by a device is owned by the caller. `close()` destroys the buffer: it runs the WebGPU `destroy` operation, and a native backend must also release its owned reference. Closing an already closed buffer does not release the same reference a second time; general thread safety is not promised. Mapped ranges are borrowed: they are invalidated by `unmap()` and by destroying the buffer. Whether a backend detects an access to an invalidated range is not portable.

Properties

label

abstract var label: String

A developer-provided label which is used in an implementation-defined way. It can be used by the browser, OS, or other tools to help identify the underlying internal object to the developer. Examples include displaying the label in GPUError messages, console warnings, browser developer tools, and platform debugging utilities.

mapState

abstract val mapState: GPUBufferMapState

The buffer is not mapped for use by this.getMappedRange(). A mapping of the buffer has been requested, but is pending. It may succeed, or fail validation in mapAsync().

size

abstract val size: GPUSize64Out

The length of the GPUBuffer allocation in bytes. See [GPUBuffer.size in the WebGPU specification](https://www.w3.org/TR/webgpu/#dom-gpubuffer-size).

usage

abstract val usage: GPUBufferUsage

The allowed usages for this GPUBuffer. See [GPUBuffer.usage in the WebGPU specification](https://www.w3.org/TR/webgpu/#dom-gpubuffer-usage).

Functions

close

expect abstract fun close()

getMappedRange

abstract fun getMappedRange(offset: GPUSize64, size: GPUSize64? = null): ArrayBuffer

Returns an ArrayBuffer with the contents of the GPUBuffer in the given mapped range. The returned range is borrowed, not owned: it is invalidated by `unmap()` and by destroying the buffer, and it must not be retained or used after either. Prefer `GPUBuffer.withMappedRange`, which maps, runs a non-suspending block with the borrowed range and unmaps in a `finally`. **Parameters** - offset: Offset in bytes into the buffer to return buffer contents from. - size: Size in bytes of the ArrayBuffer to return.

mapAsync

abstract suspend fun mapAsync(
    mode: GPUMapMode, 
    offset: GPUSize64, 
    size: GPUSize64? = null
): Result<Unit>

Maps the given range of the GPUBuffer and resolves the returned Promise when the GPUBuffer’s content is ready to be accessed with getMappedRange(). The resolution of the returned Promise only indicates that the buffer has been mapped. It does not guarantee the completion of any other operations visible to the content timeline, and in particular does not imply that any other Promise returned from onSubmittedWorkDone() or mapAsync() on other GPUBuffers have resolved. **Parameters** - mode: Whether the buffer should be mapped for reading or writing. - offset: Offset in bytes into the buffer to the start of the range to map. - size: Size in bytes of the range to map.

unmap

abstract fun unmap()

Unmaps the mapped range of the GPUBuffer and makes its contents available for use by the GPU again. Every borrowed range previously returned by `getMappedRange` is invalidated by this call.

withMappedRange

suspend fun <T> GPUBuffer.withMappedRange(
    mode: GPUMapMode, 
    offset: GPUSize64, 
    size: GPUSize64? = null, 
    block: (ArrayBuffer) -> T
): T

Maps this buffer, runs [`block`](index.md#withmappedrange) with the mapped range and unmaps the buffer afterwards, even when [`block`](index.md#withmappedrange) throws. The helper starts a new mapping on a buffer that is currently unmapped; it does not take over a mapping that is already in progress. Because the `try`/`finally` only starts after `mapAsync` succeeded, a failed mapping request never unmaps a pre-existing mapping. The range passed to [`block`](index.md#withmappedrange) is borrowed: it is invalidated by the `unmap()` this helper performs on exit, and by destroying the buffer. [`block`](index.md#withmappedrange) is not suspending and must neither retain nor return the borrowed view; this restriction is not enforceable through the generic type parameter. **Return** The value returned by [`block`](index.md#withmappedrange). **Parameters** - mode: The mapping mode, [`GPUMapMode.Read`](../-g-p-u-map-mode/-companion/index.md#read) or [`GPUMapMode.Write`](../-g-p-u-map-mode/-companion/index.md#write). - offset: The offset in bytes of the range to map. - size: The size in bytes of the range to map, or `null` for the rest of the buffer. - block: The non-suspending block to run with the borrowed mapped range.