👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 HarmonyOS 的过程都记录在这里。
  
  🛠️ 主要方向:ArkTS 语言基础、HarmonyOS 原生应用(Stage 模型、UIAbility/ServiceAbility)、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战,以及 Android → 鸿蒙的迁移踩坑与复盘。
  🧭 内容节奏:从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘,让每篇都有可落地的代码与方法论。
  💡 我相信:写作是把知识内化的过程,分享是让生态更繁荣的方式。
  
   如果你也想拥抱鸿蒙、热爱成长,欢迎关注我,一起交流进步!🚀

前言

三维高斯泼溅(3D Gaussian Splatting,3DGS)作为一种端侧可实时渲染的三维场景表达方式,已经进入 HarmonyOS 的官方图形能力体系。但整个场景一次性加载的方式,在面对城市街区、大型园区、展馆全景这类大规模场景时,会遇到明显的瓶颈。

HarmonyOS API 26(对应 HarmonyOS 7)新增了 TiledGSNode、TileRequestCallback 等分块 3DGS 能力,提供了一套针对大规模场景的按需加载机制。这篇文章结合官方 API Reference 中的接口定义,梳理从 manifest 设计、节点创建到瓦片调度的完整开发流程。

一、普通 3DGS 场景的瓶颈在哪里

HarmonyOS 图形引擎已经支持通过 GSNode 加载标准 .splat 格式的 3DGS 资源。对于一个体量可控的单场景,这个方式完全够用:加载一份资源文件,挂到场景图中,渲染器负责其余的事情。

问题出现在场景体量增大时:

  • 一个包含数百万高斯核的大型场景,资源文件本身可能就有数百 MB;
  • 即使设备内存能撑住,一次性把全部高斯核传入 GPU,帧率下降几乎是必然的;
  • 用户的摄像机在任意时刻实际可见的区域,只是整个场景很小的一部分。

Tiled 3DGS 的核心思路是:把整个大场景切成若干空间瓦片(Tile),引擎根据摄像机当前位置和视锥,只向应用层请求真正需要渲染的瓦片,其余的暂不加载。

这种按需加载不是 HarmonyOS 独创,但 API 26 将这一机制以 TiledGSNode 的形式纳入官方图形 API 体系,开发者可以通过标准回调控制每个瓦片的生命周期。

二、官方能力边界先确认

在动手之前,有几个前提条件必须确认。

API Level 要求

TiledGSNode 及本文涉及的 TileRequestCallback 接口,均在 API 26 首次引入,对应 HarmonyOS 7。低于 API 26 的设备不支持这组接口,开发时需要做版本判断或在 module.json5 中明确声明最低版本。

所属 Kit

这组能力属于 Scene Kit(场景图形服务)。使用前需要确认工程依赖中已经接入 Scene Kit。

设备支持

当前官方文档描述中,Scene Kit 的 3DGS 相关能力适用于支持 GPU 渲染的设备,具体设备兼容性以官方文档中 @kit.SceneKit 对应的 supported devices 说明为准。建议在 module.json5 中配合 deviceTypes 字段明确声明目标设备类型。

权限

加载本地资源无需特殊权限;如果瓦片资源来自网络或沙箱外路径,需要按照标准文件访问或网络权限规则处理。

三、Tiled 3DGS 的 manifest 与瓦片结构

Tiled 3DGS 场景的组织方式是:一个 manifest 文件描述整个大场景的切分方式和各瓦片的元数据,每个瓦片对应一份独立的 3DGS 资源文件。

根据官方文档的描述,manifest 文件以 JSON 格式组织,包含场景的空间划分信息及各瓦片的 URI。典型结构如下(以概念示意为主,实际字段以官方资料为准):

{
  "version": 1,
  "tiles": [
    {
      "id": "tile_0_0",
      "boundingBox": {
        "min": [-50, 0, -50],
        "max": [0, 20, 0]
      },
      "uri": "resources/rawfile/tiles/tile_0_0.splat"
    },
    {
      "id": "tile_0_1",
      "boundingBox": {
        "min": [0, 0, -50],
        "max": [50, 20, 0]
      },
      "uri": "resources/rawfile/tiles/tile_0_1.splat"
    }
  ]
}

每个瓦片通过 boundingBox(轴对齐包围盒)描述其在世界坐标系中的空间范围,引擎根据这个范围与当前视锥做相交判断,决定是否请求该瓦片。

四、核心代码实现

下面按照官方 Scene Kit API 的接口定义,组织一个最小示例,覆盖从创建 TiledGSNode、绑定驱动摄像机到实现 TileRequestCallback 的完整流程。

4.1 创建场景与 TiledGSNode

