libpag 4.5.0 → 4.5.2

package/README.md

@@ -98,50 +98,209 @@ with HTML, Vue, React, and PixiJS.
 
 You can find the API documentation [here](https://pag.io/docs/apis-web.html).
 
-## Browser
+`The above steps integrate the single-threaded version of libpag. To integrate the multithreaded version, please refer to the following integration guide.`
+
+## Multithreaded Integration Guide
+
+### Multithreading Support Basics
+
+[WebAssembly multithreaded](https://emscripten.org/docs/porting/pthreads.html) relies on browser support for [SharedArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer). By leveraging `SharedArrayBuffer` and `Web Worker`, multithreaded Wasm modules can perform parallel computation to improve performance.
+
+- **Key mechanisms**:
+    - Wasm threads use shared memory via `SharedArrayBuffer` for data synchronization and communication.
+    - Multiple thread instances of the same wasm module run in separate `Web Worker` execution contexts.
+
+- **Requirements**:
+    - Wasm must be compiled with threading-related flags enabled (e.g., Emscripten’s `-pthread` support).
+    - The runtime environment must support `SharedArrayBuffer` and `Web Worker`.
+
+### Cross-Origin Security Requirements
+
+To mitigate side-channel attacks, modern browsers enforce strict environment restrictions on enabling [SharedArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer). Enabling Wasm multithreading requires satisfying **Cross-Origin Isolation** conditions.
+
+#### Required Response Headers
+
+To enable cross-origin isolation, the server must set the following HTTP response headers for all relevant resources (HTML, wasm, JS, etc.):
+
+| Header                         | Example Value       | Purpose                                      |
+|-------------------------------|---------------------|----------------------------------------------|
+| `Cross-Origin-Opener-Policy` (COOP)   | `same-origin`         | Isolates the current browsing context from cross-origin documents  |
+| `Cross-Origin-Embedder-Policy` (COEP) | `require-corp`        | Restricts embedded resources to those complying with CORP or CORS policies |
+
+For more details, see the [SharedArrayBuffer documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer).
+
+#### Notes
+
+- **The page and related resources must be served over HTTPS (or localhost).**  
+  Browsers enable cross-origin isolation and `SharedArrayBuffer` only in [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts). Multithreading depends on this secure environment.
+- Cross-origin isolation cannot be enabled on HTTP, and multithreading support will be disabled.
+
+### Browser (Recommended)
+
+The web-side code for integrating multithreading is the same as the single-threaded, but the server must meet the above requirements; otherwise, multithreading will fail to load.
+
+#### Important Notes
+
+- **Do NOT load wasm resources cross-origin directly from public CDNs (such as npm CDNs).**
+  Most public npm CDNs (e.g., unpkg, jsDelivr) do not set COOP/COEP response headers by default and do not enable cross-origin isolation for all requests.
+  As a result, loading wasm/js from these CDNs via cross-origin requests will prevent browsers from enabling shared memory, disabling multithreading features.
+  It is strongly recommended to deploy wasm/js along with your webpage under the same origin to avoid cross-origin loading issues that disable multithreading.
+- The multithreaded wasm/js packages are not published on the npm registry. You can download the web packages from the [release page](https://github.com/Tencent/libpag/releases) and deploy them yourself.
+
+### Local Build
+
+```bash
+# ./web
+npm run build:mt
+```
+
+This will generate wasm/js files in the `web/lib-mt` directory. You can then start a local HTTP server to run the demo:
+
+```bash
+# ./web
+npm run server:mt
+```
+
+Open http://localhost:8081/index.html in Chrome to see the demo.
+
+To build a debug version, follow these steps:
+
+```bash
+# ./web
+npm run build:debug:mt
+npm run server:mt
+```
+
+> ⚠️ In the multithreaded version, if you rename the compiled output file libpag.min.js, you must search within the libpag.min.js file for all occurrences of "libpag.min.js" and replace them with the new filename.
+> Otherwise, the program will fail to run. The following shows an example of this modification:
+
+Before modification:
+
+```js
+    // filename: libpag.min.js
+    var worker = new Worker(new URL("libpag.min.js", import.meta.url), {
+     type: "module",
+     name: "em-pthread"
+    });
+```
+
+After modification:
+
+```js
+    // filename: libpag.min.test.js
+    var worker = new Worker(new URL("libpag.min.test.js", import.meta.url), {
+     type: "module",
+     name: "em-pthread"
+    });
+```
+
+## Browser Compatibility
 
 | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Chrome | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Safari | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Chrome for Android | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Safari on iOS | QQ Browser Mobile |
 | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ----------------- |
 | Chrome >= 69                                                 | Safari >= 11.3                                               | Android >= 7.0                                               | iOS >= 11.3                                                  | last 2 versions   |
 
+**The compatibility table above only represents the compatibility for running the application. For users requiring mobile access, please refer to this article on [compatibility details](./doc/compatibility.md).**
+
+## Usage Guide
+
+### Garbage Collection
+
+Since libpag is based on WebAssembly for cross-platform applications, the objects retrieved from WebAssembly are essentially C++ pointers, so JavaScript's garbage collector (GC) cannot release this memory. Therefore, when you no longer need the objects created by libpag, you must call the `destroy` method on the object to free the memory.
+
+### Rendering
+
+#### First Frame Rendering
+
+`PAGView.init` will render the first frame by default. If you don't need this, you can pass `{ firstFrame: false }` as the third parameter to `PAGView.init` to disable first-frame rendering.
+
+During first-frame rendering, if there are BMP pre-compositions in the PAG animation file (details on how to check for BMP pre-composition in PAG files will be explained later), the `VideoReader` module will be invoked.
+
+Since the `VideoReader` module relies on `VideoElement` on the Web platform, on certain mobile scenarios where `PAGView.init` is not called within a user interaction chain, the video playback may not be allowed, preventing proper rendering.
+
+In such cases, we recommend initializing `PAGView` early with `PAGView.init(pagFile, canvas, { firstFrame: false })` and disabling first-frame rendering, and then calling `pagView.play()` for rendering when the user interacts.
+
+#### PAG Rendering Size
+
+On the Web platform, the device pixel resolution differs from the CSS pixel resolution, and the ratio between them is called `devicePixelRatio`. Therefore, to display 1px in CSS pixels, the rendering size should be 1px * `devicePixelRatio`.
+
+PAG will scale the Canvas based on its visible size on the screen, which may affect the Canvas width, height, and `style`. If you want to avoid scaling the Canvas, you can pass `{ useScale: false }` as the third parameter to `PAGView.init` to disable scaling.
+
+#### Large PAGView Size
+
+For high-definition rendering, `PAGView` will default to rendering at Canvas size * `devicePixelRatio`. Due to performance limitations of the device, the maximum renderable size for WebGL can vary. Rendering at too large a size may lead to a white screen.
+
+For mobile devices, it is recommended that the actual renderable size not exceed 2560px.
+
+#### Multiple PAGView Instances
+
+Since the Web version of PAG is a single-threaded SDK, we do not recommend **playing multiple PAGView instances on the same screen**.
+
+For scenarios involving multiple PAGView instances, you need to be aware that the number of active WebGL contexts in a browser is limited: 16 contexts for Chrome, 8 for Safari. Due to this limitation, it is important to use `destroy` to reclaim unused PAGView instances and remove Canvas references.
+
+Here is a solution for special cases, though it is not recommended:
+
+If you need to have multiple PAGView instances on the same screen in Chrome and do not require support in Safari, you can try using the `canvas2D` mode by passing `{ useCanvas2D: true }` when calling `PAGView.init`. In this mode, a single WebGL context is used as the renderer, and the frames are distributed to multiple canvas2D contexts, bypassing the WebGL context limit.
+
+Since the performance of [`CanvasRenderingContext2D.drawImage()`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage) is poor on Safari, we do not recommend using this mode on Safari.
+
+#### Registering a Decoder
+
+To bypass the "Video tags can only be used after user interaction with the page" restriction, the PAG Web version provides a software decoder injection interface `PAG.registerSoftwareDecoderFactory()`.
+
+After injecting a software decoder, PAG will schedule the decoder to decode and display the BMP pre-compositions, thus enabling auto-play functionality on some platforms.
+
+Recommended decoder integration: https://github.com/libpag/ffavc/tree/main/web
+
+Platforms known to have the "Video tags can only be used after user interaction" restriction include: mobile WeChat browsers, iPhone power-saving mode, and some Android browsers.
+
+## About BMP Pre-composition
+
+You can download [PAGViewer](https://pag.io/docs/install.html) to open PAG files, click "View" -> "Show Edit Panel". In the edit panel, you can see the number of Videos. If the number of Videos is greater than 0, it indicates that the PAG animation file contains BMP pre-compositions.
+
 
 ## Development
 
 First, ensure you have installed all the tools and dependencies listed in the [README.md](../README.md#Development)
 located in the project root directory.
 
+> This section describes the development and testing process for the single-threaded version of libpag.
+
 ### Dependency Management
 
 Next, run the following command to install the required Node modules:
 
 ```bash
+# ./web
 $ npm install
 ```
 
 ### Build (Debug)
 
-Execute `build.sh debug` to get `libpag.wasm` file.
+Run the following command to compile the wasm/js.
 
 ```bash
 # ./web
-$ npm run build:debug
+$ npm run build:debug:st
 ```
 
+This will generate the wasm/js files in the `web/lib` directory.
+
 Start the TypeScript compiler watcher (optional).
 
 ```bash
 # ./web
-$ npm run dev
+$ npm run dev:st
 ```
 
 Start the HTTP server.
 
 ```bash
-# ./
-$ npm run server
+# ./web
+$ npm run server:st
 ```
 
-Open Chrome and go to `http://localhost:8081/demo/index.html` to see the demo.
+Open Chrome and go to `http://localhost:8081/index-st.html` to see the demo.
 
 To debug, install [C/C++ DevTools Support (DWARF)](https://chrome.google.com/webstore/detail/cc%20%20-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb). 
 Then, open Chrome DevTools, go to Settings, Experiments, and check the "WebAssembly Debugging: Enable
@@ -151,7 +310,7 @@ DWARF support" option to enable SourceMap support. Now you can debug C++ files i
 
 ```bash
 # ./web
-$ npm run build
+$ npm run build:st
 ```
 
 ### Build with CLion
@@ -167,17 +326,20 @@ Create a new build target in CLion and use the following **CMake options** (foun
 Build the release version
 
 ```bash
-$ npm run build
+# ./web
+$ npm run build:st
 ```
 
 Start the HTTP server.
 
 ```bash
-$ npm run server
+# ./web
+$ npm run server:st
 ```
 
 Start the cypress test.
 
 ```bash
+# ./web
 $ npm run test
 ```

package/README.zh_CN.md

@@ -1,6 +1,6 @@
 <img src="https://pag.io/img/readme/logo.png" alt="PAG Logo" width="474"/>
 
-[官网](https://pag.io) | [English](./README.md) | 简体中文 | [Weblite版本](./web/lite) | [小程序版本](./web/wechat) | [小程序lite版本](./web/lite/wechat)
+[官网](https://pag.io) | [English](./README.md) | 简体中文 | [Weblite版本](./lite/README.md) | [小程序版本](./wechat/README.md) | [小程序lite版本](./lite/wechat/README.md)
 
 ## 介绍
 
@@ -91,6 +91,99 @@ Demo 项目提 [pag-web](https://github.com/libpag/pag-web) 供了简单的接
 
 更多的 API 接口可以阅读 [API 文档](https://pag.io/api.html#/apis/web/)。
 
+`上述步骤接入的是 libpag 单线程版本，若要接入多线程版本请参考如下接入指南。`
+
+## 多线程接入指南
+
+### 多线程支持基础
+
+[WebAssembly 多线程](https://emscripten.org/docs/porting/pthreads.html) 依赖于浏览器对 [SharedArrayBuffer](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) 的支持。通过 `SharedArrayBuffer` 和 `Web Worker` ，多线程 Wasm 模块可以实现并行计算以提升性能。
+
+- **主要机制**：
+    - Wasm 线程使用共享内存 `SharedArrayBuffer` 实现数据同步与通信。
+    - 利用 `Web Worker` 作为执行上下文，加载同一个 wasm 模块的多个线程实例。
+
+- **使用条件**：
+    - Wasm 编译时需启用 `threads` 等相关编译特性（例如 Emscripten 的 `-pthread` 支持）。
+    - 运行环境须支持 `SharedArrayBuffer` 和 `Web Worker`。
+
+### 跨域安全性要求
+
+为了防范侧信道攻击，现代浏览器对启用 [SharedArrayBuffer](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) 施加了严格的环境限制。开启 Wasm 多线程必须满足 **跨域隔离（Cross-Origin Isolation）** 条件。
+#### 必须配置的响应头
+
+为启用跨域隔离，服务端必须为所有相关资源（html、wasm、js等）设置以下 HTTP 响应头：
+
+| 头部名称                      | 示例值                | 作用说明                             |
+|----------------------------|---------------------|----------------------------------|
+| `Cross-Origin-Opener-Policy` (COOP)   | `same-origin`          | 将当前上下文与跨域文档隔离          |
+| `Cross-Origin-Embedder-Policy` (COEP) | `require-corp`         | 限制嵌入当前页面的资源必须遵守 CORP 或 CORS 策略 |
+
+详细信息见 [SharedArrayBuffer文档](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer)。
+
+#### 注意事项
+
+- **必须通过 HTTPS（或 localhost）访问页面和相关资源**
+  浏览器仅在 [安全上下文](https://developer.mozilla.org/zh-CN/docs/Web/Security/Secure_Contexts) 中启用跨域隔离和 SharedArrayBuffer，多线程功能依赖此安全环境。
+- HTTP 协议下不允许启用跨域隔离，多线程支持将被禁用
+
+### Browser（推荐）
+
+接入多线程的 Web 端代码与单线程相同，但服务端要符合上述接入要求，否则多线程会加载失败。
+
+#### 注意事项
+- **禁止直接从公共 CDN（如 npm CDN）跨域加载 wasm 资源**
+  大多数公共 npm CDN（如 unpkg、jsDelivr 等）不会为静态资源默认设置 COOP/COEP 相关头，也不会对所有请求启用跨源隔离。
+  因此，将 wasm/js 上传至此类 CDN 并通过跨域方式加载时，浏览器不会开启共享内存，多线程功能将被禁用。建议将 wasm/js 与页面文件部署至同源服务器，避免出现跨域加载导致多线程失效的问题。
+- 多线程 wasm/js 不会发布至 npm 官网，可从 [release](https://github.com/Tencent/libpag/releases) 下载 web 端压缩包后自行部署使用。
+
+### 本地编译
+
+```bash
+# ./web
+$ npm run build:mt
+```
+
+这将会在 `web/lib-mt` 目录中生成 wasm/js，接下来，您可以通过运行以下命令启动一个 HTTP 服务器运行本地 demo
+
+```bash
+# ./web
+$ npm run server:mt
+```
+
+Chrome 浏览器打开 `http://localhost:8081/index.html` 即可看到效果
+
+可根据如下步骤编译 debug 版本
+
+```bash
+# ./web
+$ npm run build:debug:mt
+$ npm run server:mt
+```
+
+>**⚠️** 在多线程版本中，如果修改了编译输出文件 libpag.min.js 的文件名，需要在 libpag.min.js 文件内搜索关键字 "libpag.min.js" ，并将所有出现的 "libpag.min.js" 替换为新的文件名。  
+>否则程序将无法运行。以下是修改示例：
+
+修改前
+
+```js
+    // 文件名: libpag.min.js
+    var worker = new Worker(new URL("libpag.min.js", import.meta.url), {
+     type: "module",
+     name: "em-pthread"
+    });
+```
+
+修改后
+
+```js
+    // 文件名: libpag.min.test.js
+    var worker = new Worker(new URL("libpag.min.test.js", import.meta.url), {
+     type: "module",
+     name: "em-pthread"
+    });
+```
+
 ## 浏览器兼容性
 
 | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Chrome | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Safari | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Chrome for Android | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Safari on iOS | QQ Browser Mobile |
@@ -158,49 +251,52 @@ PAG 默认会对 Canvas 在屏幕中的可视尺寸进行缩放计算后进行
 
 ## 参与开发
 
+> 本节介绍的是 libpag 单线程版本的开发、测试流程
+
 ### 前置工作
 
 需要确保已经可编译 C++ libpag 库，并且安装 [Emscripten 套件](https://emscripten.org/docs/getting_started/downloads.html) 和 Node 依赖
 
 ```bash
 # 安装Node依赖
+# ./web
 $ npm install
 ```
 
 ### 开发流程
 
-执行 `build.sh debug` 来获得 `libpag.wasm` 文件
+执行如下命令编译 wasm/js
 
 ```bash
-# ./web 目录下
-$ npm run build:debug
+# ./web
+$ npm run build:debug:st
 ```
 
+这将会在 `web/lib` 目录中生成 wasm/js
+
 开启 Typescript 自动编译(可选)，修改 Typescript 文件会自动打包到 Javascript 文件
 
 ```bash
-# web目录下
-$ npm run dev
+# ./web
+$ npm run dev:st
 ```
 
 启动 HTTP 服务
 
 ```bash
-# web目录下
-$ npm run server
+# ./web
+$ npm run server:st
 ```
 
-Chrome 浏览器打开 `http://localhost:8081/demo/index.html` 即可看到效果
+Chrome 浏览器打开 `http://localhost:8081/index-st.html` 即可看到效果
 
 需要断点调试时，可以安装 [C/C++ DevTools Support (DWARF)](https://chrome.google.com/webstore/detail/cc%20%20-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb)，并打开 Chrome DevTools > 设置 > 实验 > 勾选「WebAssembly Debugging: Enable DWARF support」选项启用 SourceMap 支持。现在就可以在 Chrome DevTools 中对 C++ 文件进行断点调试了。
 
 ### 生产流程
 
-执行 `build.sh` 脚本
-
 ```bash
-# ./web 目录下
-$ npm run build
+# ./web
+$ npm run build:st
 ```
 
 ### CLion 编译
@@ -216,17 +312,20 @@ $ npm run build
 打包生产版本
 
 ```bash
-$ npm run build
+# ./web
+$ npm run build:st
 ```
 
 启动测试 HTTP 服务
 
 ```bash
-$ npm run server
+# ./web
+$ npm run server:st
 ```
 
 启动 cypress 测试
 
 ```bash
+# ./web
 $ npm run test
 ```