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) | [Contributing](#contributing) >> <br><br><br><br> ## 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.  * [Support TextMeshPro](#support-textmeshpro) #### Components | Component | Description | Screenshot | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | SoftMask | Use instead of Mask for smooth masking.<br><br>**Show Mask Graphic:** Show the graphic that is associated with the Mask render area.<br>**Desampling Rate:** The desampling rate for soft mask buffer. The larger the value, the better the performance but the lower the quality.<br>**Softness:** The value used by the soft mask to select the area of influence defined over the soft mask's graphic.<br>**Ignore Parent:** Should the soft mask ignore parent soft masks?<br>**Part Of Parent:** Is the soft mask a part of parent soft mask? | ![softmask][] | | SoftMaskable | Add this component to Graphic under SoftMask for smooth masking.<br><br>**Use Stencil:** Use stencil buffer to mask. If disabled, the stencil buffer is ignored.<br>**RaycastFilter:** Use soft-masked raycast target. **This option is expensive.**<br>**Mask Interaction:** The interaction for each mask layers. | ![softmaskable][] | [softmask]:https://user-images.githubusercontent.com/12690315/90349065-44e5e780-e073-11ea-8ca2-c005bff90def.png [softmaskable]:https://user-images.githubusercontent.com/12690315/90349068-47e0d800-e073-11ea-9749-18df13b8cb87.png <br><br><br><br> ## Demo [WebGL Demo](http://mob-sakai.github.io/SoftMaskForUGUI) <br><br><br><br> ## Installation #### Requirement * Unity 2017.1 or later (2018.x, 2019.x and 2020.x are included) * 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) <br><br><br><br> ## How to play demo - For Unity 2019.1 or later - Open `Package Manager` window and select `UI Soft Mask` package in package list and click `Demo > Import in project` button - For Unity 2018.4 or earlier - Click `Assets/Samples/UISoftMask/Import Demo` from menu The assets will be imported into `Assets/Samples/UI Soft Mask/{version}/Demo`. Open `UISoftMask_Demo` scene and play it. <br><br><br><br> ## 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! <br><br><br><br> ## Usage with TextMeshPro To use SoftMask with TextMeshPro, import a sample asset. - For Unity 2019.1 or later - Open `Package Manager` window and select `UI Soft Mask` package in package list and click `TextMeshPro Support > Import in project` button - For Unity 2018.4 or earlier - Click `Assets/Samples/UISoftMask/Import TextMeshPro Support` from menu The assets will be imported into `Assets/Samples/UI Soft Mask/{version}/TextMeshPro Support`. **NOTE:** You must import `TMP Essential Resources` before using. They include shaders, fonts, etc.  **NOTE:** If the shader error is not resolved, reimport the shader. Or, import the `TextMeshPro Support` again. <br><br><br><br> ## Support soft masks with your custom shaders Only a few steps are needed to support soft mask in your custom shaders! 1. Duplicate your shader file and add the ` (SoftMaskable)` suffix to the file name. ``` Your_Custom_Shader.shader -> Your_Custom_Shader (SoftMaskable).shader ``` 1. Modify the shader name (defined at the beginning of the shader file) as follows: - Add `Hidden/` prefix - Add ` (SoftMaskable)` suffix ``` Shader "UI/Your_Custom_Shader" -> Shader "Hidden/UI/Your_Custom_Shader (SoftMaskable)" ``` 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://github.com/mob-sakai/SoftMaskForUGUI/blob/upm/Shaders/Resources/UI-Default-SoftMaskable.shader). <br><br><br><br> ## Contributing ### Issues Issues are very valuable to this project. - Ideas are a valuable source of contributions others can make - Problems show where this project is lacking - With a question you show where contributors can improve the user experience ### Pull Requests Pull requests are, a great way to get your ideas into this repository. See [CONTRIBUTING.md](/../../blob/upm/CONTRIBUTING.md). ### Support This is an open source project that I am developing in my spare time. If you like it, please support me. With your support, I can spend more time on development. :) [](https://www.patreon.com/join/2343451?) [](https://github.com/users/mob-sakai/sponsorship) <br><br><br><br> ## License * MIT * © UTJ/UCL ## 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