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:

PartDescription
objectAn expression evaluating to an object of type McGeometry.
vSourceImgRequired. 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.

ControlFlagsOptional. A mcBlendControlFlags enumeration, as described in settings.

bit is set, in which case the size will be limited by the destination Aoi bounds.

SourceBlendPercentOptional. 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.

DestRectOptional. 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

SourceRectOptional. 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.

vDestImgOptional. 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:

ConstantValueDescription
 mcbcfDefault0

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.

 mcbcfMaskBySourceAoi1

If set, source pixels are only blended if they are within the source image's Aoi.

 mcbcfMaskByDestAoi2

If set, destination pixels are only replaced if they are within the destination image's Aoi.

 mcbcfBlendingStyleLighter4

Blending only occurs if a destination image pixel is brighter than the corresponding source pixel. This flag and mcbcfBlendingStyleDarker are mutually exclusive.

 mcbcfBlendingStyleDarker8

Blending only occurs if a destination image pixel is darker than the corresponding source pixel. This flag and mcbcfBlendingStyleLighter are mutually exclusive.

 mcbcfDefaultSourceIsImage16

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.

 mcbcfDefaultDestIsImage32

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.

 mcbcfCopySourceAoiToDest64

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.

 mcbcfIntersectSourceAndDestAoi128

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.

 mcbcfClearDestAoi256

If set, after the blending is done, the destination image's Aoi is cleared.

 mcbcfDoNotScaleSource2048

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.