Soft Mask - A replacement of Unity UI Mask with alpha support

Hi, I'm using Softmask with TextMeshPro, and while using sprite assets, TMP creates a child object with the sprite in the specific place. The problem is that this child object needs a SoftMaskable component. Is there any solution that I've missed? Thanks.

 

Hi @SkitchSketch

Sorry for such a long delay.

As far as I remember, Soft Mask should attach the SoftMaskable component to TMPro subobjects automatically. Are you using TextMeshPro_UGUI component? Soft Mask works only with Unity UI and it's not able to mask Sprite or MeshRenderer.

I just tested it out in Unity 2019.2 with a standard TMPro example (15 - Inline Graphics & Sprites):



Here you can see that the selected object (TMP SubMeshUI) already has a Soft Mask-compatible shader.

If you need to mask 3D texts then, unfortunately, Soft Mask is not suited for your task. Probably you could use TMPro built-in masking facilities?

 

hi @zxkne .
i wanted to use softmask for the ui with particles attached. it seems soft mask do mask the ui elemnts as unity's default does, but it doesn't mask particles as unity's default does.
would you tell me what should i do?
information is in images below.

 

oh i think that's because of the shader that i'm using for particle material.
here it is:

 

Hi @afshinunity

Are you using this shader with a Graphic component (Image, RawImage, Text, etc.)? If yes, then you just need to add some instructions to the shader. Here is a tutorial that describes this process in detail. I already modified your shader for you, it's attached to this post

Use this shader instead of the original one on the objects you want to mask. There's also a way with dynamic shader replacement but it requires some programming. If you are interested, see MaterialReplacer.cs for details and also TextMeshPro/MaterialReplacer.cs as an example.

If you want to mask a 3D particle system, then it's not possible with Soft Mask. It works only with the UI system.

Hopefully, I helped you. Have a good day!

 

Thank you for the reply. While that behavior isn't present on my project (2018.2.21f), I implemented a workaround. A script on text that could generate a sprite that checks for a child and automatically adds a SoftMaskable component.

This does the trick, thank you.

 

Hi @zxkne,
I want to make the objects under visible area clickable and dismiss the other click actions.
Is it possible?
Thnx

 

Hi @babercan,

I'm not sure that I fully understood what you're trying to achieve. Have you seen the Raycast Threshold option? When you set a value greater than zero, Soft Mask starts to filter all the pointer events over the areas where the mask value is lower than this value. Is it what you want? If not, please, give a bit more detailed description and I'll check if it's possible with Soft Mask.

Thank you!

 

Hi zxkne,
I am using invert outside option for masking and I want to make unmasked are clickable. Raycast Threshold option only works for masked are(which should be). I want to learn if there is a way to make unmasked area clickable.
By the way I found a solution for my problem
Thanks for your great asset.

 

Great to hear that you have solved the problem! Would you share the solution? Nothing comes to my mind, except for creating additional objects that cover the area outside of the mask. Or enlarging the mask to cover the whole area. Maybe you found a more elegant solution.
Thank you!

 

@zxkne
Is it possible to make shader that is supporting your masking in shader graph?

 

Is this package still supported? Its working fine for us but it's very heavy on CPU creating lots of Garbage Collection when we have big number of elements at the same time. (E.g Leaderboard view)

 

Previously I thought that it's not possible to create a UI shader in Shader Graph, so I hadn't even researched this. But now I've tried and saw that an Unlit graph works fine, at least in HD render pipeline. Currently, I don't know a way to make a Soft Mask-compatible shader in Shader Graph. I need some time to research, will come back soon.

I answer questions and solve bugs when they appear. Time to time I release an update with some new features. Don't know if this is enough to be considered supported As for your question, how do you use a mask? Masks or masked elements are spawned or enabled/disabled dynamically? Is garbage generated each frame or one time when objects appear? To somehow improve the behavior we first need to localize what exactly causes the allocations. After that, I'll be able to suggest if it's practical to remove the allocations or it would be easier to write a specialized solution for your situation.

 

