关于Cubism 4.2功能的SDK兼容性
最終更新： 2022年6月16日
本节说明Cubism 4.2的SDK的变更内容，以及现有4系列SDK与Cubism 4.2的SDK兼容性的注意事项和变更点。
关于名称
- 4系列SDK是指Cubism 4 SDK R4 或更早版本的SDK。
- 4.2 SDK是指Cubism 4 SDK R5 beta1 或更高版本的SDK。
4.2 Editor与4.2 SDK新特性对应表
| 4.2 Editor新功能 | SDK支持[支持时间] |
|---|---|
| 正片叠底色/屏幕色 | 〇 支持[从beta1起] |
| 融合变形 | 〇 支持[从beta1起] |
| 物理模拟的FPS支持 | ○ 支持[从beta3起] |
| 增强手动编辑网格 | 由于编辑功能，不支持SDK |
| 形状的特殊粘贴 | 由于编辑功能，不支持SDK |
| 参数书签 | 由于编辑功能，不支持SDK |
| 增强自动生成四个角的形状 | 由于编辑功能，不支持SDK |
| 运行时模型轨道 | 由于编辑功能，不支持SDK |
| 冻结 | 由于编辑功能，不支持SDK |
| 改进快捷键设置 | 由于编辑功能，不支持SDK |
关于兼容性
向后兼容性和负载
正片叠底色和屏幕色的默认值在RGBA中设置如下，可以得到与4系列SDK相同的绘制结果。
- 正片叠底色（1.0、1.0、1.0、1.0）
- 屏幕色（0.0、0.0、0.0、1.0）
通用行为如下表所示，这次该功能没有发生破坏性变更，并且在重新安装SDK时向后兼容。
此处说明了融合变形参数的负载。
| Cubism Editor 版本 |
嵌入 模型数据 版本 |
模型正片叠底色/ 屏幕色的颜色信息 |
融合变形 参数信息 |
4.2 SDK行为 | 负载 |
|---|---|---|---|---|---|
| 4.2 | “支持SDK 4.2/Cubism 4.2” | 被输出 （MOC3文件的大小会因新功能而增加） |
输出为融合变形参数 | 从模型的Drawable数据中获取颜色信息值 | 计算正片叠底色和屏幕色的负载增加。 |
| 4.2 | “支持SDK 4.0/Cubism 4.0” | 未被输出 （MOC3文件大小和4.0一样，无变更） |
输出为没有键的通常参数 | 获取每个正片叠底色和屏幕色的默认值 | 无区别 |
| 4.0 | “支持SDK 4.0/Cubism 4.0” | 未被输出 | 未被输出 | 获取每个正片叠底色和屏幕色的默认值 | 无区别 |
关于现有4系列SDK的更新和向前兼容性
从现有的4系列SDK更新到4.2 SDK时，如果您照常替换所有文件，它将没有任何问题。
请注意，现有的4系列SDK无法导入为4.2 SDK输出的模型数据。
尝试使用现有的4系列SDK导入为4.2 SDK输出的模型数据时，调用csmReviveMocInPlace函数时从CubismCore输出以下错误。
[CSM] [E]csmReviveMocInPlace is failed. The Core unsupport later than moc3 ver:[3]. This moc3 ver is [4].
正片叠底色、屏幕色
从自定义的现有4系列SDK更新
■SDK for Unity
万一客户自定义了SDK，很难像通常一样更新，您也可以用“Cubism Core”覆盖4.2 SDK，覆盖Framework文件夹中的以下项目来处理。
- Live2D/Cubism/Rendering/CubismRenderer.cs
- Live2D/Cubism/Rendering/CubismRenderController.cs
- Live2D/Cubism/Rendering/CubismShaderVariables.cs
- Live2D/Cubism/Core文件夹的内容
查看Github的Comparing changes以获取详细的差异内容。
■SDK for Native
万一客户自定义了SDK，很难像通常一样更新，您也可以用“Cubism Core”覆盖4.2 SDK，覆盖Framework文件夹中的以下项目来处理。
- CubismModel
- 各平台的CubismRenderer
- 各平台的CubismShader
- CubismType_D3D11.hpp（仅限DirectX 11）
- MetalShaderTypes.h（仅限Metal）
- MetalShaders.metal（仅限Metal）
查看Github的Comparing changes以获取详细的差异内容。
■SDK for Web
万一客户自定义了SDK，很难像通常一样更新，您也可以用“CubismCore”覆盖4.2 SDK，覆盖Framework文件夹中的以下项目来处理。
- cubismmodel.ts
- cubismrenderer.ts
- cubismrenderer_webgl.ts
查看Github的Comparing changes以获取详细的差异内容。
现有4系列SDK的变更
使用Cubism Editor 4.2输出为4.2 SDK的模型数据时，正片叠底色和屏幕色的信息将添加到Drawable的数据中。
上述相应处理被追加到各SDK。
■SDK for Unity
在Unlit.shader中，追加了将正片叠底色和屏幕色应用到Fragment shader部分的公式。
除此之外，我们还定义了ColorField，允许您通过CubismRenderer的检查器在SDK端设置任意正片叠底色和屏幕色的颜色信息。
使SDK中指定的颜色信息可用的功能
SDK基本上是设计成使用从模型数据中获取的颜色信息作为正片叠底色和屏幕色的应用处理，但SDK端直接通过代码对全体模型或单个Drawable进行指定，也可以指定颜色信息。
当使用SDK端的任意颜色信息时，在决定是否从SDK端为全体模型 = 所有Drawable启用正片叠底色/屏幕色操作时，通过启用CubismRenderController中定义的以下属性中的标志，用户可以设置任意全体模型的正片叠底色/屏幕色。
- 正片叠底色时为OverwriteFlagForModelMultiplyColors
- 屏幕色时为OverwriteFlagForModelScreenColors
通过启用CubismRenderer中定义的以下属性中的标志，可以将单个Drawable的标志设置为用户指定的Drawable的任意正片叠底色/屏幕色。
- 正片叠底色时为OverwriteFlagForMultiplyColors
- 屏幕色时为OverwriteFlagForScreenColors
启用全体模型的标志后，所有Drawable都被设计为使用来自SDK端的任意颜色信息，而不管单个Drawable的标志状态如何。
如果全体模型的标志被禁用，则应用单个Drawable的标志状态。
SDK端使用的任任意正片叠底色和屏幕色都旨在保存，无论标志状态如何。
接收Drawable的正片叠底色/屏幕色已变更的功能
如果正片叠底色/屏幕色变更与模型参数相关联，则在模型动画时可能从模型侧更改正片叠底色/屏幕色。
IsBlendColorDirty 在CubismDynamicDrawableData中实装为一个功能，即可以接收此时正片叠底色和屏幕色的变更。
该功能是在模型侧变更正片叠底色或屏幕色时设置的标志，它不判断变更正片叠底色、还是屏幕色。
此外，它不适用于SDK端的正片叠底色/屏幕色信息操作。
为了处理CubismDynamicDrawableData的数据，需要使用CubismModel 的Event OnDynamicDrawableData。
■SDK for Native
各平台的着色器部分都追加了应用正片叠底色和屏幕色的公式。
此外，CubismModel类中提供了以下函数，用于设置SDK上任意正片叠底色和屏幕色的颜色信息。
- SetMultiplyColor
- SetScreenColor
使SDK中指定的颜色信息可用的功能
SDK基本上是设计成使用从模型数据中获取的颜色信息作为正片叠底色和屏幕色的应用处理，但SDK端直接通过代码对全体模型或单个Drawable进行指定，也可以指定颜色信息。
当使用SDK端的任意颜色信息时，在决定是否从SDK端为全体模型 = 所有 Drawable启用正片叠底色/屏幕色操作时，通过启用CubismModel中定义的以下函数中的标志，用户可以设置任意全体模型的正片叠底色/屏幕色。
- 正片叠底色时为SetOverwriteFlagForModelMultiplyColors
- 屏幕色时为SetOverwriteFlagForModelScreenColors
通过启用以下函数中的标志，可以将单个Drawable的标志设置为用户指定的Drawable的任意正片叠底色/屏幕色。
- 正片叠底色时为SetOverwriteFlagForDrawableMultiplyColors
- 屏幕色时为SetOverwriteFlagForDrawableScreenColors
启用全体模型的标志后，所有Drawable都被设计为使用来自SDK端的任意颜色信息，而不管单个Drawable的标志状态如何。
如果全体模型的标志被禁用，则应用单个Drawable的标志状态。
SDK端使用的任任意正片叠底色和屏幕色都旨在保存，无论标志状态如何。
接收Drawable的正片叠底色/屏幕色已变更的功能
如果正片叠底色/屏幕色变更与模型参数相关联，则在模型动画时可能从模型侧更改正片叠底色/屏幕色。
这时候GetDrawableDynamicFlagBlendColorDidChange在CubismModel中实装为一个功能，即可以接收Drawable的正片叠底色和屏幕色的变更。
该功能是在模型侧变更正片叠底色或屏幕色时设置的标志，它不判断变更正片叠底色、还是屏幕色。
此外，它不适用于SDK端的正片叠底色/屏幕色信息操作。
■SDK for Web
在cubismrenderer_webgl.ts的着色器部分追加了应用正片叠底色和屏幕色的公式。
此外，CubismModel类中提供了以下函数，用于设置SDK上任意正片叠底色和屏幕色的颜色信息。
- setMultiplyColorByTextureColor
- setScreenColorByTextureColor
- setMultiplyColorByRGBA
- setScreenColorByRGBA
使SDK中指定的颜色信息可用的功能
SDK基本上是设计成使用从模型数据中获取的颜色信息作为正片叠底色和屏幕色的应用处理，但SDK端直接通过代码对全体模型或单个Drawable进行指定，也可以指定颜色信息。
当使用SDK端的任意颜色信息时，在决定是否从SDK端为全体模型 = 所有 Drawable启用正片叠底色/屏幕色操作时，通过启用CubismModel中定义的以下函数中的标志，用户可以设置任意全体模型的正片叠底色/屏幕色。
- 正片叠底色时为setOverwriteFlagForModelMultiplyColors
- 屏幕色时为setOverwriteFlagForModelScreenColors
通过启用以下函数中的标志，可以将单个Drawable的标志设置为用户指定的Drawable的任意正片叠底色/屏幕色。
- 正片叠底色时为setOverwriteFlagForDrawableMultiplyColors
- 屏幕色时为setOverwriteFlagForDrawableScreenColors
启用全体模型的标志后，所有Drawable都被设计为使用来自SDK端的任意颜色信息，而不管单个Drawable的标志状态如何。
如果全体模型的标志被禁用，则应用单个Drawable的标志状态。
SDK端使用的任任意正片叠底色和屏幕色都旨在保存，无论标志状态如何。
接收Drawable的正片叠底色/屏幕色已变更的功能
如果正片叠底色/屏幕色变更与模型参数相关联，则在模型动画时可能从模型侧更改正片叠底色/屏幕色。
这时候getDrawableDynamicFlagBlendColorDidChange在CubismModel中实装为一个功能，即可以接收Drawable的正片叠底色和屏幕色的变更。
该功能是在模型侧变更正片叠底色或屏幕色时设置的标志，它不判断变更正片叠底色、还是屏幕色。
此外，它不适用于SDK端的正片叠底色/屏幕色信息操作。
为了处理CubismDynamicDrawableData的数据，需要使用CubismModel的Event OnDynamicDrawableData。
融合变形功能
关于现有4系列SDK的变更点和负载
没有被变更的功能，可以通过与通常参数相同的方式获取融合变形参数。
无需特殊支持，但通常参数组合和融合变形组合的计算成本不同。
通常参数倾向于以指数方式增加数据和计算成本，而融合变形倾向于线性增加。
融合变形参数的特点是即使在SDK中也能够以较常规参数相比更低的成本使用。
Cubism Core API的变更
现有4系列SDK的Cubism Core的变更点
在4.2 SDK的Cubism Core中，根据上述功能追加，追加了一些函数，并且变更了部分动作行为。
以下是每个追加的函数和行为变更的简要说明。
结构
csmVector4
这个结构内部有4个float成员变量。
4.2 SDK的Cubism Core API用于保存和获取正片叠底色及屏幕色数据。
正片叠底色/屏幕色相关
csmGetDrawableMultiplyColors
此函数将地址返回到图形网格的正片叠底色数组。
csmGetDrawableScreenColors
此函数将地址返回到图形网格的屏幕色数组。
csmBlendColorDidChange
这是在Cubism Core侧变更正片叠底色或屏幕色时有效的动态标志。
融合变形相关
行为变更
作用于csmGetParameterCount函数等参数数据的函数现在支持融合变形用参数。
实装为使得可以在不区分融合变形用参数和通常参数的情况下进行获取。
Cubism Core API本身没有变更。
4.2 SDK Cubism Core追加的各函数和功能详情请参考Cubism Core API参考。
物理模拟的FPS支持
在Cubism SDK R5 beta2之前的物理模拟中，由于SDK的渲染FPS，物理模拟行为与Editor不匹配。
从Cubism SDK R5 beta3开始，物理模拟的计算方法已更改，无论SDK的渲染FPS如何，都可以再现Editor中设置的物理模拟行为。
由于物理模拟的计算方式发生变更，需要从Editor通知SDK端物理模拟的设置FPS。
因此，在Cubism 4.2.00或更高版本中输出嵌入数据时，FPS设置会输出到.physics3.json。
使用输出到.physics3.json的FPS设置，并通过时间对因渲染FPS的差异所产生的状态进行直线插值，行为结果现在尽可能接近Editor。
如果.physics3.json中没有FPS设置的项目，物理模拟的行为会按照渲染FPS和之前一样，保证常规SDK中的行为。
将FPS设置从Editor输出到.physics3.json
| 要使用的 Editor Version | 要使用的CMO3文件的状态 | .physics3.json的 FPS描述 |
|---|---|---|
| 4.2.00 beta2或更早版本 | 全部 | 无 |
| 4.2.00正式版或更高版本 | 保存为4.1.01或更早版本且未打开物理模拟 | 无 |
| 4.2.00正式版或更高版本 | 在4.1.02 beta1或更高版本中加工物理模拟 | 有（*） |
*：根据输出MOC3时的设置，也可以选择不在.physics3.json中描述FPS。
与.physics3.json中的FPS设置的行为兼容性
| 使用的SDK Version | 行为兼容性 |
|---|---|
| R5 beta 2或更早版本 | FPS设置的有无不影响导入操作。 即使没有FPS设置，也不会产生任何影响。（照常） 动作与R5 beta2之前相同，并且没有改变。 |
| R5 beta 3或更高版本 | 如果存在FPS设置，则使用FPS设置将物理模拟行为与Editor相匹配。 如果不存在FPS设置，则计算将与R5 beta2之前相同。 * 作为尽可能保持行为的错误，当与R5 beta2比较行为时，物理模拟的行为延迟一帧。 |
.physics3.json的FPS设置的有无和SDK行为
| json的FPS 设置状态 | 使用的SDK Version | 物理模拟的动作细微差别 | 每次Update的计算成本 | 单位时间的计算成本 |
|---|---|---|---|---|
| 无 | R5 beta2或更早版本 | 与渲染FPS相同 | 恒定 | 与渲染FPS成比例 |
| 有 | R5 beta2或更早版本 | 与渲染FPS相同 | 恒定 | 与渲染FPS成比例 |
| 无 | R5 beta3或更高版本 | 与渲染FPS相同 | 恒定（与 R4相比略有增加） | 与渲染FPS成比例 |
| 有 | R5 beta3或更高版本 | .physics3.json的FPS设置 | 在.physics3.json中设置FPS和 根据渲染FPS而变动 （小幅减少或小幅增加） | 与.physics3.json中设置的FPS成比例 |
关于OWViewer和Editor上的变更
对于Cubism Viewer（for OW）和Cubism Viewer for Unity，物理模拟行为与Cubism SDK R5 beta3相同。