Texture specifications for masks (UE)

Updated: 09/05/2024

This page contains statements regarding the alpha version.

Summary

With the default behavior of the Cubism SDK for Unreal Engine, all models displayed on each level share a single mask texture.

This section describes the specifications for mask textures in the Cubism SDK for Unreal Engine.

Creating textures for masks

If a texture for the mask does not exist when the model is spawned into the level, a CubismMaskTexture actor is automatically created and assigned to the model.
If a default CubismMaskTexture actor already exists in the level, it will be assigned to the model each time the model is spawned.
If you want to apply a separate mask texture to each model, create your own CubismMaskTexture actor and assign the reference to the MaskTexture property of the CubismRendererComponent.

Texture settings for masks

In the Unreal Engine, textures are managed as render targets.
Each mask texture can be individually configured with the size of the render target, the number of pieces, and the level of detail of the mask.

To set these, modify the following properties in the CubismMaskTextureComponent of the CubismMaskTexture actor.

Property	Description
Size	Set the height and width of the render target. The default setting is 4096 px. Adjust it according to the texture size of the model.
UseMultiRenderTargets	Specify whether to use multiple render targets. The default setting is false. When the setting is false, the masks registered in the mask texture are scaled down according to the number of them so that all the masks fit into a single render target. When the setting is true, if the registered masks cannot fit into a single render target, a render target is created for the amount necessary to fit the masks until MaxRenderTargetCount, described below, is reached. After the number of render targets reaches MaxRenderTargetCount, all masks are scaled down and registered according to the number of them to fit into the upper limit of render targets, as if the setting were false.
MaxRenderTargetCount	CubismMaskTexture Set the maximum number of render targets the actor can hold. Ignored when UseMultiRenderTargets is false.
LOD	Set the level of detail of the registered masks. Each increment of LOD by 1 divides the render texture into 4 parts. This reduces the area allocated to each registered mask, thereby halving the resolution. This value can only be manipulated when UseMultiRenderTargets is true and can be set small until the number of render targets reaches MaxRenderTargetCount. In addition, there is a minimum LOD value at which all registered masks can fit into a single render target, and no LOD greater than that value can be set. If you want to increase the resolution of the registered mask, decrease the LOD value.

With the properties above, the maximum number of render targets that can be tolerated in terms of performance is set as MaxRenderTargetCount, and the allowed LOD is set according to the number of registered masks, allowing for flexible adjustment of the mask resolution managed by the CubismMaskTexture actor.

Note that it is not possible to apply masks of different resolutions within a single model. If you want to set the mask resolution for each model, assign a different CubismMaskTexture actor to each model.