Blend 2 images with copypixels and alpha mask

-- copyImageWithMask
--
-- DESCRIPTION:
-- Blend 2 images with given mask
--
-- PARAMETERS:
-- theImage1 is the base image object (member or image)
-- theImage2 is the image object to be blended on top of theImage1 (member or image)
-- theMask   is the black and white mask to be used to perform the blending (member or image)
--
-- NOTE:
-- Both the images and the mask are supposed to be the same size.
-- In the test environment it was used png images as source, with 32bit depth.
--
-- EXAMPLE:
-- myImg = copyImageWithMask(theImage1, theImage2, theMask)
 
on copyImageWithMask theImage1, theImage2, theMask
  -- Process the mask and the clean images
  img1 = theImage1.image.duplicate()
  img2 = theImage2.image.duplicate()
  imask =  theMask.image.createMask()  
 
  -- Explicitly state the Alpha Modes
  img1.useAlpha = TRUE        
  img2.usealpha = FALSE
 
  -- Copy operation
  img1.copyPixels(img2, img1.rect, img2.rect, [#ink:#mask, #maskimage:imask])
 
  -- Return the image
  return img1.duplicate()
end