根据官方 API 说明,TiledGSNode 通过 Scene Kit 的场景图创建,并挂载到场景的根节点下。

import { scene } from '@kit.SceneKit';

// 从 manifest 文件创建 TiledGSNode
// manifest 文件放置于 rawfile 目录
async function createTiledScene(context: Context): Promise<void> {
  // 1. 获取或创建 Scene 实例
  const sceneInstance: scene.Scene = await scene.Scene.load(
    $rawfile('scene/base.gltf')
  );

  // 2. 通过 Scene 的节点工厂创建 TiledGSNode
  const tiledGSNode: scene.TiledGSNode = await sceneInstance.createNode(
    scene.NodeType.TILED_GS_NODE
  ) as scene.TiledGSNode;

  // 3. 设置 manifest 文件路径
  tiledGSNode.manifestUri = $rawfile('tiles/manifest.json').toString();

  // 4. 挂载到场景根节点
  sceneInstance.root?.addChildNode(tiledGSNode);
}

这段代码的关键不在于节点创建本身,而在于 manifestUri 的赋值时机。它必须在节点挂载到场景之前完成设置,否则引擎无法在节点激活时正确初始化瓦片索引。

4.2 设置驱动瓦片选择的 Camera

引擎需要知道以哪个摄像机的视锥来决定哪些瓦片需要加载。TiledGSNode 提供了 camera 属性,用于指定驱动瓦片调度的摄像机节点。

// 假设场景中已有名为 "MainCamera" 的摄像机节点
const camera = sceneInstance.getNodeByName('MainCamera') as scene.Camera;

// 将摄像机绑定到 TiledGSNode,驱动瓦片裁剪与加载
tiledGSNode.camera = camera;

这个绑定决定了引擎的瓦片可见性计算基准。如果场景中有多个摄像机(例如主视角 + 小地图),应该绑定主渲染摄像机,而不是所有摄像机。

4.3 实现 TileRequestCallback

引擎判断某个瓦片需要加载或卸载时,会通过 TileRequestCallback 通知应用层。应用层负责实际的资源获取操作,完成后再通知引擎。

// 实现 TileRequestCallback 接口
const tileCallback: scene.TileRequestCallback = {
  // 引擎请求加载瓦片时触发
  onTileRequest(tileId: string, uri: string): void {
    // uri 是 manifest 中该瓦片的资源路径
    // 应用层负责将资源数据传递给引擎
    loadTileResource(tileId, uri, tiledGSNode);
  },

  // 引擎请求卸载瓦片时触发
  onTileRelease(tileId: string): void {
    // 通知引擎释放该瓦片
    tiledGSNode.releaseTile(tileId);
  }
};

// 注册回调
tiledGSNode.setTileRequestCallback(tileCallback);

4.4 加载瓦片资源并通知渲染器

onTileRequest 触发后,应用层完成资源加载,需要调用 TiledGSNode 的相应接口将资源交给引擎,并通知渲染器该瓦片已就绪。

async function loadTileResource(
  tileId: string,
  uri: string,
  node: scene.TiledGSNode
): Promise<void> {
  try {
    // 从 rawfile 或其他路径读取瓦片资源数据
    // 这里以 rawfile 为例,实际可扩展为网络请求
    const resourceManager = getContext().resourceManager;
    const tileData: ArrayBuffer = await resourceManager.getRawFileContent(
      uri.replace('resources/rawfile/', '')
    );

    // 将瓦片数据提交给 TiledGSNode
    // 引擎完成 GPU 上传后,瓦片进入可渲染状态
    node.loadTiledGSNode(tileId, tileData);

  } catch (error) {
    // 加载失败时应通知引擎该瓦片不可用,避免引擎持续等待
    node.releaseTile(tileId);
    console.error(`Tile load failed: ${tileId}, error: ${JSON.stringify(error)}`);
  }
}

这里需要特别关注错误处理分支。如果资源加载失败但没有调用 releaseTile,引擎会持续将该瓦片标记为"请求中",后续即使视锥变化也不会再次发出请求,瓦片会永久空缺。

五、几个值得拆开看的关键点

Camera 绑定与瓦片调度时机

tiledGSNode.camera 的赋值时机会影响引擎首次进行瓦片计算的时刻。如果摄像机是异步创建的(例如从 glTF 场景中加载),需要确保摄像机节点完全初始化后再赋值,否则引擎可能以空视锥启动,导致第一帧没有任何瓦片被请求。

回调线程安全

TileRequestCallback 的回调触发在引擎内部调度线程,如果在回调中更新 UI 状态或操作 ArkUI 组件,需要通过 @ohos.taskpool 或 runOnMainThread 切换到主线程,不能直接在回调中操作 UI。