@Deusald ,
I've researched Shader Graph and come to the conclusion that it's not possible to integrate Soft Mask support to a Shader Graph-based shader. I haven't found a way to #include some custom HLSL code. Without this feature Soft Mask becomes almost useless—you may re-implement masking logic in Shader Graph, but what's the point of using Soft Mask then?

I hope when Shader Graph becomes more mature, it will expose some API for creating custom nodes and shader generation logic. Then I'll revisit the Shader Graph support question.

Of course, it's possible that I just missed something and there's a reasonable way to integrate. If you (or someone else reading this) know it, please, share, I would appreciate it.

If you bought Soft Mask and don't want to use it without Shader Graph support, please send me the invoice number via email, I'll authorize a refund.

 

Hi, I've just purchased this asset as it looks like it fits my needs perfectly.

However, I seem to be having an issue with sliced sprites. It appears that the Soft Mask component does not consider the Pixels Per Unit Multiplier specified in the Image component. Here's an example; the blue is sprite shape that should be used to mask which is a sliced imaged with a Pixels Per Unit Multiplier of 54, while the red is what is actually masked, which is the correct sprite, but the shape is what you would get using a PPUM of 1:





A solution I found is to alter the Pixels Per Unit Modifier in the sprite's import settings, however this would mean I'd need to use a different sprite every time I wanted to use a different PPUM.

 

Okay, so I fixed it so that now if you select "Graphic" as the Soft Mask Source and that graphic is a sliced image with a custom PPU multiplier, the PPU multiplier on the sprite instance will be considered.

Changed SpriteToCanvasScale() to:

Code (CSharp):

1.         float SpriteToCanvasScale(Sprite sprite, Image image = null) {
2.             var canvasPPU = canvas ? canvas.referencePixelsPerUnit : 100;
3.             var maskPPU = sprite ? (sprite.pixelsPerUnit) : 100;
4.             if (image != null)
5.             {
6.                 maskPPU = sprite ? (sprite.pixelsPerUnit * image.pixelsPerUnitMultiplier) : 100;
7.             }
8.  
9.             return canvasPPU / maskPPU;
10.         }

Changed CalculateSpriteBased() to:

Code (CSharp):

1. void CalculateSpriteBased(Sprite sprite, BorderMode borderMode, Image image = null) {
2.             var lastSprite = _lastUsedSprite;
3.             _lastUsedSprite = sprite;
4.             var spriteErrors = Diagnostics.CheckSprite(sprite);
5.             if (spriteErrors != Errors.NoError) {
6.                 if (lastSprite != sprite)
7.                     WarnSpriteErrors(spriteErrors);
8.                 CalculateSolidFill();
9.                 return;
10.             }
11.             if (!sprite) {
12.                 CalculateSolidFill();
13.                 return;
14.             }
15.             FillCommonParameters();
16.             var inner = DataUtility.GetInnerUV(sprite);
17.             var outer = DataUtility.GetOuterUV(sprite);
18.             var padding = DataUtility.GetPadding(sprite);
19.             var fullMaskRect = LocalMaskRect(Vector4.zero);          
20.             _parameters.maskRectUV = outer;
21.             if (borderMode == BorderMode.Simple) {
22.                 var normalizedPadding = Mathr.Div(padding, sprite.rect.size);
23.                 _parameters.maskRect = Mathr.ApplyBorder(fullMaskRect, Mathr.Mul(normalizedPadding, Mathr.Size(fullMaskRect)));
24.             } else {
25.                 _parameters.maskRect = Mathr.ApplyBorder(fullMaskRect, padding * SpriteToCanvasScale(sprite, image));
26.                 var adjustedBorder = AdjustBorders(sprite.border * SpriteToCanvasScale(sprite, image), fullMaskRect);
27.                 _parameters.maskBorder = LocalMaskRect(adjustedBorder);
28.                 _parameters.maskBorderUV = inner;
29.             }
30.             _parameters.texture = sprite.texture;
31.             _parameters.borderMode = borderMode;
32.             if (borderMode == BorderMode.Tiled)
33.                 _parameters.tileRepeat = MaskRepeat(sprite, _parameters.maskBorder);
34.         }

