25879749619

Committed 14 May 2026 07:05PM UTC coverage: 74.881% (-0.2%) from 75.089%

Build # 25879749619

Build Type

push

github

Committed by

web-flow

Commit Message

feat(text) TextArrowModel (#2615)

Coverage Stats

6380 of 9600 branches covered (66.46%)

Branch coverage included in aggregate %.

462 of 672 new or added lines in 6 files covered. (68.75%)

123 existing lines in 9 files now uncovered.

13975 of 17583 relevant lines covered (79.48%)

782.31 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

68.78

/modules/engine/src/dynamic-buffer/dynamic-buffer.ts

// luma.gl
// SPDX-License-Identifier: MIT
// Copyright (c) vis.gl contributors

import type {BufferMapCallback, BufferProps, Device, Binding as CoreBinding} from '@luma.gl/core';
import {Buffer} from '@luma.gl/core';
import {uid} from '../utils/uid';

/** Controls whether a {@link DynamicBuffer} keeps a CPU-side debug mirror of recent writes. */
export type DynamicBufferDebugProps =
  | boolean
  | {
      /** Maximum number of bytes retained in {@link DynamicBuffer.debugData}. */
      maxByteLength?: number;
    };

/** Construction props for a {@link DynamicBuffer}. */
export type DynamicBufferProps = Omit<BufferProps, 'handle' | 'onMapped'> & {
  /** Enables and optionally sizes the CPU-side debug mirror. */
  debugData?: DynamicBufferDebugProps;
  /** Existing immutable buffer to expose through this dynamic wrapper without copying. */
  buffer?: Buffer;
  /** Whether this dynamic wrapper should destroy an adopted `buffer`. Defaults to `true`. */
  ownsBuffer?: boolean;
};

/** Buffer-like source accepted by dynamic buffer range helpers. */
export type DynamicBufferBindingSource = Buffer | DynamicBuffer;

/** Binding range that may point at either a {@link Buffer} or a {@link DynamicBuffer}. */
export type DynamicBufferRange = {
  /** Buffer source for the binding range. */
  buffer: DynamicBufferBindingSource;
  /** Byte offset into the current backing buffer. */
  offset?: number;
  /** Byte length of the binding range. */
  size?: number;
};

/** Generic buffer range binding accepted by engine binding resolution helpers. */
export type BufferRangeBinding = {
  /** Buffer source for the binding range. */
  buffer: DynamicBufferBindingSource;
  /** Byte offset into the current backing buffer. */
  offset?: number;
  /** Byte length of the binding range. */
  size?: number;
};

const DEFAULT_MAX_DEBUG_DATA_BYTE_LENGTH = Buffer.DEBUG_DATA_MAX_LENGTH;

/**
 * Mutable engine-level wrapper around an immutable core {@link Buffer}.
 *
 * `DynamicBuffer` keeps a stable application object while allowing the backing
 * GPU buffer to be replaced on resize. Engine classes such as {@link Model} and
 * {@link Material} resolve it to the current backing buffer at draw time and
 * invalidate cached bindings when {@link generation} changes.
 */
export class DynamicBuffer {
  /** Device that owns the backing buffer. */
  readonly device: Device;
  /** Application-provided or generated identifier. */
  readonly id: string;
  /** Ready promise provided for compatibility with other dynamic resources. */
  readonly ready: Promise<Buffer>;
  /** Usage flags applied to every backing buffer created by this wrapper. */
  readonly usage: number;
  /** Normalized buffer props reused when the backing buffer is recreated. */
  readonly props: Readonly<DynamicBufferProps>;

  /** Dynamic buffers are synchronously ready after construction. */
  isReady = true;
  /** Whether {@link destroy} has been called. */
  destroyed = false;
  /** Monotonic version that increments whenever the backing buffer is replaced. */
  generation = 0;
  /** Last update timestamp for writes, reads that populate debug data, or resize operations. */
  updateTimestamp: number;
  /** Token replaced whenever cache users need a new resource identity. */
  cacheToken: object = {};
  /** Optional CPU-side mirror of recent writes and readbacks for debugging. */
  debugData: ArrayBuffer = new ArrayBuffer(0);

  private readonly _debugDataEnabled: boolean;
  private readonly _maxDebugDataByteLength: number;
  private _ownsBuffer: boolean;
  private _buffer: Buffer;

  /** Current immutable core buffer backing this dynamic wrapper. */
  get buffer(): Buffer {
    return this._buffer;
  }

  /** Current byte length of the backing buffer. */
  get byteLength(): number {
    return this._buffer.byteLength;
  }

  /** String tag used by `Object.prototype.toString`. */
  get [Symbol.toStringTag](): string {
    return 'DynamicBuffer';
  }

  /** Human-readable debug string. */
  toString(): string {
    return `DynamicBuffer:"${this.id}":${this.byteLength}B`;
  }

  /** Creates a dynamic buffer and its initial backing {@link Buffer}. */
  constructor(device: Device, props: DynamicBufferProps) {
    const {
      debugData: debugDataProps = false,
      buffer: adoptedBuffer,
      ownsBuffer = true,
      ...bufferProps
    } = props;
    if (adoptedBuffer && adoptedBuffer.device !== device) {
      throw new Error('DynamicBuffer adopted buffers must belong to the supplied device');
    }
    if (adoptedBuffer && (bufferProps.byteLength !== undefined || bufferProps.data !== undefined)) {
      throw new Error('DynamicBuffer cannot combine an adopted buffer with byteLength or data');
    }

    const id = props.id || adoptedBuffer?.id || uid('dynamic-buffer');
    const normalizedBufferProps: DynamicBufferProps = {
      ...bufferProps,
      id,
      usage: bufferProps.usage ?? adoptedBuffer?.usage,
      indexType: bufferProps.indexType ?? adoptedBuffer?.indexType
    };

    if ((normalizedBufferProps.usage || 0) & Buffer.INDEX && !normalizedBufferProps.indexType) {
      if (bufferProps.data instanceof Uint32Array) {
        normalizedBufferProps.indexType = 'uint32';
      } else if (bufferProps.data instanceof Uint16Array) {
        normalizedBufferProps.indexType = 'uint16';
      } else if (bufferProps.data instanceof Uint8Array) {
        normalizedBufferProps.indexType = 'uint8';
      }
    }

    delete normalizedBufferProps.data;
    delete normalizedBufferProps.byteOffset;

    this.device = device;
    this.id = id;
    this.props = normalizedBufferProps;
    this.usage = normalizedBufferProps.usage || 0;
    this._debugDataEnabled = Boolean(debugDataProps);
    this._maxDebugDataByteLength =
      typeof debugDataProps === 'object' && debugDataProps.maxByteLength !== undefined
        ? debugDataProps.maxByteLength
        : DEFAULT_MAX_DEBUG_DATA_BYTE_LENGTH;
    this._ownsBuffer = ownsBuffer;

    this._buffer = adoptedBuffer ?? this.device.createBuffer({...bufferProps, id});
    this.ready = Promise.resolve(this._buffer);
    this.updateTimestamp = this._buffer.updateTimestamp;

    this._resetDebugData(this._buffer.byteLength);
    if (bufferProps.data) {
      this._writeDebugData(bufferProps.data, bufferProps.byteOffset || 0);
    }
  }

  /**
   * Writes bytes into the current backing buffer.
   *
   * @param data - Bytes or typed-array view to upload.
   * @param byteOffset - Destination byte offset in the backing buffer.
   */
  write(data: ArrayBuffer | SharedArrayBuffer | ArrayBufferView, byteOffset: number = 0): void {
    this._buffer.write(data, byteOffset);
    this._touch();
    this._writeDebugData(data, byteOffset);
  }

  /**
   * Maps the current backing buffer for writing and mirrors the written range when debug data is enabled.
   *
   * @param callback - Callback invoked with the mapped range.
   * @param byteOffset - Byte offset of the mapped range.
   * @param byteLength - Byte length of the mapped range.
   */
  async mapAndWriteAsync(
    callback: BufferMapCallback<void | Promise<void>>,
    byteOffset: number = 0,
    byteLength: number = this.byteLength - byteOffset
  ): Promise<void> {
    let copiedBytes: Uint8Array | null = null;
    await this._buffer.mapAndWriteAsync(
      async (arrayBuffer, lifetime) => {
        await callback(arrayBuffer, lifetime);
        copiedBytes = new Uint8Array(arrayBuffer.slice(0, byteLength));
      },
      byteOffset,
      byteLength
    );
    this._touch();
    if (copiedBytes) {
      this._writeDebugData(copiedBytes, byteOffset);
    }
  }

  /**
   * Reads bytes from the current backing buffer.
   *
   * @param byteOffset - Source byte offset in the backing buffer.
   * @param byteLength - Number of bytes to read.
   */
  async readAsync(
    byteOffset: number = 0,
    byteLength = this.byteLength - byteOffset
  ): Promise<Uint8Array> {
    const data = await this._buffer.readAsync(byteOffset, byteLength);
    if (this._writeDebugData(data, byteOffset)) {
      this._touch();
    }
    return data;
  }

  /**
   * Maps the current backing buffer for reading.
   *
   * @param callback - Callback invoked with the mapped range.
   * @param byteOffset - Byte offset of the mapped range.
   * @param byteLength - Byte length of the mapped range.
   */
  async mapAndReadAsync<T>(
    callback: BufferMapCallback<T>,
    byteOffset: number = 0,
    byteLength: number = this.byteLength - byteOffset
  ): Promise<T> {
    let copiedBytes: Uint8Array | null = null;
    const result = await this._buffer.mapAndReadAsync(
      async (arrayBuffer, lifetime) => {
        copiedBytes = new Uint8Array(arrayBuffer.slice(0));
        return await callback(arrayBuffer, lifetime);
      },
      byteOffset,
      byteLength
    );
    if (copiedBytes && this._writeDebugData(copiedBytes, byteOffset)) {
      this._touch();
    }
    return result;
  }

  /**
   * Replaces the backing buffer with a new size.
   *
   * @param options.byteLength - New backing buffer byte length.
   * @param options.preserveData - Copies bytes from the old buffer into the new buffer.
   * @param options.copyByteLength - Maximum number of bytes to copy when preserving data.
   * @returns `true` when a new backing buffer was created.
   */
  resize(options: {byteLength: number; preserveData?: boolean; copyByteLength?: number}): boolean {
    const {byteLength, preserveData = false} = options;
    if (byteLength === this.byteLength) {
      return false;
    }

    const copyByteLength = Math.min(
      options.copyByteLength ?? Math.min(this.byteLength, byteLength),
      this.byteLength,
      byteLength
    );

    const previousBuffer = this._buffer;
    const previousDebugData = this.debugData.slice(0);
    const {
      data: _initialData,
      byteOffset: _initialByteOffset,
      ...resizableBufferProps
    } = this.props;
    const nextBuffer = this.device.createBuffer({
      ...resizableBufferProps,
      byteLength
    });

    if (preserveData && copyByteLength > 0) {
      this._copyBufferContents(previousBuffer, nextBuffer, copyByteLength);
    }

    this._buffer = nextBuffer;
    this._resetDebugData(byteLength);
    if (preserveData && previousDebugData.byteLength > 0) {
      this._writeDebugData(previousDebugData, 0);
    }

    if (this._ownsBuffer) {
      previousBuffer.destroy();
    }
    this._ownsBuffer = true;
    this.generation++;
    this.cacheToken = {};
    this._touch();
    return true;
  }

  /**
   * Grows the backing buffer when the requested size exceeds the current size.
   *
   * @param byteLength - Minimum required byte length.
   * @param options.preserveData - Copies existing bytes when growth is required.
   * @returns `true` when the backing buffer grew.
   */
  ensureSize(byteLength: number, options?: {preserveData?: boolean}): boolean {
    if (byteLength <= this.byteLength) {
      return false;
    }

    return this.resize({
      byteLength,
      preserveData: options?.preserveData
    });
  }

  /**
   * Returns the current backing buffer or a range binding over it.
   *
   * @param range - Optional byte range for uniform/storage buffer bindings.
   */
  getBinding(range?: {offset?: number; size?: number}): CoreBinding {
    if (range?.offset === undefined && range?.size === undefined) {
      return this._buffer;
    }

    return {
      buffer: this._buffer,
      offset: range?.offset,
      size: range?.size
    };
  }

  /** Destroys the current backing buffer and clears debug data. */
  destroy(): void {
    if (!this.destroyed) {
      if (this._ownsBuffer) {
        this._buffer.destroy();
      }
      this.destroyed = true;
      this.debugData = new ArrayBuffer(0);
    }
  }

  private _copyBufferContents(
    sourceBuffer: Buffer,
    destinationBuffer: Buffer,
    byteLength: number
  ): void {
    const commandEncoder = this.device.createCommandEncoder();
    commandEncoder.copyBufferToBuffer({
      sourceBuffer,
      destinationBuffer,
      size: byteLength
    });
    this.device.submit(commandEncoder.finish());
  }

  private _touch(): void {
    this.updateTimestamp = this.device.incrementTimestamp();
  }

  private _resetDebugData(byteLength: number): void {
    if (!this._debugDataEnabled) {
      this.debugData = new ArrayBuffer(0);
      return;
    }

    this.debugData = new ArrayBuffer(Math.min(byteLength, this._maxDebugDataByteLength));
  }

  private _writeDebugData(
    data: ArrayBuffer | SharedArrayBuffer | ArrayBufferView,
    byteOffset: number
  ): boolean {
    if (
      !this._debugDataEnabled ||
      this.debugData.byteLength === 0 ||
      byteOffset >= this.debugData.byteLength
    ) {
      return false;
    }

    const source = ArrayBuffer.isView(data)
      ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
      : new Uint8Array(data);
    const target = new Uint8Array(this.debugData);
    const copyByteLength = Math.min(source.byteLength, target.byteLength - byteOffset);
    target.set(source.subarray(0, copyByteLength), byteOffset);
    return copyByteLength > 0;
  }
}

/** Returns `true` when a value has the structural shape of a buffer range binding. */
export function isBufferRangeBinding(binding: unknown): binding is BufferRangeBinding {
  return (
    binding !== null &&
    typeof binding === 'object' &&
    'buffer' in (binding as Record<string, unknown>)
  );
}

/** Returns `true` when a range binding points at a {@link DynamicBuffer}. */
export function isDynamicBufferRange(binding: unknown): binding is DynamicBufferRange {
  return isBufferRangeBinding(binding) && binding.buffer instanceof DynamicBuffer;
}

/** Extracts a {@link DynamicBuffer} from a direct binding or range binding. */
export function getDynamicBufferFromBinding(binding: unknown): DynamicBuffer | null {
  if (binding instanceof DynamicBuffer) {
    return binding;
  }

  if (isBufferRangeBinding(binding) && binding.buffer instanceof DynamicBuffer) {
    return binding.buffer;
  }

  return null;
}

/** Resolves a static or dynamic buffer source to the current core {@link Buffer}. */
export function resolveBufferBindingSource(buffer: DynamicBufferBindingSource): Buffer {
  return buffer instanceof DynamicBuffer ? buffer.buffer : buffer;
}

/** Resolves a dynamic buffer range to a core buffer range over the current backing buffer. */
export function resolveDynamicBufferRangeBinding(binding: DynamicBufferRange): {
  buffer: Buffer;
  offset?: number;
  size?: number;
} {
  return resolveBufferRangeBinding(binding);
}

/** Resolves a buffer range to a core buffer range over the current backing buffer. */
export function resolveBufferRangeBinding(binding: BufferRangeBinding): {
  buffer: Buffer;
  offset?: number;
  size?: number;
} {
  return {
    buffer: resolveBufferBindingSource(binding.buffer),
    offset: binding.offset,
    size: binding.size
  };
}

1	// luma.gl
2	// SPDX-License-Identifier: MIT
3	// Copyright (c) vis.gl contributors
4
5	import type {BufferMapCallback, BufferProps, Device, Binding as CoreBinding} from '@luma.gl/core';
6	import {Buffer} from '@luma.gl/core';
7	import {uid} from '../utils/uid';
8
9	/** Controls whether a {@link DynamicBuffer} keeps a CPU-side debug mirror of recent writes. */
10	export type DynamicBufferDebugProps =
11	\| boolean
12	\| {
13	/** Maximum number of bytes retained in {@link DynamicBuffer.debugData}. */
14	maxByteLength?: number;
15	};
16
17	/** Construction props for a {@link DynamicBuffer}. */
18	export type DynamicBufferProps = Omit<BufferProps, 'handle' \| 'onMapped'> & {
19	/** Enables and optionally sizes the CPU-side debug mirror. */
20	debugData?: DynamicBufferDebugProps;
21	/** Existing immutable buffer to expose through this dynamic wrapper without copying. */
22	buffer?: Buffer;
23	/** Whether this dynamic wrapper should destroy an adopted `buffer`. Defaults to `true`. */
24	ownsBuffer?: boolean;
25	};
26
27	/** Buffer-like source accepted by dynamic buffer range helpers. */
28	export type DynamicBufferBindingSource = Buffer \| DynamicBuffer;
29
30	/** Binding range that may point at either a {@link Buffer} or a {@link DynamicBuffer}. */
31	export type DynamicBufferRange = {
32	/** Buffer source for the binding range. */
33	buffer: DynamicBufferBindingSource;
34	/** Byte offset into the current backing buffer. */
35	offset?: number;
36	/** Byte length of the binding range. */
37	size?: number;
38	};
39
40	/** Generic buffer range binding accepted by engine binding resolution helpers. */
41	export type BufferRangeBinding = {
42	/** Buffer source for the binding range. */
43	buffer: DynamicBufferBindingSource;
44	/** Byte offset into the current backing buffer. */
45	offset?: number;
46	/** Byte length of the binding range. */
47	size?: number;
48	};
49
50	const DEFAULT_MAX_DEBUG_DATA_BYTE_LENGTH = Buffer.DEBUG_DATA_MAX_LENGTH;	89✔
51
52	/**
53	* Mutable engine-level wrapper around an immutable core {@link Buffer}.
54	*
55	* `DynamicBuffer` keeps a stable application object while allowing the backing
56	* GPU buffer to be replaced on resize. Engine classes such as {@link Model} and
57	* {@link Material} resolve it to the current backing buffer at draw time and
58	* invalidate cached bindings when {@link generation} changes.
59	*/
60	export class DynamicBuffer {
61	/** Device that owns the backing buffer. */
62	readonly device: Device;
63	/** Application-provided or generated identifier. */
64	readonly id: string;
65	/** Ready promise provided for compatibility with other dynamic resources. */
66	readonly ready: Promise<Buffer>;
67	/** Usage flags applied to every backing buffer created by this wrapper. */
68	readonly usage: number;
69	/** Normalized buffer props reused when the backing buffer is recreated. */
70	readonly props: Readonly<DynamicBufferProps>;
71
72	/** Dynamic buffers are synchronously ready after construction. */
73	isReady = true;	131✔
74	/** Whether {@link destroy} has been called. */
75	destroyed = false;	131✔
76	/** Monotonic version that increments whenever the backing buffer is replaced. */
77	generation = 0;	131✔
78	/** Last update timestamp for writes, reads that populate debug data, or resize operations. */
79	updateTimestamp: number;
80	/** Token replaced whenever cache users need a new resource identity. */
81	cacheToken: object = {};	131✔
82	/** Optional CPU-side mirror of recent writes and readbacks for debugging. */
83	debugData: ArrayBuffer = new ArrayBuffer(0);	131✔
84
85	private readonly _debugDataEnabled: boolean;
86	private readonly _maxDebugDataByteLength: number;
87	private _ownsBuffer: boolean;
88	private _buffer: Buffer;
89
90	/** Current immutable core buffer backing this dynamic wrapper. */
91	get buffer(): Buffer {
92	return this._buffer;	36✔
93	}
94
95	/** Current byte length of the backing buffer. */
96	get byteLength(): number {
97	return this._buffer.byteLength;	241✔
98	}
99
100	/** String tag used by `Object.prototype.toString`. */
101	get [Symbol.toStringTag](): string {
102	return 'DynamicBuffer';	×
103	}
104
105	/** Human-readable debug string. */
106	toString(): string {
UNCOV 107	return `DynamicBuffer:"${this.id}":${this.byteLength}B`;	×
108	}
109
110	/** Creates a dynamic buffer and its initial backing {@link Buffer}. */
111	constructor(device: Device, props: DynamicBufferProps) {
112	const {
113	debugData: debugDataProps = false,	131✔
114	buffer: adoptedBuffer,
115	ownsBuffer = true,	131✔
116	...bufferProps
117	} = props;	131✔
118	if (adoptedBuffer && adoptedBuffer.device !== device) {	131!
UNCOV 119	throw new Error('DynamicBuffer adopted buffers must belong to the supplied device');	×
120	}
121	if (adoptedBuffer && (bufferProps.byteLength !== undefined \|\| bufferProps.data !== undefined)) {	131!
UNCOV 122	throw new Error('DynamicBuffer cannot combine an adopted buffer with byteLength or data');	×
123	}
124
125	const id = props.id \|\| adoptedBuffer?.id \|\| uid('dynamic-buffer');	131✔
126	const normalizedBufferProps: DynamicBufferProps = {	131✔
127	...bufferProps,
128	id,
129	usage: bufferProps.usage ?? adoptedBuffer?.usage,	220✔
130	indexType: bufferProps.indexType ?? adoptedBuffer?.indexType	262✔
131	};
132
133	if ((normalizedBufferProps.usage \|\| 0) & Buffer.INDEX && !normalizedBufferProps.indexType) {	131!
UNCOV 134	if (bufferProps.data instanceof Uint32Array) {	×
UNCOV 135	normalizedBufferProps.indexType = 'uint32';	×
UNCOV 136	} else if (bufferProps.data instanceof Uint16Array) {	×
UNCOV 137	normalizedBufferProps.indexType = 'uint16';	×
UNCOV 138	} else if (bufferProps.data instanceof Uint8Array) {	×
UNCOV 139	normalizedBufferProps.indexType = 'uint8';	×
140	}
141	}
142
143	delete normalizedBufferProps.data;	131✔
144	delete normalizedBufferProps.byteOffset;	131✔
145
146	this.device = device;	131✔
147	this.id = id;	131✔
148	this.props = normalizedBufferProps;	131✔
149	this.usage = normalizedBufferProps.usage \|\| 0;	131✔
150	this._debugDataEnabled = Boolean(debugDataProps);	131✔
151	this._maxDebugDataByteLength =	131✔
152	typeof debugDataProps === 'object' && debugDataProps.maxByteLength !== undefined	262!
153	? debugDataProps.maxByteLength
154	: DEFAULT_MAX_DEBUG_DATA_BYTE_LENGTH;
155	this._ownsBuffer = ownsBuffer;	131✔
156
157	this._buffer = adoptedBuffer ?? this.device.createBuffer({...bufferProps, id});	131✔
158	this.ready = Promise.resolve(this._buffer);	131✔
159	this.updateTimestamp = this._buffer.updateTimestamp;	131✔
160
161	this._resetDebugData(this._buffer.byteLength);	131✔
162	if (bufferProps.data) {	131✔
163	this._writeDebugData(bufferProps.data, bufferProps.byteOffset \|\| 0);	5✔
164	}
165	}
166
167	/**
168	* Writes bytes into the current backing buffer.
169	*
170	* @param data - Bytes or typed-array view to upload.
171	* @param byteOffset - Destination byte offset in the backing buffer.
172	*/
173	write(data: ArrayBuffer \| SharedArrayBuffer \| ArrayBufferView, byteOffset: number = 0): void {	51✔
174	this._buffer.write(data, byteOffset);	51✔
175	this._touch();	51✔
176	this._writeDebugData(data, byteOffset);	51✔
177	}
178
179	/**
180	* Maps the current backing buffer for writing and mirrors the written range when debug data is enabled.
181	*
182	* @param callback - Callback invoked with the mapped range.
183	* @param byteOffset - Byte offset of the mapped range.
184	* @param byteLength - Byte length of the mapped range.
185	*/
186	async mapAndWriteAsync(
187	callback: BufferMapCallback<void \| Promise<void>>,
188	byteOffset: number = 0,	×
189	byteLength: number = this.byteLength - byteOffset	×
190	): Promise<void> {
UNCOV 191	let copiedBytes: Uint8Array \| null = null;	×
UNCOV 192	await this._buffer.mapAndWriteAsync(	×
193	async (arrayBuffer, lifetime) => {
UNCOV 194	await callback(arrayBuffer, lifetime);	×
UNCOV 195	copiedBytes = new Uint8Array(arrayBuffer.slice(0, byteLength));	×
196	},
197	byteOffset,
198	byteLength
199	);
UNCOV 200	this._touch();	×
UNCOV 201	if (copiedBytes) {	×
UNCOV 202	this._writeDebugData(copiedBytes, byteOffset);	×
203	}
204	}
205
206	/**
207	* Reads bytes from the current backing buffer.
208	*
209	* @param byteOffset - Source byte offset in the backing buffer.
210	* @param byteLength - Number of bytes to read.
211	*/
212	async readAsync(
213	byteOffset: number = 0,	7✔
214	byteLength = this.byteLength - byteOffset	7✔
215	): Promise<Uint8Array> {
216	const data = await this._buffer.readAsync(byteOffset, byteLength);	7✔
217	if (this._writeDebugData(data, byteOffset)) {	7✔
218	this._touch();	5✔
219	}
220	return data;	7✔
221	}
222
223	/**
224	* Maps the current backing buffer for reading.
225	*
226	* @param callback - Callback invoked with the mapped range.
227	* @param byteOffset - Byte offset of the mapped range.
228	* @param byteLength - Byte length of the mapped range.
229	*/
230	async mapAndReadAsync<T>(
231	callback: BufferMapCallback<T>,
232	byteOffset: number = 0,	×
233	byteLength: number = this.byteLength - byteOffset	×
234	): Promise<T> {
UNCOV 235	let copiedBytes: Uint8Array \| null = null;	×
UNCOV 236	const result = await this._buffer.mapAndReadAsync(	×
237	async (arrayBuffer, lifetime) => {
238	copiedBytes = new Uint8Array(arrayBuffer.slice(0));	×
UNCOV 239	return await callback(arrayBuffer, lifetime);	×
240	},
241	byteOffset,
242	byteLength
243	);
UNCOV 244	if (copiedBytes && this._writeDebugData(copiedBytes, byteOffset)) {	×
UNCOV 245	this._touch();	×
246	}
UNCOV 247	return result;	×
248	}
249
250	/**
251	* Replaces the backing buffer with a new size.
252	*
253	* @param options.byteLength - New backing buffer byte length.
254	* @param options.preserveData - Copies bytes from the old buffer into the new buffer.
255	* @param options.copyByteLength - Maximum number of bytes to copy when preserving data.
256	* @returns `true` when a new backing buffer was created.
257	*/
258	resize(options: {byteLength: number; preserveData?: boolean; copyByteLength?: number}): boolean {
259	const {byteLength, preserveData = false} = options;	47✔
260	if (byteLength === this.byteLength) {	47!
UNCOV 261	return false;	×
262	}
263
264	const copyByteLength = Math.min(	47✔
265	options.copyByteLength ?? Math.min(this.byteLength, byteLength),	94✔
266	this.byteLength,
267	byteLength
268	);
269
270	const previousBuffer = this._buffer;	47✔
271	const previousDebugData = this.debugData.slice(0);	47✔
272	const {
273	data: _initialData,
274	byteOffset: _initialByteOffset,
275	...resizableBufferProps
276	} = this.props;	47✔
277	const nextBuffer = this.device.createBuffer({	47✔
278	...resizableBufferProps,
279	byteLength
280	});
281
282	if (preserveData && copyByteLength > 0) {	47✔
283	this._copyBufferContents(previousBuffer, nextBuffer, copyByteLength);	42✔
284	}
285
286	this._buffer = nextBuffer;	47✔
287	this._resetDebugData(byteLength);	47✔
288	if (preserveData && previousDebugData.byteLength > 0) {	47✔
289	this._writeDebugData(previousDebugData, 0);	2✔
290	}
291
292	if (this._ownsBuffer) {	47!
293	previousBuffer.destroy();	47✔
294	}
295	this._ownsBuffer = true;	47✔
296	this.generation++;	47✔
297	this.cacheToken = {};	47✔
298	this._touch();	47✔
299	return true;	47✔
300	}
301
302	/**
303	* Grows the backing buffer when the requested size exceeds the current size.
304	*
305	* @param byteLength - Minimum required byte length.
306	* @param options.preserveData - Copies existing bytes when growth is required.
307	* @returns `true` when the backing buffer grew.
308	*/
309	ensureSize(byteLength: number, options?: {preserveData?: boolean}): boolean {
310	if (byteLength <= this.byteLength) {	43✔
311	return false;	3✔
312	}
313
314	return this.resize({	40✔
315	byteLength,
316	preserveData: options?.preserveData
317	});
318	}
319
320	/**
321	* Returns the current backing buffer or a range binding over it.
322	*
323	* @param range - Optional byte range for uniform/storage buffer bindings.
324	*/
325	getBinding(range?: {offset?: number; size?: number}): CoreBinding {
UNCOV 326	if (range?.offset === undefined && range?.size === undefined) {	×
UNCOV 327	return this._buffer;	×
328	}
329
UNCOV 330	return {	×
331	buffer: this._buffer,
332	offset: range?.offset,
333	size: range?.size
334	};
335	}
336
337	/** Destroys the current backing buffer and clears debug data. */
338	destroy(): void {
339	if (!this.destroyed) {	42!
340	if (this._ownsBuffer) {	42!
341	this._buffer.destroy();	42✔
342	}
343	this.destroyed = true;	42✔
344	this.debugData = new ArrayBuffer(0);	42✔
345	}
346	}
347
348	private _copyBufferContents(
349	sourceBuffer: Buffer,
350	destinationBuffer: Buffer,
351	byteLength: number
352	): void {
353	const commandEncoder = this.device.createCommandEncoder();	42✔
354	commandEncoder.copyBufferToBuffer({	42✔
355	sourceBuffer,
356	destinationBuffer,
357	size: byteLength
358	});
359	this.device.submit(commandEncoder.finish());	42✔
360	}
361
362	private _touch(): void {
363	this.updateTimestamp = this.device.incrementTimestamp();	103✔
364	}
365
366	private _resetDebugData(byteLength: number): void {
367	if (!this._debugDataEnabled) {	178✔
368	this.debugData = new ArrayBuffer(0);	165✔
369	return;	165✔
370	}
371
372	this.debugData = new ArrayBuffer(Math.min(byteLength, this._maxDebugDataByteLength));	13✔
373	}
374
375	private _writeDebugData(
376	data: ArrayBuffer \| SharedArrayBuffer \| ArrayBufferView,
377	byteOffset: number
378	): boolean {
379	if (	65✔
380	!this._debugDataEnabled \|\|	95✔
381	this.debugData.byteLength === 0 \|\|
382	byteOffset >= this.debugData.byteLength
383	) {
384	return false;	50✔
385	}
386
387	const source = ArrayBuffer.isView(data)	15✔
388	? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
389	: new Uint8Array(data);
390	const target = new Uint8Array(this.debugData);	65✔
391	const copyByteLength = Math.min(source.byteLength, target.byteLength - byteOffset);	65✔
392	target.set(source.subarray(0, copyByteLength), byteOffset);	65✔
393	return copyByteLength > 0;	65✔
394	}
395	}
396
397	/** Returns `true` when a value has the structural shape of a buffer range binding. */
398	export function isBufferRangeBinding(binding: unknown): binding is BufferRangeBinding {
399	return (	342✔
400	binding !== null &&	1,026✔
401	typeof binding === 'object' &&
402	'buffer' in (binding as Record<string, unknown>)
403	);
404	}
405
406	/** Returns `true` when a range binding points at a {@link DynamicBuffer}. */
407	export function isDynamicBufferRange(binding: unknown): binding is DynamicBufferRange {
UNCOV 408	return isBufferRangeBinding(binding) && binding.buffer instanceof DynamicBuffer;	×
409	}
410
411	/** Extracts a {@link DynamicBuffer} from a direct binding or range binding. */
412	export function getDynamicBufferFromBinding(binding: unknown): DynamicBuffer \| null {
413	if (binding instanceof DynamicBuffer) {	20✔
414	return binding;	5✔
415	}
416
417	if (isBufferRangeBinding(binding) && binding.buffer instanceof DynamicBuffer) {	15!
UNCOV 418	return binding.buffer;	×
419	}
420
421	return null;	15✔
422	}
423
424	/** Resolves a static or dynamic buffer source to the current core {@link Buffer}. */
425	export function resolveBufferBindingSource(buffer: DynamicBufferBindingSource): Buffer {
UNCOV 426	return buffer instanceof DynamicBuffer ? buffer.buffer : buffer;	×
427	}
428
429	/** Resolves a dynamic buffer range to a core buffer range over the current backing buffer. */
430	export function resolveDynamicBufferRangeBinding(binding: DynamicBufferRange): {
431	buffer: Buffer;
432	offset?: number;
433	size?: number;
434	} {
UNCOV 435	return resolveBufferRangeBinding(binding);	×
436	}
437
438	/** Resolves a buffer range to a core buffer range over the current backing buffer. */
439	export function resolveBufferRangeBinding(binding: BufferRangeBinding): {
440	buffer: Buffer;
441	offset?: number;
442	size?: number;
443	} {
UNCOV 444	return {	×
445	buffer: resolveBufferBindingSource(binding.buffer),
446	offset: binding.offset,
447	size: binding.size
448	};
449	}

visgl / luma.gl / 25879749619

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous