《游戏引擎实现原理》4.3 对齐、padding 与 TypedArray 上的真实布局

[pos.x, pos.y, pos.z, pad][uv.u, uv.v][color.rgba]

// file: src/core/vertex-layout.ts
// tier: L1
// verify: npx vitest run src/core/vertex-layout.test.ts
//
// helio 内核：在 ArrayBuffer 上手工布局顶点结构。
// 关键点：GPU 的对齐规则（std140）与「CPU 紧打包」不一致，
// vec3 占 12 字节但要按 16 字节对齐；行距（bytesPerRow）必须是 256 的倍数。

export type FieldType = 'f32' | 'vec2f' | 'vec3f' | 'vec4f' | 'u32' | 'unorm8x4';

export type FieldSpec = { readonly name: string; readonly type: FieldType };

export type FieldLayout = {
  readonly name: string;
  readonly type: FieldType;
  readonly offset: number;
  readonly size: number;
};

export type StructLayout = {
  readonly fields: readonly FieldLayout[];
  /** 最后一个字段结束的位置（未向上取整）。 */
  readonly size: number;
  /** 顶点缓冲区的 arrayStride：结构体大小按最大对齐向上取整。 */
  readonly stride: number;
  /** 结构体的最大成员对齐。 */
  readonly align: number;
};

/** 各类型的字节数与分量数。 */
const TYPE_SIZE: Readonly<Record<FieldType, number>> = {
  f32: 4, vec2f: 8, vec3f: 12, vec4f: 16, u32: 4, unorm8x4: 4,
};
const COMPONENTS: Readonly<Record<FieldType, number>> = {
  f32: 1, vec2f: 2, vec3f: 3, vec4f: 4, u32: 1, unorm8x4: 1,
};

/**
 * 各类型的基础对齐。注意 vec3f 占 12 字节却要求 16 字节对齐——
 * 这是 std140 的规则，也是「紧打包」最容易踩的坑。
 */
const TYPE_ALIGN: Readonly<Record<FieldType, number>> = {
  f32: 4, vec2f: 8, vec3f: 16, vec4f: 16, u32: 4, unorm8x4: 4,
};

/** 向上对齐到 alignment（必须是 2 的幂）。 */
export function alignUp(value: number, alignment: number): number {
  if (alignment <= 0 || (alignment & (alignment - 1)) !== 0) {
    throw new RangeError(`alignment must be a power of two, got ${alignment}`);
  }
  return (value + alignment - 1) & ~(alignment - 1);
}

/** 按 std140 规则计算结构体布局。 */
export function layoutStruct(fields: readonly FieldSpec[]): StructLayout {
  const laid: FieldLayout[] = [];
  let offset = 0;
  let maxAlign = 1;
  for (const f of fields) {
    const align = TYPE_ALIGN[f.type];
    offset = alignUp(offset, align);
    const size = TYPE_SIZE[f.type];
    laid.push({ name: f.name, type: f.type, offset, size });
    offset += size;
    if (align > maxAlign) maxAlign = align;
  }
  return { fields: laid, size: offset, stride: alignUp(offset, maxAlign), align: maxAlign };
}

/**
 * 「CPU 紧打包」布局：把顶点当成一串连续的 4 字节标量，所有字段只按 4 字节对齐，
 * 不做 std140 的 16 字节补位。用它和 layoutStruct 对比，就能看出补位带来的偏移差异。
 */
export function layoutStructTight(fields: readonly FieldSpec[]): StructLayout {
  const laid: FieldLayout[] = [];
  let offset = 0;
  for (const f of fields) {
    offset = alignUp(offset, 4);
    const size = TYPE_SIZE[f.type];
    laid.push({ name: f.name, type: f.type, offset, size });
    offset += size;
  }
  return { fields: laid, size: offset, stride: alignUp(offset, 4), align: 4 };
}

/** WebGPU：顶点缓冲区的 arrayStride 必须是 4 的倍数。 */
export function assertVertexStride(stride: number): void {
  if (stride <= 0 || stride % 4 !== 0) {
    throw new RangeError(`vertex arrayStride ${stride} must be a positive multiple of 4`);
  }
}

/** WebGPU：copyBufferToTexture 等操作里 bytesPerRow 必须是 256 的倍数。 */
export function alignRowPitch(widthBytes: number): number {
  return alignUp(widthBytes, 256);
}

/** 按布局把一个顶点写进 buffer（用 DataView 逐字段写，便于观察偏移）。 */
export function writeVertex(
  layout: StructLayout,
  buffer: ArrayBuffer,
  base: number,
  values: Readonly<Record<string, number | readonly number[]>>,
): void {
  const dv = new DataView(buffer);
  for (const f of layout.fields) {
    const at = base + f.offset;
    const v = values[f.name];
    if (f.type === 'u32' || f.type === 'unorm8x4') {
      dv.setUint32(at, v as number, true);
    } else if (f.type === 'f32') {
      dv.setFloat32(at, v as number, true);
    } else {
      const a = v as readonly number[];
      for (let i = 0; i < COMPONENTS[f.type]; i++) dv.setFloat32(at + i * 4, a[i]!, true);
    }
  }
}