And finally changed CalculateMaskParameters() to:

Code (CSharp):

1.         void CalculateMaskParameters() {
2.             var sourceParams = DeduceSourceParameters();
3.             if (sourceParams.sprite)              
4.                 CalculateSpriteBased(sourceParams.sprite, sourceParams.spriteBorderMode, sourceParams.image);
5.             else if (sourceParams.texture)
6.                 CalculateTextureBased(sourceParams.texture, sourceParams.textureUVRect);
7.             else
8.                 CalculateSolidFill();
9.         }

 

Hi @ShockpointGames

Sorry for such a long delay. I see, you already solved the issue on your own!

It seems like I missed the moment when the Pixels Per Unit Multiplier parameter was added. You're right, it should be supported when the source mode is set to Image. I'll definitely include this improvement to the next version. Thank you very much for pointing it out and for providing an example implementation!

 

@zxkne
You can include custom HLSL code:
https://docs.unity3d.com/Packages/com.unity.shadergraph@7.1/manual/Custom-Function-Node.html

 

Yes, you're right. It's even possible to #include some other .cginc file here. But then other issues come up. For example, it's possible to declare some uniform variable, but I don't see a way to reference this variable from an #included .cginc file.

I believe that it's possible in theory to build a shader in Shader Graph that fully supports Soft Mask, but it requires a lot of manual work: all the Soft Mask uniforms and keywords should be recreated manually in Shader Graph. That's the reason why I think that creating shaders with Soft Mask support in Shader Graph isn't very practical at the current stage.

I'm going to play with it further and will try to create a fully working example of Soft Mask-compatible shader in Shader Graph, but I'm not sure that I will ever succeed.

If you want to try it on your own, I'll give you some guidance. The file SoftMask.cginc contains several uniform variables that are set up from the code. They may be added to a graph via the Blackboard window. The same for multi_compile flags which Soft Mask relies on, you can find its declaration in SoftMaskTemplate.cginc. After creating parameters, it's actually possible to implement masking logic which consists of several steps. First, we should calculate mask UV by multiplying the input position by _SoftMask_WorldToMask matrix. Then we transform computed UV by applying __SoftMask_XY2UV function that takes the Image mode into account. After this, it's possible to sample the actual mask texture and perform some final calculations: mask inversion and channel weights. Some of this logic you can put out into a separate .cginc file that may be shared between Shader Graph and standard versions of Soft Mask shader. And, of course, it's possible to repeat only the features that you actually need, for example, if you don't use Channel Weights, you may just use the sampled mask value.

I'm not sure that I put my thoughts clear enough but if you really want to go this way, feel free to ask me further, I'll try to help you.

 

Hello,

I am having trouble to make an inverted softmask work on mobile.

Here is the result from the unity game window:


And here is the same result on my galaxy s9 test phone:

(note the top right icon)

My softmask has the following settings:

The sprite is the top right icon sprite, and I set the icon rect transform as the separate mask parametter.

Did I make something wrong? I tried on different icons and resolutions but the problem is the same.

 

Hello @Feezen,

It seems like a bug. Which version of Unity are you using?

I'll try to reproduce it and then come back to you. Thank you for reporting!

 

Hello,

We are using Unity 2018.4.14f1

Apart from this, the asset is great and saved us lot of time.

Thank you!

 

Thank you!

Sorry, but I still not able to reproduce the issue. I tested a setup similar to your on a Galaxy S9 and didn't succeed. May I ask you to perform some other actions to help me reproduce the issue?

1. Could you prepare a minimal reproduction project? Just one scene on which the same issue reproduces on your device is enough. You may send it to me as a .unitypackage or .zip to email.
2. Are there any errors while executing on device? You may access them via adb logcat command while debugging. Here is also a standard package for this purpose but I personally haven't used it yet.
3. Could I see your project settings? If would be great to see the files QualitySettings.asset, GraphicsSettings.asset and ProjectSettings.asset from the ProjectSettings folder. Again, you may send it by email if you don't want to publish them here.

 

Hello,

