SoftMaskForUGUI
===
UI Soft Mask is a smooth masking component for Unity UI (uGUI) elements.
[](https://openupm.com/packages/com.coffee.softmask-for-ugui/)
[](https://github.com/mob-sakai/SoftMaskForUGUI/releases)
[](https://github.com/mob-sakai/SoftMaskForUGUI/releases)
[](https://github.com/mob-sakai/SoftMaskForUGUI/blob/upm/LICENSE.txt)
[](http://makeapullrequest.com)
[](https://github.com/mob-sakai/SoftMaskForUGUI/subscription)
[](https://twitter.com/intent/follow?screen_name=mob_sakai)
<< [Description](#Description) | [WebGL Demo](#demo) | [Installation](#installation) | [Usage](#usage) | [For Your Custom Shader](#support-soft-masks-with-your-custom-shaders) >>
## Description
By using SoftMask instead of the default Mask component, you can beautifully represent the rounded edges of UI elements.
#### Features
* SoftMask is compatible with Mask.
* You can adjust the visible part.
* Text, Image, RawImage can be used as a masking.
* Support multiple-sprites and SpriteAtlas.
* Support up to 4 nested soft masks.
* Support scroll view.
* Support inversed soft mask.
* Support overlay, camera space and world space.
* (Option) Raycast is filtered only for the visible part.
* Contain soft maskable UI shader.
* Support soft masks in your custom shaders by adding just 3 lines. For details, please see [Development Note](#support-soft-masks-in-your-custom-shaders).
* Adjust soft mask buffer size to improve performance.
* Convert existing Mask to SoftMask from context menu.
* Render the soft mask buffer only when needed to improve performance.
* Add a SoftMaskable component to the child UI elements of SoftMask from the inspector.
* Preview soft mask buffer in inspector.
* Make multiple holes on one background by 'Parts of parent' option.
#### Components
|Component|Description|Screenshot|
|-|-|-|
|SoftMask|Use instead of Mask for smooth masking.
**Show Mask Graphic:** Show the graphic that is associated with the Mask render area.
**Desampling Rate:** The desampling rate for soft mask buffer. The larger the value, the better the performance but the lower the quality.
**Softness:** The value used by the soft mask to select the area of influence defined over the soft mask's graphic.
**Ignore Parent:** Should the soft mask ignore parent soft masks?
**Part Of Parent:** Is the soft mask a part of parent soft mask?|
|
|SoftMaskable|Add this component to Graphic under SoftMask for smooth masking.
**Inverse:** The graphic will be visible only in areas where no mask is present.|
|
## Demo
[WebGL Demo](http://mob-sakai.github.io/SoftMaskForUGUI)
## Installation
#### Requirement
* Unity 2017.1 or later
* No other SDK are required
#### Using OpenUPM (for Unity 2018.3 or later)
This package is available on [OpenUPM](https://openupm.com).
You can install it via [openupm-cli](https://github.com/openupm/openupm-cli).
```
openupm add com.coffee.softmask-for-ugui
```
#### Using Git (for Unity 2018.3 or later)
Find the manifest.json file in the Packages folder of your project and edit it to look like this:
```js
{
"dependencies": {
"com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git",
...
},
}
```
To update the package, change suffix `#{version}` to the target version.
* e.g. `"com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git#1.0.0",`
Or, use [UpmGitExtension](https://github.com/mob-sakai/UpmGitExtension) to install and update the package.
#### For Unity 2018.2 or earlier
1. Download a source code zip file from [Releases](https://github.com/mob-sakai/SoftMaskForUGUI/releases) page
2. Extract it
3. Import it into the following directory in your Unity project
- `Packages` (It works as an embedded package. For Unity 2018.1 or later)
- `Assets` (Legacy way. For Unity 2017.1 or later)
## How to play demo
#### For Unity 2019.1 or later
1. Open `Package Manager` window and select `UI Soft Mask` package in package list
2. Click `Import in project` button
3. The demo will be imported into `Assets/Samples/UI Soft Mask/{version}/Demo`｡
Open `UISoftMask_Demo` scene and play it
#### For Unity 2018.4 or earlier
1. Select `Assets/Samples/UI Soft Mask Demo` from menu
2. The demo will be imported into `Assets/Samples/UI Soft Mask/{version}/Demo`.
Open `UISoftMask_Demo` scene and play it
## Usage
1. Add a SoftMask component instead of Mask component.
Or, convert an existing Mask component to SoftMask component from the context menu.
2. Add a SoftMaskable components to the child UI elements of the SoftMask component.
Or, add a SoftMaskable components from the inspector of the SoftMask component.
3. Adjust softness setting of SoftMask.
4. Enjoy!
## Support soft masks with your custom shaders
With just three additional lines, you can now support softmasks in your custom shaders!
1. Add `#pragma` and `#include` directives, where `SOFTMASK_EDITOR` is an editor-only keyword and is not included in the build.
If you didn't use package manager to install, include `SoftMask.cginc` in the appropriate path instead.
```
#include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc"
#pragma shader_feature __ SOFTMASK_EDITOR
```
2. Apply a soft mask in the fragment shader.
This operation determines the final alpha according to the soft mask buffer.
- `IN.vertex`: the clip position
- `IN.worldPosition`: the world position
```
color.a *= SoftMask(IN.vertex, IN.worldPosition);
```
As an example of implementation, please see [UI-Default-SoftMask.shader](https://raw.githubusercontent.com/mob-sakai/SoftMaskForUGUI/upm/Shaders/Resources/UI-Default-SoftMask.shader).
## License
* MIT
* © UTJ/UCL
## Support
This is an open-source project that I am developing in my free time.
If you like it, you can support me.
By supporting, you let me spend more time working on better tools that you can use for free. :)
[](https://www.patreon.com/join/2343451?)
[](https://github.com/users/mob-sakai/sponsorship)
## Author
[mob-sakai](https://github.com/mob-sakai)
[](https://twitter.com/intent/follow?screen_name=mob_sakai)
## See Also
* GitHub page : https://github.com/mob-sakai/SoftMaskForUGUI
* Releases : https://github.com/mob-sakai/SoftMaskForUGUI/releases
* Issue tracker : https://github.com/mob-sakai/SoftMaskForUGUI/issues
* Change log : https://github.com/mob-sakai/SoftMaskForUGUI/blob/upm/CHANGELOG.md