关于Cubism 5功能的SDK兼容性
最終更新： 2023年8月17日
此页面包含有关Beta版的描述。
概述
这里我们将对Cubism 5的SDK兼容性进行以下内容的说明。
- 5 SDK进行了哪些变更？
- 为了与现有4.2 SDK兼容，有哪些注意事项和变更点？
关于名称
4.2 SDK是指Cubism 4 SDK R7或更早版本的SDK。
5 SDK是指Cubism 5 SDK R1 beta1或更高版本的SDK。
5 Editor与5 SDK新特性对应表
5 Editor新功能 | SDK支持[支持时间] |
|---|---|
| 强化融合变形 | 〇 支持（从beta1起） |
| 动态同步 | △ 支持（仅Unity从beta1开始） |
| 支持深色/浅色主题切换 | 由于是Cubism Editor的编辑功能，不支持SDK |
| 支持HiDPI显示器 | 由于是Cubism Editor的编辑功能，不支持SDK |
| 自定义工作区 | 由于是Cubism Editor的编辑功能，不支持SDK |
| 环境设置对话框 | 由于是Cubism Editor的编辑功能，不支持SDK |
| 提高自动网格生成的精度 | 由于是Cubism Editor的编辑功能，不支持SDK |
| 面部动作的自动生成 | 由于是Cubism Editor的编辑功能，不支持SDK |
对兼容性存在影响的修复
- 表情转换处理问题的修复
- Renderer相关处理的类结构的变更（Unity除外）
- Metal和OpenGL之间绘制区别的消除（仅限Native）
关于兼容性
向后兼容性和负载
强化融合变形
在“强化融合变形”中说明了融合变形参数的负载。
动态同步
在“动态同步”中说明了动态同步兼容性。
表情转换处理问题的修复
修复了混合多个表情参数的混合计算时，动画与Editor不同的不自然的问题。
因此，5 SDK的表达与4.2 SDK不同。
需要进行4.2 SDK表达时的修正方法详见“表情转换处理问题的修复”。
Renderer相关处理的类结构的变更
for Native、for Web、for Java中，变更了Renderer相关类的结构和部分函数，以提高Renderer相关处理的可维护性。
仅进行框架替换将发生构建错误。
具体修复内容详见“Renderer相关处理的类结构的变更”。
Metal和OpenGL之间绘制区别的消除
解决了for Native的Metal中与OpenGL的绘制区别。
需要进行4.2 SDK表达时的修正方法详见“Metal和OpenGL之间绘制区别的消除”。
关于现有4.2 SDK的更新和向前兼容性
- 更新到5.0 SDK时，如果您照常替换所有文件，它将没有任何问题。
- 为5输出的MOC文件无法读取，敬请知晓。
- 如果尝试读取为5输出的MOC文件，则调用csmReviveMocInPlace函数时将输出以下错误。
[CSM] [E]csmReviveMocInPlace is failed. The Core unsupport later than moc3 ver:[4]. This moc3 ver is [5].
强化融合变形
通过强化融合变形功能增加了支持融合变形的参数。支持的参数及相应的用户版本请参考下表。
融合变形SDK对应表
物体 | 属性 | 相应的用户版本 |
|---|---|---|
| 部件 | – | 5.0 |
| 绘制顺序 | 5.0 | |
| 弯曲变形器 | – | 4.2 |
| 顶点信息 | 4.2 | |
| 不透明度 | 5.0 | |
| 正片叠底色 | 5.0 | |
| 屏幕色 | 5.0 | |
| 旋转变形器 | – | 5.0 |
| 顶点信息X | 5.0 | |
| 顶点信息Y | 5.0 | |
| 正片叠底色 | 5.0 | |
| 屏幕色 | 5.0 | |
| 角度 | 5.0 | |
| 倍率 | 5.0 | |
| 图形网格 | – | 4.2 |
| 顶点信息 | 4.2 | |
| 绘制顺序 | 5.0 | |
| 正片叠底色 | 5.0 | |
| 屏幕色 | 5.0 | |
| 胶水 | – | 5.0 |
| 兼容性 | 5.0 |
关于现有SDK的变更点和负载
为了保证向后兼容，4.2之前的通用行为没有区别。
迁入模型数据版本为“支持SDK 5.0/Cubism 5.0”时
- 作为融合变形参数信息，输出部件/图形网格/弯曲变形器/旋转变形器/胶水的属性。
- 像以前一样从模型的Drawable数据中获取各属性的值。
关于负载，计算融合变形参数的负载将会增加。（融合变形趋于线性增加。）
动态同步
由于这是一项新功能，因此没有兼容性说明。
表情转换处理问题的修复
需要进行4.2 SDK表达时的修正方法
for Unity
选择模型预制件并从Inspector视窗中选中CubismExpressionController的Use Legacy Blend Calculation。
for Native
如下变更CubismUserModel::_expressionManager的类型以及CubismUserModel::CubismUserModel()中的原始化处理。
https://github.com/Live2D/CubismNativeFramework/blob/develop/src/Model/CubismUserModel.hpp#L272
修正前的代码
CubismExpressionMotionManager* _expressionManager; ///< 表情管理
修正后的代码
CubismMotionManager* _expressionManager; ///< 表情管理
https://github.com/Live2D/CubismNativeFramework/blob/develop/src/Model/CubismUserModel.cpp#L42
修正前的代码
_expressionManager = CSM_NEW CubismExpressionMotionManager();
修正后的代码
_expressionManager = CSM_NEW CubismMotionManager();
for Web
将CubismUserModel类的构造函数中原始化_expressionManager的过程变更如下。
https://github.com/Live2D/CubismWebFramework/blob/develop/src/model/cubismusermodel.ts#L368
修正前的代码
this._expressionManager = new CubismExpressionMotionManager();
修正后的代码
this._expressionManager = new CubismMotionManager();
for Java
如下变更CubismUserModel中定义的expressionManager变量的定义部分。
修正前的代码
protected CubismExpressionMotionManager expressionManager = new CubismExpressionMotionManager();
修正后的代码
protected CubismMotionManager expressionManager = new CubismMotionManager();
Renderer相关处理的类结构的变更
for Native、for Web、for Java中，变更了Renderer相关类的结构和部分函数，以提高Renderer相关处理的可维护性。
具体变更内容如下。
- ClippingManager分开
- SetupClippingContext内高清蒙版的分开
- 着色器相关源代码划分
- 将通用处理移至基类
- DrawMesh参数的整理
- “OffScreen~~”名称的统一
万一您自定义了SDK，难以正常更新，请参考以下变更内容。
ClippingManager分开
将ClippingManager相关处理从CubismRenderer_xx类文件分开到CubismClippingManager类文件中。
for Native中CubismClippingManager类是所有Renderer的通用类。
通过该变更提高了CubismRenderer_xx类文件的可读性以及ClippingManager相关处理的可维护性。
SetupClippingContext内高清蒙版的分开
我们从CubismRenderer_xx类文件中提取出高清蒙版相关处理，对其进行通用化，并将其移至CubismClippingManager类中。
通过该变更提高了CubismRenderer_xx类文件的可读性以及高清蒙版相关处理的可维护性。
着色器相关源代码划分
对各Renderer进行不同处理的着色器相关代码已统一在CubismShader_xx类文件中进行处理。
通过该变更提高了着色器相关代码的可维护性。
将通用处理移至基类
我们通过将所有派生类中以相同方式完成的处理（例如 CubismRenderer_xx 类中的矩阵计算）移动到基类来进行通用化。
通过该变更提高了CubismRenderer_xx类文件的可维护性。
DrawMesh参数的整理
在CubismRenderer_xx类中与Draw相关的函数中，整理了需要设置大量参数的位置。
由于设置了model物体的多个成员变量，因此通过将model物体本身设置为参数，大大减少了参数的数量。
此修复提高了Draw相关处理的可维护性。
“OffScreen~~”名称的统一
多处使用的名称“OffScreenBuffer”和“OffScreenFrame”已重命名为“OffScreenSurface”。
此更改通过使用通用名称提高了Renderer相关处理的可维护性。
Metal和OpenGL之间绘制区别的消除
解决了for Native的Metal中与OpenGL的绘制区别。
需要进行4.2 SDK表达时的修正方法已记载于CHANGELOG.md。
Cubism Core API的变更
csmGetMocVersion函数中追加了Cubism 5的MOC3文件返回值的定义。
有关详细信息，请参考Live2D Cubism Core API参考。