From 76ef6a8fe1e951af891d59271dfdf8042ad57d88 Mon Sep 17 00:00:00 2001 From: mob-sakai Date: Thu, 30 May 2024 22:46:23 +0900 Subject: [PATCH] docs: update readme --- Packages/src/README.md | 287 ++++++++++++++++++++++++++++++++--------- 1 file changed, 223 insertions(+), 64 deletions(-) diff --git a/Packages/src/README.md b/Packages/src/README.md index e0ef3e0..96792f3 100644 --- a/Packages/src/README.md +++ b/Packages/src/README.md @@ -14,40 +14,49 @@ ## 📝 Description - + -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. -![](https://user-images.githubusercontent.com/12690315/48661087-01ca9f00-eab0-11e8-8878-772a1ed1fb7b.gif) -* Text, Image, RawImage can be used as a masking. -* Support multiple-sprites and SpriteAtlas. -* Support up to 4 nested soft masks. -![](https://user-images.githubusercontent.com/12690315/48708326-a0d4cf80-ec45-11e8-83b8-f55d29138db7.png) -* Support scroll view. -![](https://user-images.githubusercontent.com/12690315/48708527-2b1d3380-ec46-11e8-9adf-9d33498f0353.png) -* Support inversed soft mask. -![](https://user-images.githubusercontent.com/12690315/48708328-a0d4cf80-ec45-11e8-9945-e877faabc968.png) -* Support overlay, camera space and world space. -![](https://user-images.githubusercontent.com/12690315/48708329-a0d4cf80-ec45-11e8-8328-16b697f981ec.png) -* (Option) Raycast is filtered only for the visible part. -![](https://user-images.githubusercontent.com/12690315/48708330-a16d6600-ec45-11e8-94bf-afecd1bd9a39.png) -* 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. -![](https://user-images.githubusercontent.com/12690315/48659018-902e2900-ea8e-11e8-9b6e-224365cdde7f.png) -* 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. -![](https://user-images.githubusercontent.com/12690315/50284153-76bc3a80-049b-11e9-8c55-719af897960a.png) -* Preview soft mask buffer in inspector. -![](https://user-images.githubusercontent.com/12690315/50284151-7459e080-049b-11e9-9cd3-24fb476766dc.png) -* Make multiple holes on one background by 'Parts of parent' option. -![](https://user-images.githubusercontent.com/12690315/54102470-f5c26e80-440b-11e9-89d1-899aa4dca00d.png) -* [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. + ![](https://gist.github.com/assets/12690315/e194b7a8-b82d-4714-944d-89b4c9a88ee0) +- **Adjustable Visible Part**: You can freely adjust the visible part of the mask. + +- **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. + +- **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. + +- **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. + +- **Anti-Alias Masking Mode**: If you don't need semi-transparent masks, you can use the more performant "Anti-Aliasing Masking Mode". + +- **Masking Shape**: You can add or remove mask region using `MaskingShape` component. + +- **Inverse Masking**: Use `MaskingShape` component to inverse masking. You can implement effects such as iris out. + +- **Ray-cast Filtering**: Ray-casts are filtered only for the visible part. + This feature is useful for preventing clicks on masked parts during tutorials. + +- **Stereo Support**: A shader macro `UI_SOFT_MASKABLE_STEREO` has been added for VR. + +- **TextMeshProUGUI Support**: Support TextMeshProUGUI by importing additional samples. + For details, please see [Support TextMeshPro](#usage-with-textmeshpro). +

@@ -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 com.coffee.softmask-for-ugui@2.0.0 + ``` + +#### 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` + ![](https://gist.github.com/assets/12690315/24af63ed-8a2e-483d-9023-7aa53d913330) +- 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. + ![](https://gist.github.com/assets/12690315/c7b2b17f-3069-4563-ab89-b3c0e4cf821f) +- 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: +

-``` -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. + ![](https://gist.github.com/assets/12690315/a8721071-9a12-481f-a97e-44ebbe696358) + +- NOTE: If you select "Dry Run", you can check the changes before upgrading. + ![](https://gist.github.com/assets/12690315/770287d3-fdb4-4d12-bf89-26babe908f8b) + ![](https://gist.github.com/assets/12690315/14105067-6708-4713-882e-89a7091d4245)

## 🚀 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`). - ![](https://user-images.githubusercontent.com/12690315/48659018-902e2900-ea8e-11e8-9b6e-224365cdde7f.png) -2. (Optional) By placing the `MaskingShape` component under `SoftMask`, you can add or remove the mask range. - ![](https://user-images.githubusercontent.com/12690315/48661087-01ca9f00-eab0-11e8-8878-772a1ed1fb7b.gif) -3. Enjoy! + ![](https://gist.github.com/assets/12690315/e194b7a8-b82d-4714-944d-89b4c9a88ee0) + +2. Adjust the soft mask parameters in the inspector. + ![](https://gist.github.com/assets/12690315/6a61c458-4a1d-4e4f-9471-19d819a990fd) + +3. (Optional) By placing the `MaskingShape` component under `SoftMask`, you can add or remove the masking region. + ![](https://gist.github.com/assets/12690315/5a633b7b-4411-4ab9-aa4a-aa586e5d756b) + +4. Enjoy!

-#### 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. + -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/com.unity.textmeshpro@3.0/manual/index.html#installation) before using. If the shader error is not resolved, reimport the shader. +

-#### Usage with your custom shaders +#### Masking Shape + + + +- `MaskingShape` component allows you to add or remove the masking region. +- Placing `MaskingShape` component (with any `Graphic`) under `SoftMask` component. + ![](https://gist.github.com/assets/12690315/56979800-9acd-4fa8-9a88-9984e5733e92) +- 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`. + ![](https://gist.github.com/assets/12690315/cd05567c-1710-4d53-a617-94c6cc9f1c70) + ![](https://gist.github.com/assets/12690315/fe73d465-c230-4104-a840-b6ae06f8e2ed) + ![](https://gist.github.com/assets/12690315/f961af3f-2692-4c0e-b9c5-ebd2e11ec8c5) + +

+ +#### Rect Transform Fitter + +![](https://gist.github.com/assets/12690315/ffb08715-605e-47ec-91bd-8613dd2a646e) -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. +

+ +#### Project Settings + +![](https://gist.github.com/assets/12690315/a5ae481a-9cc4-4e42-bf4e-9f4738c32e58) + +- Click `Edit > Project Settings` to open the Project Settings window and then select `UI > SoftMask` category. + +

+ +#### Usage with Scripts + +```csharp +var softMask = gameObject.GetComponent(); +softMask.maskingMode = SoftMask.MaskingMode.SoftMasking; +softMask.downSamplingRate = SoftMask.DownSamplingRate.x2; +softMask.softMaskingRange = new MinMax01(0.5f, 0.75f); +``` + +

+ +#### Usage with TextMeshPro + +1. First, you must import [TMP Essential Resources](https://docs.unity3d.com/Packages/com.unity.textmeshpro@3.0/manual/index.html#installation) before using. + ![](https://gist.github.com/assets/12690315/8a3b7357-1fed-44f8-bfc2-af14c3e56cb1) + +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. + ![](https://gist.github.com/assets/12690315/59994633-d6dd-429d-8a26-c10c142f8cd2) + +3. The assets will be imported under `Assets/Samples/UI Soft Mask/{version}`. + ![](https://gist.github.com/assets/12690315/c69912a9-2e84-4cb2-8409-ba6e35103715) + +
+ +#### 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) + +![](https://gist.github.com/assets/12690315/db779413-6896-4320-b26f-c355a85b383e)