I finally figured it out, the error was not from your asset!

I am using softmask for a tutorial on our game, and I made a class that allows me to highlight part of my game easily. In this class, I was using a dictionary with a custom enum as key and a struct as value, and I used Odin to serialize it.
Turns out that the serialization of structs didn't work well when it was compiled, resulting in an empty dictionary on phone.
Replacing the struct by a class fixed it.

Thank you for your time (and your asset)!

 

Hello!

It's great to hear that the problem is solved! And thank you for getting the time to explain what the error was. And for the positive feedback!

 

Hello,

I've been utilizing the Soft Mask Plugin in a number of projects, and it's been really handy in allowing me to fully customize UI.

I've had a minor issue that I wanted to know if you had any info on. I'm using a Text Mesh Pro UGUI field that is masked with Soft Mask. At run-time I'm inserting some text that includes font tags. I've noticed that any text covered by the font tags does not show at all. But if I disable the soft mask, or remove it all together, the font tags work correctly. I also was able to manually unparent the gameobject and reparent it (with soft mask enabled), and that seemed to display the font tags.

It seems as though I may simply need to trigger some form of refresh after inserting the text that includes font tags. This refresh seems to happen when I manually move it around in the editor, but obviously I'm hoping to trigger this through the script when the text is inserted.

Any idea how I can accomplish this? I can provide more information and images if needed, but I figured I might just be missing a refresh call somewhere.

Default Display:


Display after Gameobject is moved above the Soft Mask parent, and then reparented.


Edit (1/31/2020):
I did some tests and managed to accomplish a workaround. Effectively if I just initialize the text field at run-time and add it to the parent with the soft mask, the font tags display correctly. So I should be good with this solution, but would be interested if you had any ideas how to bundle the soft mask and text field together.

 

Hello,

Thank you for the positive feedback and for the detailed description of an issue!

It seems like Soft Mask isn't applied correctly to dynamically spawned children objects which TextMesh Pro creates for parts of the text drawn by different fonts. By design, it should work so it seems like you found some corner case.

I have tried to reproduce the problem but haven't succeeded in it yet. Here's the scenario I used:

1. Add a TextMeshProUGUI element nested into a Soft Mask.
2. Set some default text using a single font ("New Text").
3. At runtime, after a second delay, a script changes the text to one using multiple fonts ("<font="Anton SDF" material="Anton SDF - Drop Shadow">New</font> Text").

The text blinks for the first time which may be not good, but then it's actually showed and masked correctly.

I've tried it on Unity 2019.3 and TextMesh Pro 2.0.1. Which versions are you using? Maybe I missed some details? If you noticed something in my test scenario that differs from yours, please tell me. If it's no trouble, maybe you can reproduce the bug in a small separate project? Or send me assets you're using (fonts and materials) to bring my attempts closer to what actually happens in your project. If you decide to do so send the resources on email to keep them private.

Thank you!

 

Yea, I primarily discovered your plugin when I realized Unity didn't support gradient alpha masks out of the box, and it's definitely resolved a lot of headaches I had when implementing that feature on my own.

Here's a basic outline of how I was setting up the structure before applying my workaround.

1. Create a prefab that has a Soft Mask component on the parent, and a Text Mesh Pro UGUI field on the child.
2. At runtime, initialize a gameobject from the prefab on button press.
3. During initialization, set the Text Mesh Pro UGUI field with text containing one or more font tags.
4. Notice that the text contained in font tags is invisible while masked in the Soft Mask.

I did some tests the other day, and noticed this issue seems to only occur if the object is initialized at runtime. If I just had the object on a canvas the font tags worked correctly. This might be why your test worked correctly as well.

I'm currently on Unity 2019.1.14f1 and Text Mesh Pro 2.0.1.

As noted, I managed to find a simple workaround that has resolved the issue for me. This just involves loading the child object with the Text Mesh Pro UGUI field as a prefab as well. Obviously a bit of an extra step, but doesn't cause any problems once I implemented it.

But, early next week I'll see if I can create a new project and replicate the bug. I'll try it on both 2019.1.14f1 and 2019.3. I'll let you know the results and send the resources along via PM if it might be worth an investigation.

