Create Dynamic Masks - Gideros only

It has been a while since I have and many other developers have been asking for this functionality. Masks with a Mexican Beer framework has been an issue, it has to be multiples of 4, has to have a border of atleast 2 pixels and none can be created dynamically

This perhaps has been an unintended feature for Gideros as I recollect in one of my conversations with the developers, they mentioned that they will introduce masking soon. The inspiration for this came when I saw the Page curl effect in Gideros that was much more realistic than it was with the other framework, I had created that illusion within an hour (the graphics took time, masks and shadows). However with Gideros this is absolutely a dream, smooth and dynamic.

So how do we make them?

It stems from the fact of how most graphic commands or drawing is done, in the most primitive manner, (quoting a page from Windows API 3.1) each time a device context (dc) needs to be repainted, it used to be passed a dc and a rect, the rect contained the area to be repainted. This was so in order to save on redrawing the whole context where you might have wanted to just repaint a small bit that was just uncovered by another window. This was fast and this was very effective. This formed the basis for a lot of graphical custom controls. It is exactly the same thing that is the formula to create dynamic masks.

Technical Bits

With a dynamic mask, we want to only show a portion of the image than the entire image,what shall help us in this endeavour are a shape control, an image and the masking boundaries. I need to ascertain that this works for other controls/object as well, but I am sure this works for shapes and images. The fundamental idea behind it being that a shape can be filled with colour or an image. The shape can be created in whatever shape you want by using a series of graphics API like MoveTo and LineTo creating a path. So what we do is we create the path of the shape to the dynamic shape that we want masked and voila!! we have a dynamic mask.

I am confused, show me some code

It is but obvious, it is an exciting concept and you need to see it run before you comprehend how it works.

So, first we create a shape, which is quite straight forward

--Create the shape object
local myMask = Shape.new()

--Let's make it visible by placing it on the stage
stage:addChild(myMask)

--Now load the texture (image that we want to mask)
local texture = Texture.new("image1.png")


--Now let us draw the texture in the shape

myMask:clear()
myMask:setFillStyle(Shape.TEXTURE, texture)
myMask:beginPath()
myMask:moveTo(100,10)
myMask:lineTo(150,70)
myMask:lineTo(50,190)
myMask:lineTo(10,30)
myMask:closePath()
myMask:endPath()

Not only that, you can set this up in a function and keep altering the boundaries of the shape to dynamically grow/shrink the mask. The shape can have an outline, so for those clipart/sticker like experiences, you can achieve as simply as this.
Something that simple, always in front of us but missed out.

Gotchas/Gremlins

One thing to note is that the texture fill actually flood fills and that can lead to some very interesting (buggy) outcomes. So ensure that the boundaries that you set are within the dimensions of the image used for filling. Alternatively, you can also use a transformation Matrix to scale/rotate the image to suit your requirements. A tutorial on using matrices is for another day.