企业官网建设流程全解析

deck.gl WebGPU 支持现状与启用指南：图层、扩展与效果支持矩阵（v9）

【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl

deck.gl 正在逐步将渲染后端从 WebGL2 迁移到 WebGPU。本篇技术指南以docs/developer-guide/webgpu.md为骨架，结合modules/下真实存在的 WGSL 着色器、构建脚本与核心渲染管线源码，系统梳理 WebGPU 的启用方式、图层/扩展/效果的支持矩阵、特性边界与参与路线，帮助你判断当前版本中哪些功能可以迁移到 WebGPU、哪些仍需回退到 WebGL。

:::caution deck.gl v9 的 WebGPU 支持仍处于工作进展中（work in progress），尚未达到生产就绪（production ready）。本文内容基于当前源码树，随着版本演进可能发生变化。 :::

状态标记的语义

在阅读下文所有支持矩阵前，先明确本文档使用的三档状态标记（该语义由原文档定义，且与源码树一一对应）：

对于复合图层（composite layer）与包装图层（wrapper layer），状态基于其默认或常规渲染路径判定，而不是每个自定义子图层组合。

启用 WebGPU

deck.gl 的渲染完全建立在 luma.gl 设备抽象之上，因此启用 WebGPU 的关键是让 deck.gl 使用一个基于 luma.glwebgpuAdapter创建的 device。

import {webgpuAdapter} from '@luma.gl/webgpu'; new Deck({ deviceProps: { type: 'webgpu', adapters: [webgpuAdapter] } });

这段配置对应Deck的deviceProps属性（类型为CreateDeviceProps，见 modules/core/src/lib/deck.ts）。从该文件源码可以看到设备创建的完整逻辑（_createDevice）：

• deck.gl v9 的Deck始终打包并自动追加webgl2Adapter（源码注释明确说明该行为预期在 v10 中改变，以支持纯 WebGPU 构建），因此adapters中即使只传入webgpuAdapter，WebGL 回退依然可用；
• 当deviceProps.type === 'webgpu'时，画布上下文强制使用alphaMode: 'premultiplied'，这是为了在 WebGPU 下启用透明度并与着色器输出保持一致（源码注释：we must use 'premultiplied' canvas for webgpu to enable transparency and match shaders）；
• 设备创建走luma.createDevice，并开启着色器与管线缓存（_cacheShaders、_cachePipelines）。

需要特别注意的是拾取（picking）模式的联动：当Deck使用 WebGPU 设备时，pickAsync会被自动解析为'async'，而显式请求pickAsync: 'sync'会直接抛错（'pickAsync: "sync"' is not supported when Deck is using a WebGPU device.，见 modules/core/src/lib/deck.ts）。这是因为 WebGPU 的读回路径是异步的，同步拾取在 WebGPU 上不可用。

图层支持矩阵

