Class Mask

A visual element that applies color masking effects to create visual overlays and highlights.

Inheritance
object
CallbackEventHandler
Focusable
VisualElement
Image
Mask
Implements
Inherited Members
VisualElement.Focus()
VisualElement.Overlaps(Rect)
VisualElement.ToString()
VisualElement.TryGetBinding(BindingId, out Binding)
VisualElement.TryGetDataSourceContext(BindingId, out DataSourceContext)
VisualElement.TryGetLastBindingToUIResult(in BindingId, out BindingResult)
VisualElement.TryGetLastBindingToSourceResult(in BindingId, out BindingResult)
VisualElement.GetFirstOfType<T>()
VisualElement.GetFirstAncestorOfType<T>()
VisualElement.canGrabFocus
VisualElement.focusController
VisualElement.cacheAsBitmap
CallbackEventHandler.RegisterCallback<TEventType>(EventCallback<TEventType>, TrickleDown)
CallbackEventHandler.RegisterCallbackOnce<TEventType>(EventCallback<TEventType>, TrickleDown)
CallbackEventHandler.RegisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TUserArgsType, TrickleDown)
CallbackEventHandler.RegisterCallbackOnce<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TUserArgsType, TrickleDown)
CallbackEventHandler.RegisterCallback<TEventType>(EventCallback<TEventType>, CallbackOptions)
CallbackEventHandler.RegisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TUserArgsType, CallbackOptions)
CallbackEventHandler.UnregisterCallback<TEventType>(EventCallback<TEventType>, TrickleDown)
CallbackEventHandler.UnregisterCallback<TEventType>(EventCallback<TEventType>, CallbackOptions)
CallbackEventHandler.UnregisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TrickleDown)
CallbackEventHandler.UnregisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, CallbackOptions)
CallbackEventHandler.NotifyPropertyChanged(in BindingId)
Namespace: Unity.AppUI.UI
Assembly: Unity.AppUI.dll
Syntax
[UxmlElement]
public class Mask : Image, IEventHandler, IResolvedStyle, ITransform, ITransitionAnimations, IExperimentalFeatures, IVisualElementScheduler
Remarks

The Mask component is a versatile visual element that allows you to create masked areas with customizable colors, shapes, and effects. It's particularly useful for creating spotlight effects, highlighting specific areas, or creating visual overlays in your UI.

The component provides fine control over the mask's appearance through properties like inner and outer colors, mask rectangle dimensions, corner radius, and blur effects. You can specify mask dimensions either in absolute pixels or normalized coordinates (0-1 range).

Note: The Mask component inherits from Image and uses a custom shader to generate the masking effect. The mask is rendered using a RenderTexture that automatically adjusts to the component's size.

Examples

Creating a spotlight effect

var spotlight = new Mask();
spotlight.style.position = Position.Absolute;
spotlight.style.width = new StyleLength(new Length(100, LengthUnit.Percent));
spotlight.style.height = new StyleLength(new Length(100, LengthUnit.Percent));
spotlight.innerMaskColor = Color.clear;
spotlight.outerMaskColor = new Color(0, 0, 0, 0.7f);
spotlight.maskRect = new Rect(100, 100, 200, 200);
spotlight.radius = 100f; // Circular spotlight
spotlight.blur = 20f; // Soft edges

Creating a responsive highlight area using normalized coordinates

var highlight = new Mask();
highlight.useNormalizedMaskRect = true;
highlight.innerMaskColor = new Color(1, 1, 0, 0.2f); // Semi-transparent yellow
highlight.outerMaskColor = Color.clear;
highlight.maskRect = new Rect(0.1f, 0.1f, 0.8f, 0.2f); // Highlight strip
highlight.radius = 10f;
highlight.blur = 5f;

UXML definition example

<UXML xmlns="UnityEngine.UIElements">
    <Mask
        inner-mask-color="#FFFFFF"
        outer-mask-color="#000000AA"
        mask-rect-x="50"
        mask-rect-y="50"
        mask-rect-width="300"
        mask-rect-height="200"
        radius="15"
        blur="10"
        use-normalized-mask-rect="false"
        style="position: absolute; width: 100%; height: 100%;" />
</UXML>

Constructors

Mask()

Default constructor.

Declaration
public Mask()

Fields

ussClassName

The Mask main styling class.

Declaration
public const string ussClassName = "appui-mask"
Field Value
Type Description
string

Properties

blur

The mask blur. Sets the blur of the mask (in pixels).

Declaration
[CreateProperty]
[UxmlAttribute]
public float blur { get; set; }
Property Value
Type Description
float

contentContainer

The content container of this element.

Declaration
public override VisualElement contentContainer { get; }
Property Value
Type Description
VisualElement
Overrides

innerMaskColor

The inner mask color. Sets the color of the inner mask.

Declaration
[CreateProperty]
[UxmlAttribute]
public Color innerMaskColor { get; set; }
Property Value
Type Description
Color

maskRect

The mask rect. Sets the rect of the mask (in pixels or normalized if useNormalizedMaskRect is true).

Declaration
[CreateProperty]
[UxmlAttribute]
public Rect maskRect { get; set; }
Property Value
Type Description
Rect

outerMaskColor

The outer mask color. The color of the area outside the mask.

Declaration
[CreateProperty]
[UxmlAttribute]
public Color outerMaskColor { get; set; }
Property Value
Type Description
Color

radius

The mask radius. Sets the radius of the rounded corners (in pixels).

Declaration
[CreateProperty]
[UxmlAttribute]
public float radius { get; set; }
Property Value
Type Description
float

useNormalizedMaskRect

If true, the mask rect you will provide through maskRect must be normalized (0-1) instead of using pixels coordinates.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool useNormalizedMaskRect { get; set; }
Property Value
Type Description
bool

Implements

Extension Methods