three-platformize
A project to make THREE a platform
Subsequent maintenance will continue on platformize
- Currently adapted to WeChat, Taobao, and Byte mini programs
- Support tree shaking (requires webpack, rollup and other build tools)
- VSCode types are normal and the definitions of each class can be accessed normally.
- Adapt to examples/jsm/**/*.js, type is normal
- Can upgrade, downgrade version or use custom THREE
- WeChat mini program IOS memory optimization, fewer crashes caused by page switching
- Supports customized new platform adaptation, just refer to WechatPlatform to write the adapter
- three-platformize-plugin-wechat supports cross-plugin reuse of WeChat plug-ins
Special Sponsors
Yuntu 3D-Online 3D CAD design software | Auburn Future-a pioneer in the field of AR/VR |
|
Adaptation situation
| WeChat | Taobao | byte |
---|
Mini program real machine | ✔️ | ✔️ | ✔️ |
Mini program simulator | ✔️ | ✔️ | |
Mini game real machine | ✔️ | | |
Mini game simulator | ✔️ | | |
Auburn is recruiting front-end, WebGL, and graphics algorithms in the future. You are welcome to submit your resume.
DEMO
Note: When running DEMO, remember to turn on debugging mode, cancel domain name verification, and use the latest version of WeChat development tools to open it
Demo of specific Loader usage is in this repository under three-platformize-demo
WeChat Mini Program DEMO WeChat mini program basic version DEMO WeChat mini game DEMO | Taobao Mini Program DEMO | Byte applet DEMO |
---|
| | |
Tested module
Features
- VSMShadow (r131 and previous versions are OK, see Loop index cannot be compared with non-constant expression)
Loader
- GLTFLoader (supports textured GLB) && (EXT_meshopt_compression, WASM is available for Android, ASM version is available for ios, see tools) && (KHR_mesh_quantization, available for small programs) [Mesh Compression Evaluation] MeshQuan, MeshOpt, Draco (WebAssembly API is no longer available after WeChat 8.0 To use it, you need to use WXWebAssembly, and only supports wasm in the package. Meshopt_decoder.wasm.module has been added, see usage)
- TextureLoader
- RGBELoader & PMREMGenerator (some models of the mini program may occasionally generate envMap errors, which can be avoided with HDRPrefilter)
- SVGLoader
- OBJLoader
- EXRLoader (needs to support OES_texture_float_linear extension, some mobile GPUs do not support it)
- MTLLoader (the applet can use JPG texture)
- DDSLoader (needs to support WEBGL_compressed_texture_s3tc extension, not supported by mobile GPU)
- LWOLoader (needs to support EXT_blend_minmax extension, half of the effects of the mini program are drawn incorrectly)
- FBXLoader
- BVHLoader
- ColladaLoader (DOMParser querySelector not adapted)
- TTFLoader
- STLLoader
- PDBLoader
- TGALoader (use DataTextureLoader instead PR merged, r127 available)
- VTKLoader
Controls
- OrbitControls & MapControls
- DeviceOrientationControls (onDeviceMotionChange under WeChat and Taobao mini programs, the quality of data returned under Android is extremely low and basically unusable. The community bug feedback has been for more than 3 years, and the official has no intention to fix it)
Modules not supported
- ImageBitmapLoader (WeChat applet does not open ImageBitmap)
Tools
- dispose-three (destroy node
- flip (screenshot requires flipY
- screenshot
- worker-pool.module (not yet adapted to WeChat applet
- zstddec.worker.module (not yet adapted to WeChat applet
- zstddec.module (not yet adapted to WeChat applet
- toEnvMap (for hdr prefilter
- meshopt_decoder.asm.module (available in WeChat applet
- meshopt_decoder.wasm.module (available in WeChat applet
Extensions
- GLTFGPUCompressedTexture (an alternative to BasisTextureLoader) The generation tool is obtained through gltf-gpu-compressed-texture (not yet adapted to the WeChat applet
use
import * as THREE from 'three-platformize' ;
import WechatPlatform from 'three-platformize/src/WechatPlatform' ;
const platform = new WechatPlatform ( canvas ) ; // webgl canvas
platform . enableDeviceOrientation ( 'game' ) ; // 开启DeviceOrientation
THREE . PLATFORM . set ( platform ) ;
// 使用完毕后释放资源
THREE . PLATFORM . dispose ( ) ;
// 正常使用three即可
// DEMO 代码示例见 https://github.com/deepkolos/three-platformize-demo
// 基础的使用DEMO见 https://github.com/deepkolos/three-platformize-demo-wechat-simple
// 生产环境时rollup.config.js里请开启teser压缩, 即plugins末尾增加 terser({ output: { comments: false } })
experience
- WeChat applet does not support texture images above 2048
- There is a problem with the Taobao applet displaying RGB format textures (JPG). After loading the texture through TextureLoader, set texture.format to RGBAFromat (Taobao version 9.20.0). The reason may be that the server optimizes large images and compresses the images. Causes the format to change from RGB to RGBA
- r126 cannot set full pixelRatio, it can be set to half, or 2, not 3
- Although it supports loading GLB, the image is converted to base64 using the js version of ArrayBuffer, which is time-consuming and takes up memory. Although it can be alleviated by wasm's encoder (https://github.com/marcosc90/encoding-wasm), wasm does not process strings. The performance is not as good as js, tested with wasm compiled with AssemblyScript
- The crash of IOS before and after entering and exiting the page can reduce the pixelRatio and alleviate it
- IOS WeChat readPixels does not support anti-aliasing. If the buffer of the direct canvas needs to turn off anti-aliasing (antialias: false), another method is WebglRenderTarget. Anti-aliasing can also be turned on, but the texture size is limited (texture width/height under Xiaomi 8 It cannot exceed 4096, you need to pay attention to setSize first, then setPixelRatio) (for screenshot Demo, see WeChat applet DEMO)
- Taobao mini program has strict domain name verification and can use cloud storage to store models. However, if the model and texture are separated, manual association is required. GLB is recommended.
- URL polyfill can use fileSystemManager to obtain temporary files to avoid converting arraybuffer to base64, but it requires manual management of temporary files.
- Some students in the QQ group reported that the model file path on the iOS Taobao applet does not support Chinese.
accomplish
Replace platform-specific api calls at build time, forward references to PLATFORM, and update via PLATFORM.set
maintain
How to update/downgrade the version of Three?
# 拉取源码
> git clone https://github.com/deepkolos/three-platformize
# 安装依赖
> npm i
# 更新到最新的three版本
> npm i -S three@latest
# 或者指定three版本
> npm i -S [email protected]
# 需要把目标three的构建`utils/build/rollup.config.js`同步到本项目的构建`config/rollup.config.three-origin.js`
# 建立软链接
> npm run link
# 构建
> npm run build
# 使用
> npm link
# 到使用的项目目录,并链接
> cd your-project
> npm link three-platformize
# 或者自行发NPM包
How to platform customized Three?
# 把自定义Three link 到./three
> npx symlink-dir yourthree ./three
# 不使用软链接直接复制或者git submodule也可以
> cp yourthree ./three
# 复制对应版本three构建配置替换到rollup.config.three-origin.js
> cp yourthree/utils/build/rollup.config.js ./config/rollup.config.three-origin.js
# 构建
> npm run build
How to write a custom platform?
Please refer to src/WechatPlatform
or src/TaobaoPlatform
class CustomPlatform {
getGlobals ( ) {
// 自定义的polyfill
return {
atob ,
Blob ,
window ,
document ,
XMLHttpRequest ,
OffscreenCanvas ,
HTMLCanvasElement ,
createImageBitmap ,
} ;
}
setWebGLExtensions ( ) {
return {
// 可覆盖gl返回值,比如淘宝小程序IOS返回值不为null,但是扩展不可用的bug
EXT_blend_minmax : null ,
} ;
}
dispose ( ) {
// 释放资源
}
}
TODO
- Dispose more thoroughly, reduce memory leaks, Web test cases have been added, WeChat applet has been added, IOS still has memory problems, the page will still crash after switching multiple times, the 3MB model iPhone7 is opened 30 times
- Adapt to Toutiao applet done
- Generate WeChat plug-ins, and realize three's code reuse across mini programs and cross mini program plug-ins through plug-ins done three-platformize-plugin-wechat
- Adapt to WeChat mini-game done
- Adapt to ReactNative
discuss
You can contact me through the group DeepKolos
CHANGELOG
sponsor
If the project is helpful to you or has adaptation needs, please feel free to tip.
Thank you for your support~~
time | Boss |
---|
2021/11/10 | god god |
2021/09/27 | Abu |
2021/08/10 | Auburn Future |
2021/07/28 | Noth1ng |
2021/07/09 | anonymous |
2021/07/07 | Cloud CAD-Liu Xin |
2021/06/23 | Fong |
2021/06/23 | Liu Ziqi |
2021/06/23 | Joson |
2021/06/03 | Bionic Voltaire |
2021/04/28 | Noth1ng |