下表覆盖各图层包的公开图层导出，直接来源于当前源码树（而非可能滞后的官网徽章）。从find_files对**/*wgsl*的检索结果看，源码树中共有 22 个.wgsl.ts着色器文件，分布于modules/layers、modules/aggregation-layers、modules/geo-layers、modules/mesh-layers与modules/core，与下表逐一对应。

关键图层的功能边界

• GeoJsonLayer：在 WebGPU 上支持多边形（polygon）、线（line）与文本点（text point）渲染；TextLayer支持字形（glyph）渲染，但文本背景与碰撞过滤（collision filtering）仍依赖 WebGL。
• S2Layer、QuadkeyLayer、GeohashLayer：从PolygonLayer继承 WebGPU 渲染能力，包括挤出（extruded）、描边（stroked）与线框（wireframe）单元。
• H3HexagonLayer：在 WebGPU 上同时支持其高精度PolygonLayer路径与 instancedColumnLayer路径（对应源码树中的 hexagon-cell-layer.wgsl.ts）。
• H3ClusterLayer：通过多边形路径渲染。
• A5Layer：从PolygonLayer继承 WebGPU 渲染，同时支持 bigint 与十六进制两种 A5 单元标识符。
• Tile3DLayer：在 WebGPU 上支持点云（point-cloud）、glTF 场景图（scenegraph）与 I3S 网格瓦片内容。

源码级证据：以 ScatterplotLayer 为例

以最早完成移植的ScatterplotLayer（v9.2）为例，其 WGSL 着色器位于 modules/layers/src/scatterplot-layer/scatterplot-layer.wgsl.ts，可以从三个层面印证“显式 WebGPU 实现”的含义：

1. Uniform 结构与 GLSL 版本一一对应：ScatterplotUniforms中声明了radiusScale、radiusMinPixels、radiusMaxPixels、lineWidthScale、stroked、filled、antialiasing、billboard、radiusUnits、lineWidthUnits等字段，通过@group(0) @binding(0) var<uniform>绑定。
2. WGSL 原生语法：顶点着色器使用@builtin(instance_index)/@builtin(vertex_index)读取实例索引，使用select(...)代替 GLSL 的三元表达式做条件选择（文件中有注释明确说明：WGSL selects the second value when the condition is true, so keep the antialiased path second.），片段着色器通过@location(0)返回颜色。
3. 共享着色器模块的 WGSL 端口：着色器内调用的project_unit_size_to_pixel、project_position_to_clipspace_and_commonspace等函数来自核心project模块的 WGSL 版本（见 modules/core/src/shaderlib/project/project.wgsl.ts），这正是“核心project/project32着色器模块已有 WGSL 端口”的落地证据。

此外，在 WebGPU 设备上，图层着色器模块列表会动态追加clipExtension（...(this.context.device.type === 'webgpu' ? [clipExtension] : [])，见 modules/layers/src/scatterplot-layer/scatterplot-layer.ts），说明部分扩展已能通过 WGSL 专用路径与 WebGPU 图层协同工作。

扩展支持矩阵

下表覆盖@deck.gl/extensions的公开扩展。绝大多数扩展仍是 WebGL-only，原因在于它们依赖 GLSL 着色器注入（GLSL shader injections）、仅 GLSL 可用的着色器模块，或尚未移植到 WebGPU 的额外渲染/拾取通道。

ClipExtension是唯一取得进展的扩展：在默认MVTLayer渲染路径所用到的图元图层（ScatterplotLayer、PathLayer、SolidPolygonLayer）上具有初步 WebGPU 支持。从 modules/extensions/src/clip/clip-extension.ts 的源码可以看到其双路径设计：当device.type === 'webgpu'时，getShaders返回空模块对象（即不再注入 GLSL 顶点着色器模块），改由 WGSL 着色器内的clip_filterPosition/clip_filterColor钩子完成裁剪；WebGL 路径则维持基于clipByInstance的 GLSL 模块注入逻辑。

效果（Effects）支持矩阵

下表覆盖@deck.gl/core导出的公开效果类。

功能特性支持矩阵

源码佐证：Picking 与 Constant attributes

• 异步拾取：拾取模式在 modules/core/src/lib/deck.ts 中由设备类型决定——WebGPU 设备强制异步拾取。而 modules/core/src/passes/pick-layers-pass.ts 进一步展示了渲染层面的差异：WebGPU 使用渲染通道动态状态（render-pass dynamic state）中的blendConstant进行拾取颜色编码，WebGL 则使用blendColor。
• 常量属性物化：AttributeManager在构造时检测device.type === 'webgpu'，并创建专用的AttributeBufferGroups实例（见 modules/core/src/lib/attribute/attribute-manager.ts），通过getBufferLayouts/getBufferGroupBindings生成 WebGPU 风格的缓冲布局描述符与共享缓冲绑定（同文件 L307-L349）。
• 绘制参数拆分：图层绘制时，Layer._draw会调用splitWebGPUDrawParameters将blendConstant从管线参数中拆出，作为渲染通道参数单独应用（见 modules/core/src/lib/layer.ts 与 L1431-L1449），并调用syncModelAttachmentFormats同步 WebGPU 模型附件格式（L1454-L1456）。

构建、测试与双后端基础设施

WebGPU 支持不仅是运行时渲染，还涉及一整套构建基础设施，这部分在原文档中未展开，但在仓库中可以直接验证：

• 依赖：根 package.json 声明了@luma.gl/webgpu（版本^9.4.0-beta.7），这是webgpuAdapter的来源。
• 测试命令：根 package.json 的test-webgpu脚本为RENDER_TEST_DEVICE=webgpu ocular-test render，通过环境变量切换渲染测试设备，验证 WGSL 实现的渲染结果。
• 双态构建开关：scripts/set-webgpu-build.mjs 通过node scripts/set-webgpu-build.mjs <true|false>切换根 tsconfig.json 中的webGPUEnabled选项，并清理各模块的tsconfig.tsbuildinfo缓存以保证增量编译不会漏掉开关变更。根build脚本会先以false产出visgl:webgl-only条件输出，再以true产出默认输出。
• TypeScript 转换插件：根 tsconfig.json 注册了@vis.gl/ts-plugins/ts-transform-webgpu插件，并配置ts-transform-append-extension处理.wgsl.js扩展名，使.wgsl.ts着色器源文件能够被正确编译打包。

这些基础设施意味着：即使某个图层尚未完成 WebGPU 移植，WebGL 路径也始终可用，二者通过 luma.gl 设备抽象并存。

背景与参与

虽然 deck.gl 可见的 WebGPU 表面仍有限，但大量底层工作已在 luma.gl（deck.gl 底层的 GPU 框架）中完成——包括 WebGPU 设备/适配器、渲染管线与缓冲管理等。deck.gl 正通过逐层、逐特性地移植着色器模块、图层与渲染功能来跟进这一工作。本文支持矩阵中从 v9.2 到 v9.4 的推进节奏（从ScatterplotLayer/LineLayer/PointCloudLayer到 v9.4 批量覆盖聚合类、网格类与瓦片类图层）正是这一增量策略的体现。

如果你希望参与 deck.gl 的 WebGPU 开发，或只是跟进进展，可以关注 OpenJS / Open Visualization Slack 社区的专属频道，并查看发布跟踪（release tracker）任务与 GitHub 上的持续实现工作。在 v9 阶段投入生产环境前，请务必对照上文的支持矩阵确认你所使用的图层、扩展与效果组合均在 WebGPU 路径上可用，或将关键场景回退到 WebGL。

【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl