前沿资讯/我的第一个开源项目|Sceneform‑EQR:我的开源进化之路
我的第一个开源项目|Sceneform‑EQR:我的开源进化之路
我的第一个开源项目|Sceneform‑EQR:我的开源进化之路

2025-07-24发布

image.png

投稿作者:EQ-雪梨蛋花汤

GitCode 平台 G-Star 孵化项目 Sceneform-EQR 项目作者

“那一夜凌晨 3 点,第一次提交 PR 的手在抖……” —— 那是我第一次把代码推向世界,也是我真正开始与开源世界对话的起点。


一、起点:一次“救火”式的开源尝试

2020 年,Google 官方宣布 sceneform-android-sdk 归档。对很多 Android 3D/AR 开发者来说,这是一次技术断崖。

network-asset-05250979be1e4b938596b075db5d1463-20250723165610-ub43u9k.png

而我,当时正是一名“AR + GIS”的一线开发人员,Sceneform 是我们业务中与 ARCore 深度结合的核心模块。SDK 突然停摆,不只是“无法更新”,更是直接影响业务连续性。

起初,我只是“临时救火”:Fork 一份仓库,想办法让它多撑一阵子。但这个“应急操作”很快演变成一次深入的技术探索——我开始学习Filament、尝试接入华为 AREngine、调试场景渲染 bug,逐步把 Sceneform 从“被遗弃的代码”转变为“可维护、可拓展的系统”。

也正是在这个过程中,我意识到:

这不是在修复一个 SDK,而是在建造一座属于中国开发者自己的 3D 渲染桥梁。


二、一段接力:从谷歌到社区,再到我

1、SceneView/sceneform-android

谷歌 Sceneform 被归档后,社区的开发者们并未放弃这条技术线。

开发者 ThomasGorisse 接过了第一棒,基于原始 SDK 构建并维护了 SceneView sceneform-android,为社区延续了 Sceneform 的生命。

network-asset-a92d2193f35c40c6ae27613386ece6ed-20250723165610-w5vp2e9.png

但在 2023 年之后,这条线也停止了维护。
network-asset-b1c8c7237d854a889340c530adab07bd-20250723165611-bwmz7r5.png


2、EQ-Renderer

在 ThomasGorisse 的仓库不再维护 Java 接口的 Sceneform 之后,我开始维护一个私有的仓库,初次命名为“EQ-Renderer”,意为“EQ的渲染器”。

主要内容是基于谷歌存档的 Sceneform-android-sdk,接入了 ThomasGorisse 对 Sceneform 的一些修改。并解决了 gltf 模型加载内存泄漏问题,接入了 AREngine,解决了由于颜色映射异常导致的 View 颜色显示不正确的问题。

repo截图: network-asset-92ff1073bc8e4fc9926739cc7acf25f1-20250723165611-067sxzo.png 版本记录:
network-asset-64d5bc0b7ecb42f5915acae9ccdc8072-20250723165611-e69p0eu.png


3、Sceneform‑EQR

2024年初,我开源了自己的本地库“EQ-Renderer”,并重命名为“Sceneform‑EQR”。
network-asset-32f01a9894264b06a318ebca1ee3555d-20250723165611-fublj1v.png EQR = Extended, Quick, Rewired

一套为新场景而生、快速适配、重新连接生态的安卓原生 3D 渲染引擎。

这是我第一次在社区独立维护一个依赖库——我不是在“造轮子”,而是在“守火种”。

尽管文档不完善,也没有做任何推广,仅是随缘挂着,但总会有一线研发人员私信我,请教适配问题或请求 SDK 支持。

这些沟通、答复与调试,都是出于对 Sceneform 的热爱—— 哪怕只有一个人用着,它也值得被延续。

image-20250731104335-4b58fa5.png


三、如今的 Sceneform‑EQR

至今,我一直以个人开发者身份维护这份代码。

不再有业务束缚,我可以真正从架构层重构它:

  • 翻译 Sceneform 源码,增补注释;
  • 剔除已弃用的接口;
  • 理解 Filament 材质调用流程;
  • 深入安卓与底层渲染接口的适配逻辑;
  • 尝试更多的可能,扩展新功能;

我把它当作一次学习机会,一个可以实践所有三维原生图形想法的场所。

Sceneform‑EQR 是 EQ(EQ-雪梨蛋花汤) 对谷歌 sceneform-android-sdk 的扩展,适用于图形与视频、增强现实(AR)和虚拟现实(VR)相关领域。 它集成了 ARCore、AREngine 和 ORB-SLAM,支持普通场景、AR 场景、VR 场景以及自定义背景场景,以满足多端多样的原生三维开发需求。


1、GitHub & GitCode 双平台同步

2025 年 7 月,为方便国内开发者访问,项目实现了:

GitHub ⇌ GitCode 双向同步

从此,国内外开发者都能顺畅访问与协作,社区建设进一步推进。 network-asset-b2848a8a68e14bee92fb5f615759ee7e-20250723165611-ptrf06g.png


四、难关与成长:从内存泄漏到动态材质

1、内存泄漏的破冰之战

2022年3月左右开发“AR + GIS SDK”时,我们发现一个致命问题:

3D模型多次加载与释放,会导致内存泄漏,最终崩溃。 network-asset-ae2fddbd88ae431197f3aa899ca66b6a-20250723165611-83g5xxq.png

我反复比对日志、查阅源码,最终通过社区开发者 steven-gao 的一段代码找到了突破口。

以下是问题解决后,内存正常释放的监控截图 network-asset-d68421fa52444a7da2b599b92077e011-20250723165611-yslv2j3.png

这项修复被我合入 Sceneform‑EQR 本地库,在社区伙伴遇到类似问题时,我也积极帮助。 Issue#424

