typegpu 0.11.9 → 0.12.1

package/core/buffer/buffer.d.ts

@@ -1,82 +1,99 @@
-import { TgpuNamable } from "../../shared/meta.js";
-import { $internal } from "../../shared/symbols.js";
-import { Prettify, UnionToIntersection } from "../../shared/utilityTypes.js";
-import { StorageFlag } from "../../extension.js";
-import { TgpuBufferMutable, TgpuBufferReadonly, TgpuBufferUniform, TgpuFixedBufferUsage } from "./bufferUsage.js";
-import "../root/rootTypes.js";
-import { BaseData } from "../../data/wgslTypes.js";
-import { Infer, InferInput, InferPartial, InferPatch, IsValidIndexSchema, IsValidStorageSchema, IsValidUniformSchema, IsValidVertexSchema, MemIdentity } from "../../shared/repr.js";
-import "../../data/dataTypes.js";
-
-//#region src/core/buffer/buffer.d.ts
-interface UniformFlag {
-  usableAsUniform: true;
+import type { AnyData } from '../../data/dataTypes.ts';
+import type { BaseData } from '../../data/wgslTypes.ts';
+import type { StorageFlag } from '../../extension.ts';
+import type { TgpuNamable } from '../../shared/meta.ts';
+import type { Infer, InferInput, InferPatch, InferPartial, IsValidIndexSchema, IsValidStorageSchema, IsValidUniformSchema, IsValidVertexSchema, MemIdentity } from '../../shared/repr.ts';
+import type { TgpuDeviceOwningSoul } from '../../shared/soul.ts';
+import { $internal, $soul } from '../../shared/symbols.ts';
+import type { Prettify, UnionToIntersection } from '../../shared/utilityTypes.ts';
+import type { TgpuCommandEncoder } from '../commandEncoder/commandEncoder.ts';
+import type { ExperimentalTgpuRoot } from '../root/rootTypes.ts';
+import { type TgpuMutable, type TgpuReadonly, type TgpuUniform } from './bufferBinding.ts';
+export interface UniformFlag {
+    usableAsUniform: true;
 }
 /**
  * @deprecated Use UniformFlag instead.
  */
-type Uniform = UniformFlag;
-interface VertexFlag {
-  usableAsVertex: true;
+export type Uniform = UniformFlag;
+export interface VertexFlag {
+    usableAsVertex: true;
 }
-interface IndexFlag {
-  usableAsIndex: true;
+export interface IndexFlag {
+    usableAsIndex: true;
 }
-interface IndirectFlag {
-  usableAsIndirect: true;
+export interface IndirectFlag {
+    usableAsIndirect: true;
 }
 /**
  * @deprecated Use VertexFlag instead.
  */
-type Vertex = VertexFlag;
-type UsageLiteral = 'uniform' | 'storage' | 'vertex' | 'index' | 'indirect';
+export type Vertex = VertexFlag;
+export type TgpuStorageBuffer<T extends BaseData> = TgpuBuffer<T> & StorageFlag;
+export type TgpuUniformBuffer<T extends BaseData> = TgpuBuffer<T> & UniformFlag;
+export type TgpuVertexBuffer<T extends BaseData> = TgpuBuffer<T> & VertexFlag;
+export type TgpuIndexBuffer<T extends BaseData> = TgpuBuffer<T> & IndexFlag;
+export type UsageLiteral = 'uniform' | 'storage' | 'vertex' | 'index' | 'indirect';
+export interface TgpuBufferSoul<TData extends BaseData = BaseData> extends TgpuDeviceOwningSoul<'buffer', GPUBuffer> {
+    readonly dataType: TData;
+    flags: GPUBufferUsageFlags;
+    readonly usages: UsageLiteral[];
+}
 type LiteralToUsageType<T extends UsageLiteral> = T extends 'uniform' ? UniformFlag : T extends 'storage' ? StorageFlag : T extends 'vertex' ? VertexFlag : T extends 'index' ? IndexFlag : T extends 'indirect' ? IndirectFlag : never;
 type ViewUsages<TBuffer extends TgpuBuffer<BaseData>> = (boolean extends TBuffer['usableAsUniform'] ? never : 'uniform') | (boolean extends TBuffer['usableAsStorage'] ? never : 'readonly' | 'mutable');
-type UsageTypeToBufferUsage<TData extends BaseData> = {
-  uniform: TgpuBufferUniform<TData> & TgpuFixedBufferUsage<TData>;
-  mutable: TgpuBufferMutable<TData> & TgpuFixedBufferUsage<TData>;
-  readonly: TgpuBufferReadonly<TData> & TgpuFixedBufferUsage<TData>;
+type UsageTypeToBufferBinding<TData extends BaseData> = {
+    uniform: TgpuUniform<TData>;
+    mutable: TgpuMutable<TData>;
+    readonly: TgpuReadonly<TData>;
 };
 /**
  * Done as an object to later Prettify it
  */
 type InnerValidUsagesFor<T> = {
-  usage: (IsValidStorageSchema<T> extends true ? 'storage' : never) | (IsValidUniformSchema<T> extends true ? 'uniform' : never) | (IsValidVertexSchema<T> extends true ? 'vertex' : never) | (IsValidIndexSchema<T> extends true ? 'index' : never) | 'indirect';
+    usage: (IsValidStorageSchema<T> extends true ? 'storage' : never) | (IsValidUniformSchema<T> extends true ? 'uniform' : never) | (IsValidVertexSchema<T> extends true ? 'vertex' : never) | (IsValidIndexSchema<T> extends true ? 'index' : never) | 'indirect';
 };
-type ValidUsagesFor<T> = InnerValidUsagesFor<T>['usage'];
-type BufferWriteOptions = {
-  startOffset?: number;
-  endOffset?: number;
+export type ValidUsagesFor<T> = InnerValidUsagesFor<T>['usage'];
+export type BufferWriteOptions = {
+    startOffset?: number;
+    endOffset?: number;
 };
-interface TgpuBuffer<TData extends BaseData> extends TgpuNamable {
-  readonly [$internal]: true;
-  readonly resourceType: 'buffer';
-  readonly dataType: TData;
-  readonly initial?: InferInput<TData> | undefined;
-  readonly arrayBuffer: ArrayBuffer;
-  readonly buffer: GPUBuffer;
-  readonly destroyed: boolean;
-  usableAsUniform: boolean;
-  usableAsStorage: boolean;
-  usableAsVertex: boolean;
-  usableAsIndex: boolean;
-  usableAsIndirect: boolean;
-  $usage<T extends [Prettify<InnerValidUsagesFor<TData>>['usage'], ...Prettify<InnerValidUsagesFor<TData>>['usage'][]]>(...usages: T): this & UnionToIntersection<LiteralToUsageType<T[number]>>;
-  $addFlags(flags: GPUBufferUsageFlags): this;
-  as<T extends ViewUsages<this>>(usage: T): UsageTypeToBufferUsage<TData>[T];
-  compileWriter(): void;
-  write(data: InferInput<TData>, options?: BufferWriteOptions): void;
-  write(data: ArrayBuffer, options?: BufferWriteOptions): void;
-  /** @deprecated Use {@link patch} instead. */
-  writePartial(data: InferPartial<TData>): void;
-  patch(data: InferPatch<TData>): void;
-  clear(): void;
-  copyFrom(srcBuffer: TgpuBuffer<MemIdentity<TData>>): void;
-  read(): Promise<Infer<TData>>;
-  destroy(): void;
-  toString(): string;
+export type BufferInitCallback<TData extends BaseData> = (buffer: TgpuBuffer<TData>) => void;
+export type BufferInitialData<TData extends BaseData> = InferInput<TData> | BufferInitCallback<TData>;
+export interface TgpuBuffer<TData extends BaseData> extends TgpuNamable {
+    readonly [$internal]: {
+        readonly root: ExperimentalTgpuRoot;
+        readonly materialize: () => GPUBuffer;
+    };
+    readonly [$soul]: TgpuBufferSoul<TData>;
+    readonly resourceType: 'buffer';
+    readonly dataType: TData;
+    readonly initial?: InferInput<TData> | undefined;
+    readonly arrayBuffer: ArrayBuffer;
+    readonly buffer: GPUBuffer;
+    readonly destroyed: boolean;
+    usableAsUniform: boolean;
+    usableAsStorage: boolean;
+    usableAsVertex: boolean;
+    usableAsIndex: boolean;
+    usableAsIndirect: boolean;
+    $usage<T extends [
+        Prettify<InnerValidUsagesFor<TData>>['usage'],
+        ...Prettify<InnerValidUsagesFor<TData>>['usage'][]
+    ]>(...usages: T): this & UnionToIntersection<LiteralToUsageType<T[number]>>;
+    $addFlags(flags: GPUBufferUsageFlags): this;
+    as<T extends ViewUsages<this>>(usage: T): UsageTypeToBufferBinding<TData>[T];
+    compileWriter(): void;
+    write(data: InferInput<TData>, options?: BufferWriteOptions): void;
+    write(data: ArrayBuffer, options?: BufferWriteOptions): void;
+    /** @deprecated Use {@link patch} instead. */
+    writePartial(data: InferPartial<TData>): void;
+    patch(data: InferPatch<TData>): void;
+    clear(encoder?: TgpuCommandEncoder): void;
+    copyFrom(srcBuffer: TgpuBuffer<MemIdentity<TData>>, encoder?: TgpuCommandEncoder): void;
+    read(): Promise<Infer<TData>>;
+    destroy(): void;
+    toString(): string;
 }
-declare function isBuffer(value: unknown): value is TgpuBuffer<BaseData>;
-declare function isUsableAsVertex<T extends TgpuBuffer<BaseData>>(buffer: T): buffer is T & VertexFlag;
-//#endregion
-export { BufferWriteOptions, IndexFlag, IndirectFlag, TgpuBuffer, Uniform, UniformFlag, ValidUsagesFor, Vertex, VertexFlag, isBuffer, isUsableAsVertex };
+export declare function INTERNAL_createBuffer<TData extends AnyData>(group: ExperimentalTgpuRoot, typeSchema: TData, initialOrBuffer?: BufferInitialData<TData> | GPUBuffer): TgpuBuffer<TData>;
+export declare function INTERNAL_applyBufferUsages(buffer: TgpuBuffer<BaseData>, usages: UsageLiteral[]): void;
+export {};

package/core/buffer/buffer.js

@@ -1,212 +1,290 @@
-import { $internal } from "../../shared/symbols.js";
+import { getCompiledWriter } from "../../data/compiledIO.js";
+import { convertPartialToPatch, getPatchInstructions } from "../../data/partialIO.js";
+import { sizeOf } from "../../data/sizeOf.js";
 import { isWgslData } from "../../data/wgslTypes.js";
 import { getName, setName } from "../../shared/meta.js";
+import { $internal, $soul } from "../../shared/symbols.js";
 import { isGPUBuffer } from "../../types.js";
-import { sizeOf } from "../../data/sizeOf.js";
-import { getCompiledWriter } from "../../data/compiledIO.js";
 import { calculateOffsets, readFromArrayBuffer, writeToArrayBuffer } from "../../data/dataIO.js";
-import { convertPartialToPatch, getPatchInstructions, patchArrayBuffer } from "../../data/partialIO.js";
-import { mutable, readonly, uniform } from "./bufferUsage.js";
-
-//#region src/core/buffer/buffer.ts
-const usageToUsageConstructor = {
-	uniform,
-	mutable,
-	readonly
-};
-function INTERNAL_createBuffer(group, typeSchema, initialOrBuffer) {
-	if (!isWgslData(typeSchema)) return new TgpuBufferImpl(group, typeSchema, initialOrBuffer, ["storage", "uniform"]);
-	return new TgpuBufferImpl(group, typeSchema, initialOrBuffer);
+import { patchArrayBuffer } from "../../data/partialIO.js";
+import { mutable, readonly, uniform, } from "./bufferBinding.js";
+import { warnIfNotUniformAligned } from "../pipeline/webgpuLimitations.js";
+const usageToUsageConstructor = { uniform, mutable, readonly };
+export function INTERNAL_createBuffer(group, typeSchema, initialOrBuffer) {
+    if (!isWgslData(typeSchema)) {
+        return new TgpuBufferImpl(group, typeSchema, initialOrBuffer, ['storage', 'uniform']);
+    }
+    return new TgpuBufferImpl(group, typeSchema, initialOrBuffer);
 }
-function isBuffer(value) {
-	return value.resourceType === "buffer";
+export function INTERNAL_applyBufferUsages(buffer, usages) {
+    if (usages.length > 0) {
+        buffer.$usage(...usages);
+    }
 }
-function isUsableAsVertex(buffer) {
-	return !!buffer.usableAsVertex;
+// --------------
+// Implementation
+// --------------
+class TgpuBufferImpl {
+    [$internal];
+    [$soul];
+    resourceType = 'buffer';
+    #ownBuffer;
+    #destroyed = false;
+    #internalBuffer;
+    get #hostBuffer() {
+        return (this.#internalBuffer ??= new ArrayBuffer(sizeOf(this.dataType)));
+    }
+    #mappedRange;
+    #initialCallback;
+    #disallowedUsages;
+    initial;
+    usableAsUniform = false;
+    usableAsStorage = false;
+    usableAsVertex = false;
+    usableAsIndex = false;
+    usableAsIndirect = false;
+    constructor(root, dataType, initialOrBuffer, disallowedUsages) {
+        this[$soul] = {
+            type: 'buffer',
+            device: root.device,
+            dataType,
+            flags: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+            usages: [],
+            raw: undefined,
+            label: undefined,
+        };
+        this.#disallowedUsages = disallowedUsages;
+        if (isGPUBuffer(initialOrBuffer)) {
+            this.#ownBuffer = false;
+            this[$soul].raw = initialOrBuffer;
+        }
+        else {
+            this.#ownBuffer = true;
+            if (typeof initialOrBuffer === 'function') {
+                this.#initialCallback = initialOrBuffer;
+            }
+            else {
+                this.initial = initialOrBuffer;
+            }
+        }
+        this[$internal] = {
+            root,
+            materialize: () => {
+                if (this.#destroyed) {
+                    throw new Error('This buffer has been destroyed');
+                }
+                const soul = this[$soul];
+                if (!soul.raw) {
+                    soul.raw = soul.device.createBuffer({
+                        size: sizeOf(soul.dataType),
+                        usage: soul.flags,
+                        mappedAtCreation: !!this.initial || !!this.#initialCallback,
+                        label: getName(this) ?? '<unnamed>',
+                    });
+                    if (this.initial || this.#initialCallback) {
+                        if (this.#initialCallback) {
+                            this.#initialCallback(this);
+                        }
+                        else if (this.initial) {
+                            writeToArrayBuffer(this.#getMappedRange(), this.dataType, this.initial);
+                        }
+                        this.#unmapBuffer();
+                    }
+                }
+                return soul.raw;
+            },
+        };
+    }
+    get dataType() {
+        return this[$soul].dataType;
+    }
+    get flags() {
+        return this[$soul].flags;
+    }
+    set flags(value) {
+        this[$soul].flags = value;
+    }
+    get buffer() {
+        return this[$internal].materialize();
+    }
+    get destroyed() {
+        return this.#destroyed;
+    }
+    get arrayBuffer() {
+        const gpuBuffer = this.buffer;
+        if (gpuBuffer.mapState === 'mapped') {
+            return this.#getMappedRange();
+        }
+        return this.#hostBuffer;
+    }
+    #getMappedRange() {
+        const raw = this[$soul].raw;
+        if (!raw || raw.mapState !== 'mapped') {
+            throw new Error('Buffer is not mapped.');
+        }
+        this.#mappedRange ??= raw.getMappedRange();
+        return this.#mappedRange;
+    }
+    #unmapBuffer() {
+        const raw = this[$soul].raw;
+        if (!raw || raw.mapState !== 'mapped') {
+            return;
+        }
+        this.#mappedRange = undefined;
+        raw.unmap();
+    }
+    $name(label) {
+        setName(this, label);
+        const raw = this[$soul].raw;
+        if (raw) {
+            raw.label = label;
+        }
+        return this;
+    }
+    $usage(...usages) {
+        for (const usage of usages) {
+            if (this.#disallowedUsages?.includes(usage)) {
+                throw new Error(`Buffer of type ${this.dataType.type} cannot be used as ${usage}`);
+            }
+            if (usage === 'uniform') {
+                warnIfNotUniformAligned(this.dataType);
+            }
+            this.flags |= usage === 'uniform' ? GPUBufferUsage.UNIFORM : 0;
+            this.flags |= usage === 'storage' ? GPUBufferUsage.STORAGE : 0;
+            this.flags |= usage === 'vertex' ? GPUBufferUsage.VERTEX : 0;
+            this.flags |= usage === 'index' ? GPUBufferUsage.INDEX : 0;
+            this.flags |= usage === 'indirect' ? GPUBufferUsage.INDIRECT : 0;
+            this.usableAsUniform = this.usableAsUniform || usage === 'uniform';
+            this.usableAsStorage = this.usableAsStorage || usage === 'storage';
+            this.usableAsVertex = this.usableAsVertex || usage === 'vertex';
+            this.usableAsIndex = this.usableAsIndex || usage === 'index';
+            this.usableAsIndirect = this.usableAsIndirect || usage === 'indirect';
+            if (!this[$soul].usages.includes(usage)) {
+                this[$soul].usages.push(usage);
+            }
+        }
+        return this;
+    }
+    $addFlags(flags) {
+        if (!this.#ownBuffer) {
+            throw new Error('Cannot add flags to a buffer that is not managed by TypeGPU.');
+        }
+        if (flags & GPUBufferUsage.MAP_READ) {
+            this.flags = GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ;
+            return this;
+        }
+        if (flags & GPUBufferUsage.MAP_WRITE) {
+            this.flags = GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE;
+            return this;
+        }
+        this.flags |= flags;
+        return this;
+    }
+    compileWriter() {
+        getCompiledWriter(this.dataType);
+    }
+    write(data, options) {
+        const gpuBuffer = this.buffer;
+        if (gpuBuffer.mapState === 'mapped') {
+            const mapped = this.#getMappedRange();
+            if (data instanceof ArrayBuffer && data === mapped) {
+                // The caller already wrote data directly into the mapped range
+                // via arrayBuffer. Nothing to do here
+                return;
+            }
+            writeToArrayBuffer(mapped, this.dataType, data, options);
+            return;
+        }
+        // If the caller already wrote directly into #hostBuffer via
+        // arrayBuffer, skip the redundant copy, the data is already in place.
+        if (!(data instanceof ArrayBuffer && data === this.#hostBuffer)) {
+            writeToArrayBuffer(this.#hostBuffer, this.dataType, data, options);
+        }
+        const { startOffset, endOffset } = calculateOffsets(options, this.dataType, data);
+        const size = endOffset - startOffset;
+        this[$soul].device.queue.writeBuffer(gpuBuffer, startOffset, this.#hostBuffer, startOffset, size);
+    }
+    /** @deprecated Use {@link patch} instead. */
+    writePartial(data) {
+        this.patch(convertPartialToPatch(this.dataType, data));
+    }
+    patch(data) {
+        const gpuBuffer = this.buffer;
+        if (gpuBuffer.mapState === 'mapped') {
+            patchArrayBuffer(this.#getMappedRange(), this.dataType, data);
+        }
+        else {
+            const instructions = getPatchInstructions(this.dataType, data, this.#hostBuffer);
+            for (const { data, gpuOffset } of instructions) {
+                this[$soul].device.queue.writeBuffer(gpuBuffer, gpuOffset, data);
+            }
+        }
+    }
+    clear(encoder) {
+        const gpuBuffer = this.buffer;
+        if (encoder) {
+            encoder[$internal].rawEncoder.clearBuffer(gpuBuffer);
+            return;
+        }
+        if (gpuBuffer.mapState === 'mapped') {
+            new Uint8Array(this.#getMappedRange()).fill(0);
+            return;
+        }
+        const rawEncoder = this[$soul].device.createCommandEncoder();
+        rawEncoder.clearBuffer(gpuBuffer);
+        this[$soul].device.queue.submit([rawEncoder.finish()]);
+    }
+    copyFrom(srcBuffer, encoder) {
+        if (this.buffer.mapState === 'mapped') {
+            throw new Error('Cannot copy to a mapped buffer.');
+        }
+        const size = sizeOf(this.dataType);
+        if (encoder) {
+            encoder[$internal].rawEncoder.copyBufferToBuffer(srcBuffer.buffer, 0, this.buffer, 0, size);
+            return;
+        }
+        const rawEncoder = this[$soul].device.createCommandEncoder();
+        rawEncoder.copyBufferToBuffer(srcBuffer.buffer, 0, this.buffer, 0, size);
+        this[$soul].device.queue.submit([rawEncoder.finish()]);
+    }
+    async read() {
+        const gpuBuffer = this.buffer;
+        if (gpuBuffer.mapState === 'mapped') {
+            return readFromArrayBuffer(this.#getMappedRange(), this.dataType);
+        }
+        if (gpuBuffer.usage & GPUBufferUsage.MAP_READ) {
+            await gpuBuffer.mapAsync(GPUMapMode.READ);
+            const res = readFromArrayBuffer(this.#getMappedRange(), this.dataType);
+            this.#unmapBuffer();
+            return res;
+        }
+        const stagingBuffer = this[$soul].device.createBuffer({
+            size: sizeOf(this.dataType),
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+        });
+        const commandEncoder = this[$soul].device.createCommandEncoder();
+        commandEncoder.copyBufferToBuffer(gpuBuffer, 0, stagingBuffer, 0, sizeOf(this.dataType));
+        this[$soul].device.queue.submit([commandEncoder.finish()]);
+        await stagingBuffer.mapAsync(GPUMapMode.READ, 0, sizeOf(this.dataType));
+        const res = readFromArrayBuffer(stagingBuffer.getMappedRange(), this.dataType);
+        stagingBuffer.unmap();
+        stagingBuffer.destroy();
+        return res;
+    }
+    as(usage) {
+        return usageToUsageConstructor[usage](this);
+    }
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+        this.#destroyed = true;
+        this.#mappedRange = undefined;
+        if (this.#ownBuffer) {
+            this[$soul].raw?.destroy();
+        }
+    }
+    toString() {
+        return `buffer:${getName(this) ?? '<unnamed>'}`;
+    }
 }
-var TgpuBufferImpl = class {
-	[$internal] = true;
-	resourceType = "buffer";
-	flags = GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
-	dataType;
-	#device;
-	#buffer = null;
-	#ownBuffer;
-	#destroyed = false;
-	#internalBuffer;
-	get #hostBuffer() {
-		return this.#internalBuffer ??= new ArrayBuffer(sizeOf(this.dataType));
-	}
-	#mappedRange;
-	#initialCallback;
-	#disallowedUsages;
-	initial;
-	usableAsUniform = false;
-	usableAsStorage = false;
-	usableAsVertex = false;
-	usableAsIndex = false;
-	usableAsIndirect = false;
-	constructor(root, dataType, initialOrBuffer, disallowedUsages) {
-		this.dataType = dataType;
-		this.#disallowedUsages = disallowedUsages;
-		this.#device = root.device;
-		if (isGPUBuffer(initialOrBuffer)) {
-			this.#ownBuffer = false;
-			this.#buffer = initialOrBuffer;
-		} else {
-			this.#ownBuffer = true;
-			if (typeof initialOrBuffer === "function") this.#initialCallback = initialOrBuffer;
-			else this.initial = initialOrBuffer;
-		}
-	}
-	get buffer() {
-		if (this.#destroyed) throw new Error("This buffer has been destroyed");
-		if (!this.#buffer) {
-			this.#buffer = this.#device.createBuffer({
-				size: sizeOf(this.dataType),
-				usage: this.flags,
-				mappedAtCreation: !!this.initial || !!this.#initialCallback,
-				label: getName(this) ?? "<unnamed>"
-			});
-			if (this.initial || this.#initialCallback) {
-				if (this.#initialCallback) this.#initialCallback(this);
-				else if (this.initial) writeToArrayBuffer(this.#getMappedRange(), this.dataType, this.initial);
-				this.#unmapBuffer();
-			}
-		}
-		return this.#buffer;
-	}
-	get destroyed() {
-		return this.#destroyed;
-	}
-	get arrayBuffer() {
-		if (this.buffer.mapState === "mapped") return this.#getMappedRange();
-		return this.#hostBuffer;
-	}
-	#getMappedRange() {
-		if (!this.#buffer || this.#buffer.mapState !== "mapped") throw new Error("Buffer is not mapped.");
-		this.#mappedRange ??= this.#buffer.getMappedRange();
-		return this.#mappedRange;
-	}
-	#unmapBuffer() {
-		if (!this.#buffer || this.#buffer.mapState !== "mapped") return;
-		this.#mappedRange = void 0;
-		this.#buffer.unmap();
-	}
-	$name(label) {
-		setName(this, label);
-		if (this.#buffer) this.#buffer.label = label;
-		return this;
-	}
-	$usage(...usages) {
-		for (const usage of usages) {
-			if (this.#disallowedUsages?.includes(usage)) throw new Error(`Buffer of type ${this.dataType.type} cannot be used as ${usage}`);
-			this.flags |= usage === "uniform" ? GPUBufferUsage.UNIFORM : 0;
-			this.flags |= usage === "storage" ? GPUBufferUsage.STORAGE : 0;
-			this.flags |= usage === "vertex" ? GPUBufferUsage.VERTEX : 0;
-			this.flags |= usage === "index" ? GPUBufferUsage.INDEX : 0;
-			this.flags |= usage === "indirect" ? GPUBufferUsage.INDIRECT : 0;
-			this.usableAsUniform = this.usableAsUniform || usage === "uniform";
-			this.usableAsStorage = this.usableAsStorage || usage === "storage";
-			this.usableAsVertex = this.usableAsVertex || usage === "vertex";
-			this.usableAsIndex = this.usableAsIndex || usage === "index";
-			this.usableAsIndirect = this.usableAsIndirect || usage === "indirect";
-		}
-		return this;
-	}
-	$addFlags(flags) {
-		if (!this.#ownBuffer) throw new Error("Cannot add flags to a buffer that is not managed by TypeGPU.");
-		if (flags & GPUBufferUsage.MAP_READ) {
-			this.flags = GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ;
-			return this;
-		}
-		if (flags & GPUBufferUsage.MAP_WRITE) {
-			this.flags = GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE;
-			return this;
-		}
-		this.flags |= flags;
-		return this;
-	}
-	compileWriter() {
-		getCompiledWriter(this.dataType);
-	}
-	write(data, options) {
-		const gpuBuffer = this.buffer;
-		if (gpuBuffer.mapState === "mapped") {
-			const mapped = this.#getMappedRange();
-			if (data instanceof ArrayBuffer && data === mapped) return;
-			writeToArrayBuffer(mapped, this.dataType, data, options);
-			return;
-		}
-		if (!(data instanceof ArrayBuffer && data === this.#hostBuffer)) writeToArrayBuffer(this.#hostBuffer, this.dataType, data, options);
-		const { startOffset, endOffset } = calculateOffsets(options, this.dataType, data);
-		const size = endOffset - startOffset;
-		this.#device.queue.writeBuffer(gpuBuffer, startOffset, this.#hostBuffer, startOffset, size);
-	}
-	/** @deprecated Use {@link patch} instead. */
-	writePartial(data) {
-		this.patch(convertPartialToPatch(this.dataType, data));
-	}
-	patch(data) {
-		const gpuBuffer = this.buffer;
-		if (gpuBuffer.mapState === "mapped") patchArrayBuffer(this.#getMappedRange(), this.dataType, data);
-		else {
-			const instructions = getPatchInstructions(this.dataType, data, this.#hostBuffer);
-			for (const { data: data$1, gpuOffset } of instructions) this.#device.queue.writeBuffer(gpuBuffer, gpuOffset, data$1);
-		}
-	}
-	clear() {
-		const gpuBuffer = this.buffer;
-		if (gpuBuffer.mapState === "mapped") {
-			new Uint8Array(this.#getMappedRange()).fill(0);
-			return;
-		}
-		const encoder = this.#device.createCommandEncoder();
-		encoder.clearBuffer(gpuBuffer);
-		this.#device.queue.submit([encoder.finish()]);
-	}
-	copyFrom(srcBuffer) {
-		if (this.buffer.mapState === "mapped") throw new Error("Cannot copy to a mapped buffer.");
-		const size = sizeOf(this.dataType);
-		const encoder = this.#device.createCommandEncoder();
-		encoder.copyBufferToBuffer(srcBuffer.buffer, 0, this.buffer, 0, size);
-		this.#device.queue.submit([encoder.finish()]);
-	}
-	async read() {
-		const gpuBuffer = this.buffer;
-		if (gpuBuffer.mapState === "mapped") return readFromArrayBuffer(this.#getMappedRange(), this.dataType);
-		if (gpuBuffer.usage & GPUBufferUsage.MAP_READ) {
-			await gpuBuffer.mapAsync(GPUMapMode.READ);
-			const res$1 = readFromArrayBuffer(this.#getMappedRange(), this.dataType);
-			this.#unmapBuffer();
-			return res$1;
-		}
-		const stagingBuffer = this.#device.createBuffer({
-			size: sizeOf(this.dataType),
-			usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
-		});
-		const commandEncoder = this.#device.createCommandEncoder();
-		commandEncoder.copyBufferToBuffer(gpuBuffer, 0, stagingBuffer, 0, sizeOf(this.dataType));
-		this.#device.queue.submit([commandEncoder.finish()]);
-		await stagingBuffer.mapAsync(GPUMapMode.READ, 0, sizeOf(this.dataType));
-		const res = readFromArrayBuffer(stagingBuffer.getMappedRange(), this.dataType);
-		stagingBuffer.unmap();
-		stagingBuffer.destroy();
-		return res;
-	}
-	as(usage) {
-		return usageToUsageConstructor[usage]?.(this);
-	}
-	destroy() {
-		if (this.#destroyed) return;
-		this.#destroyed = true;
-		this.#mappedRange = void 0;
-		if (this.#ownBuffer) this.#buffer?.destroy();
-	}
-	toString() {
-		return `buffer:${getName(this) ?? "<unnamed>"}`;
-	}
-};
-
-//#endregion
-export { INTERNAL_createBuffer, isBuffer, isUsableAsVertex };