MaskGroup

MaskGroup component for applying alpha masks to child content

import { MaskGroup } from "@roku-sdk/components";

MaskGroup(props: IMaskGroupProps): JSX.Element

Description

MaskGroup component for applying alpha masks to child content.

Use MaskGroup to create decorative effects like fading content at edges, vignette effects, or shaped reveals. The mask bitmap's alpha channel determines the opacity of the rendered children.

How Masking Works:

• Each pixel's alpha is multiplied by the corresponding mask pixel value
• White (255) in the mask = fully visible
• Black (0) in the mask = fully transparent
• Gray values = partial transparency

Limitations:

• Only works on OpenGL-capable Roku devices
• On other devices, children render normally without the mask
• Not suitable for critical UI elements due to device variability
• Does not support 9-patch images

Parameters

Example

// Basic fade effect at bottom
<maskGroup maskUri="pkg:/images/bottom-fade.png">
    <poster uri="pkg:/images/hero.jpg" width={1920} height={1080} />
</maskGroup>

// Scaled and offset mask
<maskGroup
    maskUri="pkg:/images/vignette.png"
    maskSize={[800, 600]}
    maskOffset={[100, 50]}
>
    <rectangle width={1000} height={700} color="#FF0000FF" />
</maskGroup>

// Circular reveal effect
<maskGroup maskUri="pkg:/images/circle-mask.png">
    <poster uri={thumbnailUri} width={200} height={200} />
</maskGroup>

Types

IMaskGroupProps

Properties for the MaskGroup node.

MaskGroup allows an alpha mask bitmap to be applied to the rendering of its children. This enables effects such as having content fade out at edges.

Important Notes:

• MaskGroup only works on Roku players that support OpenGL
• On non-OpenGL players, children render without the mask effect
• Should only be used for decorative purposes (fading effects, etc.)
• Does NOT work with 9-patch images
• If mask size doesn't match group bounds, edge rows/columns are repeated

Example

<MaskGroup maskUri="pkg:/images/fade-mask.png">
    <Poster uri="pkg:/images/content.jpg" width={400} height={300} />
</MaskGroup>

Extends IGroupProps.

IMaskGroupProps.maskOffset

Specifies an offset of the mask coordinate system relative to the group coordinate system.

For example, if set to [100, 0], then mask pixel [0, 0] is used as the alpha value for pixels rendered at group coordinate [100, 0].

IMaskGroupProps.maskSize

Specifies a scaling factor of the alpha mask coordinate system relative to the group coordinate system.

If either element doesn't match the corresponding mask bitmap size (reported via onMaskBitmapWidth / onMaskBitmapHeight), the mask is scaled to the specified size in that dimension.

Setting either element to 0 causes the mask bitmap to be used at its actual size in that dimension.

IMaskGroupProps.maskUri

Specifies the bitmap to use for the group alpha mask.

The alpha value of each pixel rendered in the group is multiplied by the corresponding pixel value in the alpha mask. The mapping from pixel coordinates in the group to mask pixel coordinates is controlled by the maskSize and maskOffset field values.