前车之覆,后车之鉴。这是我从“使用者”转变为“参与者”的分水岭。


2、材质探索:复刻 AR 涂鸦的全过程

2023 年底,一位朋友拿来三星手机,展示了其 AR 涂鸦功能:“你能实现吗?”

功能包括:

  • 文本与图片的涂鸦;
  • 3D 自由线条绘制;
  • 流动、透明、呼吸等视觉材质。

我查阅 Filament 的材质文档,使用 matc 工具自编 .mat 文件:

  • 支持动态图、视频纹理注入;
  • 搭配 Sceneform 节点系统,实现交互绘制;
  • 自研材质支持透明通道、UV 位移、实时变色;

这项功能虽未正式商用,但成为我深入理解 Filament 材质使用流程的重要跳板。
👉 【Sceneform-EQR】在安卓中使用filament(sceneform)材质(一)
👉 【Sceneform-EQR】在安卓中使用filament(sceneform)材质(二)

部分效果图如下:

network-asset-b0d83c634d664e0f9a43f9a6c0aedd82-20250723165612-75tlzk2.gif network-asset-a695a5364eea4e8fa376028871f42d34-20250723165616-jx0nv1j.gif


3、OST AR 眼镜项目:眼镜上的 Launcher 实战

network-asset-009e95978eab4d1db1274f2538659f72-20250723165617-77tly33.jpeg

2023年底,在深圳的FBEC会上,认识的新朋友希望用原生方式实现 眼镜 Launcher 应用

我发现 Sceneform‑EQR 具备极佳的适配潜力:

  • 原生 AR 渲染体验;
  • 支持 ARCore / AREngine 双平台统一;
  • 适配单双屏、XR 显示模式;

最终成功打造出一个可部署到 AR 眼镜的 Launcher 原型。

👉 文档:【Sceneform-EQR】使用EQ-Renderer实现AR桌面

支持ARCore的平板上显示效果:
network-asset-336d69bd133745639ba7e5bca382a62b-20250723165617-64xpty4.png 眼镜端左右双屏显示效果:
network-asset-4f1743a7e644441c997cafb6cbd76a20-20250723165617-3cj6q7p.png


五、项目现状:生态建设持续进化中

1. 项目地址

2. 项目结构

  • Eq‑Renderer 渲染库:
    • Android/eq‑renderer:主要源码;
  • 示例工程 SampleProj/app:Demo 程序;
  • Maven 本地依赖发布:
maven {
  allowInsecureProtocol true
  url "http://repo.eqgis.cn"
}
implementation "com.eqgis:eq‑renderer:1.0.9"

3. 核心功能模块

  • 场景加载:支持 glTF 模型加载(普通场景、AR/VR 场景均可)(github.com);
  • 动画支持:封装 ModelAnimation,自动播放、设置时长、循环,接入 FilamentAnimator;
  • XR 支持:支持AR、VR、普通3D场景。集成 ARCore、AREngine、ORB‑SLAM3,支持场景间一键切换;
  • 背景扩展:支持透明背景、图片背景、视频背景,特点是灵活配置、流程简洁 (blog.csdn.net);
  • 材质扩展:调用 matc 生成材质,实现呼吸、流动纹理、视频贴图等;
  • 手势交互:单指旋转、双指平移/缩放、点击事件等基本场景交互内置;(blog.csdn.net);

4. 核心功能截图

  • 在普通 3d 场景加载 GLTF 格式的模型
    network-asset-b7e6f45aafb34126a62d731a46ad0fdb-20250723165617-t8s25qg.png

  • 在 AR 场景加载 GLTF 格式的模型
    network-asset-ca4270760de94584a4fa7084932bd8dc-20250723165617-gr3i07i.png

  • 支持 GLTF 模型动画
    network-asset-4c2c1d36996e4fcbae3d77035a294a55-20250723165617-lglwqpv.gif

  • 手势点击交互
    network-asset-972ed3a86452481aa1f06680461a7a75-20250723165618-8mmfi1x.gif

  • 通过手势控制模型(单指旋转、双指平移、双指缩放)
    network-asset-36195ebc39184312b2f08ab1660dd26b-20250723165618-2g1549c.gif

  • 案例:AR 桌面

通过渲染安卓原生 View 实现
network-asset-8bc2c09aa1c4471397e3ab8e3e29078d-20250723165619-j0d7z65.gif

  • 支持双屏显示,常用于 XR 眼镜

曾用于团队定制的 AR 眼镜,实现原生安卓 Launcher(支持 3DOF|6DOF 切换)
network-asset-e4ac9d831f024176aeb49515e18e1fc0-20250723165619-k1zwgc2.png

  • 案例:AR 涂鸦(自定义纹理、流动纹理、视频纹理、移位贴图)

呼吸效果,通过 Filament 的 matc 工具编译自定义材质文件
network-asset-b0d83c634d664e0f9a43f9a6c0aedd82-20250723165612-75tlzk2.gif 流动纹理,使用视频资源作为纹理贴图
network-asset-a695a5364eea4e8fa376028871f42d34-20250723165616-jx0nv1j.gif


六、写在最后:开源是信仰,更是修行

开源的起点,是热爱;中途,是孤独;坚持,是信仰。

从谷歌 Sceneform 被弃,到我多次凌晨提交代码。 从一人维护,到今日支持多设备适配与社区反馈。

Sceneform‑EQR 不只是一个技术项目,它也是我技术成长、自我构建、走向开源世界的旅程。

“用不用在你,做与不做在我。”

这句话,我写给自己,也写给每一个仍在热爱技术的你。

愿每一个在深夜为 PR 苦战的人,都能看到属于自己的光,也成为别人的光。


如果你也有想法、有热情,欢迎加入共建。

📫 交流地址:GitCode Issues