manifest URI 格式

manifestUri 接受的路径格式需要与引擎的资源解析机制匹配。使用 $rawfile() 宏时,返回的是 Resource 对象,直接赋值给 string 类型属性时需要做格式转换,或确认官方 API 是否接受 Resource 类型。这一点在实际接入时建议优先参考官方 Sample 中的赋值方式。

瓦片粒度与内存压力的平衡

瓦片划分粒度是一个场景设计问题,不是 API 问题。瓦片太少,每个瓦片体量大,加载慢,内存峰值高;瓦片太多,回调频繁,调度开销增加。实际项目中建议结合目标设备内存规格和场景的高斯核密度分布来决定切分粒度,而不是均匀切分。

六、容易踩坑的地方

忘记处理 onTileRelease 导致内存泄漏

onTileRelease 触发时,如果应用层只是停止了加载任务,但没有调用 releaseTile 通知引擎,引擎的瓦片状态机会出现不一致。随着摄像机移动,未被释放的瓦片会持续占用内存,在长时间运行的场景漫游中会触发 OOM。

API Level 检查遗漏

TiledGSNode 仅在 API 26 及以上可用。如果工程的 minAPIVersion 低于 26,但没有在运行时做版本判断就直接调用,低版本设备上会直接抛出异常。正确的做法是在调用之前通过 deviceInfo.sdkApiVersion 判断当前运行环境。

scene.NodeType.TILED_GS_NODE 拼写

NodeType 枚举值的大小写和拼写需要严格对照官方 API Reference。3DGS 相关枚举在不同版本间可能有命名调整,建议在接入时直接从官方 API Reference 查阅 scene.NodeType 的枚举列表,不要凭印象拼写。

七、加载流程梳理

大型三维场景的完整加载流程如下:

应用启动
   │
   ▼
加载 Scene(glTF 基础场景)
   │
   ▼
创建 TiledGSNode,设置 manifestUri
   │
   ▼
注册 TileRequestCallback
   │
   ▼
设置驱动 Camera,挂载节点到场景根
   │
   ▼
引擎解析 manifest,初始化瓦片索引
   │
   ▼
引擎根据 Camera 视锥计算可见瓦片集合
   │
   ├──有新瓦片进入视锥──► onTileRequest 触发──► 应用加载资源──► loadTiledGSNode
   │
   ├──有瓦片离开视锥──► onTileRelease 触发──► 应用调用 releaseTile
   │
   └──Camera 移动──► 重新计算可见集合(循环)

八、实际项目中的排查顺序

如果接入后出现瓦片不渲染或渲染异常,建议按以下顺序排查:

  1. 确认 API Level:当前设备是否运行在 API 26 及以上;
  2. 确认 manifest 路径:manifestUri 的路径格式是否与引擎预期一致,尝试打印路径字符串检查;
  3. 确认 Camera 已绑定:tiledGSNode.camera 是否在节点挂载前成功赋值,打印 camera 对象确认非 null;
  4. 确认回调已注册:setTileRequestCallback 是否在引擎首次调度之前完成注册,如果晚于节点激活注册,可能漏掉第一批请求;
  5. 确认 onTileRelease 分支完整:检查资源加载失败时是否有 releaseTile 兜底;
  6. 查看 HiLog:过滤 Scene Kit 相关 tag,观察引擎是否有瓦片请求日志输出;
  7. 缩小场景规模验证:先用只有 2~4 个瓦片的最小 manifest 验证整个回调链路是否通畅,排除资源格式问题后再扩大。

开发经验总结

  • Tiled 3DGS 的本质是把内存和 GPU 压力的时序从"启动时集中"变成"运行时按需分散",代价是应用层需要维护一个可靠的瓦片生命周期回调实现;
  • TileRequestCallback 的错误处理分支(资源加载失败时的 releaseTile 兜底)容易在初期被忽略,但对长时间运行的漫游场景影响较大;
  • Camera 的绑定时机和回调注册时机,两者都需要在引擎首次调度之前完成,这是整个流程中最容易因异步初始化顺序问题出错的地方;
  • manifest 的切分粒度不是 API 层面的问题,而是场景设计层面的决策,需要结合目标设备规格提前规划。

如果你正在把一个现有的 GSNode 场景迁移到 TiledGSNode,建议先检查原有场景资源能否在工具链侧按空间包围盒切分为独立瓦片——资源切分工具和 manifest 生成方式直接决定了引擎调度的效果,这一步往往比 API 接入本身花费更多时间。

📝 写在最后

如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!

我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!

感谢你的阅读,我们下篇文章再见~👋

✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