UIMask

UIMask clips everything below its node in the hierarchy to the area covered by the node’s own UIImage (the component is required and added automatically). Children outside that area are simply not drawn.

../_images/ui_mask.svg

How the mask area is determined:

  • The mask follows the visible pixels of the mask’s image: fully transparent texels are cut out, so a shaped texture (circle, rounded rectangle) gives a shaped mask.

  • The mask is binary — semi-transparent pixels mask exactly like opaque ones, the edge is always hard (no soft feathering).

  • fillMode/fillAmount of the UIImage shrink the mask area as well.

A mask also blocks mouse input outside its frame, so children scrolled out of view can’t be clicked. Masks can be nested — an inner mask clips within the outer one.

Typical tasks: scroll lists (UIScrollArea uses a mask for its view area), round minimaps (a circle texture on the mask), portraits, reveal/wipe effects where you animate the mask’s frame size.

Usage example:

// A panel that clips its content
let panel = create_node(NodeData(parent = canvas))
add_component(panel, new UIImage(size = float2(300., 200.)))
add_component(panel, new UIMask())

// This child is clipped to the 300×200 panel rect
let content = create_node(NodeData(parent = panel))
add_component(content, new UIImage(size = float2(500., 500.), textureId = request_texture("ui/map.png")))

See also the UI Basics guide.

Classes

UIMask : NativeComponent

Note

UIImage component is automatically added to the node if it is not already present

Component that clips all descendant UI elements to the visible pixels of the node’s own UIImage. Children outside the mask area are not drawn and don’t receive mouse input.

Properties:

UIMask.enabled: bool
UIMask.enabled =(value: bool)

Whether the mask is enabled and applied to descendant UI elements.

Arguments:

  • value : bool

UIMask.showMaskSource: bool
UIMask.showMaskSource =(value: bool)

If true, the mask’s own image is also drawn on screen (e.g. a visible panel background); if false, the image only defines the mask area and is invisible.

Arguments:

  • value : bool