The documentation is at Image Meter - Mask Image.
What this will allow you to do is to define a MaskImageName on the meter, and then the primary image, defined as normal by ImageName or the value of MeasureName, will be "masked" into the image defined by MaskImageName, preserving any transparency in MaskImageName.
The end result is that you can mask an image into a "shape". The sample below will demonstrate.
Let's use three images for now:
This will be our primary image This is an image we will use as a "mask" And another image to use as a "mask"
Code: Select all
[Rainmeter]
Update=1000
DynamicWindowSize=1
AccurateText=1
;Abbey.jpg is 300 X 300
;Circle.png is 300 X 300
;Apple.png is 491 X 480
[MeterMaskedImage]
Meter=Image
W=250
ImagePath=#@#Images\
MaskImagePath=#@#Masks\
ImageName=Abbey.jpg
MaskImageName=Apple.png
[MeterSize]
Meter=String
Y=5R
FontSize=12
FontColor=255,255,255,255
SolidColor=47,47,47,255
Padding=5,5,5,5
AntiAlias=1
Text=W: [MeterMaskedImage:W] | H: [MeterMaskedImage:H]
DynamicVariables=1
MaskImageName
Mask Image is only supported on systems using D2D. This means that it will not work on Windows XP or when D2D is turned off in the Rainmeter settings.
While all image formats are supported for MaskImageName, it is entirely pointless to use any formats except .png or .gif, as the idea is to get a "shape", which requires that some areas of the mask image be transparent or partially transparent.
MaskImagePath can be used to define the path where images specified with MaskImageName can be found. For instance MaskImagePath=#@#Masks\. Alternatively, you can just specify a full or relative path when setting MaskImageName.
Sizing
When MaskImageName is defined, then W and H define the size of the mask image, and the resulting size of the meter. If you define both W and H, then the mask image will be sized to those specific dimensions. If you define only W or H, then the mask image will be sized to the dimension you define, while automatically preserving the aspect ratio. If neither W or H is defined, the size of the mask will be the original image size.
The ImageName defined, either specifically or by binding the meter to a measure with MeasureName, will be sized to fit in the mask image. It will "fill" the image by sizing and cropping as needed, similar to the PreserveAspectRatio=2 setting on a normal image meter.
The result is that if only one of W or H is specified, the code automatically "fits" the mask image while preserving the aspect ratio. It always automatically "fills" the primary image while preserving the aspect ratio. Any PreserveAspectRatio set on the meter is ignored.
While just like with PreserveApectRatio=2 there is no control over the "origin" when the ImageName image is cropped to fit in the MaskImageName image, some control over what part of the image is used when masked can be had by creating a mask image with transparent areas of any size on the left, right, top or bottom as desired. This in effect will allow for some control over what part of the image is "displayed" when the image is sized and cropped to fit the mask. The size of the meter itself will be the full size of the mask image of course, as defined by W and / or H.
So in a sense W and H are used to size both images. Then the ImageName image is masked onto the MaskImageName image, only displaying in non-transparent areas of MaskImageName.
Transparency
If either the primary image or the mask image has areas of transparency or partial transparency, those "alpha channel" values are applied to the final image. When both images have a shared area with full or partial transparency, the "most transparent" value is applied.
Transformations
The mask image can be rotated or flipped, using MaskImageRotate and MaskImageFlip. These work the same as their ImageRotate / ImageFlip counterparts, only they operate on the mask image instead of the primary image.
It should be said though, that transformations with ImageRotate / MaskImageRotate are going to be tricky to get right, given that the W and H of the meter is defined by the non-rotated images, and then the images are rotated inside that existing "container". It is easy to have undesirable clipping of the final image if any rotation causes the primary image to no longer fit the mask image, or the mask image to no longer fit the meter.
While admittedly complex, TransformationMatrix is probably a better approach for manipulating the rotation, skew, etc. of the entire final image. With TransformationMatrix, the entire meter is transformed rather than the image being transformed "inside" the original meter size and shape. As with any use of TransformationMatrix, care should be taken that the meter still fits in the boundaries of the skin when transformed.
Other image transformations, like ScaleMargins and Tile, are not supported at all on the meter if MaskImageName is defined.
Other notes
The Mask Image functionality cannot be used with an Image meter that is drawing a square or rectangle using only SolidColor, and no ImageName. Setting W and H and SolidColor actually only "colors" the meter container itself, and no actual "image" is ever created.
