关于Cubism 5.3功能的SDK兼容性和限制

最終更新： 2025年8月26日

此页面包含有关Beta版的描述。

概述

这里我们将对Cubism 5的SDK兼容性进行以下内容的说明。

• 5.3 SDK进行了哪些变更？
• 为了与现有5 SDK兼容，有哪些注意事项和变更点？

关于名称

• 5 SDK是指Cubism 5 SDK R4或更早版本的SDK。
• 5.3 SDK是指Cubism 5 SDK R5 beta1或更高版本的SDK。

5.2 Editor与5.3 SDK新特性对应表

5 Editor新功能	SDK支持[支持时间]
参数控制器	× 不支持（后续会支持）
翻转形状粘贴	由于是Cubism Editor的编辑功能，不支持SDK
循环编辑辅助	由于是Cubism Editor的编辑功能，不支持SDK
恢复变形器形状	由于是Cubism Editor的编辑功能，不支持SDK
混合模式	△ 支持（仅Native的部分平台、Web、Unity自beta1开始支持）
离屏绘制	△ 支持（仅Native的部分平台、Web、Unity自beta1开始支持）
笔刷工具强化	由于是Cubism Editor的编辑功能，不支持SDK
弯曲变形器的尺寸重整辅助	由于是Cubism Editor的编辑功能，不支持SDK
将WebM格式追加到视频输出设置	由于是Cubism Editor的编辑功能，不支持SDK

对兼容性存在影响的修复

• Renderer相关处理的类结构的变更（Unity除外）
• 融合变形功能的使用确认处理
• Cubism Core API的变更

关于兼容性

向后兼容性

混合模式/离屏绘制

由于这是一项新功能，因此没有兼容性说明。

Renderer相关处理的类结构的变更（Unity除外）

for Native、for Web、中，变更了Renderer相关类的结构和部分函数，以提高Renderer相关处理的可维护性。

仅进行框架替换将发生构建错误。
具体修复内容详见“Renderer相关处理的类结构的变更”。

关于使用Cubism 5.3新功能的模型绘制方法（Unity）

使用Cubism 5.3中追加的混合模式或离屏绘制的模型采用新的绘制方法进行绘制，与仅使用Cubism 5.2之前功能的模型不同。

具体的修改在“关于使用Cubism 5.3新功能的模型绘制方法（Unity）”中有说明。

关于现有5 SDK的更新

更新到5.3 SDK时，如果您照常替换所有文件，它将没有任何问题。

关于Native和Web，由于SDK Framework中部分类名的变更，需要修改调用者。

关于与现有5 SDK的向前兼容性

为5.3输出的MOC文件无法读取，敬请知晓。

如果您尝试读取为5.3输出的MOC文件，则调用csmReviveMocInPlace和csmMocConsistency函数时将输出以下错误。

[CSM] [E]csmReviveMocInPlace is failed. The Core unsupport later than moc3 ver:[5]. This moc3 ver is [6].
[CSM][E]Inconsistent MOC3.

Renderer相关处理的类结构的变更

for Native、for Web、中，变更了Renderer相关类的结构和部分函数，以提高Renderer相关处理的可维护性。

具体变更内容如下。

• CubismOffscreenSurface_xx类重命名为CubismRenderTarget_xx类（Native）
• 为CubismRenderTarget_xx类创建一个新的基类，并移动通用处理（Native）
• CubismRenderer类的绘制处理结构的变更（Native/Web）
• 混合方法获取方式的变更

万一您自定义了SDK，难以正常更新，请参考以下变更内容。

CubismOffscreenSurface_xx类重命名为CubismRenderTarget_xx类（Native）

CubismOffscreenSurface_xx类已重命名为CubismRenderTarget_xx类。

这是为了避免由于追加诸如离屏绘制之类的新功能而导致程序内部发生命名冲突的情况。

由于此变更，需要修改SDK Framework之外调用CubismOffscreenSurface_xx类的部位。

为RenderTarget类创建一个新的基类，并移动通用处理（Native）

从CubismRenderTarget_xx类文件创建了新的基类CubismRenderTarget类，并移动了通用处理。

通过该变更提高了CubismRenderTarget_xx类文件的可读性和可维护性。

CubismRenderer类的绘制处理结构的变更（Native/Web）

由于在5 SDK及更早版本中绘制物件仅有Drawable，而从5.3 SDK起追加了Offscreen，因此对CubismRenderer_xx类内的绘制处理结构进行了大幅变更。

此外，视窗尺寸Width和Height现在传递给CubismRenderer_xx类的构造函数。
因此，您需要将Width和Height传递给CubismUserModel类的CreateRenderer函数。

混合方法获取方式的变更

从5.3 SDK开始，混合方法被合并到混合模式中，获取方法由csmGetDrawableConstantFlags变更为csmGetDrawableBlendModes。

此变更还允许处理来自5.3 SDK的混合模式。

关于使用Cubism 5.3新功能的模型绘制方法（Unity）

使用混合模式或离屏绘制的模型绘制方法

对于使用混合模式或离屏绘制的模型，所有绘制物件都会被绘制到RenderTexture上，并最终绘制在一张Plane上。

不使用混合模式或屏幕外功能的模型使用传统绘制方法绘制。

传统绘制方法与使用Cubism 5.3新功能的模型绘制方法之间的区别

传统绘制方法

• 各Drawable都使用Unity的Mesh Filter组件绘制为Unity物体。
• 各Drawable物体可以使用BackToFrontZ等的Transform.localPosition.z进行排序。
• 蒙版绘制是使用预处理蒙版方法进行的。

使用新功能的模型绘制方法

• 采用高清蒙版方法进行蒙版绘制。
• 各绘制物件（Drawable/Offscreen）在CubismRenderer.DrawObject()内进行绘制处理。
• 各绘制物件都绘制在单独的RenderTexture上，然后将RenderTexture绘制应用到Plane上。
• 各绘制物件都按BackToFrontOrder或FrontToBackOrder排序。

使用新功能的模型绘制方法产生的影响

通过使用新功能的模型绘制方法，将不再可能使用MeshRenderer.sortingOrder或Transform.localPosition.z等来中断Unity物体的绘制，如“在模型的Drawable之间放置其他Sprite”中所述。

我们计划在未来新增扩展功能来减轻这些影响。

Cubism Core API的变更

csmGetDrawableRenderOrders函数已停止使用，并新追加了csmGetRenderOrders函数。

有关详细信息，请参考Live2D Cubism Core API参考。

关于负载

混合模式

关于混合模式的负载，即使使用一张混合模式也会对模型全体产生很小的负载。此外，根据使用张数负载会增加。

负载将根据您使用的绘制API的类型和版本而有所不同。例如，在OpenGL的情况下，可以使用glTextureBarrier的环境将比不能使用glTextureBarrier的环境产生更低的负载。

离屏绘制

关于离屏绘制的负载，每次使用时生成屏幕大小的屏幕外图像都会产生负载。

而且，即使只使用一次离屏绘制，在模型导入时也会进行模型结构分析处理，这会大大降低模型导入速度。