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のカスタマイズを行っており、通常通りのアップデートが難しい状態には「Cubism Core」を4.2 SDKの物に上書きして頂き、Frameworkフォルダ内の以下の項目を上書きすることでも対処できます。

• cubismmodel.ts
• cubismrenderer.ts
• cubismrenderer_webgl.ts

詳細な差分内容はGithubのComparing changesをご確認ください。

既存の4系SDKからの変更点

CubismEditor 4.2で4.2 SDK向けのモデルデータとして書き出した場合、Drawableのデータに乗算色・スクリーン色の情報が加わるようになります。
これらに対する処理を各SDKに追加しています。

■SDK for Unity

Unlit.shaderにて、Fragmentシェーダー部分へ乗算色・スクリーン色を反映するための式を追加いたしました。
また、それに伴いCubismRendererのインスペクタ上からSDK側で任意の乗算色・スクリーン色のそれぞれの色情報を設定が可能なColorFieldを定義しています。

SDKで指定した色情報を利用できるようにする機能

SDKは基本的に乗算色・スクリーン色の反映処理としてモデルデータから取り込まれる色情報を使用するような仕様となっていますが、SDK側からモデル全体または個別のDrawableに対し、コードを介して直接色情報を指定することもできます。
SDK側から任意の色情報を利用する場合、モデル全体 = 全てのDrawableに対してSDK側から乗算色・スクリーン色の操作を可能とするかを決める際には、CubismRenderControllerに定義されている以下のプロパティからフラグを有効にすることによって、ユーザーがモデル全体に任意の乗算色・スクリーン色を設定できるようになります。

• 乗算色の場合は、OverwriteFlagForModelMultiplyColors
• スクリーン色の場合は、OverwriteFlagForModelScreenColors

個別のDrawableに対するフラグはCubismRendererに定義されている以下のプロパティからフラグを有効にすることによって、ユーザーが指定したDrawableに任意の乗算色・スクリーン色を設定できるようになります。

• 乗算色の場合は、OverwriteFlagForMultiplyColors
• スクリーン色の場合は、OverwriteFlagForScreenColors

モデル全体のフラグが有効となった場合は個別のDrawableに対するフラグの状態に関わらず、全てのDrawableがSDK側から任意の色情報を利用するように設計されています。
モデル全体のフラグが無効の場合は個別のDrawableに対するフラグの状態が適用されます。

SDK側で利用する任意の乗算色・スクリーン色はフラグの状態に関わらず保存されるように設計されています。

Drawableの乗算色・スクリーン色が変更されたことを受け取る機能

モデルのパラメータに乗算色・スクリーン色の変更が結びつけられている場合、モデルがアニメーションした際などにモデル側から乗算色・スクリーン色が変更される事があります。
この時に乗算色・スクリーン色が変更されたことを受け取る事が出来る機能として、IsBlendColorDirty がCubismDynamicDrawableDataに実装されています。

この機能は乗算色もしくはスクリーン色のいずれかがモデル側で変更された際に立つフラグとなっており、乗算色とスクリーン色のどちらが変更されたかは判別しません。

また、SDK側からの乗算色・スクリーン色情報操作では機能しません。

CubismDynamicDrawableDataのデータを扱うにはCubismModelのイベントOnDynamicDrawableDataを利用する必要があります。

■SDK for Native

各プラットフォームのシェーダー部分へ乗算色・スクリーン色を反映するための式を追加いたしました。
また、SDK上で任意の乗算色・スクリーン色のそれぞれの色情報を設定するための以下の関数をCubismModelクラスに用意しています。

• SetMultiplyColor
• SetScreenColor

SDKで指定した色情報を利用できるようにする機能

SDKは基本的に乗算色・スクリーン色の反映処理としてモデルデータから取り込まれる色情報を使用するような仕様となっていますが、SDK側からモデル全体または個別のDrawableに対し、コードを介して直接色情報を指定することもできます。
SDK側から任意の色情報を利用する場合、モデル全体 = 全てのDrawableに対してSDK側から乗算色・スクリーン色の操作を可能とするかを決める際には、CubismModelに定義されている以下の関数からフラグを有効にすることによって、ユーザーがモデル全体に任意の乗算色・スクリーン色を設定できるようになります。

• 乗算色の場合は、SetOverwriteFlagForModelMultiplyColors
• スクリーン色の場合は、SetOverwriteFlagForModelScreenColors

個別のDrawableに対するフラグは以下の関数からフラグを有効にすることによって、ユーザーが指定したDrawableに任意の乗算色・スクリーン色を設定できるようになります。

• 乗算色の場合は、SetOverwriteFlagForDrawableMultiplyColors
• スクリーン色の場合は、SetOverwriteFlagForDrawableScreenColors

モデル全体のフラグが有効となった場合は個別のDrawableに対するフラグの状態に関わらず、全てのDrawableがSDK側から任意の色情報を利用するように設計されています。
モデル全体のフラグが無効の場合は個別のDrawableに対するフラグの状態が適用されます。

