Clipping mask

(Updated 07/30/2020)

Clipping masks are often used, for example, for blinking movements.
This section describes the clipping mask procedure.

 

Clipping Mask Procedure

By specifying the ID of the ArtMesh to be masked, a clipping mask can be used.
Here are the steps to apply the clipping mask to the ArtMesh in the black eye area with the white eye ArtMesh.

First, select and copy the ArtMesh to be used as a mask (the white part of the eyes).

Select the ArtMesh to be clipped (the black eye area) and paste it into the [Clipping ID] field of the [Inspector] palette.

The ID of the ArtMesh to be used as a mask (ArtMesh36) is pasted into [Clipping ID], and the black eyes are clipped.

The following procedure can also be used to apply a clipping mask in the same way.

  1. Select the ArtMesh to be masked and copy the [ID] text in the [Inspector] palette.
  2. Select the ArtMesh to be clipped and paste it into the [Clipping ID] in the [Inspector] palette.

TIPS
Multiple ArtMeshes can be specified by separating them with a comma (e.g.: ArtMesh1, ArtMesh2...)

POINT
When used in video productions other than SDKs, clipping masks can be used extensively. 

 

Clipping notes when using SDK

If you intend to incorporate the software into an SDK for the purpose of game development, etc., please be sure to read the following notes.

• Clipping limit

In the clipping drawing method of Cubism 3 SDK or later, if the number of ID permutation types specified for clipping exceeds a certain number, the display may become distorted or other problems may occur.
Since the actual characteristics depend on the program implementation, please confirm the display on the actual device.

For more detailed principles, please refer to “Mask Preprocessing Methods” in the SDK manual.

• Load and performance degradation

In some environments, the load caused by clipping can be significant.
It is recommended that use be kept to the minimum necessary.

• Difference in Expression

The expression and appearance may differ depending on the environment, display size, and other factors.
If strict representation is required, please check with the actual device beforehand.

 
TIPS
The standard mask characteristics for each platform SDK are as follows:

Platform Name Maximum number of masks Range of masks to be provided Size of masks to be provided
Cubism SDK for Native 36/model*1 Rectangle containing all ArtMeshes to be clipped Variable according to number
Cubism SDK for Web 36/model Rectangle containing all ArtMeshes to be clipped Variable according to number
Cubism SDK for Unity 64/Scene Rectangle containing all ArtMeshes to be masked*2 Fixation

*1 In Cubism SDK for Native, CubismRenderer::_useHighPrecisionMask can be changed to “true” to generate a mask for each drawing.
   This removes the upper limit on the number of masks and ensures that the masks are always drawn with maximum quality.
*2 Cubism SDK for Unity differs from other for Native and for Web in the scope of mask preparation.
   For more information, see the Mask Characteristics section of “Comparison of UnitySDK and NativeSDK”.

 

 

About the white edge of the mask

When viewing a model with a clipping mask set in the Cubism Editor or Cubism SDK, the outline may appear to have a rim.

This is caused by the translucent areas in the mask outline that allow the colors of the underlying ArtMesh to show through.

Cubism's clipping masks are represented by the following two, each existing as a separate ArtMesh.

  • ArtMesh for Mask
  • ArtMesh for clipping cut by mask

Any translucent areas in the mask outline will have their opacity applied to the ArtMesh being cut out.

If the ArtMesh for the mask is visible, the color of the translucent area of the ArtMesh for the mask will be visible through the translucent area of the cut-out outline.


If the mask shape is not complex, it can be avoided by modifying the model using the following procedure.

  1. Duplicate ArtMesh for mask
  2. Change the ArtMesh for the specified mask from the original ArtMesh to the duplicated ArtMesh.
  3. Enlarge the duplicated ArtMesh so that the outline of the original is hidden.
  4. Set the opacity of this ArtMesh to 0%.
  5. Same transformation as the source of the duplicate.

 

Check the number of masks

Checking the number of masks on the editor

In Cubism Editor 4.0.03 or later, statistics information allows you to check the number of clippings in the model and the type of mask permutations.

 

 

Counting masks recognized by the SDK

The number of masks recognized by the SDK is identified by a sequence of IDs.
An example would be the following count.

Mask ID display Number of sheets to be recognized
ArtMesh1
ArtMesh1
ArtMesh2
2
ArtMesh1 , ArtMesh2
ArtMesh1
ArtMesh1 , ArtMesh2
ArtMesh2
3
ArtMesh1, ArtMesh2, ArtMesh3
ArtMesh1, ArtMesh2, ArtMesh3
ArtMesh1, ArtMesh2, ArtMesh3
ArtMesh1, ArtMesh2, ArtMesh3
1

 

