BltMaskBitMapRastPort

blit from source BitMap to destination RastPort with masking of source image. The mask acts like a stencil or frisket. (V33)

Blits from source BitMap to position specified in destination RastPort using bltmask to determine where source overlays destination, and minterm to determine whether to copy the source image "as is" or to "invert" the sense of the source image when copying.

In either case, blit only occurs where a bit in the mask is non-zero. The mask acts like a stencil or frisket, so that only the destination area will be affected for which the mask has a pixel set to 1.

srcbm

A pointer to the source BitMap

srcx

X offset into source BitMap

srcy

Y offset into source BitMap

destrp

A pointer to the destination RastPort

destX

X offset into destination RastPort

destY

Y offset into destination RastPort

sizeX

Width of blit in pixels

sizeY

Height of blit in rows

minterm

Either (ABC|ABNC|ANBC) if copy source and blit thru mask or (ANBC) if invert source and blit thru mask

bltmask

Pointer to the single bit-plane mask, which must be the same size and dimensions as the planes of the source BitMap, i.e. as wide and high as the source.

CAUTION:

The bltmask plane must reside in chip memory. It can be created with AllocRaster().

The BltMaskBitMapRastPort() function has always been documented as requiring the bltmask plane to have the exact dimensions as the area being copied. While these requirements applied to Kickstart 3.0 and 3.1 alike, the use of an interleaved BitMap for the srcbm parameter would invariably produce a corrupted copy. This bug breaks correct code which followed the official documentation on how to create a correct bltmask plane without making assumptions about the srcbm width or height.

This bug, which was a side-effect of how the interleaved srcbm was used by BltMaskBitMapRastPort(), could be worked around as discussed in the NOTES section. However, this workaround creates additional complications which will manifest as a bug on Amigas for which the BltMaskBitMapRastPort() bug has been fixed (V45).

The maximum number of bit planes used by srcbm and dstbm is limited to 8 in V33-V44. This limit has been raised to a maximum of 24 planes in V45. Please note that it unsafe to use more than 24 planes in V45.

WHY IMAGE CORRUPTION CAN OCCUR IN KICKSTART 3.0 AND 3.1

The BltMaskBitMapRastPort() function's chief purpose is to render images such as Workbench icons, painting in only the shape covered by the bltmask and leaving the rest unchanged.

The Amiga Blitter would be able to conveniently handle blitting an image through a mask to the destination BitMap, but BltMaskBitMapRastPort() has to make use of the BltBitMap() function which features only two source bitmaps, with the second source also being the destination.

For this reason the "simple" blit operation has to be broken down into a sequence of three individual blits, which is why it might flicker a little when performed.

Because BltBitMap() is used, a temporary BitMap will be constructed using the bltmask plane. This works well enough for standard format planar image data such as used by intuition.library/DrawImage but there are problems when using an interleaved source BitMap. A bug in the V39/V40 BltMaskBitMapRastPort() function caused the temporary BitMap constructed using the bltmask plane to be both too wide and too tall for the mask data available.

Interleaved BitMaps are typically featuring BitMap.BytesPerRow values much greater than what the InitBitMap() function would fill in. Please see the AllocBitMap() documentation for a detailed description of how interleaved BitMaps work.

Because the bltmask plane is supposed to be created in the manner documented for Kickstart 1.0-2.04 (see the RASSIZE() macro in <graphics/gfx.h> and the AllocRaster() documentation) it will appear to be both narrower and shorter than the interleaved srcbm BitMap. This accounts for the apparent corruption of the image copied: the mask no longer exactly matches the dimensions (width and height) of the interleaved srcbm BitMap.

WORKAROUND FOR AVOIDING THE IMAGE CORRUPTION

A workaround which saw wider use in 1992 and beyond (Kickstart versions 3.0 and 3.1) has side-effects and will only work with a graphics.library which features the image corruption bug. Put another way, it "works correctly" only under the assumption that the BltMaskBitMapRastPort() function *does not work correctly*.

Because the width of the bltmask plane does not match the interleaved srcbm BitMap, it was discovered that you could make it fit by allocating the plane in a specific manner:

This workaround is discouraged for three reasons. The first being that assumptions are made about the contents of a BitMap created through the AllocBitMap() function. These assumptions are bound not to hold because of how retargetable graphics (RTG) may store the image data. The second reason is that you cannot determine in advance and with confidence if the BltMaskBitMapRastPort() bug fix is in effect. If it is, then the workaround will produce a corrupted image which is what the workaround was intended to avoid. The third reason is that RTG systems may not make the same assumptions about the bltmask plane as the graphics.library internals, which may lead to corruption.

WHY ONLY THE TWO PROVIDED MINTERM VALUES ARE USEFUL

As mentioned above, the blit operation performed by the BltMaskBitMapRastPort() function has to be broken down into a sequence of three individual BltBitMap() calls. These blits are designed to be performed in such a manner that the same results will be achieved as if a single blit operation using two sources and a separate destination were performed.

In order to conserve ROM space, the minterms chosen are optimized for two cases only. This being "copying the source image through a mask" with (ABC|ABNC|ANBC) as the minterm and "copy the inverted source image through a mask" with the mintern (ANBC). While the BltMaskBitMapRastPort() function does not enforce the use of these two documented minterms, no other minterms achieve such outcomes (note that because BltBitMap() does not use source A, minterms which use logic terms that employ A or ~A will produce identical results).

BltMaskBitMapRastPort() is limited to a maximum of 8 bit planes in V33-V44. If the BitMaps involved use more than these, data corruption and undefined behaviour will follow.

This function did not work properly in V39 and V40 if the srcbm BitMap was interleaved. In such a case, the mask was erroneously expected to be as wide as 8 * srcbm->BytesPerRow pixels. This was fixed in V45.

AllocBitMap(), AllocRaster(), BltBitMap(), BltBitMapRastPort(), ClipBlit(), DrawImage(), GetBitMapAttr(), RASSIZE(), <graphics/gfx.h> <graphics/rastport.h>