Skip to content

Latest commit

 

History

History
473 lines (355 loc) · 23.2 KB

README.md

File metadata and controls

473 lines (355 loc) · 23.2 KB
Raw

logo SoftMaskForUGUI v2



PRs Welcome

<< 📝 Description | 📌 Key Features | 🎮 Demo | ⚙ Installation | 🚀 Usage | 🤝 Contributing >>

📝 Description

Enhance Unity UI (uGUI) with advanced soft-masking features to create more visually appealing effects!



📌 Key Features

  • 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.
  • 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.
  • ScrollRect Support: SoftMask supports ScrollRect component.
  • 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 soft-maskable shader.
  • 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: Soft masking for VR.
  • TextMeshProUGUI Support: Support TextMeshProUGUI by importing additional shaders.
    It also supports TextMeshPro v3.2/4.0 (pre-release) and uGUI 2.0 (Unity 2023.2+/6.0+). For details, please see Support TextMeshPro.
  • Better Editor Experience: In the Scene view, objects outside the screen are displayed as stencil masks, allowing for more intuitive editing.
  • Automatic Shader Include and Stripping: SoftMaskable shaders are automatically included at build time, and unused shader variants are removed.



🎮 Demo

WebGL Demo



⚙ Installation

This package requires Unity 2019.4 or later.

