Cubism 4.2 기능의 SDK 호환성에 대해
업데이트： 2022/06/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 버전 | 물리 연산의 동작 뉘앙스 | 업데이트당 계산 비용 | 단위 시간 계산 비용 |
|---|---|---|---|---|
| 없음 | 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와 같습니다.