关于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 5.3新功能的模型渲染方式（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类内的绘制处理结构进行了大幅调整。

另外，规格变更为向CubismRenderer_xx类的构造函数传递窗口大小的Width和Height。 因此，需要向CubismUserModel类的CreateRenderer函数传递Width和Height。

混合方式获取方法的变更

从5.3 SDK开始，混合方式被整合到混合模式中，获取方法发生了变更，从csmGetDrawableConstantFlags变更为csmGetDrawableBlendModes。

通过这个变更，也能够处理从5.3 SDK开始的混合模式。

关于使用Cubism 5.3新功能的模型渲染方式（Unity）

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

使用混合模式或离屏绘制的模型，所有绘制对象会先被绘制到RenderTexture中，最终绘制在一个Plane上。

未使用混合模式或离屏功能的模型将使用传统的绘制方式进行渲染。

传统绘制方式与使用Cubism 5.3新功能的模型绘制方式的差异

传统绘制方式

• 各个Drawable使用Unity的Mesh Filter组件，分别作为Unity对象进行绘制。
• 各个Drawable对象可以使用Transform.localPosition.z进行BackToFrontZ等排序。
• 蒙版绘制使用预处理蒙版方式进行。

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

• 蒙版绘制使用高精度蒙版方式进行。
• 各个绘制对象（Drawable・Offscreen）在CubismRenderer.DrawObject()内进行绘制处理。
• 各个绘制对象先绘制到一个RenderTexture中，然后以将RenderTexture应用到Plane的形式进行绘制。
• 各个绘制对象使用BackToFrontOrder或FrontToBackOrder中的一种进行排序。

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

在使用新功能的模型绘制方式中，无法进行如”在模型的Drawable之间放置其他Sprite“中记载的那样，使用MeshRenderer.sortingOrder或Transform.localPosition.z等让Unity对象插入绘制中的处理。

计划今后实现用于抑制这些影响的扩展功能。

Cubism Core API的变更

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

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

关于负载

混合模式

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

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

离屏绘制

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

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