/** 打包成 0xRRGGBBAA 的 unorm8x4。 */
export function packRGBA(r: number, g: number, b: number, a: number): number {
  return (((r & 0xff) << 24) | ((g & 0xff) << 16) | ((b & 0xff) << 8) | (a & 0xff)) >>> 0;
}

// file: src/core/vertex-layout.test.ts
// tier: L1
// verify: npx vitest run src/core/vertex-layout.test.ts

import { describe, expect, it } from 'vitest';
import {
  alignRowPitch,
  alignUp,
  assertVertexStride,
  layoutStruct,
  layoutStructTight,
  packRGBA,
  writeVertex,
  type FieldSpec,
} from './vertex-layout.ts';

// 顶点：[pos.x, pos.y, pos.z, pad][uv.u, uv.v][color.rgba]
const VERTEX: FieldSpec[] = [
  { name: 'position', type: 'vec3f' },
  { name: 'pad', type: 'f32' },
  { name: 'uv', type: 'vec2f' },
  { name: 'color', type: 'unorm8x4' },
];

describe('alignUp', () => {
  it('向上对齐到 2 的幂', () => {
    expect(alignUp(0, 16)).toBe(0);
    expect(alignUp(12, 16)).toBe(16);
    expect(alignUp(16, 16)).toBe(16);
    expect(alignUp(17, 16)).toBe(32);
    expect(alignUp(1000, 256)).toBe(1024);
  });

  it('拒绝非 2 的幂', () => {
    expect(() => alignUp(1, 3)).toThrow(RangeError);
  });
});

describe('layoutStruct（std140）', () => {
  it('算出顶点结构的偏移与步长', () => {
    const l = layoutStruct(VERTEX);
    const byName = Object.fromEntries(l.fields.map((f) => [f.name, f.offset]));
    expect(byName).toEqual({ position: 0, pad: 12, uv: 16, color: 24 });
    expect(l.size).toBe(28);
    expect(l.align).toBe(16);
    expect(l.stride).toBe(32); // 28 向上对齐到 16
  });

  it('紧打包会把 uv 挤到未对齐的偏移上', () => {
    const tight = layoutStructTight([
      { name: 'position', type: 'vec3f' },
      { name: 'uv', type: 'vec2f' },
      { name: 'color', type: 'unorm8x4' },
    ]);
    const byName = Object.fromEntries(tight.fields.map((f) => [f.name, f.offset]));
    expect(byName).toEqual({ position: 0, uv: 12, color: 20 });
    expect(tight.size).toBe(24);
    // 紧打包省了 8 字节，但 uv 落在 12——不是 8 的倍数
    expect(byName['uv']! % 8).not.toBe(0);
  });

  it('arrayStride 是 4 的倍数', () => {
    const l = layoutStruct(VERTEX);
    expect(() => assertVertexStride(l.stride)).not.toThrow();
    expect(() => assertVertexStride(30)).toThrow(RangeError);
  });
});

describe('bytesPerRow 必须是 256 的倍数', () => {
  it('把行宽向上对齐到 256', () => {
    expect(alignRowPitch(4 * 100)).toBe(512); // 400 → 512
    expect(alignRowPitch(256)).toBe(256);
    expect(alignRowPitch(257)).toBe(512);
  });
});

describe('writeVertex', () => {
  it('按偏移写入，颜色落在第 24 字节', () => {
    const l = layoutStruct(VERTEX);
    const buf = new ArrayBuffer(l.stride * 2);
    const color = packRGBA(255, 128, 0, 255);
    writeVertex(l, buf, 0, { position: [1.5, -2.0, 3.25], pad: 0, uv: [0.5, 0.25], color });
    writeVertex(l, buf, l.stride, { position: [4, 5, 6], pad: 0, uv: [1, 0], color });

    const dv = new DataView(buf);
    expect(dv.getFloat32(0, true)).toBeCloseTo(1.5);
    expect(dv.getFloat32(8, true)).toBeCloseTo(3.25);
    expect(dv.getFloat32(16, true)).toBeCloseTo(0.5); // uv.u
    expect(dv.getUint32(24, true)).toBe(color); // color.rgba
    // 第二个顶点从 stride=32 开始
    expect(dv.getFloat32(32, true)).toBeCloseTo(4);
    expect(dv.getUint32(32 + 24, true)).toBe(color);
  });

  it('packRGBA 大端序排列', () => {
    expect(packRGBA(0xff, 0x80, 0x00, 0xff)).toBe(0xff8000ff);
  });
});

std140: position@0 pad@12 uv@16 color@24 | size 28 align 16 stride 32
tight : position@0 uv@12 color@20        | size 24 stride 24
rowPitch(400) = 512   rowPitch(256) = 256