Cubism 5.3 기능의 SDK 호환성 및 제한 정보

업데이트： 2025/08/26

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

개요

이 섹션에서는 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 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 오브젝트는 BackToFrontZ 등의 Transform.localPosition.z를 이용한 정렬이 가능하다.
• 마스크 그리기는 전처리 마스크 방식으로 수행된다.

새로운 기능을 이용한 모델 렌더링 방식

• 마스크 그리기는 고선명 마스크 방식으로 수행된다.
• 각 그리기 오브젝트(Drawable·Offscreen)는 CubismRenderer.DrawObject() 내에서 그리기 처리한다.
• 각 그리기 오브젝트는 한 장의 RenderTexture에 그려진 후 Plane에 RenderTexture의 그리기를 적용하는 형태로 그려진다.
• 각 그리기 오브젝트는 BackToFrontOrder 또는 FrontToBackOrder로 정렬된다.

새로운 기능을 이용한 모델 렌더링 방식에서 발생하는 영향

새로운 기능을 이용한 모델의 렌더링 방식에서는 「모델의 Drawable 사이에 다른 스프라이트 끼우기」에 기재된 바와 같은 MeshRenderer.sortingOrder나 Transform.localPosition.z 등을 이용해 Unity 오브젝트를 그리기에 끼어들게 하는 처리를 실시할 수 없게 됩니다.

이러한 영향을 억제하기 위한 확장 기능을 향후 구현 예정입니다.

Cubism Core API 변경

csmGetDrawableRenderOrders 함수를 제거하고 csmGetRenderOrders 함수를 새로 추가했습니다.

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

부하 관련

블렌드 모드

블렌드 모드의 부하는 블렌드 모드를 1장이라도 사용하면 모델 전체에 극히 약간의 부하가 발생합니다. 또한 사용 매수마다 부하가 증가합니다.

그 부하는 사용하고 있는 그리기 API의 종류·버전에 따라 다릅니다. 예를 들어 OpenGL의 경우 glTextureBarrier를 사용할 수 있는 환경이면 사용할 수 없는 환경보다 부하가 줄어듭니다.

오프스크린 렌더링

오프스크린 렌더링의 부하는 하나씩 사용할 때마다 화면 크기의 오프스크린을 생성하기 때문에 부하가 발생합니다.

또한 오프스크린 렌더링을 하나라도 사용하고 있는 경우 모델 구조의 분석 처리를 모델 불러오기 시에 실시하기 때문에 모델 불러오기 속도가 대폭 저하됩니다.