Description
Blends a portion of a source image into a portion of another image.
-
Return Type
-
A McImage object.
The destination image.
-
Syntax
-
object.Blend (vSourceImg, [ControlFlags], [SourceBlendPercent], [DestRect], [SourceRect], [vDestImg])
The Blend Method syntax has these parts: |
| object | An expression evaluating to an object of type McGeometry. | | vSourceImg | Required. A Variant value. Required source image or IMcRegionAccess instance. For a source image the VARIANT may hold the IMcImage instance, a string image name or numeric index for an Item in the Images collection. If given as an IMcRegionAccess instance, the SourceRect argument is ignored and is the bounds of the IMcRegionAccess.
| | ControlFlags | Optional. A mcBlendControlFlags enumeration, as described in settings. bit is set, in which case the size will be limited by the destination Aoi bounds.
| | SourceBlendPercent | Optional. A Long value.
The percentage blending factor to use for combining
source with destination. Each matched pixel will be blended
using the following formula,
ResultPixelLuminance = SourcePixelLuminance * SourceBlendPercent/100
DestPixelLuminance * (100-SourceBlendPercent)/100
By default, the BlendPercent is 100, so that each source pixel completely replaces the destination pixel, thus making the default Blend operation equivalent to a Paste.
Blending only is done for pixels that are not optionally masked by the source or destination Aoi and where the optional mcbcfBlendingStyleLighter or mcbcfBlendingStyleDarker ControlFlags criteria are met.
| | DestRect | Optional. A Variant value. Optional destination rectangle for the blend. This may be given as a LONGRECT structure or as a numeric array of length-4 in the order left, top, right, bottom. If given, the left and top must be given, but the right and/or bottom may be given as -1 to indicate that the width and/or height is to be matched to the source rectangle. If not given, then the left-top of the destination rectange is either the destination Aoi's left-top (the default) or if the mcbcfDefaultDestIsImage ControlFlags bit is set, it is 0,0, left-top of the destination image. The default size of the destination rectangle is the SourceRect size unless the mcbcfMaskByDestAoi
| | SourceRect | Optional. A Variant value. Optional source rectangle for the blend. This may be given as a LONGRECT structure or as a numeric array of length-4 in the order left, top, right, bottom. If not given, then the source rectange is either the source Aoi's bounds (the default) or the source image bounds the mcbcfDefaultSourceIsImage ControlFlags bit is set. The final blended rectangle is the intersection of the SourceRect aligned with the DestRect, each clipped to the source and destination Aoi or image bounds.
| | vDestImg | Optional. A Variant value. An optional destination image or McRegionAccess instance. For a destination image the VARIANT may hold the McImage instance, a string image name or numeric index for an Item in the Images collection. What is done with the destination depends on whether the McGeometry operator has a parent image; if so, then the vDestImg Aoi is copied into the parent image's Aoi and then the blending is done into the parent image. If the McGeometry operator is global or otherwise has no image parent, then the blend is done directly into the vDestImag. In this later case, if vDestImg is given as an McRegionAccess instance, the DestRect argument is ignored and is the bounds of the McRegionAccess.
| Settings The settings for ControlFlags are:
 | mcbcfDefault | 0 |
By default a missing SourceRect is the bounds of the source Aoi, a missing DestRect is the bounds of the destination Aoi, no masking by either source or destination Aoi is done and normal blending is done (no conditional blending on lighter or darker pixels). The destination Aoi is left undisturbed and the source image bit-depth is scaled to the destination image's bit-depth.
|
 | mcbcfMaskBySourceAoi | 1 |
If set, source pixels are only blended if they are within the source image's Aoi.
|
 | mcbcfMaskByDestAoi | 2 |
If set, destination pixels are only replaced if they are within the destination image's Aoi.
|
 | mcbcfBlendingStyleLighter | 4 |
Blending only occurs if a destination image pixel is brighter than the corresponding source pixel. This flag and mcbcfBlendingStyleDarker are mutually exclusive.
|
 | mcbcfBlendingStyleDarker | 8 |
Blending only occurs if a destination image pixel is darker than the corresponding source pixel. This flag and mcbcfBlendingStyleLighter are mutually exclusive.
|
 | mcbcfDefaultSourceIsImage | 16 |
If set and no SourceRect argument is given, then the SourceRect will be the whole source image. If not set and no SourceRect argument is given, then the SourceRect will be the bounds of the source image Aoi.
|
 | mcbcfDefaultDestIsImage | 32 |
If set and no DestRect argument is given, then the DestRect will be the whole destination image. If not set and no DestRect argument is given, then the DestRect will be the bounds of the destination image Aoi.
|
 | mcbcfCopySourceAoiToDest | 64 |
If set, after the blending is done, the destination image's Aoi is replaced by a copy of the source image's Aoi, aligned so that the left-top of the SourceRect matches the left-top of the DestRect.
|
 | mcbcfIntersectSourceAndDestAoi | 128 |
If set, after the blending is done, the destination image's Aoi is replaced by a the intersection of the destination image's Aoi and the source image's Aoi, aligned so that the left-top of the SourceRect matches the left-top of the DestRect. If there is no overlap between the source rect and the destination rect, then the Aoi will be cleared.
|
 | mcbcfClearDestAoi | 256 |
If set, after the blending is done, the destination image's Aoi is cleared.
|
 | mcbcfDoNotScaleSource | 2048 |
If set and the source image has a different pixel bit-depth than the destination, no scaling is done to match the source to the destination's bit-depth before blending. If not set (the default), the source image is scaled to match the destination's bit-depth before blending.
|
Remarks
The Blend method is a more general version of the Paste method. It matches each pixel from a portion of a source image (optionally masked by the source image's Aoi) to each pixel in a matching portion (optionally masked by the Aoi) of a destination image (by default, the destination image is the parent image of the McGeometry operator).
A pixel match may be optionally masked by the source and/or destination Aoi and pixels may be optionally blended only if the source pixel is lighter or darker that the corresponding destination pixel.
|