SDK側で利用する任意の乗算色・スクリーン色はフラグの状態に関わらず保存されるように設計されています。

Drawableの乗算色・スクリーン色が変更されたことを受け取る機能

モデルのパラメータに乗算色・スクリーン色の変更が結びつけられている場合、モデルがアニメーションした際などにモデル側から乗算色・スクリーン色が変更される事があります。

この時にDrawableの乗算色・スクリーン色が変更されたことを受け取る事が出来る機能として、CubismModelにGetDrawableDynamicFlagBlendColorDidChangeが実装されています。

この機能は乗算色もしくはスクリーン色のいずれかがモデル側で変更された際に立つフラグとなっており、乗算色とスクリーン色のどちらが変更されたかは判別しません。
また、SDK側からの乗算色・スクリーン色情報操作では機能しません。

■SDK for Web

cubismrenderer_webgl.tsのシェーダー部分へ乗算色・スクリーン色を反映するための式を追加いたしました。
また、SDK上で任意の乗算色・スクリーン色のそれぞれの色情報を設定するための以下の関数をCubismModelクラスに用意しています。

• setMultiplyColorByTextureColor
• setScreenColorByTextureColor
• setMultiplyColorByRGBA
• setScreenColorByRGBA

SDKで指定した色情報を利用できるようにする機能

SDKは基本的に乗算色・スクリーン色の反映処理としてモデルデータから取り込まれる色情報を使用するような仕様となっていますが、SDK側からモデル全体または個別のDrawableに対し、コードを介して直接色情報を指定することもできます。
SDK側から任意の色情報を利用する場合、モデル全体 = 全てのDrawableに対してSDK側から乗算色・スクリーン色の操作を可能とするかを決める際にはCubismModelに定義されている以下の関数からフラグを有効にすることによって、ユーザーがモデル全体に任意の乗算色・スクリーン色を設定できるようになります。

• 乗算色の場合は、setOverwriteFlagForModelMultiplyColors
• スクリーン色の場合は、setOverwriteFlagForModelScreenColors

個別のDrawableに対するフラグは以下の関数からフラグを有効にすることによって、ユーザーが指定したDrawableに任意の乗算色・スクリーン色を設定できるようになります。

• 乗算色の場合は、setOverwriteFlagForDrawableMultiplyColors
• スクリーン色の場合は、setOverwriteFlagForDrawableScreenColors

モデル全体のフラグが有効となった場合は個別のDrawableに対するフラグの状態に関わらず、全てのDrawableがSDK側から任意の色情報を利用するように設計されています。
モデル全体のフラグが無効の場合は個別のDrawableに対するフラグの状態が適用されます。

SDK側で利用する任意の乗算色・スクリーン色はフラグの状態に関わらず保存されるように設計されています。

Drawableの乗算色・スクリーン色が変更されたことを受け取る機能

モデルのパラメータに乗算色・スクリーン色の変更が結びつけられている場合、モデルがアニメーションした際などにモデル側から乗算色・スクリーン色が変更される事があります。

この時にDrawableの乗算色・スクリーン色が変更されたことを受け取る事が出来る機能として、CubismModelにgetDrawableDynamicFlagBlendColorDidChangeが実装されています。

この機能は乗算色もしくはスクリーン色のいずれかがモデル側で変更された際に立つフラグとなっており、乗算色とスクリーン色のどちらが変更されたかは判別しません。
また、SDK側からの乗算色・スクリーン色情報操作では機能しません。

CubismDynamicDrawableDataのデータを扱うにはCubismModelのイベント 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から物理演算の設定FPSをSDK側へ伝える必要があります。
そのため、Cubism 4.2.00 以降では組み込みデータ書き出しの際に.physics3.jsonへFPS設定が書き出されます。

.physics3.jsonに書き出されたFPS設定を使用し、レンダリングFPSの相違で発生してしまう間の状態を時間で線形補間することで、挙動の結果がなるべくEditorと一致するようになりました。

.physics3.jsonにFPS設定の項目がない場合は、従来と同じレンダリングFPSに応じた物理演算の挙動となり、従来のSDKでの挙動を担保します。

Editorからの.physics3.jsonへのFPS設定の書き出し

使用する エディタ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 beta2以前	FPS設定の有無は読み込み動作に影響はありません。 FPS設定が存在しなくても、何も影響ありません。(従来通り) 動作もR5 beta2以前以前と同様のまま、変化しません。
R5 beta3以降	FPS設定が存在する場合、FPS設定を使用して物理演算の挙動をEditorと一致させます。 FPS設定が存在しない場合、R5 beta2 以前と同様の計算となるように動作します。 ※挙動をなるべく保った際の誤差として、R5 beta2と動作を比較したときに、物理演算の挙動が1フレーム分遅れます。

.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と同様です。