Documentation for version 1.6
Asset Store | Demo | Email | Forum
What is Soft Mask? 2
Features 3
Getting Started 3
The Use of Soft Mask 3
Applying a Soft Mask 3
Replacing a standard mask by a Soft Mask 4
Disabling a Soft Mask 4
Using Soft Mask with TextMesh Pro 4
Adding support of Soft Mask to custom shaders 4
Using Soft Mask in code 5
Reference 6
Interaction with the Graphic component 6
Integration with TextMesh Pro 6
Prefabs 8
Nested Masks 9
Properties 10
Limitations 13
Performance 14
Compatibility 14
Support and feedback 14
Change history 14
What is Soft Mask?
Soft Mask is a component for smooth masking of UI elements in Unity.
After adding to a Game Object, Soft Mask “masks” its child elements. Soft Mask gives a quite similar
effect as standard Mask and Mask Rect 2D but has some advantages over them.
● Unlike Rect Mask 2D, Soft Mask does not need to be axis-aligned and may be rotated freely.
● Unlike Mask, Soft Mask may be semi-transparent, which allows you to create smooth
transitions from visible to invisible parts of an image, and also use inclined or rounded edges
of UI elements.
Soft Mask
Unity’s Standard Mask
(notice visual artifacts on the rounded
corners caused by cutoff)
Features
● Ease of use: just place it on a parent element in the same way as standard Mask. There’s no
need to assign special materials or modify the masked elements in any other way.
● Support for Image, Raw Image, Sprite, and Texture: use standard Image or Raw Image
components as a mask. Or set a Sprite, Texture or even Render Texture explicitly.
● Support for TextMesh Pro: mask your high-quality SDF texts along with other UI elements.
● Custom shader support: make your UI shaders compatible with Soft Mask by adding just a
few lines to the shader code.
● Mask Inversion: invert the inner and outer areas of the mask separately.
● Real-time updates: change the configuration at runtime — create, destroy, enable, disable,
move, rotate and reorder a mask or masked elements.
● Raycast filtering: restrict input processing to only visible parts of the masked UI.
● Flexible adjustment of mask’s color channels: use black and white images, images with
transparency or set a custom weight for each color channel.
Getting Started
Soft Mask requires no additional setup. Just import the package, and you are ready to go.
The package includes example scenes so that you can see Soft Mask in action right away. These
scenes can be found in the Samples folder. This folder is unnecessary for the Soft Mask to work, so
you can safely remove it from your project if you want.
If you are using UnityScript instead of C#, you can move the imported SoftMask folder to the
Plugins folder. It allows you to use Soft Mask in UnityScript code.
The Use of Soft Mask
Applying a Soft Mask
To apply a Soft Mask, follow the steps below.
1. Add a UI/Soft Mask component to a Game Object in the same way as you add a standard
Mask.
2. Set up a Soft Mask:
○ If you want the mask image to be visible (as with the Show Mask Graphic option of
the standard Mask), ensure that the Game Object has an Image or Raw Image
component. The Soft Mask will use the same image that is rendered by this
component.
○ If you do not want the mask image to be visible and only want to use it as a mask,
you have two ways to do this:
■ Select Sprite or Texture in the Source drop-down list and set a sprite or
texture for the mask. In this case, the Game Object doesn't have to have a
Graphic component at all.
■ Alternatively, if you already have an Image or Raw Image on the Game
Object, you can just disable it. Soft Mask will continue masking. Note that
this option has some limitations, for details see Interaction with the Graphic
component.
Replacing a standard mask by a Soft Mask
You can easily replace a standard Mask that uses an Image or Raw Image component by a Soft Mask.
To do so, follow the steps below.
1. Select one or more Game Objects with Mask that you want to convert.
2. Execute Tools / Soft Mask / Convert Mask to Soft Mask menu.
This menu is available only when all the selected objects have a standard Mask component as well an
either Image or Raw Image component. There are also several cases when the menu is available but
conversion is still not possible. In these cases a message box with a detailed explanation is shown up
on a conversion attempt.
All the changes made by this menu are recorded to the Undo history, so if you are not satisfied with
the result, you may easily roll back the changes by the standard Undo command.
Disabling a Soft Mask
If you want to turn off masking, disable the Soft Mask component on the Game Object. Unlike the
standard Mask, when the Graphic component of a Game Object is disabled, Soft Mask still keeps
masking.
Using Soft Mask with TextMesh Pro
To enable Soft Mask to mask TextMesh Pro texts in your project, follow the steps below.
1. Import TextMesh Pro resources:
○ For the package version (available starting from 2018.2) execute the Window /
TextMesh Pro / Import TMP Essential Resources menu.
○ For the source or binary version just import TextMesh Pro package into your project.
2. Click the menu Tools / Soft Mask / Update TextMesh Pro Integration. This will generate
versions of TextMesh Pro shaders with Soft Mask support which will be used automatically
on TextMesh Pro UGUI objects inside a Soft Mask.
For more information on using SoftMask with TextMesh Pro, see Integration with TextMesh Pro.
Adding support of Soft Mask to custom shaders
Soft Mask is able to mask all Graphic components which use the standard Unity UI shader. If you
want to use a custom shader for rendering masked UI elements (your own ones or from another
package from Asset Store), you can adapt them to work with Soft Mask.
To add the support of Soft Mask to a shader, you have to insert some declarations and instructions
into the shader code. As an example of what exactly should be done, see the shader
SoftMask/Samples/Materials/WaveWithSoftMask.shader. This shader is used by the
04-CustomShaders example. All the instructions required for Soft Mask support have the comment
// Soft Mask Support
For a more detailed step-by-step guide, see Custom Shader Tutorial.
Using Soft Mask in code
Everything related to Soft Mask is contained in the SoftMasking namespace. All the properties
described in the Properties section are also available from the code. The public interface of SoftMask
is documented via XML comments.
If you are interested in how Soft Mask is implemented, you can find an overall description at the
beginning of the SoftMask class.
Reference
Interaction with the Graphic component
Unlike Unity’s standard Mask, Soft Mask doesn’t rely on the rendering of the Graphic component.
When you set Source to Graphic, Soft Mask just picks up some properties (texture and border mode
or UV rectangle) from the Graphic component but doesn’t really use it in itself.
This approach has some limitations compared to a standard Mask:
● You can use only Image or Raw Image of all Graphic components as a mask source. Text and
any other Graphics will not work as a mask.
● Soft Mask doesn’t support the Filled type and Fill Center option of Image.
● The color set in the properties of Image or Raw Image isn’t taken into account by Soft Mask.
Only the texture is used.
When the Graphic component is disabled, Soft Mask continues to work, but it isn’t updated
accordingly when properties of the Graphic change. Despite the limitation, this operating mode may
be useful when you migrate from a standard Mask with the Show Mask Graphic option enabled to
Soft Mask.
Integration with TextMesh Pro
TextMesh Pro is a package that implements high-quality text rendering. Starting from 2018.2, it’s
included in Unity by default and available in Package Manager.
Soft Mask supports TextMesh Pro and can be used to mask TMPro texts. To make it possible, Soft
Mask includes a script that generates specializations of TMPro’s shaders with special Soft Mask
instructions. These shaders then replace the originals for masked text objects on the fly.
The shader generation should be invoked manually. It is available via the Tools / Soft Mask / Update
TextMesh Pro menu. The generated shaders are stored in the project, it’s a good idea to put them
under version control and share across the team. For more about generated shaders see Shader
Generation section.
Samples
There are two example scenes included in Soft Mask which demonstrate usage of Soft Mask with
TextMesh Pro. You can find these scenes in the Samples/Scenes/TextMeshPro folder.
If you open a TextMesh Pro sample scene and see no texts, chances are that you’re using an old
version of TextMesh Pro which was distributed via Asset Store. Soft Mask contains sample scenes
for these versions too, just try to open scenes from _ForOldBinaryTMProVersion and
_ForOldSourceTMProVersion subfolders until you find a working one.
Shader Generation
To activate integration the menu Tools / Soft Mask / Update TextMesh Pro Integration should be
executed. It runs a script that generates specializations of TextMesh Pro shaders with Soft Mask