Once again, since I got a solution in place, don't worry too much about it. Thanks for your support!

 

Thank you for the information! It increases the chances that I will be able to reproduce the issue locally. For now, I tried several scenarios with prefabs and runtime instantiation but haven't succeeded yet. I'm going to continue trials with different setups and will let you know if I figure out something.

 

Any chance of this still happening? I really need Softmask to support RenderTextures.

 

Well, it's time to figure it out. Give me a week to experiment with this and see how it all works together. After this, if everything will go fine, I may share a version with you and everyone who wanted this feature before uploading it on the Asset Store. It would be great to hear your feedback before publishing a new version.

 

Hey! I'm working on a game using SpriteMask, but I keep bumping into issues. I'm now considering redoing everything in UI so I could use Soft Masks.

Specifically, does Soft Mask handle nested masks? As far as I know, SpriteMask doesn't.



Here is a diagram I made explaining the situation I'm facing with SpriteMask. Can you confirm it would display properly in Soft Masks?

Thanks, cheers~

 

Hi! I'm sorry to disappoint you but Soft Mask doesn't support nested masks It works when a Soft Mask is nested into a standard Mask or vice versa but that's not your case as far as I see because you want rounded corners which are impossible with a stencil-based mask.

 

Hello again,

As promised, I've sketched RenderTexture support. It's not production-ready yet, the documentation and better error handling are on the way. But it's usable, as far as I can see, so you may check it out. Your feedback will be very welcome!

A .zip with a patch is attached to this post. If you want to get source code modifications as a whole, please, contact me via email, as you understand, I can't publish the code right here. The patch file should be applied to the Soft Mask root folder (Assets/SoftMask by default). All the changes affect the only SoftMask.cs file. The archive also contains a .unitypackage with an example scene. It's not in final quality too, but it shows a way RenderTexture may be used together with Soft Mask.

 

Hey,

Probably a bug, reproduced in 2019.2.1.
If you add a SoftMask before creating children GOs graphics, it seems to hide all the graphics


When I delete the SoftMask and add it again it works fine.

 

Hi,
Thank you for reporting! Unfortunately, I've not been able to reproduce the bug. Here's what I did:

1. Created an empty GO
2. Created an empty child GO
3. Added a Soft Mask to the parent and assigned a sprite as the mask source
4. Added Raw Image to the child and assigned it

And everything worked as expected. Am I missing something? Do you perform these actions in the Editor or programmatically in runtime?

 

Ok, I've reproduced it by placing the masked item inside a scroll view (i.e. inside default mask). Reproduces for both Image and RawImage.

 

Thank you for clarification, now I've reproduced it. Unfortunately, it's a known issue that I cannot fix on my side. Soft Mask documentation says the following about this:

 

Hi zxkne! We love your SoftMask, it's been an invaluable tool for our UI artist. But we just hit an issue you may be able to help us out

We have a sprite shader that makes some of our Images shows up in greyscale. By default they don't get properly masked, so I followed your instructions on how to make our shader SoftMask-compatible at:

https://docs.google.com/document/d/1mFEml0JWhR968GG1gVBBTLsJ8ubf_oraW5MBbrvkrb0/edit

But I'm getting this compile error:

Shader error in 'LS/s_BW_sprite': invalid subscript 'maskPosition' at line 91 (on metal)

Line 91 is where I call:

SOFTMASK_CALCULATE_COORDS(OUT, IN.vertex);

Note that we are using a mask in "Slice" mode. Any idea what I may be missing?

 

Hello! Thank you for your kind words

I'm not sure that understood right, you based your shader on a sprite shader, not on the "Default UI"? Maybe something UI-specific stuff is missing? That may be the reason, but it's hard to say for sure by seeing just an error message. Could I take a look at your shader? If you don't want to share it here, you may send it to me in a private message or via email.

Thank you!

 

