feat: Rename d.getOffsetInfoAt to d.memoryLayoutOf (#2205)

iwoplaza · web-flow · commit 4627843c7dc6 · 2026-02-24T13:41:13.000+01:00
diff --git a/packages/typegpu/src/core/pipeline/computePipeline.ts b/packages/typegpu/src/core/pipeline/computePipeline.ts
@@ -30,7 +30,7 @@ import type { ExperimentalTgpuRoot } from '../root/rootTypes.ts';
 import type { TgpuSlot } from '../slot/slotTypes.ts';
 import { warnIfOverflow } from './limitsOverflow.ts';
 import {
-  getOffsetInfoAt,
+  memoryLayoutOf,
   type PrimitiveOffsetInfo,
 } from '../../data/offsetUtils.ts';
 import {
@@ -77,10 +77,10 @@ export interface TgpuComputePipeline
   /**
    * Dispatches compute workgroups using parameters read from a buffer.
    * The buffer must contain 3 consecutive u32 values (x, y, z workgroup counts).
-   * To get the correct offset within complex data structures, use `d.getOffsetInfoAt(...)`.
+   * To get the correct offset within complex data structures, use `d.memoryLayoutOf(...)`.
    *
    * @param indirectBuffer - Buffer marked with 'indirect' usage containing dispatch parameters
-   * @param start - PrimitiveOffsetInfo pointing to the first dispatch parameter. If not provided, starts at offset 0. To obtain safe offsets, use `getOffsetInfoAt(...)`.
+   * @param start - PrimitiveOffsetInfo pointing to the first dispatch parameter. If not provided, starts at offset 0. To obtain safe offsets, use `d.memoryLayoutOf(...)`.
    */
   dispatchWorkgroupsIndirect<T extends AnyWgslData>(
     indirectBuffer: TgpuBuffer<T> & IndirectFlag,
@@ -244,14 +244,14 @@ class TgpuComputePipelineImpl implements TgpuComputePipeline {
   ): void {
     const DISPATCH_SIZE = 12; // 3 x u32 (x, y, z)
 
-    let offsetInfo = start ?? getOffsetInfoAt(indirectBuffer.dataType);
+    let offsetInfo = start ?? memoryLayoutOf(indirectBuffer.dataType);
 
     if (typeof offsetInfo === 'number') {
       if (offsetInfo === 0) {
-        offsetInfo = getOffsetInfoAt(indirectBuffer.dataType);
+        offsetInfo = memoryLayoutOf(indirectBuffer.dataType);
       } else {
         console.warn(
-          `dispatchWorkgroupsIndirect: Provided start offset ${offsetInfo} as a raw number. Use getOffsetInfoAt(...) to include contiguous padding info for safer validation.`,
+          `dispatchWorkgroupsIndirect: Provided start offset ${offsetInfo} as a raw number. Use d.memoryLayoutOf(...) to include contiguous padding info for safer validation.`,
         );
         // When only an offset is provided, assume we have at least 12 bytes contiguous.
         offsetInfo = {
diff --git a/packages/typegpu/src/data/index.ts b/packages/typegpu/src/data/index.ts
@@ -221,7 +221,7 @@ export { PUBLIC_isContiguous as isContiguous } from './isContiguous.ts';
 export {
   PUBLIC_getLongestContiguousPrefix as getLongestContiguousPrefix,
 } from './getLongestContiguousPrefix.ts';
-export { getOffsetInfoAt } from './offsetUtils.ts';
+export { memoryLayoutOf } from './offsetUtils.ts';
 export { PUBLIC_alignmentOf as alignmentOf } from './alignmentOf.ts';
 export { builtin } from '../builtin.ts';
 export { deepEqual } from './deepEqual.ts';
diff --git a/packages/typegpu/src/data/offsetUtils.ts b/packages/typegpu/src/data/offsetUtils.ts
@@ -305,23 +305,23 @@ export interface PrimitiveOffsetInfo {
 }
 
 /**
- * A function that retrieves offset information for a specific primitive within a data schema.
+ * A function that retrieves offset and information for a specific primitive within a data schema.
  * Example usage:
  * ```ts
  * const Boid = d.struct({
  *  position: d.vec3f,
  *  velocity: d.vec3f,
  * });
- * const offsetInfo = d.getOffsetInfoAt(Boid, (b) => b.velocity.y);
- * console.log(offsetInfo.offset); // Byte offset of velocity.y within Boid (here 20 bytes)
- * console.log(offsetInfo.contiguous); // Contiguous bytes available from that offset (here 8 bytes)
+ * const memLayout = d.memoryLayoutOf(Boid, (b) => b.velocity.y);
+ * console.log(memLayout.offset); // Byte offset of velocity.y within Boid (here 20 bytes)
+ * console.log(memLayout.contiguous); // Contiguous bytes available from that offset (here 8 bytes)
  * ```
  *
  * @param schema - The data schema to analyze.
  * @param accessor - Optional function that accesses a specific primitive within the schema. If omitted, uses the root offset (0).
  * @returns An object containing the offset and contiguous byte information.
  */
-export function getOffsetInfoAt<T extends BaseData>(
+export function memoryLayoutOf<T extends BaseData>(
   schema: T,
   accessor?: (proxy: Infer<T>) => number,
 ): PrimitiveOffsetInfo {
diff --git a/packages/typegpu/tests/computePipeline.test.ts b/packages/typegpu/tests/computePipeline.test.ts
@@ -9,7 +9,6 @@ import {
 import { $internal } from '../src/shared/symbols.ts';
 import { it } from './utils/extendedIt.ts';
 import { extensionEnabled } from '../src/std/extensions.ts';
-import { getOffsetInfoAt } from '../src/data/offsetUtils.ts';
 
 describe('TgpuComputePipeline', () => {
   it('can be created with a compute entry function', ({ root, device }) => {
@@ -648,7 +647,7 @@ describe('TgpuComputePipeline', () => {
 
       pipeline.dispatchWorkgroupsIndirect(
         buffer,
-        getOffsetInfoAt(PaddedStruct, (s) => s.a),
+        d.memoryLayoutOf(PaddedStruct, (s) => s.a),
       );
 
       expect(warnSpy.mock.calls[0]![0]).toMatchInlineSnapshot(
@@ -658,7 +657,7 @@ describe('TgpuComputePipeline', () => {
       const deepBuffer = root.createBuffer(DeepStruct).$usage('indirect');
       pipeline.dispatchWorkgroupsIndirect(
         deepBuffer,
-        getOffsetInfoAt(DeepStruct, (s) => s.someData[11] as number),
+        d.memoryLayoutOf(DeepStruct, (s) => s.someData[11] as number),
       );
 
       expect(warnSpy.mock.calls[1]![0]).toMatchInlineSnapshot(
@@ -667,7 +666,7 @@ describe('TgpuComputePipeline', () => {
 
       pipeline.dispatchWorkgroupsIndirect(
         deepBuffer,
-        getOffsetInfoAt(
+        d.memoryLayoutOf(
           DeepStruct,
           (s) => s.nested.innerNested[0]?.yy as number,
         ),
diff --git a/packages/typegpu/tests/offsetUtils.test.ts b/packages/typegpu/tests/offsetUtils.test.ts
@@ -1,11 +1,10 @@
 import { describe, expect, it } from 'vitest';
 import { d } from '../src/index.ts';
 import { sizeOf } from '../src/data/sizeOf.ts';
-import { getOffsetInfoAt } from '../src/data/offsetUtils.ts';
 
-describe('getOffsetInfoAt (default)', () => {
+describe('d.memoryLayoutOf (default)', () => {
   it('returns offset 0 and full contiguous size for a scalar', () => {
-    const info = getOffsetInfoAt(d.u32);
+    const info = d.memoryLayoutOf(d.u32);
 
     expect(info.offset).toBe(0);
     expect(info.contiguous).toBe(sizeOf(d.u32));
@@ -17,34 +16,34 @@ describe('getOffsetInfoAt (default)', () => {
       b: d.vec3f,
     });
 
-    const info = getOffsetInfoAt(Schema);
+    const info = d.memoryLayoutOf(Schema);
 
     expect(info.offset).toBe(0);
     expect(info.contiguous).toBe(4);
   });
 });
 
-describe('getOffsetInfoAt (vectors)', () => {
+describe('d.memoryLayoutOf (vectors)', () => {
   it('computes component offsets and remaining contiguous bytes', () => {
-    const info = getOffsetInfoAt(d.vec4u, (v) => v.z);
+    const info = d.memoryLayoutOf(d.vec4u, (v) => v.z);
 
     expect(info.offset).toBe(8);
     expect(info.contiguous).toBe(8);
   });
 
   it('supports numeric component access', () => {
-    const info = getOffsetInfoAt(d.vec3f, (v) => v[1]);
+    const info = d.memoryLayoutOf(d.vec3f, (v) => v[1]);
 
     expect(info.offset).toBe(4);
     expect(info.contiguous).toBe(8);
   });
 });
 
-describe('getOffsetInfoAt (arrays)', () => {
+describe('d.memoryLayoutOf (arrays)', () => {
   it('computes offsets for array elements without padding', () => {
     const Schema = d.arrayOf(d.u32, 6);
 
-    const info = getOffsetInfoAt(Schema, (a) => a[3] as number);
+    const info = d.memoryLayoutOf(Schema, (a) => a[3] as number);
 
     expect(info.offset).toBe(12);
     expect(info.contiguous).toBe(12);
@@ -53,22 +52,22 @@ describe('getOffsetInfoAt (arrays)', () => {
   it('limits contiguous bytes to element size when array stride has padding', () => {
     const Schema = d.arrayOf(d.vec3u, 3);
 
-    const info = getOffsetInfoAt(Schema, (a) => a[1]?.x as number);
+    const info = d.memoryLayoutOf(Schema, (a) => a[1]?.x as number);
 
     expect(info.offset).toBe(16);
     expect(info.contiguous).toBe(12);
   });
 });
 
-describe('getOffsetInfoAt (struct runs)', () => {
+describe('d.memoryLayoutOf (struct runs)', () => {
   it('returns contiguous bytes within a packed run', () => {
     const Schema = d.struct({
       a: d.u32,
       b: d.u32,
       c: d.u32,
     });
 
-    const info = getOffsetInfoAt(Schema, (s) => s.b);
+    const info = d.memoryLayoutOf(Schema, (s) => s.b);
 
     expect(info.offset).toBe(4);
     expect(info.contiguous).toBe(8);
@@ -80,14 +79,14 @@ describe('getOffsetInfoAt (struct runs)', () => {
       b: d.vec3u,
     });
 
-    const info = getOffsetInfoAt(Schema, (s) => s.a);
+    const info = d.memoryLayoutOf(Schema, (s) => s.a);
 
     expect(info.offset).toBe(0);
     expect(info.contiguous).toBe(4);
   });
 });
 
-describe('getOffsetInfoAt (nested layouts)', () => {
+describe('d.memoryLayoutOf (nested layouts)', () => {
   // offset calculator for this struct: https://shorturl.at/NQggS
   const DeepStruct = d.struct({
     someData: d.arrayOf(d.f32, 13),
@@ -110,7 +109,7 @@ describe('getOffsetInfoAt (nested layouts)', () => {
   });
 
   it('tracks offsets and contiguous bytes within nested arrays', () => {
-    const info = getOffsetInfoAt(
+    const info = d.memoryLayoutOf(
       DeepStruct,
       (s) => s.someData[11] as number,
     );
@@ -120,7 +119,7 @@ describe('getOffsetInfoAt (nested layouts)', () => {
   });
 
   it('tracks offsets for nested structs inside arrays', () => {
-    const info = getOffsetInfoAt(
+    const info = d.memoryLayoutOf(
       DeepStruct,
       (s) => s.nested.innerNested[1]?.myVec.x as number,
     );
@@ -130,7 +129,7 @@ describe('getOffsetInfoAt (nested layouts)', () => {
   });
 
   it('tracks offsets inside a later struct run', () => {
-    const info = getOffsetInfoAt(
+    const info = d.memoryLayoutOf(
       DeepStruct,
       (s) => s.nested.additionalData[1] as number,
     );
@@ -140,7 +139,7 @@ describe('getOffsetInfoAt (nested layouts)', () => {
   });
 });
 
-describe('getOffsetInfoAt (edge cases)', () => {
+describe('d.memoryLayoutOf (edge cases)', () => {
   it('tracks offsets between array elements', () => {
     const E = d.struct({
       x: d.u32,
@@ -151,7 +150,7 @@ describe('getOffsetInfoAt (edge cases)', () => {
       arr: d.arrayOf(E, 3),
     });
 
-    const info = getOffsetInfoAt(
+    const info = d.memoryLayoutOf(
       S,
       (s) => s.arr[1]?.vec.x as number,
     );
@@ -170,7 +169,7 @@ describe('getOffsetInfoAt (edge cases)', () => {
       r: I,
     });
 
-    const info = getOffsetInfoAt(
+    const info = d.memoryLayoutOf(
       S,
       (s) => s.l.vec.z,
     );
@@ -191,7 +190,7 @@ describe('getOffsetInfoAt (edge cases)', () => {
       arr: d.arrayOf(E, 4),
     });
 
-    const info = getOffsetInfoAt(
+    const info = d.memoryLayoutOf(
       S,
       (s) => s.arr[1]?.x.x as number,
     );
@@ -210,7 +209,7 @@ describe('getOffsetInfoAt (edge cases)', () => {
       s: I,
     });
 
-    const info = getOffsetInfoAt(
+    const info = d.memoryLayoutOf(
       S,
       (s) => s.arr[0]?.y as number,
     );
