社区精选资源

先看哪一类

官方仓库与文档

• luma.gl 官网：项目首页与文档入口。解决的问题：确认 9.4 的定位——统一 WebGL2 与 WebGPU 的渲染引擎，而不是地图库。
• 文档总入口：按概念、API、指南分区。解决的问题：先建立目录感，知道某类问题该去哪一章。
• visgl/luma.gl：源码与 issue。解决的问题：文档没写清的行为，直接读实现或搜讨论。
• Getting Started：安装与第一个 Device、Buffer 的创建流程。解决的问题：从零跑通最小渲染，不必先理解全部抽象。
• Device API：设备对象的创建、资源工厂与销毁。解决的问题：9.x 的所有资源都从 Device 派生，先弄懂它是关键。
• 官方示例：渲染管线、计算着色器与着色器玩具等示例集合。解决的问题：需要可直接运行、可改参数的代码时先看这里。
• modules 目录：按子包拆分的源码结构。解决的问题：确认某个能力属于 core、engine 还是 webgl，避免装错包。
• 设计理念：解释为什么用 WebGPU 风格的资源与命令模型来抽象 WebGL2。解决的问题：理解抽象层的取舍，写自定义管线时不做无用功。
• Releases：版本发布记录。解决的问题：定位某 API 从哪个版本开始可用或失效。
• CHANGELOG：逐版本变更记录。解决的问题：升级前确认被改名的类与参数。

子包与 npm 包

• @luma.gl/core：Device、Buffer、Texture、RenderPipeline 等核心抽象。解决的问题：只做基础渲染时，不必引入 engine 与模型层。
• @luma.gl/engine：Model、Geometry、AnimationLoop 等高层封装。解决的问题：需要现成的模型对象与渲染循环，少写胶水代码。
• @luma.gl/webgl：WebGL2 后端适配。解决的问题：确认能力探测与 WebGL 后端的具体行为。
• @luma.gl/shadertools：着色器模块、依赖解析与代码拼装。解决的问题：多个片段组合时的注入顺序与 uniform 冲突。
• @luma.gl/constants：GL 常量与枚举。解决的问题：避免代码里散落魔法数字。
• @luma.gl/gltf：glTF 模型的解析与渲染支持。解决的问题：需要直接渲染 glTF，而不经过 deck.gl 图层。
• modules/core：核心抽象源码。解决的问题：理解 Device 的资源生命周期与销毁时机。
• modules/engine：Model 与 Geometry 的实现。解决的问题：查模型绘制的属性映射与索引处理细节。
• modules/shadertools：着色器模块实现与内置模块清单。解决的问题：搞清某个模块注入了哪些 uniform 与函数。
• modules/gpgpu：GPU 计算与数据回读受限的批处理实现。解决的问题：把逐帧的 CPU 循环搬到 GPU，处理大体量点或栅格。
• modules/gltf：glTF 模块源码。解决的问题：需要扩展或裁剪模型加载行为时对照实现。

与 deck.gl 的关系

• visgl/deck.gl：deck.gl 的图层体系建立在 luma.gl 之上。解决的问题：想知道某个渲染行为为何如此，往上追一层看 deck.gl 的调用方式。
• deck.gl 自定义图层指南：自定义 Layer 的渲染钩子与模型创建。解决的问题：写自定义图层时弄清 render、updateState 与 luma 资源的关系。
• examples 目录：示例源文件与依赖声明。解决的问题：把示例搬进项目时确认所需包与资源。
• visgl/loaders.gl：同一团队维护的数据加载框架。解决的问题：自定义图层要读非标准格式时，避免自己写解析器。
• modules/core/src：核心包实现目录。解决的问题：确认某个方法内部调用了哪个 WebGL 接口时逐层追查。

底层原理与工具

• WebGL Fundamentals：从着色器到缓冲区的系统讲解。解决的问题：理解 luma.gl 抽象背后的原生流程。
• WebGL2 Fundamentals：面向 WebGL2 的对应内容。解决的问题：9.x 默认走 WebGL2，确认新特性怎么用。
• webgl-fundamentals 仓库：教程的示例源码。解决的问题：想直接跑通某段讲解代码时取用。
• MDN · WebGL API：浏览器接口的权威参考。解决的问题：查某个 GL 调用的参数与返回值。
• MDN · WebGPU API：WebGPU 的接口说明。解决的问题：luma.gl 同时支持 WebGPU 后端，需要对照原生接口时用。
• Khronos OpenGL Wiki：GL 概念与常见误区。解决的问题：帧缓冲、纹理格式这类名词的准确含义。
• KhronosGroup/glTF：glTF 规范与工具仓库。解决的问题：确认模型格式与扩展的支持范围。
• ShaderToy：着色器片段的在线试验场。解决的问题：快速验证一个噪声或光照公式的写法。
• KhronosGroup/WebGL：WebGL 规范仓库。解决的问题：确认某个行为是规范要求还是实现差异。

社区问答

• GitHub Issues：bug 与设计讨论。解决的问题：确认异常是已知缺陷还是用法有误。
• Stack Overflow · webgl 标签：英文问答存量最大。解决的问题：着色器编译、纹理与帧缓冲的通用问题。
• r/webgl：偏实践交流的版块。解决的问题：性能与兼容性这类需要经验判断的讨论。

注意事项

• @luma.gl/core 与 @luma.gl/engine 必须锁在同一版本，混用不同大版本会在运行时抛出难以定位的类型错误。
• Buffer、Texture、Pipeline 都要显式销毁，否则切换图层时 GPU 内存只增不减。
• 9.x 的所有资源都从 Device 创建，不再直接传 gl 上下文，旧代码的构造函数参数需要整体替换。

怎么判断一篇教程是否过时

三条线索：版本号是否写明 9.x；日期是否近两年； API 是否已废弃——9.x 用 Device 抽象，出现 new Model(gl, {...})、 new Program(gl, ...) 这类直接传 gl 的写法，是 8.x 及更早的形态，照抄必然报错。

版本与发布时间以 npm 为准：

npm view @luma.gl/core version
npm view @luma.gl/core time.modified
npm view @luma.gl/engine version

再看 Upgrade Guide 与 CHANGELOG：里面按版本列出删除项与替换项。子包版本必须一致—— @luma.gl/core 与 @luma.gl/engine 混用不同大版本时， 往往要等到运行时才报出一句难以定位的类型错误。