-
-
Notifications
You must be signed in to change notification settings - Fork 270
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
223 additions
and
64 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -14,40 +14,49 @@ | |
|
|
||
| ## 📝 Description | ||
|
|
||
| <img src="https://github.com/mob-sakai/mob-sakai/assets/12690315/3cca20d0-8565-49d1-9f5c-0a6dbc2cb2eb" width="500"/> | ||
| <img src="https://gist.github.com/assets/12690315/fca4ae5f-4b55-41c8-a77e-9af3d469c864" width="500" alt=""/> | ||
|
|
||
| This package provides a soft masking for Unity UI (uGUI). | ||
| - **Soft Masking for Unity UI**: SoftMaskForUGUI provides a soft masking feature for Unity UI, allowing you to create more visually appealing UI effects. | ||
| - **Compatible with Mask**: SoftMask is fully compatible with the existing Mask component, making it easy to integrate into your current projects. | ||
| - **Support for Multiple Sprites and SpriteAtlas**: You can use multiple sprites and SpriteAtlas with SoftMask, giving you more flexibility in designing your UI. | ||
| - **Performance Optimization**: SoftMaskForUGUI is designed with performance in mind. It only renders the soft mask buffer when needed, helping to keep your game running smoothly. | ||
| - **Easy to Use**: Just add a `SoftMask` component instead of `Mask` component, or convert an existing `Mask` to `SoftMask` from the context menu. It's that simple! | ||
|
|
||
| #### 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-with-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) | ||
| - **Compatibility with Mask**: SoftMask is fully compatible with the existing Mask component. | ||
| You can convert an existing Mask to SoftMask from the context menu. | ||
|  | ||
| - **Adjustable Visible Part**: You can freely adjust the visible part of the mask. | ||
| <img height="200" src="https://gist.github.com/assets/12690315/5e8f37b2-74a9-4905-9fe9-b65f5c515e53"/> | ||
| - **Versatile Masking Options**: Text, Image, RawImage can be used as a masking graphic. | ||
| - **Support for Multiple Sprites and SpriteAtlas**: SoftMask supports multiple sprites and SpriteAtlas. | ||
| - **Nested Soft Masks**: SoftMask supports up to 4 nested soft masks. | ||
| <img height="200" src="https://gist.github.com/assets/12690315/12a6459f-f10c-48f9-95d0-854f122a2fbd"/> | ||
| - **Scroll View Support**: SoftMask supports scroll views. | ||
| - **All Render Mode Support**: SoftMask supports overlay, camera space, and world space. | ||
| - **Soft-Maskable UI Shader Included**: The package includes a soft-maskable UI shader for `UI/Dafault`. | ||
| - **Custom Shader Support**: You can make your custom shaders soft-maskable with little modification. For details, please see [Development Note](#usage-with-your-custom-shaders). | ||
| - **Performance/Quality Adjustment**: You can adjust the soft mask buffer size to improve performance or quality. | ||
| <img height="200" src="https://gist.github.com/assets/12690315/fbd298c3-bac3-4410-93fe-1b7a53b0d299"/> | ||
| - **Efficient Rendering**: The soft mask buffer will be updated only when needed to improve performance. | ||
| - **SoftMaskable Component**: `SoftMaskable` component will be added automatically at runtime as needed. | ||
| - **Soft Mask Buffer Preview**: You can preview the soft mask buffer in the inspector. | ||
| <img height="200" src="https://gist.github.com/assets/12690315/f0215026-f536-414c-ad69-2db2a472f6f1"/> | ||
| - **Anti-Alias Masking Mode**: If you don't need semi-transparent masks, you can use the more performant "Anti-Aliasing Masking Mode". | ||
| <img height="200" src="https://gist.github.com/assets/12690315/45fde8f9-27c6-4294-bd3a-b5be8e6cb6bd"/> | ||
| - **Masking Shape**: You can add or remove mask region using `MaskingShape` component. | ||
| <img height="200" src="https://gist.github.com/assets/12690315/4c7f36fa-0280-4852-83ce-9b5bcca62195"/> | ||
| - **Inverse Masking**: Use `MaskingShape` component to inverse masking. You can implement effects such as iris out. | ||
| <img height="200" src="https://gist.github.com/assets/12690315/5e61a4f0-9968-4df9-b0f5-4938560d6128"/> | ||
| - **Ray-cast Filtering**: Ray-casts are filtered only for the visible part. | ||
| This feature is useful for preventing clicks on masked parts during tutorials. | ||
| <img height="200" src="https://gist.github.com/assets/12690315/ed202fd8-b3c7-49ea-a8f7-fb78affb13a9"/> | ||
| - **Stereo Support**: A shader macro `UI_SOFT_MASKABLE_STEREO` has been added for VR. | ||
| <img height="200" src="https://gist.github.com/assets/12690315/3ade0585-f621-4fde-b8ad-baa7f588fe7d"/> | ||
| - **TextMeshProUGUI Support**: Support TextMeshProUGUI by importing additional samples. | ||
| For details, please see [Support TextMeshPro](#usage-with-textmeshpro). | ||
| <img height="200" src="https://gist.github.com/assets/12690315/4649ba1c-a0a1-40b8-99dc-1531606fa9a4"/> | ||
|
|
||
| <br><br> | ||
|
|
||
|
|
@@ -63,63 +72,213 @@ _This package requires **Unity 2019.4 or later**._ | |
|
|
||
| #### Install via OpenUPM | ||
|
|
||
| This package is available on [OpenUPM](https://openupm.com) package registry. | ||
| This is the preferred method of installation, as you can easily receive updates as they're released. | ||
| - This package is available on [OpenUPM](https://openupm.com) package registry. | ||
| - This is the preferred method of installation, as you can easily receive updates as they're released. | ||
| - If you have [openupm-cli](https://github.com/openupm/openupm-cli) installed, then run the following command in your project's directory: | ||
| ``` | ||
| openupm add com.coffee.softmask-for-ugui | ||
| ``` | ||
| - To update the package, use Package Manager UI (`Window > Package Manager`) or run the following command: | ||
| ``` | ||
| openupm add [email protected] | ||
| ``` | ||
|
|
||
| #### Install via UPM (with Package Manager UI) | ||
|
|
||
| - Click `Window > Package Manager` to open Package Manager UI. | ||
| - Click `+ > Add package from git URL...` and input the repository URL: `https://github.com/mob-sakai/SoftMaskForUGUI.git` | ||
|  | ||
| - To update the package, change suffix `#{version}` to the target version. | ||
| - e.g. `https://github.com/mob-sakai/SoftMaskForUGUI.git#2.0.0` | ||
|
|
||
| #### Install via UPM (Manually) | ||
|
|
||
| - Open the `Packages/manifest.json` file in your project. Then add this package somewhere in the `dependencies` block: | ||
| ```json | ||
| { | ||
| "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#2.0.0",` | ||
|
|
||
| #### Install as Embedded Package | ||
|
|
||
| 1. Download a source code zip file from [Releases](https://github.com/mob-sakai/SoftMaskForUGUI/releases) and extract it. | ||
| 2. Place it in your project's `Packages` directory. | ||
|  | ||
| - If you want to fix bugs or add features, install it as an embedded package. | ||
| - To update the package, you need to re-download it and replace the contents. | ||
|
|
||
| If you have [openupm-cli](https://github.com/openupm/openupm-cli) installed, then run the following command in your project's directory: | ||
| <br><br> | ||
|
|
||
| ``` | ||
| openupm add com.coffee.softmask-for-ugui | ||
| ``` | ||
| ## 🔄 Upgrading from v1 to v2 | ||
|
|
||
| #### Install via UPM (using Git URL) | ||
| When updating from v1 to v2, the following breaking changes are included: | ||
|
|
||
| Navigate to your project's Packages folder and open the `manifest.json` file. Then add this package somewhere in the `dependencies` block: | ||
| 1. **Shader macros changes**: The existing shader macros are changed. | ||
| - `SOFTMASK_EDITOR` -> `UI_SOFT_MASKABLE`, `UI_SOFT_MASKABLE_EDITOR` and `UI_SOFT_MASKABLE_STEREO` | ||
|
|
||
| ```json | ||
| { | ||
| "dependencies": { | ||
| "com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git", | ||
| ... | ||
| }, | ||
| } | ||
| ``` | ||
| 2. **API changes**: Some APIs are obsolete. | ||
| - SoftMask.softness: Use SoftMask.softMaskingRange instead. | ||
| - SoftMask.partOfParent: Use `MaskingShape` component instead. | ||
|
|
||
| 3. **`SoftMaskable` behaviour**: `SoftMaskable` component is no longer required to be added explicitly. | ||
| It will be added automatically at runtime as needed. | ||
|
|
||
| To update the package, change suffix `#{version}` to the target version. | ||
| To apply these changes, please follow the steps below: | ||
|
|
||
| * e.g. `"com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git#2.0.0",` | ||
| 1. Click `Edit > Project Settings` to open the Project Settings window. | ||
|
|
||
| 2. Select `UI > SoftMask` category. | ||
|
|
||
| 3. Click on "Upgrade All Assets V1 to V2" to modify the assets. | ||
|  | ||
|
|
||
| - NOTE: If you select "Dry Run", you can check the changes before upgrading. | ||
|  | ||
|  | ||
|
|
||
| <br><br> | ||
|
|
||
| ## 🚀 Usage | ||
|
|
||
| 1. Add a `SoftMask` component instead of `Mask` component. | ||
| 1. Add a `SoftMask` component instead of `Mask` component. | ||
| Or, convert an existing `Mask` component to `SoftMask` component from the context menu (`Convert To SoftMask`). | ||
|  | ||
| 2. (Optional) By placing the `MaskingShape` component under `SoftMask`, you can add or remove the mask range. | ||
|  | ||
| 3. Enjoy! | ||
|  | ||
|
|
||
| 2. Adjust the soft mask parameters in the inspector. | ||
|  | ||
|
|
||
| 3. (Optional) By placing the `MaskingShape` component under `SoftMask`, you can add or remove the masking region. | ||
|  | ||
|
|
||
| 4. Enjoy! | ||
|
|
||
| <br><br> | ||
|
|
||
| #### Usage with TextMeshPro | ||
| #### Comparison of Masking Mode | ||
|
|
||
| Open the `Package Manager` window and select the `UI Soft Mask` package in the package list and click the `TextMeshPro Support > Import in project` button. | ||
| <img height="200" src="https://gist.github.com/assets/12690315/920c6e13-3e1a-430a-b431-ae7f425aa3b2" alt=""/> | ||
|
|
||
| The assets will be imported into `Assets/Samples/UI Soft Mask/{version}/TextMeshPro Support`. | ||
| - **Soft Masking**: Smooth mask with semi-transparency. | ||
| Requires memory for `RenderTexture` and [soft-maskable shader](#usage-with-your-custom-shaders). | ||
| - **Anti-Aliasing**: Less jagged stencil mask. | ||
| It does not require `RenderTexture` or soft-maskable shader, and works faster. | ||
| - **Normal**: Same as `Mask` component's stencil mask. | ||
|
|
||
| **NOTE:** You must import [TMP Essential Resources](https://docs.unity3d.com/Packages/[email protected]/manual/index.html#installation) before using. If the shader error is not resolved, reimport the shader. | ||
| <br><br> | ||
|
|
||
| #### Usage with your custom shaders | ||
| #### Masking Shape | ||
|
|
||
| <img height="200" src="https://gist.github.com/assets/12690315/4c7f36fa-0280-4852-83ce-9b5bcca62195" alt=""/> | ||
|
|
||
| - `MaskingShape` component allows you to add or remove the masking region. | ||
| - Placing `MaskingShape` component (with any `Graphic`) under `SoftMask` component. | ||
|  | ||
| - You can use it not only with `SoftMask` component but also with `Mask` component. | ||
| - If the `MaskingMode` is `AntiAliasing` or `Normal`, or if you are using the `Mask` component, the `MaskingShape` component must be placed above the masked `Graphic` in the hierarchy. This is a limitation based on the stencil mask. | ||
| - The available features depend on the `Masking Mode`. | ||
|  | ||
|  | ||
|  | ||
|
|
||
| <br><br> | ||
|
|
||
| #### Rect Transform Fitter | ||
|
|
||
|  | ||
|
|
||
| There are two ways to support soft masks with custom shaders. | ||
| - `RectTransformFitter` component follows the target RectTransform. | ||
| - You can specify the properties to follow (position, rotation, scale, delta size) with `RectTransformFitter.targetProperties`. | ||
| - By combining it with the `MaskingShape` component, you can implement an effect that displays only the buttons during the tutorial. | ||
|
|
||
| NOTE: To support soft masks, you need to add the `(SoftMaskable)` suffix to the shader name. | ||
| <br><br> | ||
|
|
||
| #### Project Settings | ||
|
|
||
|  | ||
|
|
||
| - Click `Edit > Project Settings` to open the Project Settings window and then select `UI > SoftMask` category. | ||
|
|
||
| <br><br> | ||
|
|
||
| #### Usage with Scripts | ||
|
|
||
| ```csharp | ||
| var softMask = gameObject.GetComponent<SoftMask>(); | ||
| softMask.maskingMode = SoftMask.MaskingMode.SoftMasking; | ||
| softMask.downSamplingRate = SoftMask.DownSamplingRate.x2; | ||
| softMask.softMaskingRange = new MinMax01(0.5f, 0.75f); | ||
| ``` | ||
|
|
||
| <br><br> | ||
|
|
||
| #### Usage with TextMeshPro | ||
|
|
||
| 1. First, you must import [TMP Essential Resources](https://docs.unity3d.com/Packages/[email protected]/manual/index.html#installation) before using. | ||
|  | ||
|
|
||
| 2. Open the `Package Manager` window and select the `UI Soft Mask` package in the package list and click the `TextMeshPro Support > Import` button. | ||
| NOTE: If you are using TextMeshPro v3.2+ or v4.0+, click the `TextMeshPro Support v3.2 or v4.0 > Import` button instead. | ||
|  | ||
|
|
||
| 3. The assets will be imported under `Assets/Samples/UI Soft Mask/{version}`. | ||
|  | ||
|
|
||
| <br> | ||
|
|
||
| #### Usage with your custom shaders | ||
|
|
||
| 1. **Hybrid (recommended)**: Add a `SoftMaskable` variant to the existing shader. | ||
| This way requires minimal changes (add few lines). | ||
| 2. **Separate**: Create a new shader with a `SoftMaskable` variant. | ||
| Use this way for built-in shaders that cannot be edited, like `UI/Default`. | ||
| Here, let's make [UI/Additive](https://raw.githubusercontent.com/mob-sakai/SoftMaskForUGUI/develop/Assets/Demos/SoftMaskable%20Shader/UI-Additive.shader) custom shader soft-maskable. There are two ways to support SoftMask with custom shaders. | ||
|
|
||
| - **Hybrid (recommended)**: Add soft-maskable variants to the existing shader. | ||
| Modify the shader as follows: | ||
| ```shaderlab | ||
| // Add the ` (SoftMaskable)` suffix to the shader name. | ||
| Shader "UI/Additive (SoftMaskable)" | ||
| // Import "UISoftMask.cginc" and add shader variants. | ||
| #include "Packages/com.coffee.softmask-for-ugui/Shaders/UISoftMask.cginc" | ||
| #pragma multi_compile_local __ UI_SOFT_MASKABLE UI_SOFT_MASKABLE_EDITOR // default, soft-maskable, soft-maskable (for editor) | ||
| #pragma multi_compile_local __ UI_SOFT_MASKABLE_STEREO // (Optional) for stereo rendering (VR) | ||
| // "SoftMask" function returns [0-1]. Multiply this by the final output. | ||
| color.a *= SoftMask(IN.vertex, mul(unity_ObjectToWorld, IN.worldPosition)); | ||
| // Use "SoftMaskClip" function instead of "clip" | ||
| #ifdef UNITY_UI_ALPHACLIP | ||
| SoftMaskClip (color.a - 0.001); | ||
| #endif | ||
| ``` | ||
| - Result: [UI/Additive (SoftMaskable)](https://raw.githubusercontent.com/mob-sakai/SoftMaskForUGUI/develop/Assets/Demos/SoftMaskable%20Shader/UI-Additive-SoftMaskable.shader) | ||
| - **Separate**: Create a new shader with soft-maskable variants. | ||
| Use this way for built-in shaders that cannot be edited, like `UI/Default`. | ||
| Modify the shader as follows: | ||
| ```shaderlab | ||
| // Add the `Hidden/` prefix and ` (SoftMaskable)` suffix to the shader name. | ||
| Shader "Hidden/UI/Additive (SoftMaskable)" | ||
| // Import "UISoftMask.cginc" and add shader variants. | ||
| #include "Packages/com.coffee.softmask-for-ugui/Shaders/UISoftMask.cginc" | ||
| #pragma multi_compile_local UI_SOFT_MASKABLE UI_SOFT_MASKABLE_EDITOR // soft-maskable, soft-maskable (for editor) | ||
| #pragma multi_compile_local __ UI_SOFT_MASKABLE_STEREO // (Optional) for stereo rendering (VR) | ||
| // "SoftMask" function returns [0-1]. Multiply this by the final output. | ||
| color.a *= SoftMask(IN.vertex, mul(unity_ObjectToWorld, IN.worldPosition)); | ||
| // Use "SoftMaskClip" function instead of "clip" | ||
| #ifdef UNITY_UI_ALPHACLIP | ||
| SoftMaskClip (color.a - 0.001); | ||
| #endif | ||
| ``` | ||
| - Result: [Hidden/UI/Additive (SoftMaskable)](https://raw.githubusercontent.com/mob-sakai/SoftMaskForUGUI/develop/Assets/Demos/SoftMaskable%20Shader/Hidden-UI-Additive-SoftMaskable.shader) | ||
|  | ||
| <br><br> | ||
|
|
||