@zxkne
Hello, thank you for your useful asset.
I'm using softmask for mobile project but I faced performance issues.
Recently I found sometimes softmask made spikes OnCanvasHierarchyChanged since it called GetComponent in NearestMask method.
Can you fix it or can I have some workaround to avoid spikes?

 

Hello,
OnCanvasHierarchyChanged mostly aimed at cases when you move your objects between Canvases or change their 'Sorting Override' property. If you do not do this, as a workaround you may just comment out these calls:
SoftMask.cs:

Code (CSharp):

1. protected override void OnCanvasHierarchyChanged() {
2.     base.OnCanvasHierarchyChanged();
3.     _canvas = null;
4.     _dirty = true;
5.     //NotifyChildrenThatMaskMightChanged();
6. }

SoftMaskable.cs:

Code (CSharp):

1. protected override void OnCanvasHierarchyChanged() {
2.     base.OnCanvasHierarchyChanged();
3.     // A change of override sorting might change the mask instance that's masking us
4.     //FindMaskOrDie();
5. }

Please keep in mind, that with these changes Soft Mask may behave incorrectly in some cases. I'm not 100% sure but I think it should not affect the regular flow unless you're using multiple canvases.
Honestly, I'm not sure if NotifyChildrenThatMaskMightChanged() is really does anything. If I comment it out, all my automation tests still pass. This is not true for the second proposed change. I'll investigate it further and either I write a new test that fails, or remove this call in an upcoming version.
Also, may I ask you a bit more details about the spikes? What's happening in the UI when they occur?
Thank you!

 

Hey @zxkne, our project suddenly seems to be having trouble displaying TextMeshPro underlays for text within a SoftMask. This issue only happens in a build of the game, both for Android and iOS. Other text components use the same TMP font and display properly both in editor and build. Any ideas what the issue might be?

 

As a follow-up, I managed to figure out a workaround. I simply created a duplicate TMP Font asset and preset its material to the SoftMask/TextMeshPro/Mobile/Distance Field. Then I applied that to an instance of text that was under a SoftMask. It not only fixed that one piece of text but also fixed all of the others! I'm wondering if the SoftMask shaders were being stripped from the build since they were only ever used at runtime?

 

Hi @JacobFDunbar,

Sorry for the delay. Yeah, it looks like the required shaders are stripped out of a build. It's a known issue, I didn't manage to fix it yet. Here's what the documentation says:

Your solution is fine too if it works for you.

Have a good day!

 

hi there

does soft mask support the functionality of masking "out of the texture", like the Masking Interaction: Visible Outside of Mask.
i am looking to deduct parts in a texture, and i create a new texture that is used as mask to the main one.
then i want to have an alpha blend as well.

 

and can soft mask also replace the Sprite Mask?
not the mask of the UI?

 

Hi @shacharoz,

If I understand you right, you describe something like Inverted Mask, that is, the areas where a mask is zero are fully opaque and the areas where a mask is one are fully transparent? Please, check out this demo. In a dropdown there select the example 05-InvertedMask. Is it what you asked?

What's about sprites, unfortunately, Soft Mask doesn't support sprites, it works only with UI.

 

hi there: yes inverted mask is what i was looking for ! (great scaling controls you have built by the way

about the sprites - damn it
let me check if i can convert my mechanism. but not sure about that.

 

Sorry if these have been asked and answered, but 6 pages to read is a lot. I have two questions:

First, can I move the mask without having to script 'returning' the position of the child elements? Based on "Separation of a mask from the masked hierarchy." from page 1, it sounds like I can have the mask in a sibling object, and move it without affecting the position of the masked objects?

Second: How CPU intensive is this asset? I'm designing a utility app that is intended to be used/open/active a lot, and battery drain is a massive consideration for my application. With all the features it supports, it sounds like this may be processor intensive?

Basically I'm using this to create screen effects... rolling static, scanlines, screen glitches, etc, by animating the mask moving across the UI. The standard mask element isn't ideal because it must be a parent, and I need to re-set the child position every frame. Plus the lack of alpha support limits the effects I can achieve. Looking at this as a solution (or input/ideas on alternatives, though, thats for another thread I'm about to post).

Any input is appreciated. Thanks all.