docs: update readme
mob-sakai
parent
5c37d27d63
commit
1119d4cc24
|
|
@ -1,24 +1,22 @@
|
||||||
SoftMaskForUGUI
|
SoftMaskForUGUI
|
||||||
===
|
===
|
||||||
|
|
||||||
Soft masking for uGUI elements in Unity.
|
UI Soft Mask is a smooth masking component for Unity UI (uGUI) elements.
|
||||||
|
|
||||||
|
By using SoftMask instead of the default Mask component, you can beautifully represent the rounded edges of UI elements.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
[](https://github.com/mob-sakai/SoftMaskForUGUI/releases)
|
[](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/releases)
|
||||||
|
|
||||||
[](https://github.com/mob-sakai/SoftMaskForUGUI/blob/upm/LICENSE.txt)
|
[](https://github.com/mob-sakai/SoftMaskForUGUI/blob/upm/LICENSE.txt)
|
||||||
[](http://makeapullrequest.com)
|
[](http://makeapullrequest.com)
|
||||||
|
[](https://github.com/mob-sakai/SoftMaskForUGUI/subscription)
|
||||||
[](https://twitter.com/intent/follow?screen_name=mob_sakai)
|
[](https://twitter.com/intent/follow?screen_name=mob_sakai)
|
||||||
|
|
||||||
<< [Description](#Description) | [WebGL Demo](#demo) | [Download](https://github.com/mob-sakai/SoftMaskForUGUI/releases) | [Usage](#usage) | [Development Note](#development-note) >>
|
<< [Description](#Description) | [WebGL Demo](#demo) | [Installation](#installation) | [Usage](#usage) | [For Your Custom Shader](#support-soft-masks-with-your-custom-shaders) >>
|
||||||
|
|
||||||
### What's new? [See changelog ](https://github.com/mob-sakai/SoftMaskForUGUI/blob/develop/CHANGELOG.md)
|
|
||||||
### Do you want to receive notifications for new releases? [Watch this repo ](https://github.com/mob-sakai/SoftMaskForUGUI/subscription)
|
|
||||||
### Support me on Patreon!
|
|
||||||
[](https://www.patreon.com/join/2343451?)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -45,7 +43,7 @@ By using SoftMask instead of default Mask, rounded edges of UI elements can be e
|
||||||
|
|
||||||
* Support overlay, camera space and world space.
|
* Support overlay, camera space and world space.
|
||||||
|
|
||||||
* Raycast is filtered only for the visible part.
|
* (Option) Raycast is filtered only for the visible part.
|
||||||
|
|
||||||
* Contain soft maskable UI shader.
|
* 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).
|
* 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).
|
||||||
|
|
@ -57,12 +55,9 @@ By using SoftMask instead of default Mask, rounded edges of UI elements can be e
|
||||||
|
|
||||||
* Preview soft mask buffer in inspector.
|
* Preview soft mask buffer in inspector.
|
||||||
|
|
||||||
* Support TextMeshPro.
|
|
||||||
|
|
||||||
* Make multiple holes on one background by 'Parts of parent' option.
|
* Make multiple holes on one background by 'Parts of parent' option.
|
||||||
|
|
||||||
* Camera movement affects the mask rendering when on a World Space Canvas.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
#### Components
|
#### Components
|
||||||
|
|
@ -84,7 +79,20 @@ By using SoftMask instead of default Mask, rounded edges of UI elements can be e
|
||||||
<br><br><br><br>
|
<br><br><br><br>
|
||||||
## Install
|
## Install
|
||||||
|
|
||||||
#### Using UnityPackageManager (for Unity 2018.3 or later)
|
#### 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:
|
Find the manifest.json file in the Packages folder of your project and edit it to look like this:
|
||||||
```js
|
```js
|
||||||
|
|
@ -95,69 +103,71 @@ Find the manifest.json file in the Packages folder of your project and edit it t
|
||||||
},
|
},
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
To update the package, change prefix `#{version}` to the target version.
|
|
||||||
|
|
||||||
* `"com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git#0.9.2",`
|
To update the package, change suffix `#{version}` to the target version.
|
||||||
|
|
||||||
Or, use [UpmGitExtension](https://github.com/mob-sakai/UpmGitExtension).
|
* e.g. `"com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git#1.0.0",`
|
||||||
|
|
||||||
#### Using .unitypackage file (for Unity 2017.1 or later)
|
Or, use [UpmGitExtension](https://github.com/mob-sakai/UpmGitExtension) to install and update the package.
|
||||||
|
|
||||||
Download `*.unitypackage` from [Releases](https://github.com/mob-sakai/SoftMaskForUGUI/releases) and import the package into your Unity project.
|
#### For Unity 2018.2 or earlier
|
||||||
Select `Assets > Import Package > Custom Package` from the menu.
|
|
||||||
|
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>
|
<br><br><br><br>
|
||||||
## How to play demo
|
## How to play demo
|
||||||
|
|
||||||
* Import `SoftMask_Demo.unitypackage` into your project.
|
#### For Unity 2019.1 or later
|
||||||
* The unitypackage exists in `Assets/Assets/Coffee/UIExtensions/SoftMaskForUGUI` or `Packages/Soft Mask For uGUI`.
|
|
||||||
|
|
||||||
* Open SoftMask_Demo scene and play it.
|
|
||||||
* The demo requires `TextMeshPro` and `TextMeshPro Essential Resources`. Import it before playing.
|
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
|
||||||
<br><br><br><br>
|
<br><br><br><br>
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
1. Add SoftMask component instead of Mask component.
|
1. Add a SoftMask component instead of Mask component.
|
||||||
Or, convert existing Mask component to SoftMask component from the context menu.
|
Or, convert an existing Mask component to SoftMask component from the context menu.
|
||||||
|
|
||||||
2. Add SoftMaskable components to the child UI elements of SoftMask component.
|
2. Add a SoftMaskable components to the child UI elements of the SoftMask component.
|
||||||
|
|
||||||
Or, add SoftMaskable components from the inspector of SoftMask component.
|
Or, add a SoftMaskable components from the inspector of the SoftMask component.
|
||||||
|
|
||||||
3. Adjust softness of SoftMask.
|
3. Adjust softness setting of SoftMask.
|
||||||
|
|
||||||
4. Enjoy!
|
4. Enjoy!
|
||||||
|
|
||||||
|
|
||||||
##### Requirement
|
|
||||||
|
|
||||||
* Unity 2017 or later *(including Unity 2018.x)*
|
|
||||||
* No other SDK are required
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<br><br><br><br>
|
<br><br><br><br>
|
||||||
## Development Note
|
## Support soft masks with your custom shaders
|
||||||
|
|
||||||
#### Support soft masks in your custom shaders
|
<b>With just three additional lines,</b> you can now support softmasks in your custom shaders!
|
||||||
|
|
||||||
You can support soft masks in your custom shaders, by adding just 3 lines!
|
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.
|
||||||
1. Add `#pragma` and `#include`. `SOFTMASK_EDITOR` is a keyword for editor only, not included in the build.
|
|
||||||
If you installed using packageManager, include `Packages/com.coffee.softmask-for-ugui/SoftMask.cginc` instead of.
|
|
||||||
```
|
```
|
||||||
#include "Assets/Coffee/UIExtensions/SoftMaskForUGUI/SoftMask.cginc"
|
#include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc"
|
||||||
#pragma shader_feature __ SOFTMASK_EDITOR
|
#pragma shader_feature __ SOFTMASK_EDITOR
|
||||||
```
|
```
|
||||||
2. Apply a soft mask in the fragment shader.
|
2. Apply a soft mask in the fragment shader.
|
||||||
- `IN.vertex` is clip position
|
This operation determines the final alpha according to the soft mask buffer.
|
||||||
- `IN.worldPosition` is world position
|
- `IN.vertex`: the clip position
|
||||||
|
- `IN.worldPosition`: the world position
|
||||||
```
|
```
|
||||||
color.a *= SoftMask(IN.vertex, IN.worldPosition);
|
color.a *= SoftMask(IN.vertex, IN.worldPosition);
|
||||||
```
|
```
|
||||||
|
|
@ -165,149 +175,6 @@ 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).
|
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).
|
||||||
|
|
||||||
|
|
||||||
<br><br>
|
|
||||||
#### Tips: Convert component from context menu
|
|
||||||
|
|
||||||
Converting components from the context menu is very convenient.
|
|
||||||
You can convert multiple components at the same time, without having to remove the source components.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
If the destination component has the same properties as the source component, the value is set automatically.
|
|
||||||
|
|
||||||
In addition, if the destination component is compatible with the source component, it will not lose its reference.
|
|
||||||
For example, if `public Mask mask;` refers to a Mask, converting it to SoftMask in this way does not lose references.
|
|
||||||
|
|
||||||
This way consists of two generic methods.
|
|
||||||
|
|
||||||
```cs
|
|
||||||
/// <summary>
|
|
||||||
/// Verify whether it can be converted to the specified component.
|
|
||||||
/// </summary>
|
|
||||||
protected static bool CanConvertTo<T>(Object context)
|
|
||||||
where T : MonoBehaviour
|
|
||||||
{
|
|
||||||
return context && context.GetType() != typeof(T);
|
|
||||||
}
|
|
||||||
|
|
||||||
/// <summary>
|
|
||||||
/// Convert to the specified component.
|
|
||||||
/// </summary>
|
|
||||||
protected static void ConvertTo<T>(Object context) where T : MonoBehaviour
|
|
||||||
{
|
|
||||||
var target = context as MonoBehaviour;
|
|
||||||
var so = new SerializedObject(target);
|
|
||||||
so.Update();
|
|
||||||
|
|
||||||
bool oldEnable = target.enabled;
|
|
||||||
target.enabled = false;
|
|
||||||
|
|
||||||
// Find MonoScript of the specified component.
|
|
||||||
foreach (var script in Resources.FindObjectsOfTypeAll<MonoScript>())
|
|
||||||
{
|
|
||||||
if (script.GetClass() != typeof(T))
|
|
||||||
continue;
|
|
||||||
|
|
||||||
// Set 'm_Script' to convert.
|
|
||||||
so.FindProperty("m_Script").objectReferenceValue = script;
|
|
||||||
so.ApplyModifiedProperties();
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
|
|
||||||
(so.targetObject as MonoBehaviour).enabled = oldEnable;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
In SoftMask, they are implemented as follows.
|
|
||||||
* Mask and SoftMask can be converted to each other.
|
|
||||||
* If conversion is not possible, gray out the context menu.
|
|
||||||
|
|
||||||
```cs
|
|
||||||
[MenuItem("CONTEXT/Mask/Convert To SoftMask", true)]
|
|
||||||
static bool _ConvertToSoftMask(MenuCommand command)
|
|
||||||
{
|
|
||||||
return CanConvertTo<SoftMask>(command.context);
|
|
||||||
}
|
|
||||||
[MenuItem("CONTEXT/Mask/Convert To SoftMask", false)]
|
|
||||||
static void ConvertToSoftMask(MenuCommand command)
|
|
||||||
{
|
|
||||||
ConvertTo<SoftMask>(command.context);
|
|
||||||
}
|
|
||||||
[MenuItem("CONTEXT/Mask/Convert To Mask", true)]
|
|
||||||
static bool _ConvertToMask(MenuCommand command)
|
|
||||||
{
|
|
||||||
return CanConvertTo<Mask>(command.context);
|
|
||||||
}
|
|
||||||
[MenuItem("CONTEXT/Mask/Convert To Mask", false)]
|
|
||||||
static void ConvertToMask(MenuCommand command)
|
|
||||||
{
|
|
||||||
ConvertTo<Mask>(command.context);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
For details, please see [SoftMaskEditor.cs](https://raw.githubusercontent.com/mob-sakai/SoftMaskForUGUI/upm/Scripts/Editor/SoftMaskEditor.cs).
|
|
||||||
|
|
||||||
|
|
||||||
<br><br>
|
|
||||||
#### Tips: Shader code for editor only
|
|
||||||
|
|
||||||
Do you know how to implement shader code "for editor only"?
|
|
||||||
SoftMask uses `SOFTMASK_EDITOR` keyword in shader code to determine whether it is running in the editor.
|
|
||||||
|
|
||||||
`#pragma shader_feature __ SOFTMASK_EDITOR`
|
|
||||||
|
|
||||||
`SOFTMASK_EDITOR` keyword is set from the editor script, but it is not set after it is built. Also, this shader variant will be excluded from build.
|
|
||||||
|
|
||||||
```cs
|
|
||||||
#if UNITY_EDITOR
|
|
||||||
material = new Material(shader);
|
|
||||||
material.hideFlags = HideFlags.HideAndDontSave;
|
|
||||||
material.EnableKeyword("SOFTMASK_EDITOR");
|
|
||||||
#endif
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
<br><br>
|
|
||||||
#### Tips: Shader code for SceneView only
|
|
||||||
|
|
||||||
Do you know how to implement shader code "for SceneView only"?
|
|
||||||
SoftMask understands that the current rendering is for SceneView, when SceneView's view projection matrix and UNITY_MATRIX_VP match.
|
|
||||||
|
|
||||||
`fixed isSceneView = 1 - any(UNITY_MATRIX_VP - _SceneViewVP);`
|
|
||||||
|
|
||||||
Actually, because of the movement operation in SceneView, use "approximate" instead of "match".
|
|
||||||
|
|
||||||
```cs
|
|
||||||
float4x4 _SceneViewVP;
|
|
||||||
|
|
||||||
fixed Approximate(float4x4 a, float4x4 b)
|
|
||||||
{
|
|
||||||
float4x4 d = abs(a - b);
|
|
||||||
return step(
|
|
||||||
max(d._m00,max(d._m01,max(d._m02,max(d._m03,
|
|
||||||
max(d._m10,max(d._m11,max(d._m12,max(d._m13,
|
|
||||||
max(d._m20,max(d._m21,max(d._m22,max(d._m23,
|
|
||||||
max(d._m30,max(d._m31,max(d._m32,d._m33))))))))))))))),
|
|
||||||
0.01);
|
|
||||||
}
|
|
||||||
|
|
||||||
fixed isSceneView = Approximate(UNITY_MATRIX_VP, _SceneViewVP);
|
|
||||||
```
|
|
||||||
|
|
||||||
`_SceneViewVP` is set every frame from the editor script.
|
|
||||||
|
|
||||||
```cs
|
|
||||||
#if UNITY_EDITOR
|
|
||||||
UnityEditor.EditorApplication.update += ()
|
|
||||||
{
|
|
||||||
Camera cam = UnityEditor.SceneView.lastActiveSceneView.camera;
|
|
||||||
Matrix4x4 vp = cam.projectionMatrix * cam.worldToCameraMatrix;
|
|
||||||
material.SetMatrix("_SceneViewVP", vp);
|
|
||||||
};
|
|
||||||
#endif
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<br><br><br><br>
|
<br><br><br><br>
|
||||||
## License
|
## License
|
||||||
|
|
@ -317,12 +184,22 @@ UnityEditor.EditorApplication.update += ()
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<br><br><br><br>
|
||||||
|
## 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
|
## Author
|
||||||
|
|
||||||
[mob-sakai](https://github.com/mob-sakai)
|
[mob-sakai](https://github.com/mob-sakai)
|
||||||
[](https://twitter.com/intent/follow?screen_name=mob_sakai)
|
[](https://twitter.com/intent/follow?screen_name=mob_sakai)
|
||||||
[](https://www.patreon.com/join/2343451?)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -331,5 +208,4 @@ UnityEditor.EditorApplication.update += ()
|
||||||
* GitHub page : https://github.com/mob-sakai/SoftMaskForUGUI
|
* GitHub page : https://github.com/mob-sakai/SoftMaskForUGUI
|
||||||
* Releases : https://github.com/mob-sakai/SoftMaskForUGUI/releases
|
* Releases : https://github.com/mob-sakai/SoftMaskForUGUI/releases
|
||||||
* Issue tracker : https://github.com/mob-sakai/SoftMaskForUGUI/issues
|
* Issue tracker : https://github.com/mob-sakai/SoftMaskForUGUI/issues
|
||||||
* Current project : https://github.com/mob-sakai/SoftMaskForUGUI/projects/1
|
|
||||||
* Change log : https://github.com/mob-sakai/SoftMaskForUGUI/blob/upm/CHANGELOG.md
|
* Change log : https://github.com/mob-sakai/SoftMaskForUGUI/blob/upm/CHANGELOG.md
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue