The MaskGroup node allows an alpha mask bitmap to be applied to the rendering of its children. This allows effects such as having a list fade out at the bottom to be easily created.
Note: MaskGroup does not work on all Roku hardware (specifically, MaskGroup only works on hardware that supports OpenGL). On hardware whose graphics do not support OpenGL, MaskGroup just renders its children without applying the extra alpha mask.
Unlike other bitmaps, the MaskGroup does not work with 9-patch images. If the bitmap size does not match the group's bounding rectangle, the edge rows of the mask are repeated as needed. For example, suppose the MaskGroup's bounding rectangle has an origin at (0, 0), a width of 150 and a height of 80. If the mask bitmap were also 150 by 80 and the maskOffset and maskSize fields were left at their default values of [ 0, 0 ], then each pixel of the mask bitmap would be applied to corresponding pixel of the MaskGroup's bounding rectangle. The figure below illustrates that case. On the right is a MaskGroup that contains a Poster. In the center is an alpha bitmap with the same size as the Poster. On the right is the result of rendering the MaskGroup with the image in the center used as a mask.
Figure 1 - On the right is the unmasked MaskGroup. In the center, a mask bitmap is shown that has the same size as the MaskGroup's bounding rectangle. The result of applying the mask to the MaskGroup is shown on the right.
The maskSize and maskOffset fields can be used to scale and offset the mask bitmap relative to the group's coordinate system, as shown in the figure below. In the case, the maskOffset field has been set to (50, 30), offsetting the origin of the mask bitmap's coordinate system relative to the origin of the MaskGroup's coordinate system 50 pixels to the left and 30 pixels down.The maskSize field has been set to (100, 50), This causes the width of the mask bitmap to be scaled from 150 to 100 and the height of the mask bitmap to be scaled from 80 to 50, so that the mask's right edge aligns with the right edge of the MaskGroup's bounding rectangle and the mask's bottom edge aligns with the bottom edge of the MaskGroup's bounding rectangle. The center of the figure shows the mask with the maskOffset and maskSize applied overlaid on top of the MaskGroup The right side of the figure shows the result of applying the mask to the MaskGroup. Notice that the left column of pixels in the mask is used as the mask for all columns of the MaskGroup that lie to the left of the mask, causing those columns to be rendered with full opacity. Similarly, and the top row of the mask is used as the mask for all rows of the MaskGroup that lie above the mask, causing each of the rows to fade out on the right.
Figure 2 - On the right is the unmasked MaskGroup. In the center, the mask is shown overlaid on top of the MaskGroup. The mask is the same bitmap as in Figure 1 with the maskOffset field set to (50, 30) and the maskSize field set to (100, 50). The result of applying the mask to the MaskGroup is shown on the right.
|maskUri||string||""||Specifies the bitmap to use for the group's alpha mask. Each pixel that's rendered in the group is multiplied by the value of a pixel in the alpha mask. The mapping from pixel coordinates in the group to mask pixel coordinates is controlled by the maskSize and maskOffset fields. Those fields define a coordinate system relative to the group's coordinate system that is used to map group coordinate values to mask coordinates.|
|maskSize||Vector2D||[ 0, 0 ]||Specifies a scaling factor of the alpha mask's coordinate system relative to the group's coordinate system. For example, if the maskSize is set to [2, 2], then each pixel in the mask is applied to 2 pixels in the group's coordinate system. Setting either element of the maskSize vector to 0 causes the mask bitmap to be used at its actual size in that direction.|
|maskOffset||Vector2D||[0, 0 ]||Specifies an offset of the mask coordinate system relative to the group's coordinate system. For example, if the maskOffset is set to [ 100, 0 ], then mask pixel [0, 0] is used as the alpha value for group coordinate [100, 0]. Group coordinate [ 50, 0 ] would map to mask coordinate [-50, 0], but since mask coordinates are clamped to the range 0 to mask|
|maskBitmapWidth||float||0||A read-only field that contains the actual width of the mask bitmap. The mask bitmap can be stretched horizontally by setting maskSize to a different value than maskBitmapWidth.|
|maskBitmapHeight||float||0||A read-only field that contains the actual height of the mask bitmap. The mask bitmap can be stretched vertically by setting maskSize to a different value than maskBitmapHeight.|