Skip to content

doc: 补充emscriptenglx的相关文档 #1021

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 23, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .config/.vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,7 @@ export default defineConfig({
{ text: "资源优化工具与建议", link: "/Design/AssetOptimization" },
{ text: "iOS高性能 与 高性能+ 模式", link: "/Design/iOSOptimization" },
{ text: "优化Unity WebGL的渲染性能", link: "/Design/RenderOptimization" },
{ text: "EmscriptenGLX渲染模式", link: "/Design/EmscriptenGLX" },
{ text: "定制微信小游戏的 URP 管线", link: "/Design/CustomURP" },
{ text: "WebGL2.0渲染支持说明", link: "/Design/WebGL2" },
{ text: "性能深度分析工具", link: "/Design/DeepProfileTool" },
Expand Down
54 changes: 54 additions & 0 deletions Design/EmscriptenGLX.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# EmscriptenGLX 渲染模式

## 简介

游戏内所有 GL 指令调用需要经过三层转换:`WASM(业务逻辑)` -> `WebGL JS胶水层(GL -> WebGL)` -> `平台渲染`,WASM 模块与 JavaScript 之间的高频通信无疑带来了繁重的性能开销。

通过 EmscriptenGLX 渲染模式,可以实现在 WASM 内部完成 `GL -> WebGL` 指令的处理,将原本 `WebGL JS胶水层` 的代码下沉至业务逻辑(WASM)中,消除**WASM 与 JS 之间高频调用链路**。详细文档请查阅[EmscriptenGLX 渲染模式](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-emscriptenglx.html)

## 特别说明

1. EmscriptenGLX 目前仅支持在 **iOS 高性能+模式** 以及 **Android 平台** 下运行,其他运行时将会自动降级为原有的运行方案。
2. 基础库版本须 `>= 3.8.10`,低版本的基础库会使用原有的运行模式运行游戏。
3. 当前仅支持 `Unity2022` 和 `团结引擎` 接入
4. 本方案处于 `Beta` 测试阶段,建议**充分验证后**再进行发布。

## 接入指南

### 1. SDK 接入

请参照 [微信 SDK 安装](./SDKInstaller.md),使用 `Package方式`进行安装

`打开游戏工程` -> `Editor 菜单栏` -> `Package Manager` -> `右上方 "+"` -> `Add package from git URL` -> `输入下方的URL地址`,即可完成 SDK 导入

```javascript
https://github.com/wechat-miniprogram/minigame-tuanjie-transform-sdk#feat-emscriptenglx
```

### 2. 开启 EmscriptenGLX

通过「微信小游戏工具面板」-「调试编译选项」-「EmscriptenGLX」进行勾选,并开启转换

![开启EmscriptenGLX](../image/emscripten_enable.png)

## 常见问题

### Q1. 如何确认转换后的游戏使用到了 EmscriptenGLX 的渲染模式?

请按照下方的步骤进行验证

1. 删除本地小游戏(包括开发版、体验版和正式版)。
2. 重新进入游戏并打开调试,查看 vConsole 中的相关日志

- vConsole 第一行,确认基础库版本 `>=3.8.10`
- 在 WebGL Context 创建上下文前后,查看是否包含下图高亮的日志信息
![成功开启EmscriptenGLX](../image/emscripten_enable_log.png)

### Q2. 为什么开启了 EmscriptenGLX 后,性能更差了?比如单帧耗时更大了。

A2. 如果遇到了此类情况,一般是踩到了新方案的坑,[联系我们](./IssueAndContact.md)一起进行排查。

### Q3. 为什么开启 EmscriptenGLX 模式后,渲染异常了?

A3. 新方案对 GL 的相关指令进行了重构,若遇到了渲染相关的表现异常问题,请先排查游戏在 iOS 高性能+ 和 原 Android 设备下的渲染表现是否正常,若正常,请[联系我们](./IssueAndContact.md)一起进行排查。

Binary file added image/emscripten_enable.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added image/emscripten_enable_log.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading