Cubism 5 기능의 SDK 호환성에 대해

업데이트： 2023/08/17

이 페이지에는 베타 버전에 관한 설명이 포함되어 있습니다.

개요

이 섹션에서는 Cubism 5의 SDK 호환성에 대해 다음 내용을 설명합니다.

• 5 SDK에서 어떤 변경이 이루어졌는가?
• 기존의 4.2 SDK와의 호환성에 대해 어떤 주의점이나 변경점이 있는가?

명칭에 대해

• 4.2 SDK는 Cubism 4 SDK R7 이전의 SDK를 가리킵니다.

• 5 SDK는 Cubism 5 SDK R1 beta1 이상의 SDK를 나타냅니다.

5 Editor와 5 SDK의 새로운 기능 대응표

5 Editor의 새로운 기능	SDK 대응 [대응 시기]
블렌드 셰이프 강화	〇 대응(beta1부터)
모션 싱크	△ 대응(Unity만 beta1부터)
다크/라이트 테마 전환 대응	Cubism Editor의 기능이므로 SDK는 지원하지 않음
HiDPI 디스플레이 지원	Cubism Editor의 기능이므로 SDK는 지원하지 않음
커스텀 워크 스페이스	Cubism Editor의 기능이므로 SDK는 지원하지 않음
환경 설정 대화 상자	Cubism Editor의 기능이므로 SDK는 지원하지 않음
메쉬 자동 생성의 정확도 향상	Cubism Editor의 기능이므로 SDK는 지원하지 않음
얼굴 동작 자동 생성	Cubism Editor의 기능이므로 SDK는 지원하지 않음

호환성에 영향을 미치는 수정

• 표정 전환 처리 버그 수정
• Renderer 관련 처리의 클래스 구조 변경(Unity 이외)
• Metal과 OpenGL의 그리기 차이 해소(Native 한정)

호환성 정보

하위 호환성 및 부하에 대해

블렌드 셰이프 강화

블렌드 셰이프 파라미터의 부하에 대해서는 「블렌드 셰이프 강화」에서 설명합니다.

모션 싱크

모션 싱크의 호환성은 「모션 싱크」에서 설명합니다.

표정 전환 처리 버그 수정

복수의 표정 파라미터의 블렌드 계산 시에 Editor와 다른 부자연스러운 애니메이션이 되는 버그를 수정했습니다.

따라서 5 SDK에서는 4.2 SDK와 다른 표현이 됩니다.
4.2 SDK의 표현이 바람직한 경우의 수정 방법은 「표정 전환 처리 버그 수정」에서 설명하고 있습니다.

Renderer 관련 처리의 클래스 구조 변경

for Native, for Web, for Java에서 Renderer 관련 처리의 유지보수성 향상을 위해 Renderer 관련 클래스의 구조 및 일부 함수를 변경했습니다.

프레임워크만 바꾸면 빌드 오류가 발생합니다.
구체적인 수정 내용은 「Renderer 관련 처리의 클래스 구조 변경」에서 설명하고 있습니다.

Metal과 OpenGL의 그리기 차이 해소

for Native의 Metal에서 발생하던 OpenGL과의 그리기 차이를 해소했습니다.
4.2 SDK의 표현이 바람직한 경우의 수정 방법은 「Metal과 OpenGL의 그리기 차이 해소」에서 설명하고 있습니다.

기존의 4.2 계열 SDK로부터의 업데이트 및 상위 호환성에 대하여

• 5.0 SDK로 업데이트를 할 때는 일반적인 방법과 같이 파일을 모두 덮어쓰면 문제없이 동작합니다.
• 5용으로 내보낸 MOC 파일은 읽을 수 없으므로 미리 양해 바랍니다.
• 5용으로 내보낸 MOC 파일을 읽으려고 하면 csmReviveMocInPlace 함수를 호출할 때 다음 오류가 출력됩니다.

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

블렌드 셰이프 강화

블렌드 셰이프 기능의 강화로 블렌드 셰이프에 대응한 파라미터가 증가했습니다. 대응하는 파라미터와 대응 버전은 아래 표를 참조하십시오.

블렌드 셰이프 SDK 대응표

오브젝트	프로퍼티	대응 버전
파츠	–	5.0
	그리기 순서	5.0
워프디포머	–	4.2
	정점 정보	4.2
	불투명도	5.0
	곱하기 색	5.0
	스크린색	5.0
회전 디포머	–	5.0
	정점 정보 X	5.0
	정점 정보 Y	5.0
	곱하기 색	5.0
	스크린색	5.0
	각도	5.0
	배율	5.0
아트메쉬	–	4.2
	정점 정보	4.2
	그리기 순서	5.0
	곱하기 색	5.0
	스크린색	5.0
글루	–	5.0
	적용도	5.0

기존 SDK로부터의 변경점·부하에 대해서

하위 호환성을 유지하기 위해 4.2까지의 공통 동작에 차이가 없습니다.

임베디드 모델 데이터 버전이 「SDK 5.0 / Cubism 5.0 대응」인 경우

• 블렌드 셰이프 파라미터에 대한 정보로 파츠/아트메쉬/워프디포머/회전 디포머/글루의 속성이 내보내집니다.
• 지금까지와 마찬가지로 모델의 Drawable 데이터에서 각 속성의 값을 가져옵니다.

부하에 대해서는 블렌드 셰이프 파라미터의 계산분의 부하가 증가합니다. (블렌드 셰이프는 선형적으로 늘어나는 경향이 있습니다.)

모션 싱크

새로운 기능이기 때문에 호환성에 대한 설명은 없습니다.

표정 전환 처리 버그 수정

4.2 SDK의 표현이 바람직한 경우의 수정 방법

for Unity

모델의 프리팹을 선택 상태로 두고 Inspector 창에서 CubismExpressionController의 Use Legacy Blend Calculation에 체크 표시합니다.

for Native

CubismUserModel::_expressionManager의 형태와 CubismUserModel::CubismUserModel() 내의 초기화 처리를 다음과 같이 변경합니다.

https://github.com/Live2D/CubismNativeFramework/blob/develop/src/Model/CubismUserModel.hpp#L272

수정 전 코드

CubismExpressionMotionManager*    _expressionManager;         ///< 표정 관리

수정 후 코드

CubismMotionManager*    _expressionManager;         ///< 표정 관리

https://github.com/Live2D/CubismNativeFramework/blob/develop/src/Model/CubismUserModel.cpp#L42

수정 전 코드

_expressionManager = CSM_NEW CubismExpressionMotionManager();

수정 후 코드

_expressionManager = CSM_NEW CubismMotionManager();

for Web

CubismUserModel 클래스의 생성자 내에서 수행하는, _expressionManager를 초기화하는 처리를 이하와 같이 변경합니다.

https://github.com/Live2D/CubismWebFramework/blob/develop/src/model/cubismusermodel.ts#L368

수정 전 코드

this._expressionManager = new CubismExpressionMotionManager();

수정 후 코드

this._expressionManager = new CubismMotionManager();

for Java

CubismUserModel에 정의된 expressionManager 변수의 정의 부분을 다음과 같이 변경합니다.

https://github.com/Live2D/CubismJavaFramework/blob/develop/framework/src/main/java/com/live2d/sdk/cubism/framework/model/CubismUserModel.java#L392

수정 전 코드

protected CubismExpressionMotionManager expressionManager = new CubismExpressionMotionManager();

수정 후 코드

protected CubismMotionManager expressionManager = new CubismMotionManager();

Renderer 관련 처리의 클래스 구조 변경

for Native, for Web, for Java에서 Renderer 관련 처리의 유지보수성 향상을 위해 Renderer 관련 클래스의 구조 및 일부 함수를 변경했습니다.

구체적인 변경 내용은 다음과 같습니다.

• ClippingManager 분리
• SetupClippingContext 내의 고선명 마스크 처리 분리
• 셰이더 관련 소스코드 분류
• 공통 처리를 기본 클래스로 이동
• DrawMesh 인수 정리
• 「OffScreen~~」의 명칭 통일

만일 고객이 SDK의 커스터마이즈를 실시한 관계로 일반적인 업데이트가 어려운 경우에는 아래의 변경 내용을 참조해 주세요.

ClippingManager 분리

CubismRenderer_xx 클래스 파일에서 ClippingManager 관련 처리를 CubismClippingManager 클래스 파일로 분리했습니다.

for Native에서 CubismClippingManager 클래스는 모든 Renderer의 공통 클래스입니다.

이 변경으로 CubismRenderer_xx 클래스 파일의 가독성 향상 및 ClippingManager 관련 처리의 유지보수성이 향상되었습니다.

SetupClippingContext 내의 고선명 마스크 처리 분리

CubismRenderer_xx 클래스 파일에서 고선명 마스크 관련 처리를 추출하고 공통화하여 CubismClippingManager 클래스로 이동했습니다.

이 변경으로 CubismRenderer_xx 클래스 파일의 가독성 향상, 고선명 마스크 관련 처리의 유지보수성이 향상되었습니다.

셰이더 관련 소스코드 분류

Renderer마다 취급이 다르던 셰이더 관련 코드를 CubismShader_xx 클래스 파일로 취급하도록 통일했습니다.

이 변경으로 셰이더 관련 코드의 유지보수성이 향상되었습니다.

공통 처리를 기본 클래스로 이동

CubismRenderer_xx 클래스 내의 행렬 계산 등 모든 파생 클래스에서 동일하게 수행하던 처리를 기본 클래스로 이동함으로써 공통화했습니다.

이 변경으로 CubismRenderer_xx 클래스 파일의 유지보수성이 향상되었습니다.

DrawMesh 인수 정리

CubismRenderer_xx 클래스의 Draw 관련 함수에서 대량의 인수를 설정할 필요가 있던 부분을 정리했습니다.

model 오브젝트의 멤버 변수를 복수 설정했기 때문에 model 오브젝트 자체를 인수로 설정하여 인수의 수를 크게 줄였습니다.

이 수정으로 Draw 관련 처리의 유지보수성이 향상되었습니다.

「OffScreen~~」의 명칭 통일

여러 곳에 사용하던 「OffScreenBuffer」및 「OffScreenFrame」라고 명명하던 것을 「OffScreenSurface」로 명칭을 변경했습니다.

이 변경으로 일반적인 호칭을 사용함으로써 Renderer 관련 처리의 유지보수성이 향상되었습니다.

Metal과 OpenGL의 그리기 차이 해소

for Native의 Metal에서 발생하던 OpenGL과의 그리기 차이를 해소했습니다.

4.2 SDK의 표현이 바람직한 경우의 수정 방법은 CHANGELOG.md에 기재했습니다.

Cubism Core API 변경

csmGetMocVersion 함수에 Cubism 5의 MOC3 파일 반환값 정의를 추가했습니다.

자세한 내용은 Live2D Cubism Core API 레퍼런스를 참조하십시오.