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의 compare URL을 확인하십시오.


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의 compare URL을 확인하십시오.


■SDK for Web

만일 고객이 SDK의 커스터마이즈를 실시한 관계로 일반적인 업데이트가 어려운 상태일 경우 「Cubism Core」를 4.2 SDK에 덮어쓰기해 주시고 Framework 폴더 내의 이하의 항목을 덮어쓰는 것으로도 대처할 수 있습니다.

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

자세한 차이점은 Github의 compare URL을 확인하십시오.

 

기존 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

이 구조체는 네 개의 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
사용할 CMO 3 파일의 상태 .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 버전
행동의 호환성
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와 같습니다.

 

© 2010 - 2022 Live2D Inc.