If the combination is the same but in a different order, it is recognized as the same mask in for Native and for Web, but
for Unity, they are recognized as a different mask.

Mask ID display Number of recognitions in for Native, for Web Number of recognitions in for Unity
ArtMesh1,ArtMesh2
ArtMesh2,ArtMesh1
ArtMesh1,ArtMesh2
ArtMesh2,ArtMesh1
1 2

 

 

Confirmation with Cubism Viewer (for OW)

You can also check the number of mask ID permutations in Statistics in Cubism Viewer (for OW).

 

 

About Mask Warnings

A warning is issued if the mask used for the clipping mask is in an incorrect state.

 

Cautions when warnings occur

If an embedded file is output with a “Mask Warning” and then loaded into an application using the SDK
the following problems may occur.

Problems that occur:

  • Forced termination
  • Unable to load files for embedding
  • The display on the SDK and the Editor are different.

To avoid the above problems, warnings are issued for conditions that are “temporarily acceptable for editing but undesirable at output”.
Although it appears to be fine on Animator, we recommend a fix because future updates may change what is displayed.

 

The situation at the time the warning occurs

There are two main types of situations in which a “mask warning” may occur.

Key Lost:

The ArtMesh that will become the mask is invisible because it exists outside the key form of the parameter.
The display may differ significantly depending on the implementation of the application.

ArtMesh set to hidden and underdraw:

ArtMeshes that are set to hidden or underdraw will not be output with the standard settings when outputting files for incorporation.
Therefore, if the mask ArtMesh is loaded in the SDK as it is, the mask ArtMesh will indicate incorrect values, which may cause problems such as forced termination
.

Masks have been removed:

The ArtMesh that will become the mask has already been deleted and
the clipping column in the inspector of the clipping ArtMesh is set to “null”.

 

Case-specific model modification methods

1. If you want to refer to a transparent ArtMesh as a mask

Please respond by setting the opacity of the ArtMesh set for the mask to 0%.
If the ArtMesh is already keyformed and opacity is difficult to manipulate, use “Multiple Keys Editing” or set the deformer
as the ArtMesh's parent and manipulate opacity only at once.

TIPS
The behavior of the clipping mask depends on the implementation status.
Detailed notes should be discussed with the development staff before creating the model.

-> Comparison of UnitySDK and NativeSDK (for programmers)

2. If you want to refer to an ArtMesh that exists in a hidden part as a mask

In Cubism Editor 3.2.05 and later, the clipping mask itself is now released when all masks are hidden.
If an ArtMesh in a hidden part is set as a mask, the clipping mask will look unmasked.

If it is difficult to edit, temporarily move the ArtMesh set in the mask to the display part to accommodate the change.

TIPS
If there are masks that are hidden, the aforementioned warnings and errors will be displayed during moc3 export.
When used for embedded applications, as exporting moc3 in its non-displayed form may result in an unintended display,
be careful not to forget to put the part in the display state.

3.When you want to refer to a disappearing ArtMesh as a mask without interpolation, such as when switching arms

This is a case where you want to use the effect of the ArtMesh display disappearing when the key moves outside the range of the keyform without changing it.

In Cubism Editor 3.2.05 or later, if all masks are hidden, or if the object set as a mask is hidden outside the range of the keyform,
the clipping mask itself will be released.

As a workaround, create an empty ArtMesh and use it as a mask that is always visible.
For the empty ArtMesh, use “ArtMesh for hit detection”.
-> How to set up ArtMesh for judging hits

By setting the empty ArtMesh you created as a mask along with the “mask you want to turn off”, there will always be a mask in the visible state.
This will not release the clipping mask itself, but will allow the use of the effect of erasing the display outside the range of the keyform.

* In this case, there is no need to key in an empty ArtMesh. Position and size are not affected, so feel free to set them as you wish.
* If there are masks that are hidden, the aforementioned warnings and errors will be displayed at the time of moc3 export.
When using the model for embedded applications, it is recommended to consult with the developer before creating the model, as it may result in unintended displays depending on the implementation status.

 

Hide warnings

The warning can be hidden by unchecking the “Always show file/settings/mask settings” checkbox.

 

When ignoring warnings, check the display on the actual device before creating.

 

© 2010 - 2022 Live2D Inc.