TypeScript中如何定义WebGPU Stencil Read Mask按位与操作的类型

在WebGPU的渲染管线中，模板测试的判定逻辑可以概括为一条公式：(stencilBufferValue AND readMask) === (referenceValue AND readMask)。这里的readMask就是模板读取掩码，它决定了模板缓冲区中的哪些位参与比较。当我们在TypeScript中封装这个API时，如何正确地为mask字段定义数据类型，是一个比看上去更微妙的问题，因为JavaScript的位运算符会把操作数截断为32位有符号整数，而WebGPU规范要求的却是无符号32位。

GPUStencilFaceState结构中mask字段的规范定义

根据WebGPU规范，模板状态由GPUStencilFaceState描述，它包含三个字段：compare、failOp、depthFailOp和passOp之外，还有一个关键字段mask，即模板读取掩码。规范明确将mask的类型定义为GPUFlagsConstant，其底层表示是32位无符号整数，取值范围是0到4294967295，也就是0x00000000到0xFFFFFFFF。规范还规定mask的默认值为0xFFFFFFFF，表示所有位都参与模板测试。

JavaScript位运算的隐式截断与按位与的边界问题

要理解为什么readMask的类型必须是严格的无符号32位，需要先看JavaScript的位运算机制。当你写a & b时，JavaScript引擎会先把两个操作数通过ToInt32转换成32位有符号整数，运算结果再以有符号整数的形式返回。这意味着0xFFFFFFFF & 0xFF在JavaScript中会得到-1而不是255，因为0xFFFFFFFF被解释成了有符号的-1。

为了得到无符号结果，标准做法是使用无符号右移运算符：(0xFFFFFFFF & 0xFF) >>> 0会正确返回255。下面的代码展示了如何在TypeScript中安全地模拟GPU的模板测试运算：

function stencilTest(bufferValue: number, reference: number, readMask: number): boolean {
  // 全部通过 >>> 0 转为无符号32位再参与按位与
  const b = bufferValue >>> 0;
  const r = reference >>> 0;
  const m = readMask >>> 0;
  // 按WebGPU规范：(buffer AND mask) 与 (reference AND mask) 比较
  return ((b & m) >>>> 0) === ((r & m) >>>> 0);
}

// 示例：只比较低4位
console.log(stencilTest(0x1F, 0x12, 0x0F)); // true，0xF === 0x2? 实际为 0xF vs 0x2 -> false
console.log(stencilTest(0x1F, 0x1A, 0x0F)); // true，0xF === 0xA? 需逐位验证

注意代码中连续两次使用>>>的地方是对运算结果再做一次无符号转换，避免高位为1时出现负数。这正是readMask类型定义必须强调无符号性的根本原因：如果你的封装库直接用&返回结果，调用方拿到的可能是一个负数，再把它写回uniform buffer或调用writeBuffer时就会出错。

用品牌类型与运行时校验约束合法掩码值

既然TypeScript的number无法在类型层面区分有符号与无符号，业界常见的做法是使用品牌类型（branded type）。它通过给类型附加一个私有的品牌属性，让未经校验的普通number无法直接赋值给掩码参数，从而把非法值拦截在编译期。

// 品牌类型定义
declare const StencilReadMaskBrand: unique symbol;
export type StencilReadMask = number & { readonly [StencilReadMaskBrand]: true };

export function createStencilReadMask(value: number): StencilReadMask {
  // 运行时校验：必须是0到0xFFFFFFFF之间的整数
  if (!Number.isInteger(value) || value < 0 || value > 0xFFFFFFFF) {
    throw new RangeError(
      `readMask must be an integer in [0, 0xFFFFFFFF], got ${value}`
    );
  }
  return (value >>> 0) as StencilReadMask;
}

// 使用示例
const mask = createStencilReadMask(0xFF); // 只比较低8位
const pipelineDesc: GPURenderPipelineDescriptor = {
  // ...省略其他字段
  depthStencil: {
    format: 'depth24plus-stencil8',
    stencilFront: {
      compare: 'equal',
      // mask字段接收品牌类型，普通number直接传入会编译报错
      failOp: 'keep',
      depthFailOp: 'keep',
      passOp: 'keep',
    },
    stencilBack: {
      compare: 'equal',
      failOp: 'keep',
      depthFailOp: 'keep',
      passOp: 'keep',
    },
    stencilReadMask: mask,
    stencilWriteMask: 0xFFFFFFFF,
  },
};

这套方案的优势是双保险：类型层面，普通number不能直接冒充StencilReadMask，开发者必须显式经过校验函数；运行时层面，NaN、Infinity、小数和超出范围的值都会被RangeError拦截，避免传入GPUDevice.createRenderPipeline后触发验证错误甚至静默的默认管线。对于写掩码（writeMask）也可以如法炮制，定义一个独立的品牌类型，两者互不混淆。

总结来说，WebGPU规范层面readMask是u32，TypeScript层面只能声明为number，但通过品牌类型加上运行时校验，可以在实际工程中把这条类型缝隙填平。同时记得所有涉及模板位运算的辅助函数都使用>>> 0做无符号转换，才能保证按位与的结果与GPU端行为一致。

TypeScriptWebGPUStencil Read Mask修改时间：2026-09-02 13:20:39