mirror of
https://github.com/smallmain/cocos-enhance-kit.git
synced 2025-09-24 21:39:00 +00:00
完善 docs
This commit is contained in:
SmallMain
@@ -23,7 +23,7 @@ description: "推荐使用此方式进行一键安装。"
|
||||
|
||||
这个引擎扩展只会为你提供自动化的安装方式，即使以后也只会添加版本管理方面的功能。
|
||||
|
||||
你可以选择 [手动安装](./installation-manual) 服务包，只需要几分钟即可完成。
|
||||
你可以选择 [手动安装](./installation-manual.md) 服务包，只需要几分钟即可完成。
|
||||
|
||||
:::
|
||||
|
||||
@@ -56,7 +56,7 @@ description: "推荐使用此方式进行一键安装。"
|
||||
|
||||
|
||||
|
||||
接下来推荐你从 [入门教程](../start-guide/start-guide-intro) 开始了解服务包为你的开发都带来了哪些新特性！
|
||||
接下来推荐你从 [入门教程](../start-guide/start-guide-intro.mdx) 开始了解服务包为你的开发都带来了哪些新特性！
|
||||
|
||||
---
|
||||
## 支持的引擎版本
|
||||
|
||||
@@ -7,7 +7,7 @@ description: "需掌握一定的自定义引擎知识。"
|
||||
|
||||
## Service Pack v1.0.0
|
||||
|
||||
适配 Cocos Creator v2.4.9 版本，[点此下载服务包](http://www.baidu.com)
|
||||
适配 Cocos Creator v2.4.9 版本，[点此下载服务包](TODO)
|
||||
|
||||
---
|
||||
## 标准安装
|
||||
@@ -21,7 +21,7 @@ description: "需掌握一定的自定义引擎知识。"
|
||||
|
||||
建议升级到最新的引擎版本，官方只会对 2.x 版本只会进行维护性更新，所以不用担心其稳定性问题。
|
||||
|
||||
如果你的项目引擎版本较低，可以看一看 [使用引擎扩展安装](./installation-engine-plugin) ，支持对多个引擎版本进行一键安装。
|
||||
如果你的项目引擎版本较低，可以看一看 [使用引擎扩展安装](./installation-engine-plugin.md) ，支持对多个引擎版本进行一键安装。
|
||||
|
||||
:::
|
||||
|
||||
@@ -84,7 +84,7 @@ description: "需掌握一定的自定义引擎知识。"
|
||||
|
||||
|
||||
|
||||
接下来推荐你从 [入门教程](../start-guide/start-guide-intro) 开始了解服务包为你的开发都带来了哪些新特性！
|
||||
接下来推荐你从 [入门教程](../start-guide/start-guide-intro.mdx) 开始了解服务包为你的开发都带来了哪些新特性！
|
||||
|
||||
---
|
||||
## 补丁安装
|
||||
|
||||
@@ -49,7 +49,7 @@ TODO
|
||||
- 通过我们发布的引擎扩展一键安装
|
||||
- 下载源码包，使用里面的 Git Patch 文件进行安装
|
||||
|
||||
具体教程可以参考 [安装指南](./installation-guide/installation-intro)。
|
||||
具体教程可以参考 [安装指南](./installation-guide/installation-intro.mdx)。
|
||||
|
||||
## 更新日志
|
||||
|
||||
@@ -66,7 +66,7 @@ TODO
|
||||
- [修复] CHAR 缓存模式 hash 计算可能会有重复的问题
|
||||
- [调整] 默认禁用 Label 原生 TTF 渲染器
|
||||
|
||||
所有更新日志请移步 [此处](./update-log)。
|
||||
所有更新日志请移步 [此处](./update-log.md)。
|
||||
|
||||
## 贡献指南
|
||||
|
||||
|
||||
@@ -71,7 +71,7 @@ description: "在游戏开发中享受不用关注 Draw Call 的快乐。"
|
||||
|
||||
### 放宽能参与合图的纹理尺寸限制
|
||||
|
||||
**动态图集会自动进行多纹理合批，你可以放心地使用多达 8 张图集而不用担心交叉渲染导致的打断批次！**
|
||||
**动态图集会自动进行多纹理合批，你可以放心地使用多达 7 张图集而不用担心交叉渲染导致的打断批次！**
|
||||
|
||||
有了这个新特性，你可以根据项目的具体情况来放宽能参与合图的纹理尺寸限制。
|
||||
|
||||
@@ -97,7 +97,7 @@ cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048
|
||||
|
||||
**还可以控制组件是否默认参与动态合图，也可以控制单个组件是否参与动态合图。**
|
||||
|
||||
可前往 [动态合图](TODO) 的文档了解详情。
|
||||
可前往 [动态合图](../user-guide/dynamic-batcher/dynamic-batcher-intro.mdx) 的文档了解详情。
|
||||
|
||||
在上面我们推荐可以将纹理尺寸限制放宽到 `2048`，这听起来貌似有点离谱，但只要规划得当确实可行，比如：
|
||||
|
||||
@@ -120,7 +120,7 @@ cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048
|
||||
|
||||
但，**服务包重构了 Char 缓存模式，除了解决不能复用的问题之外，由于支持了多纹理渲染，所以既能与动态图集合批，还有最多 8 张字体图集可以使用！**
|
||||
|
||||
### 委以重任一把梭 —— Char
|
||||
### 脱胎换骨的 Char 缓存模式
|
||||
|
||||
**如果你不知道该选择什么缓存模式，那就遇事不决，先选 Char 缓存模式。**
|
||||
|
||||
@@ -135,7 +135,7 @@ cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048
|
||||
- Char 缓存模式不支持一些字体样式，可以在官方文档中了解详情。
|
||||
- 巨大的字体大小（比如几百的）可能会瞬间占满整张字符图集，字符图集虽然有 8 张但也不能这么霍霍。
|
||||
|
||||
### 最后的合批守护者 —— Bitmap
|
||||
### 兜底的 Bitmap 缓存模式
|
||||
|
||||
即使不能选择 Char 缓存模式，Bitmap 缓存模式也能成为批次的最后一道防线。
|
||||
|
||||
@@ -152,24 +152,13 @@ cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048
|
||||
|
||||
:::
|
||||
|
||||
### 关于字符图集与动态图集
|
||||
### 注意事项
|
||||
|
||||
**1.Char 缓存模式所使用的字符图集与动态图集并不是一个东西**
|
||||
- **Char 缓存模式所使用的字符图集与动态图集不是一个东西**
|
||||
|
||||
有多种因素导致没有让 Char 缓存模式直接使用动态图集，在 Char 缓存模式的原理文档中有详细解释。
|
||||
有多种因素导致没有让 Char 缓存模式直接使用动态图集来实现，这个原因在 Char 缓存模式的原理文档中有详细解释。
|
||||
|
||||
多纹理材质只有 8 个纹理插槽，所以默认情况下动态图集最大数量为 7，字符图集自动多纹理合批的数量为 1（注意，这个不是指字符图集的最大数量，字符图集的最大数量是 8 张，并且不能调整）。
|
||||
|
||||
你可以自己调整这个分配值，比如 6 张动态图集，字符图集自动合批 2 张，保持数量加起来不超过 8 张，也就能保持 1 Draw Call。
|
||||
|
||||
而服务包使用这个 “7 + 1” 的默认值有以下几点原因：
|
||||
|
||||
- 引擎原本就只有 1 张 Char 字符图集
|
||||
- 大多数项目因为 Char 缓存模式加入了可复用的特性后，1 张 Char 字符图集是足够的
|
||||
|
||||
建议你合理搭配使用 Bitmap 和 Char 两种缓存模式后再进行实际测试，发现 Char 字符图集 1 张是真的不够再对其做调整。
|
||||
|
||||
**2.Char 缓存模式依然不能在图集用完的情况下正常渲染**
|
||||
- **Char 缓存模式依然不能在图集用完的情况下正常渲染**
|
||||
|
||||
原因有以下几点：
|
||||
|
||||
@@ -185,4 +174,4 @@ cc.dynamicAtlasManager.maxFrameSize = 1024; // 推荐 512、1024 甚至 2048
|
||||
- 优先使用 Char 缓存模式，不适合则使用 Bitmap 缓存模式，都不适合则采用老方法
|
||||
- 不要优先考虑修改节点顺序这种需要维护成本的优化方式
|
||||
|
||||
如果你对批次合并还有着更高的需求，可以阅读 [进阶合批指南](./advance-batcher-guide)。
|
||||
如果你对批次合并还有着更高的需求，可以阅读 [进阶合批指南](./advance-batcher-guide.md)。
|
||||
|
||||
@@ -37,11 +37,11 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false;
|
||||
|
||||
这不意味着你不能手动调整了，而是建议你阅读新动态图集和新 Char 缓存模式相关的文档后再考虑是否有必要进行调整。
|
||||
|
||||
关于这个你可以从 [新 UI 渲染批次合并指南](./batcher-guide) 进行了解。
|
||||
关于这个你可以从 [新 UI 渲染批次合并指南](./batcher-guide.md) 进行了解。
|
||||
|
||||
- **动态图集重复纹理的判断从 `texture._id` 改为使用 `texture._uuid`**
|
||||
|
||||
具体的设计原因和原理可前往 [动态合图](TODO) 文档进行了解。
|
||||
具体的设计原因和原理可查看动态合图的原理文档。
|
||||
|
||||
- **`cc.dynamicAtlasManager.insertSpriteFrame(spriteFrame)` 不再检查纹理的 `packable` 属性**
|
||||
|
||||
@@ -49,9 +49,17 @@ cc.macro.ENABLE_NATIVE_TTF_RENDERER = false;
|
||||
|
||||
- **如果你的项目依赖动态图集的内部实现细节，请重新检查相关代码**
|
||||
|
||||
这个就是因为动态图集被重构了，如果你的项目依赖一些未公开的类或者接口（引擎在 `creator.d.ts` 声明了的则是已经公开的），则可能需要重新编写。
|
||||
比如你的项目依赖一些动态图集未公开的类或者接口（引擎在 `creator.d.ts` 声明了的则是已经公开的），则可能需要重新编写。
|
||||
|
||||
---
|
||||
### 使用 Char 缓存模式的 Label 暂不支持在编辑器中设置材质
|
||||
### Char 缓存模式的一些变化
|
||||
|
||||
如果项目中有 Label 使用了 Char 缓存模式并且设置了自定义材质，可能会失效，具体原因可前往 [Char 缓存模式](TODO) 文档进行了解。
|
||||
对 Char 缓存模式也进行了重构，内部变化比较大。
|
||||
|
||||
- **暂不支持自定义材质**
|
||||
|
||||
如果项目中有组件在使用 Char 缓存模式并且设置了自定义材质则可能会失效，具体原因可前往 [新的 Char 缓存模式](../user-guide/text-render/text-char-mode.md) 文档进行了解。
|
||||
|
||||
- **如果你的项目依赖 Char 缓存模式的内部实现细节，请重新检查相关代码**
|
||||
|
||||
比如你的项目依赖一些 Char 缓存模式未公开的类或者接口（引擎在 `creator.d.ts` 声明了的则是已经公开的），则可能需要重新编写。
|
||||
|
||||
@@ -12,21 +12,19 @@ description: "了解并上手服务包提供的所有其他新特性。"
|
||||
|
||||
以前我们会使用将 Label 字号放大一倍，Label 节点缩小一倍的方式去解决字体模糊的问题。
|
||||
|
||||
而现在不需要了，高 DPI 文本渲染默认是关闭的，你可以通过
|
||||
而现在不需要了，你可以通过一句代码调整渲染比例：
|
||||
|
||||
```js
|
||||
cc.sp.labelRetinaScale = 2; // 渲染文本时纹理的缩放倍数，默认值为 1.
|
||||
```
|
||||
|
||||
来开启高 DPI 文本渲染。
|
||||
|
||||
|
||||
|
||||
> 图片中，上方的是开启后效果，下面是未开启效果。
|
||||
|
||||
**推荐你根据设备像素比（devicePixelRatio）来动态设置该值，并且该值不要大于 `2`，这不会带来更好的效果，但却将字体纹理放大了数倍，会影响到游戏整体性能，影响动态图集的效率。**
|
||||
|
||||
可前往 [高 DPI 支持](TODO) 文档了解更多详情。
|
||||
可前往 [高 DPI 支持](../user-guide/text-render/text-high-dpi.md) 文档了解更多详情。
|
||||
|
||||
---
|
||||
## 使用 SpriteFrame 进行 Spine 换装
|
||||
@@ -45,7 +43,7 @@ this.skel.setRegion('head', 'head', sp.SkeletonData.createRegion(spriteFrame));
|
||||
|
||||
> 图片中是被换头的小男孩。
|
||||
|
||||
这样做是直接替换了 SkeletonData 中的数据，一般情况下所有使用该数据的 Spine 组件都会受到影响，但我们提供了克隆 SkeletonData 数据的接口，可前往 [Spine](TODO) 文档了解更多详情。
|
||||
这样做是直接替换了 SkeletonData 中的数据，一般情况下所有使用该数据的 Spine 组件都会受到影响，但我们提供了克隆 SkeletonData 数据的接口，可前往 [Spine](../user-guide/spine/spine-intro.mdx) 文档了解更多详情。
|
||||
|
||||
:::tip 提示
|
||||
|
||||
@@ -58,4 +56,4 @@ this.skel.setRegion('head', 'head', sp.SkeletonData.createRegion(spriteFrame));
|
||||
|
||||
这可能是很少用得到的功能，虽然加上去也简单，但主要还是我们看到几乎所有渲染组件可以自定义材质，这个组件却不可以。
|
||||
|
||||
可前往 [RichText](TODO) 了解更多详情。
|
||||
可前往 [RichText 自定义材质](../user-guide/text-render/text-richtext.md) 文档了解更多详情。
|
||||
|
||||
@@ -6,7 +6,7 @@ sidebar_position: 6
|
||||
|
||||
虽然服务包没有对项目有侵入性修改，但这种操作还是有风险的，毕竟这就像要将引擎降级一样。
|
||||
|
||||
所以我们提供两种卸载方式仅供参考：
|
||||
所以我们提供两种卸载方式以供参考：
|
||||
|
||||
:::tip 提示
|
||||
|
||||
@@ -17,7 +17,7 @@ sidebar_position: 6
|
||||
---
|
||||
## 使用引擎扩展卸载
|
||||
|
||||
请参考 [手动卸载](#手动卸载) 中提到的 **解除代码与资源依赖**，确保项目不再依赖任何服务包的特性之后，点击服务包管理界面的 **卸载服务包** 按钮，会自动帮你恢复自定义引擎，将引擎内的 `jsb-adapter` 替换为原版备份，并删除 `creator-sp.d.ts` 文件。
|
||||
请参考 [手动卸载](#手动卸载) 中提到的 **解除代码依赖与资源依赖**，确保项目不再依赖任何服务包的特性之后，点击服务包管理界面的 **卸载服务包** 按钮，会自动帮你恢复自定义引擎，将引擎内的 `jsb-adapter` 替换为原版备份，并删除 `creator-sp.d.ts` 文件。
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ sidebar_position: 7
|
||||
---
|
||||
## Service Pack v1.0.0
|
||||
|
||||
适配 Cocos Creator v2.4.9 版本，[点此下载服务包](http://www.baidu.com)
|
||||
适配 Cocos Creator v2.4.9 版本，[点此下载服务包](TODO)
|
||||
|
||||
- **[新特性] 支持多纹理渲染**
|
||||
- **[新特性] 重构动态图集，支持多个新特性**
|
||||
|
||||
BIN
docs/docs/user-guide/dynamic-batcher/assets/7.png
Normal file
BIN
docs/docs/user-guide/dynamic-batcher/assets/7.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 9.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 90 KiB |
@@ -0,0 +1,99 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
description: "了解调校动态合图的方式。"
|
||||
---
|
||||
# 调整合图设置
|
||||
|
||||
---
|
||||
## 动态图集最大数量为什么是 7
|
||||
|
||||
在前面的文档中有提到动态图集的最大数量默认为 **设备能同时采样纹理数 - Char 缓存模式自动合批图集数**。
|
||||
|
||||
因为设备能同时采样纹理数固定为 `8`，而 Char 缓存模式自动合批图集数默认为 `1`，所以动态合图的最大数量默认值为 `7`。
|
||||
|
||||
这样就只需要使用 1 个材质，也就是能在 1 Draw Call 里完成所有参与动态合图的纹理（包括 Bitmap 缓存模式 Label）与 Char 缓存模式 Label 的渲染。
|
||||
|
||||
一般情况下不推荐直接修改 `maxAtlasCount`，请参考 [新的 Char 缓存模式](../text-render/text-char-mode.md#与动态图集合批的注意事项) 文档。
|
||||
|
||||
> 难道真正的原因是...
|
||||
>
|
||||
> 
|
||||
|
||||
---
|
||||
## 控制纹理是否参与动态合图
|
||||
|
||||
可以在编辑器上调整纹理的 `packable` 属性，或者用代码控制：
|
||||
|
||||
```js
|
||||
texture.packable = false;
|
||||
```
|
||||
|
||||
---
|
||||
## 控制组件是否参与动态合图
|
||||
|
||||
使用下面的代码控制组件是否默认激活动态合图机制，默认为开启：
|
||||
|
||||
```js
|
||||
cc.sp.allowDynamicAtlas = false;
|
||||
```
|
||||
|
||||
也可以控制单组件是否激活动态合图机制：
|
||||
|
||||
|
||||
|
||||
除了在编辑器调整，也可以通过代码控制：
|
||||
|
||||
```js
|
||||
// cc.RenderComponent.EnableType
|
||||
// GLOBAL: 全局默认值
|
||||
// ENABLE: 开启
|
||||
// DISABLE: 关闭
|
||||
label.allowDynamicAtlas = cc.RenderComponent.EnableType.ENABLE;
|
||||
```
|
||||
|
||||
如果一个纹理参与动态合图但是组件不参与，那么使用该组件进行渲染时就不会参与，但如果同时在其它参与的组件上渲染，那么依然会被打入动态图集。
|
||||
|
||||
:::caution 注意
|
||||
|
||||
组件有脏检查标记，修改后可能需要对渲染组件调用 `comp.setVertsDirty()` 才会生效。
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
## 是否自动多纹理合批
|
||||
|
||||
控制图集纹理是否会自动添加到多纹理合批管理器，默认为开启状态，如果关闭也就意味着**失去了自动进行多个图集纹理合批的特性**。
|
||||
|
||||
```js
|
||||
cc.dynamicAtlasManager.autoMultiBatch = false;
|
||||
```
|
||||
|
||||
---
|
||||
## 在场景切换时清空所有图集
|
||||
|
||||
控制在场景切换时是否会清空所有的动态图集，默认为开启状态。
|
||||
|
||||
```js
|
||||
cc.dynamicAtlasManager.autoResetBeforeSceneLoad = false;
|
||||
```
|
||||
|
||||
:::tip 提示
|
||||
|
||||
在引擎原来的设计中，该机制不可被关闭，由于旧动态合图不支持复用废弃的空间，图集终究会被用完，所以引擎加入了这个治标不治本的功能。
|
||||
|
||||
但现在，我们认为该机制可以关闭，你只需要管理好纹理资源的释放即可，因为纹理资源释放的同时会释放使用的动态图集空间。
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
## 不进行复用的区域空间大小
|
||||
|
||||
在实际的测试中，我们发现废弃空间出现碎片化的现象，比如尺寸 5 * 2 这样的非常小的废弃空间，当碎图尝试加入图集的时候会在这些废弃空间中寻找，这些数量多的小废弃空间无法被复用，却要在每次加入时遍历判断一次。
|
||||
|
||||
所以我们加入了 `ignoreRectSize` 设置，当废弃空间尺寸小于这个值就不会被遍历到（但是能合并为大的废弃空间时还是会合并），这能提升大约 50% 的理论性能。
|
||||
|
||||
这个值默认为 `10`，如果你的项目有很多小于 10 * 10 的纹理，可以考虑进行调整：
|
||||
|
||||
```js
|
||||
cc.dynamicAtlasManager.Atlas.ignoreRectSize = 2;
|
||||
```
|
||||
@@ -3,19 +3,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
# 动态合图
|
||||
|
||||
我们基本重构了动态合图系统，在原有的功能基础上，增加了以下重要特性：
|
||||
动态合图是一个非常好的合批手段，但是在之前引擎实现的比较简陋，所以服务包重构了动态合图系统，在原有功能基础上增加了许多重要特性。
|
||||
|
||||
- **完全开放所有接口**，以方便如果你想手动规划或控制动态图集
|
||||
- **增加默认是否参与动态合图的全局设置，并支持设置单个组件是否参与动态合图**
|
||||
- **支持自动加入多纹理合批**
|
||||
- **优化图集装箱算法**（使用 Guillotine）
|
||||
- **支持复用废弃的空间**
|
||||
- **所有图集作为一个整体进行管理**（不再出现纹理被加入到两张图集的情况）
|
||||
|
||||
:::tip 提示
|
||||
|
||||
你可以阅读官方文档来了解怎么使用 [动态合图](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/dynamic-atlas.html)，由于动态合图的使用本来就是自动的，所以如果没有特殊需求则**不需要阅读后面的内容**。
|
||||
|
||||
:::
|
||||
比如支持复用废弃碎图空间，优化了图集装箱算法，所有图集作为一个整体进行管理等等，你可以阅读下面的文档了解详情：
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
|
||||
@@ -5,22 +5,55 @@ description: "随心所欲地控制动态合图的使用。"
|
||||
|
||||
# 手动管理合图
|
||||
|
||||
我们在保留原来所有接口的基础上重构了动态合图，除了通过 `maxFrameSize` `insertSpriteFrame` 等原有的接口来手动管理合图之外，还新增了以下方法：
|
||||
有时候你可能需要更细致地去控制哪些纹理加入动态图集，考虑到这一点，服务包在保留原来所有接口的基础上完全开放了动态图集相关的所有接口。
|
||||
|
||||
## 控制图集
|
||||
---
|
||||
## 访问图集数组与已用空间集合
|
||||
|
||||
### 添加 SpriteFrame
|
||||
你可以通过
|
||||
|
||||
你可以通过该接口添加 SpriteFrame 的 Texture 到图集中，内部也是使用该接口。
|
||||
```js
|
||||
cc.dynamicAtlasManager.atlases
|
||||
```
|
||||
|
||||
和
|
||||
|
||||
```js
|
||||
cc.dynamicAtlasManager.rects
|
||||
```
|
||||
|
||||
分别访问到图集数组与所有图集的已用空间集合。
|
||||
|
||||
---
|
||||
## 添加 SpriteFrame 到动态图集
|
||||
|
||||
```js
|
||||
cc.dynamicAtlasManager.insertSpriteFrame(spriteFrame);
|
||||
```
|
||||
|
||||
### 删除 SpriteFrame
|
||||
可以将 SpriteFrame 所使用的纹理添加到动态图集，这是引擎原有接口，但服务包对其做了一点修改，这个接口不再会检查纹理的 `packable` 属性，也就是变成了一个强制添加的接口。
|
||||
|
||||
`cc.dynamicAtlasManager.deleteSpriteFrame(spriteFrame)`
|
||||
这样设计的原因是你可以将所有纹理的 `packable` 都设为 `false`，或者直接将 `maxFrameSize` 设为 `0`，然后完全手动地进行动态合图。
|
||||
|
||||
### 删除 Texture
|
||||
---
|
||||
## 从动态图集删除 SpriteFrame
|
||||
|
||||
`cc.dynamicAtlasManager.deleteTexture(texture)`
|
||||
```js
|
||||
cc.dynamicAtlasManager.deleteSpriteFrame(spriteFrame);
|
||||
```
|
||||
|
||||
可以使 SpriteFrame 取消使用动态图集纹理，这不一定会将 SpriteFrame 的纹理从动态图集删除，因为可能还会有其它 SpriteFrame 在使用，只有没有 SpriteFrame 在使用时才会删除纹理。
|
||||
|
||||
---
|
||||
## 从动态图集删除 Texture
|
||||
|
||||
```js
|
||||
cc.dynamicAtlasManager.deleteTexture(texture);
|
||||
```
|
||||
|
||||
这个接口与 `deleteSpriteFrame` 相似，但是它会直接删除纹理，并且会使使用该纹理的 SpriteFrame 全部恢复。
|
||||
|
||||
---
|
||||
## 更多接口
|
||||
|
||||
虽然还暴露了其它接口出来，但因为太过于底层所以不推荐使用，如果你想了解可以阅读原理文档。
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
description: "更细致地控制动态合图的使用。"
|
||||
---
|
||||
|
||||
# 新的合图设置
|
||||
|
||||
## 全局设置
|
||||
|
||||
### 是否参与动态合图
|
||||
|
||||
`cc.sp.allowDynamicAtlas`
|
||||
|
||||
控制所有组件默认情况下是否会参与动态合图，默认为开启状态。
|
||||
|
||||
### 自动多纹理合批
|
||||
|
||||
`cc.dynamicAtlasManager.autoMultiBatch`
|
||||
|
||||
控制图集纹理是否会自动添加到多纹理合批管理器，默认为开启状态，如果关闭也就**失去了自动进行多个图集纹理合批的特性**（当然关闭后你依然可以手动添加）。
|
||||
|
||||
### 在场景切换时清空所有图集
|
||||
|
||||
`cc.dynamicAtlasManager.autoResetBeforeSceneLoad`
|
||||
|
||||
控制在场景切换时是否会清空所有的动态图集，默认为开启状态。
|
||||
|
||||
:::tip 提示
|
||||
|
||||
在引擎原来的设计中，该机制不可被关闭，由于旧动态合图不支持复用废弃的空间，图集终究会被用完，所以引擎加入了这个治标不治本的功能。
|
||||
|
||||
但现在，我们认为该机制可以关闭，你只需要管理好纹理资源的释放即可，纹理资源释放的同时会释放使用的动态图集空间。
|
||||
|
||||
:::
|
||||
|
||||
## 组件的单独设置
|
||||
|
||||
### 是否参与动态合图
|
||||
|
||||
`cc.Component.allowDynamicAtlas`
|
||||
|
||||
控制该组件是否会参与动态合图，类型是 `cc.RenderComponent.EnableType` 枚举，默认为 `GLOBAL`。
|
||||
|
||||
:::tip cc.RenderComponent.EnableType
|
||||
|
||||
- `GLOBAL` 使用全局设置
|
||||
- `ENABLE` 开启
|
||||
- `DISABLE` 关闭
|
||||
|
||||
:::
|
||||
@@ -5,15 +5,15 @@ description: "了解如何手动进行多纹理合批。"
|
||||
|
||||
# 多纹理合批
|
||||
|
||||
在 [新 UI 渲染批次合并指南](../../start-guide/batcher-guide#充分利用动态合图) 中提到了动态合图与多纹理渲染结合后，能让多张图集纹理在同一批次渲染。
|
||||
在 [新 UI 渲染批次合并指南](../../start-guide/batcher-guide.md#充分利用动态合图) 中提到了动态合图与多纹理渲染结合后，能让多张图集纹理在同一批次渲染。
|
||||
|
||||
如果你阅读过 [多纹理材质](./multi-material) 文档的话，肯定知道能使用 `MultiHandler` 的接口来动态设置材质的纹理插槽来实现。
|
||||
如果你阅读过 [多纹理材质](./multi-material.md) 文档的话，肯定知道能使用 `MultiHandler` 的接口来动态设置材质的纹理插槽来实现。
|
||||
|
||||
但是这种完全手动的方式实现起来比较麻烦，比如你需要使用一个纹理时，还得找到该纹理所在的材质并设置到渲染组件上。
|
||||
|
||||
为了能更方便地进行多纹理合批，服务包封装了一个自动切换多纹理材质的机制与多纹理合批管理类 `cc.sp.MultiBatcher`。
|
||||
|
||||
动态图集与字符图集使用了一个全局实例，可以通过 `cc.sp.multiBatcher` 访问。
|
||||
动态图集与字符图集使用的是一个全局的多纹理合批管理器实例，可以通过 `cc.sp.multiBatcher` 访问。
|
||||
|
||||
---
|
||||
## 开关自动切换多纹理材质
|
||||
@@ -114,7 +114,7 @@ const material = batcher.requsetMaterial(texture);
|
||||
|
||||
会返回关联的材质，如果纹理本来就已经有关联的材质，则会直接返回已关联的材质。
|
||||
|
||||
清空内部数组可以使用：
|
||||
清空内部数组可以使用（这不会取消纹理的关联）：
|
||||
|
||||
```js
|
||||
batcher.reset();
|
||||
@@ -122,4 +122,4 @@ batcher.reset();
|
||||
|
||||
### 它的用途
|
||||
|
||||
在 [进阶合批指南](../../start-guide/advance-batcher-guide) 中有提供一些常见的使用案例。
|
||||
在 [进阶合批指南](../../start-guide/advance-batcher-guide.md) 中有提供一些常见的使用案例。
|
||||
|
||||
@@ -6,6 +6,8 @@ toc_max_heading_level: 5
|
||||
|
||||
# 多纹理材质
|
||||
|
||||
服务包在引擎内置了可以直接使用的多纹理 Effect 着色器资源，并且你可以直接使用多纹理材质而不需要编写任何代码。
|
||||
|
||||
---
|
||||
## 创建多纹理材质
|
||||
|
||||
|
||||
@@ -3,14 +3,19 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
# 多纹理渲染
|
||||
|
||||
多纹理渲染在 [新 UI 渲染批次合并指南](../../start-guide/batcher-guide#什么是多纹理渲染) 中有所介绍。
|
||||
:::tip 提示
|
||||
|
||||
其原理非常简单，但是为了让它能以最简单的方式在引擎中使用，所以还进行了一些封装。
|
||||
多纹理渲染属底层设施，如果你不是准备手动使用多纹理材质或者多纹理合批管理器的话，请跳过本特性文档。
|
||||
|
||||
---
|
||||
## 原生支持多纹理材质
|
||||
:::
|
||||
|
||||
:::info 提示
|
||||
多纹理渲染在 [新 UI 渲染批次合并指南](../../start-guide/batcher-guide.md#什么是多纹理渲染) 中有所介绍。
|
||||
|
||||
其原理非常简单，并且为了让它能以最简单的方式在引擎中使用，已经在内部做好了封装：
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
|
||||
:::caution 注意
|
||||
|
||||
- **支持的渲染组件**
|
||||
|
||||
@@ -23,22 +28,3 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
DragonBones 组件：因人力有限，并且这个组件与 Spine 组件可以相互代替，所以暂时不支持该组件。
|
||||
|
||||
:::
|
||||
|
||||
服务包在引擎内置了可以直接使用的多纹理 Effect 着色器资源，并且你可以直接使用多纹理材质而不需要编写任何代码。
|
||||
|
||||
具体可阅读 [多纹理材质](./multi-material) 文档。
|
||||
|
||||
---
|
||||
## 自动切换材质
|
||||
|
||||
在大部分时候，我们都不希望你需要手动去设置多纹理材质，比如当组件的纹理加入动态图集后，能自动切换为与动态图集纹理关联的多纹理材质，所以为每个组件都加入了自动切换材质的特性。
|
||||
|
||||
这个机制的实现离不开多纹理合批管理器，具体可阅读 [多纹理合批](./multi-batcher) 文档。
|
||||
|
||||
:::tip 提示
|
||||
|
||||
多纹理渲染属底层设施，如果你并不是要手动使用多纹理材质或者多纹理合批管理器，请跳过本特性文档。
|
||||
|
||||
:::
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
|
||||
BIN
docs/docs/user-guide/text-render/assets/reina-settings.png
Normal file
BIN
docs/docs/user-guide/text-render/assets/reina-settings.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 93 KiB |
BIN
docs/docs/user-guide/text-render/assets/richtext-settings.png
Normal file
BIN
docs/docs/user-guide/text-render/assets/richtext-settings.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 86 KiB |
@@ -2,7 +2,105 @@
|
||||
sidebar_position: 1
|
||||
description: "详细了解该缓存模式重构后的所有新特性。"
|
||||
---
|
||||
|
||||
# 新的 Char 缓存模式
|
||||
|
||||
TODO
|
||||
在 [新 UI 渲染批次合并指南](../../start-guide/batcher-guide.md#充分利用动态合图) 中提到 Bitmap 与 Char 缓存模式都支持了废弃字符空间复用的特性，但 Char 缓存模式的内部变化比较大，并且提供了一些可调整的设置项，使用上依旧只需要设置缓存模式即可。
|
||||
|
||||
---
|
||||
## 在场景切换时清空所有字符图集
|
||||
|
||||
控制在场景切换时是否会清空所有的字符图集，默认为开启状态。
|
||||
|
||||
```js
|
||||
cc.sp.charAtlasAutoResetBeforeSceneLoad = false;
|
||||
```
|
||||
|
||||
:::tip 提示
|
||||
|
||||
在引擎原来的设计中，该机制不可被关闭，由于旧 Char 缓存模式不支持复用废弃的空间，图集终究会被用完，所以引擎加入了这个治标不治本的功能。
|
||||
|
||||
现在推荐关闭该机制，除非你知道你需要。
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
## 字符图集的数量与内置材质
|
||||
|
||||
现在在内部最多会创建 8 张字符图集，与多纹理材质的最大纹理插槽数一致，如果合理使用缓存模式，8 张应该对所有项目都是足够的。
|
||||
|
||||
在这种情况下，可能发生的事是 Char 缓存模式的组件使用了一个普通材质，这个材质只能使用第一张字符图集进行渲染，那么就会导致其他图集上的字就无法渲染出来了。
|
||||
|
||||
为了解决这个问题，Char 缓存模式会在内部维护一个使用内置多纹理 Effect 着色器的材质，如果你有特殊的用途，可以通过
|
||||
|
||||
```js
|
||||
const material = cc.Label._shareAtlas.material;
|
||||
```
|
||||
|
||||
获取或修改该材质。
|
||||
|
||||
渲染时内部会先判断当前所使用的是否为多纹理材质，是的话判断是否能在材质纹理插槽中找到字符图集纹理，如果有一个判断不满足则会将组件的材质设为内部维护的材质。
|
||||
|
||||
但 Char 字符图集是运行时才创建的，所以**暂时无法在使用 Char 缓存模式时直接设置自定义材质**。
|
||||
|
||||
你可以通过代码创建含有当前所有字符图集纹理的自定义材质来解决这个问题，但内部会不断创建新的字符图集（直到 8 张），所以需注意同步更新这个自定义材质，建议有自定义材质需求时使用 Bitmap 缓存模式。
|
||||
|
||||
---
|
||||
## 与动态图集合批的注意事项
|
||||
|
||||
多纹理材质只有 8 个纹理插槽，默认情况下字符图集自动多纹理合批的数量为 1，也就是说会将第 1 张字符图集纹理放入材质。
|
||||
|
||||
**你可以自己调整这个分配值，但请注意调整的时机。**
|
||||
|
||||
下面举一个例子，假设有一个脚本 `example.ts` 的部分内容是：
|
||||
|
||||
```js
|
||||
|
||||
class Example extends cc.Component {
|
||||
|
||||
onLoad() {
|
||||
// 1
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
// 2
|
||||
|
||||
```
|
||||
|
||||
一般情况下，代码位置 2 是当用户脚本被加载时就会被执行，而代码位置 1 可能需要等到引擎首场景加载后的某个时间执行。
|
||||
|
||||
服务包会自动调整动态图集的最大数量，这个调整的时机是在代码位置 2 之后的，所以比如你的项目对 Char 缓存模式使用量比较大时，想尝试将动态图集最大数量调整为 6，自动合批的字符图集数量调整为 2，那么你只需要在代码位置 2 修改字符图集自动多纹理合批的数量：
|
||||
|
||||
```js
|
||||
cc.sp.charAtlasAutoBatchCount = 2;
|
||||
```
|
||||
|
||||
之后服务包会自动将动态图集的最大数量调整为 `8 - 2`，即 6。
|
||||
|
||||
这个自动调整的时机并不意味着你在代码位置 2 修改动态图集的最大数量是无效的，因为一开始动态图集的最大数量为 `-1`，你打印一下可以看到
|
||||
|
||||
```js
|
||||
console.log(cc.dynamicAtlasManager.maxAtlasCount); // -1
|
||||
```
|
||||
|
||||
如果你在代码位置 2 修改了动态图集的最大数量，服务包就不会调整该值了。
|
||||
|
||||
```js
|
||||
cc.dynamicAtlasManager.maxAtlasCount = 5;
|
||||
```
|
||||
|
||||
这时候动态图集的最大数量是 5，字符图集自动多纹理合批的数量依旧默认为 1，多纹理材质会有 2 个空纹理插槽。
|
||||
|
||||
如果这两个数量加起来超过 8 就会使用更多的材质进行渲染，这会导致项目的 Draw Call 数量升高，建议保持加起来的数量不超过 8 张，能保持 1 Draw Call。
|
||||
|
||||
```js
|
||||
cc.dynamicAtlasManager.maxAtlasCount = 13;
|
||||
cc.sp.charAtlasAutoBatchCount = 3;
|
||||
```
|
||||
|
||||
比如上面这个设置，这会使得引擎需要用 2 个材质进行渲染，但是可用的动态图集扩充到了 13 张，Char 能自动合批的图集数量扩充到了 3 张，对于某些项目来说可能并不是一件坏事。
|
||||
|
||||
服务包使用这个 “7 + 1” 的默认值有以下几点原因：
|
||||
|
||||
- 引擎原本就只有 1 张 Char 字符图集
|
||||
- 大多数项目使用 1 张 Char 字符图集是足够的
|
||||
|
||||
@@ -2,7 +2,39 @@
|
||||
sidebar_position: 2
|
||||
description: "一行代码开启高清文本渲染。"
|
||||
---
|
||||
|
||||
# 高 DPI 支持
|
||||
|
||||
TODO
|
||||
可阅读 [上手其它新特性](../../start-guide/new-features.md#高-dpi-文本渲染) 了解基本的使用方法，除了注意性能以外，没有其它的注意事项。
|
||||
|
||||
---
|
||||
## 调整全局开关
|
||||
|
||||
使用下面的代码控制组件是否默认开启高 DPI 支持：
|
||||
|
||||
```js
|
||||
cc.sp.enableLabelRetina = false;
|
||||
```
|
||||
|
||||
---
|
||||
## 调整渲染缩放比例
|
||||
|
||||
使用下面的代码调整内部渲染的缩放倍数：
|
||||
|
||||
```js
|
||||
cc.sp.labelRetinaScale = 2;
|
||||
```
|
||||
|
||||
---
|
||||
## 控制单个组件开关
|
||||
|
||||
|
||||
|
||||
除了在编辑器调整，也可以通过代码控制：
|
||||
|
||||
```js
|
||||
// cc.RenderComponent.EnableType
|
||||
// GLOBAL: 全局默认值
|
||||
// ENABLE: 开启
|
||||
// DISABLE: 关闭
|
||||
label.enableRetina = cc.RenderComponent.EnableType.ENABLE;
|
||||
```
|
||||
|
||||
@@ -3,19 +3,6 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
# 文本渲染
|
||||
|
||||
我们基本重构了动态合图系统，在原有的功能基础上，增加了以下重要特性：
|
||||
|
||||
- **完全开放所有接口**，以方便如果你想手动规划或控制动态图集
|
||||
- **增加默认是否参与动态合图的全局设置，并支持设置单个组件是否参与动态合图**
|
||||
- **支持自动加入多纹理合批**
|
||||
- **优化图集装箱算法**（使用 Guillotine）
|
||||
- **支持复用废弃的空间**
|
||||
- **所有图集作为一个整体进行管理**（不再出现纹理被加入到两张图集的情况）
|
||||
|
||||
:::tip 提示
|
||||
|
||||
你可以阅读官方文档来了解怎么使用 [动态合图](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/dynamic-atlas.html)，由于动态合图的使用本来就是自动的，所以如果没有特殊需求则**不需要阅读后面的内容**。
|
||||
|
||||
:::
|
||||
文本渲染一般是游戏性能优化需要重点关注的地方，并且其显示效果也非常重要，所以服务包提供了以下新特性：
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
sidebar_position: 3
|
||||
description: "就像在其它组件里一样使用自定义材质。"
|
||||
---
|
||||
|
||||
# RichText 自定义材质
|
||||
|
||||
TODO
|
||||
|
||||
|
||||
像往常一样使用即可。
|
||||
|
||||
@@ -3,7 +3,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
# 使用指南
|
||||
|
||||
在 [入门教程](../start-guide/start-guide-intro) 里，你应该对如何更好地使用安装服务包后的引擎已经有所了解了。
|
||||
在 [入门教程](../start-guide/start-guide-intro.mdx) 里，你应该对如何更好地使用安装服务包后的引擎已经有所了解了。
|
||||
|
||||
通过使用指南你能更详细地了解服务包为引擎添加的每个特性与改动：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user