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 400 and a height of 300. If the mask bitmap were also 400 by 300 and the mask offset were set to (0, 0), then each pixel of the mask bitmap would be applied to corresponding pixel of the MaskGroup's bounding rectangle.
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.
<NEED A FIGURE HERE - ASK JIM FOR DETAILS>
In the above example, if the mask bitmap were only 200 pixels wide and 100 pixels tall with the maskSize field set to (200, 100) and the maskOffsetField set to (0,0), then when rendering the group, pixels with X coordinates from 0 to 200 would use the corresponding pixels of the mask bitmap. For pixels with X coordinates from 200 to 400, the right column of the mask bitmap would be used as their alpha mask. Similarly, pixels with Y coordinates from 0 to 100 would use the corresponding pixels of the mask bitmap as their alpha mask. Pixels with Y coordinates from 100 to 300 would use the values in the bottom row of the mask bitmap as their alpha mask.
The maskOffset field can be used to offset the region of the mask that is mapped to the origin of the group's bounding rectangle. Suppose you wanted to apply an alpha fade along the bottom 50 rows at the bottom of the same group as above (i.e. the group's bounding rectangle has origin = (0,0), width = 400 and height 300). To do this, you could create a small texture that was 1 column wide and 50 rows tall. The texture only needs to be 1 column wide because in this case, you want the same pixels to be used for all columns of the mask. To set up the fade, the mask bitmap would have a 50 pixel gradient from fully opaque at the top to fully transparent at the bottom. The maskOffset field would be set to (0, 250). By doing this, the fully opaque pixel in row 0 would be replicated as the alpha mask for rendered pixels with Y coordinates from 0 to 150 (i.e. the top row of the mask is replicated if the offset mask coordinate is less than zero).Pixels with Y coordinates from 250 to 300 would use the rows 0 to 50 of the alpha mask bitmap as their mask, resulting in the group fading out over the bottom 50 rows.
|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.|
|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|