Install via OpenUPM

  • This package is available on OpenUPM package registry.
  • This is the preferred method of installation, as you can easily receive updates as they're released.
  • If you have 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 with @{version}: 
    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:

    {
  "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 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.



🔄 Upgrading from v1 to v2

If you are currently using SoftMaskForUGUI v1.x, the following breaking changes are included when upgrading to v2:

  1. API changes: Some APIs are obsolete.
  • SoftMask.alpha: Use Graphic.color.a instead.
  • SoftMask.softness: Use SoftMask.softnessRange instead.
  • SoftMask.partOfParent: Use MaskingShape component instead.
  • SoftMask.ignoreParent: Removed.
  • SoftMask.ignoreSelfGraphic: Removed.
  • SoftMask.ignoreSelfStencil: Removed.
  • SoftMaskable.useStencil: Removed.
  • SoftMaskable.raycastFilter: Use SoftMask.alphaHitTest instead.
  • SoftMaskable.maskInteraction: If you want to use as inverse mask, use MaskingShape component and MaskingMethod=Subtract.

  1. SoftMaskable component: SoftMaskable component is no longer required to be added explicitly. It will be added automatically at runtime as needed.

  2. SoftMaskable shader: SoftMask() function has been updated with additional arguments.

    // Before
color.a *= SoftMask(IN.vertex, IN.worldPosition);
// After
color.a *= SoftMask(IN.vertex, IN.worldPosition, color.a);

To apply these changes automatically, please follow the steps below:

  1. Click Edit > Project Settings to open the Project Settings window and select UI > SoftMask category.

  2. Click Upgrade All Assets V1 to V2 to upgrade the assets.

  • ⚠️ If you select Dry Run, you can check the changes before upgrading.



🚀 Usage

Getting Started

  1. Install the package.

  2. Add a SoftMask component instead of Mask component.
    Or, convert an existing Mask component to SoftMask component from the context menu (Convert To SoftMask).

  3. Adjust the soft mask parameters in the inspector.

  4. (Optional) By placing the MaskingShape component under SoftMask, you can add or remove the masking region.

  5. Enjoy!



Comparison of Masking Mode

  • Soft Masking: Smooth mask with semi-transparency.
    Requires memory for RenderTexture and soft-maskable shader.
  • 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.



RectMask2D vs SoftMask

RectMask2D is a built-in component that supports soft masking.
SoftMask provides more advanced soft masking.

  • RectMask2D:
    • uGUI built-in
    • Very fast
    • Supports only rectangular shapes
    • Supports only one level of nesting
    • Supports only limited rotation
  • SoftMask:
    • Advanced soft masking
    • Supports any graphic shape
    • Supports up to 4 levels of nesting soft-masking
    • Supports fully rotation



Component: SoftMask

  • Masking Mode:
    • SoftMasking:
      • Smooth mask with semi-transparency.
      • Requires memory for RenderTexture and soft-maskable shader.
      • Use RenderTexture as a soft mask buffer.
      • The alpha of the masking graphic can be used.
    • AntiAliasing:
      • Less jagged stencil mask.
      • It does not require RenderTexture or soft-maskable shader, and works faster.
      • Suppress the jaggedness of the masking graphic.
      • The masking graphic cannot be displayed.
    • Normal: Same as Mask component's stencil mask.
  • Show Mask Graphic:
    • Show the graphic that is associated with the Mask render area.
  • Alpha Hit Test:
    • The transparent part of the mask cannot be clicked.
    • This can be achieved by enabling Read/Write enabled in the Texture Import Settings for the texture.
    • ⚠️ Enable this only if necessary, as it will require more graphics memory and processing time.
  • Anti Aliasing Threshold (AntiAliasing only):
    • Threshold for anti-alias masking.
    • The smaller this value, the less jagged it is.
  • Softness Range (SoftMasking only):
    • The minimum and maximum alpha values used for soft masking.
    • The larger the gap between these values, the stronger the softness effect.
  • Down Sampling Rate (SoftMasking only):
    • The down sampling rate for soft mask buffer.
    • The higher this value, the lower the quality of the soft masking, but the performance will improve.
  • Preview Soft Mask Buffer (editor, SoftMasking only):
    • Preview the soft mask buffer in the inspector.



Component: SoftMaskable

  • Ignore Self: The graphic is ignored when soft-masking.
  • Ignore Children: The child graphics are ignored when soft-masking.
  • Power: Soft masking power.
    • The higher this value, the faster it becomes transparent.
    • If overlapping objects appear see-through, please adjust this value.

NOTE: SoftMaskable components are added automatically.
If the properties are set to their default values, it is marked as HideFlag.DontSave and will not be saved in the scene or prefab.



Component: MaskingShape

  • 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.




Component: RectTransformFitter

  • 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.



Project Settings

  • Click Edit > Project Settings to open the Project Settings window and then select UI > SoftMask category.
  • To use the softmaskable shaders at runtime, you need to register the shaders as Always Included Shaders.
    • By default, the soft-maskable shaders will be included in the build, but you can remove it if you don't need it.



Usage with Scripts

var softMask = gameObject.GetComponent<SoftMask>();
softMask.maskingMode = SoftMask.MaskingMode.SoftMasking;
softMask.downSamplingRate = SoftMask.DownSamplingRate.x2;
softMask.softnessRange = new MinMax01(0.5f, 0.75f);



Usage with TextMeshPro

  1. First, you must import TMP Essential Resources 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.
    ⚠️ If you are using ugui 2.0 (=Unity 2023.2+/6.0+) or TextMeshPro 3.2+/4.0+, click the TextMeshPro Support (ugui 2.0) > Import button instead.

  3. The assets will be imported under Assets/Samples/UI Soft Mask/{version}.



Usage with Your Custom Shaders

Here, let's make UI/Additive 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:

    // Add the ` (SoftMaskable)` suffix to the shader name.
Shader "UI/Additive (SoftMaskable)"

// Import "UISoftMask.cginc" and add shader variants for editor.
#include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc"
#pragma multi_compile_local _ SOFTMASK_EDITOR // soft-maskable for editor

// "SoftMask" function returns [0-1]. Multiply this by the final output.
color.a *= SoftMask(IN.vertex, IN.worldPosition, color.a);

  • 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:

    // Add the `Hidden/` prefix and ` (SoftMaskable)` suffix to the shader name.
Shader "Hidden/UI/Additive (SoftMaskable)"

// Import "UISoftMask.cginc" and add shader variants for editor.
#include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc"
#pragma multi_compile_local _ SOFTMASK_EDITOR

// "SoftMask" function returns [0-1]. Multiply this by the final output.
color.a *= SoftMask(IN.vertex, IN.worldPosition, color.a);



Usage with ShaderGraph

NOTE: Unity 2023.2/6000.0+ is required.

  1. Open the Package Manager window and select the UI Soft Mask package in the package list and click the ShaderGraph Support > Import button.

  2. The sample includes UIDefault (SoftMaskable).shadergraph and SoftMask.subshadergraph.
    You can use the sample as references to make your own shader graph compatible with SoftMask.

    1. Add (SoftMaskable) at the end of the shader name.
    2. Add SOFTMASK_EDITOR as a Boolean Keyword (Shader Feature).
    3. Add the Sub Graphs > SoftMask node and connect it to the final alpha output.

  3. To use the soft-maskable ShaderGraph in the editor, the SoftMaskable ShaderGraph Support (Editor) renderer feature is required.
    This feature is specifically for previewing SoftMaskable ShaderGraph in the editor and will be automatically removed during the build process.
    SoftMaskable ShaderGraph Support

⚠️ Currently, the soft-maskable ShaderGraph does not display correctly in the SceneView.



⚠️ Limitations

The following are the limitations of SoftMaskForUGUI.

  • (Android) RGB ETC1 (+ Split alpha channel) texture format is not supported.
    • Use a format that supports alpha, such as RGBA ETC2.
    • Technically possible, but not supported because ETC2 support rate is over 95%.
    • If needed, feel free to create an issue.
  • Alpha hit test is not supported when the texture is in crunch format or non-readable.



🤝 Contributing

Issues

Issues are incredibly valuable to this project:

  • Ideas provide a valuable source of contributions that others can make.
  • Problems help identify areas where this project needs improvement.
  • Questions indicate where contributors can enhance the user experience.

Pull Requests

Pull requests offer a fantastic way to contribute your ideas to this repository.
Please refer to CONTRIBUTING.md and develop branch for guidelines.

Support

This is an open-source project developed during my spare time.
If you appreciate it, consider supporting me.
Your support allows me to dedicate more time to development. 😊




License

  • MIT

Author

See Also