WebGPU在处理视频内容时提供了一个非常实用的能力：external texture，也就是外部纹理。它允许开发者把一个HTMLVideoElement解码后的视频帧作为纹理采样来源，直接送进渲染管线，省去了通过canvas中转或者readPixels的开销。不过在TypeScript里为它编写绑定时，许多开发者会卡在GPUBindGroupLayoutEntry的类型声明上，尤其是外部纹理和采样器必须分成两个独立的绑定项这一点。本文就来详细拆解external texture绑定布局的正确写法，以及采样器类型应该如何配合。
一、外部纹理绑定的基本结构：必须与采样器分开声明
首先要明确一个核心规则：在WebGPU的绑定组布局（GPUBindGroupLayout）中，外部纹理和采样器是两个完全独立的绑定项，各自占用一个binding槽位。这一点和普通纹理不一样的地方在于，外部纹理在WGSL着色器端会展开为一个纹理二维数组加采样器矩阵的组合结构，因此布局端反而更简单：你不需要自己声明那个组合，只需要声明externalTexture这一种类型。
在TypeScript中，一个典型的外部纹理绑定布局可以这样写：
// 创建包含外部纹理的绑定组布局
const bindGroupLayout = device.createBindGroupLayout({
entries: [
{
binding: 0, // 外部纹理占据槽位0
visibility: GPUShaderStage.FRAGMENT,
externalTexture: {}, // 外部纹理布局描述符，目前无需额外字段
},
{
binding: 1, // 采样器占据槽位1
visibility: GPUShaderStage.FRAGMENT,
sampler: {
type: 'filtering', // 采样器类型：过滤型
},
},
],
});
注意externalTexture: {}这个空对象不是可省略的占位，而是必须显式给出的字段。如果漏掉它，TypeScript会报类型错误，运行时浏览器也会抛出验证异常，因为一个entry必须且只能携带一个资源布局描述符。目前外部纹理还没有类似viewDimension这样的可选属性，所以空对象就是标准写法，这也让很多初学者误以为可以不写，这是最常见的坑之一。
二、采样器类型的三个取值与着色器端的匹配关系
sampler.type字段决定了这个采样器在着色器里能以什么方式工作，它有三个合法取值：filtering、non-filtering和comparison。外部纹理用于视频渲染时，几乎总是选择filtering，因为视频画面需要线性插值才能避免锯齿。如果你把类型写成了non-filtering，却在WGSL里用普通sampler去采样，管线验证就会失败。
对应的WGSL代码需要这样组织，才能和上面的布局对齐：
// WGSL着色器中的绑定声明
// @group(0) @binding(0) var externalTexture: texture_external;
// @group(0) @binding(1) var sampler: sampler;
//
// 片元着色器中采样外部纹理
// fn sampleVideo(uv: vec2<f32>) -> vec4<f32> {
// let rgba = textureSampleBaseClampToEdge(externalTexture, sampler, uv);
// return vec4<f32>(rgba);
// }
这里有个细节值得展开：外部纹理在WGSL里不能使用通用的textureSample，而是要用textureSampleBaseClampToEdge或textureLoad这几个专门方法。这是因为视频帧的色彩空间转换（比如YUV转RGB）是在采样时由驱动内部完成的，WGSL层面的类型texture_external限制了可用的采样函数集合。TypeScript层面虽然没有直接约束，但如果布局写错，这类错误会在createRenderPipeline阶段集中爆发，报错信息又往往只指向管线验证失败，需要自己回溯到绑定布局排查。
三者的适用场景可以这样归纳：filtering用于普通带插值的采样，non-filtering用于整数纹理的无过滤读取，comparison专用于阴影比较。视频处理场景下建议固定使用filtering，除非你有明确的深度比较需求。
三、创建绑定组时的类型陷阱与排错方法
布局只是第一步，真正容易出问题的是createBindGroup阶段。外部纹理不能直接传入video元素，必须先调用device.importExternalTexture拿到GPUExternalTexture对象，而且这个对象的生命周期非常短，只在当前视频帧有效，每帧都要重新导入。TypeScript代码示例如下：
// 每帧导入外部纹理并更新绑定组
function renderFrame(device: GPUDevice, video: HTMLVideoElement) {
const externalTexture = device.importExternalTexture({
source: video, // 视频元素作为外部纹理来源
});
const bindGroup = device.createBindGroup({
layout: bindGroupLayout,
entries: [
{
binding: 0,
resource: externalTexture, // 注意：是外部纹理对象本身
},
{
binding: 1,
resource: device.createSampler({
magFilter: 'linear',
minFilter: 'linear', // 与filtering类型保持一致
}),
},
],
});
// 后续编码渲染指令并提交...
}
这里有两个高频错误。第一，把GPUTextureView塞给外部纹理槽位，TypeScript会直接提示resource类型不兼容，因为GPUExternalTexture和GPUTextureView是两个独立的联合分支；第二，布局里声明的binding序号和entries里的binding序号不一致，这种错误TypeScript查不出来，只能靠运行时的验证报错发现。建议在TypeScript中用const提取binding序号常量，布局和绑定组共用同一组值，从根源上消除不同步的可能。
另外要注意，外部纹理目前只在部分浏览器实现，在编写跨环境代码时，最好先通过navigator.gpu的存在性检查加上try-catch包裹importExternalTexture调用，给出优雅降级路径，比如回退到传统的canvas纹理上传方案。这样一来，你的TypeSHypeScript代码既保持了类型安全，又具备了足够的健壮性，能够应对不同运行环境的差异。
TypeScriptWebGPU外部纹理绑定修改时间：2026-09-10 02:02:34