bitmaptools.alphablend: add optional L8 mask= kwarg

Adds an optional mask= keyword argument to bitmaptools.alphablend()
that scales source2's per-pixel contribution by an L8 bitmap (one
byte per pixel, 0..255). When mask is None (default), behavior is
unchanged from the existing alphablend.

Mask bitmap must match the output bitmap's width and height and have
a bits_per_value of 8.

Author: makermelissa-piclaw

locale/circuitpython.pot

@@ -1441,6 +1441,14 @@ msgstr ""
 msgid "Mapping must be a tuple"
 msgstr ""
 
+#: shared-bindings/bitmaptools/__init__.c
+msgid "Mask bitmap must have 8 bits per pixel"
+msgstr ""
+
+#: shared-bindings/bitmaptools/__init__.c
+msgid "Mask bitmap size must match the other bitmaps"
+msgstr ""
+
 #: py/persistentcode.c
 msgid "MicroPython .mpy file; use CircuitPython mpy-cross"
 msgstr ""

shared-bindings/bitmaptools/__init__.c

@@ -311,6 +311,7 @@ MAKE_ENUM_TYPE(bitmaptools, BlendMode, bitmaptools_blendmode);
 //|     blendmode: Optional[BlendMode] = BlendMode.Normal,
 //|     skip_source1_index: Union[int, None] = None,
 //|     skip_source2_index: Union[int, None] = None,
+//|     mask: Optional[displayio.Bitmap] = None,
 //| ) -> None:
 //|     """Alpha blend the two source bitmaps into the destination.
 //|
@@ -326,14 +327,19 @@ MAKE_ENUM_TYPE(bitmaptools, BlendMode, bitmaptools_blendmode);
 //|     :param bitmaptools.BlendMode blendmode: The blend mode to use. Default is Normal.
 //|     :param int skip_source1_index: Bitmap palette or luminance index in source_bitmap_1 that will not be blended, set to None to blend all pixels
 //|     :param int skip_source2_index: Bitmap palette or luminance index in source_bitmap_2 that will not be blended, set to None to blend all pixels
+//|     :param displayio.Bitmap mask: Optional 8-bits-per-value grayscale mask bitmap controlling per-pixel opacity of ``source_bitmap_2``.
+//|         The mask must have the same width and height as the other bitmaps and a ``bits_per_value`` of 8. A mask value of 0
+//|         means ``source_bitmap_2`` is fully transparent at that pixel (only ``source_bitmap_1`` contributes); a value of 255 means
+//|         ``source_bitmap_2`` is fully opaque at that pixel (subject to ``factor2``). Intermediate values scale ``factor2`` linearly.
+//|         Pass ``None`` to disable per-pixel masking.
 //|
 //|     For the L8 colorspace, the bitmaps must have a bits-per-value of 8.
 //|     For the RGB colorspaces, they must have a bits-per-value of 16."""
 //|
 //|
 
 static mp_obj_t bitmaptools_alphablend(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    enum {ARG_dest_bitmap, ARG_source_bitmap_1, ARG_source_bitmap_2, ARG_colorspace, ARG_factor_1, ARG_factor_2, ARG_blendmode, ARG_skip_source1_index, ARG_skip_source2_index};
+    enum {ARG_dest_bitmap, ARG_source_bitmap_1, ARG_source_bitmap_2, ARG_colorspace, ARG_factor_1, ARG_factor_2, ARG_blendmode, ARG_skip_source1_index, ARG_skip_source2_index, ARG_mask};
 
     static const mp_arg_t allowed_args[] = {
         {MP_QSTR_dest_bitmap, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = NULL}},
@@ -345,6 +351,7 @@ static mp_obj_t bitmaptools_alphablend(size_t n_args, const mp_obj_t *pos_args,
         {MP_QSTR_blendmode, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = (void *)&bitmaptools_blendmode_Normal_obj}},
         {MP_QSTR_skip_source1_index, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = mp_const_none} },
         {MP_QSTR_skip_source2_index, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = mp_const_none} },
+        {MP_QSTR_mask, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = mp_const_none} },
     };
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
     mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
@@ -411,8 +418,19 @@ static mp_obj_t bitmaptools_alphablend(size_t n_args, const mp_obj_t *pos_args,
         skip_source2_index_none = false;
     }
 
+    displayio_bitmap_t *mask = NULL;
+    if (args[ARG_mask].u_obj != mp_const_none) {
+        mask = MP_OBJ_TO_PTR(mp_arg_validate_type(args[ARG_mask].u_obj, &displayio_bitmap_type, MP_QSTR_mask));
+        if (mask->width != destination->width || mask->height != destination->height) {
+            mp_raise_ValueError(MP_ERROR_TEXT("Mask bitmap size must match the other bitmaps"));
+        }
+        if (mask->bits_per_value != 8) {
+            mp_raise_ValueError(MP_ERROR_TEXT("Mask bitmap must have 8 bits per pixel"));
+        }
+    }
+
     common_hal_bitmaptools_alphablend(destination, source1, source2, colorspace, factor1, factor2, blendmode, skip_source1_index,
-        skip_source1_index_none, skip_source2_index, skip_source2_index_none);
+        skip_source1_index_none, skip_source2_index, skip_source2_index_none, mask);
 
     return mp_const_none;
 }

shared-bindings/bitmaptools/__init__.h

@@ -69,7 +69,8 @@ void common_hal_bitmaptools_arrayblit(displayio_bitmap_t *self, void *data, int
 void common_hal_bitmaptools_dither(displayio_bitmap_t *dest_bitmap, displayio_bitmap_t *source_bitmap, displayio_colorspace_t colorspace, bitmaptools_dither_algorithm_t algorithm);
 
 void common_hal_bitmaptools_alphablend(displayio_bitmap_t *destination, displayio_bitmap_t *source1, displayio_bitmap_t *source2, displayio_colorspace_t colorspace, mp_float_t factor1, mp_float_t factor2,
-    bitmaptools_blendmode_t blendmode, uint32_t skip_source1_index, bool skip_source1_index_none, uint32_t skip_source2_index, bool skip_source2_index_none);
+    bitmaptools_blendmode_t blendmode, uint32_t skip_source1_index, bool skip_source1_index_none, uint32_t skip_source2_index, bool skip_source2_index_none,
+    displayio_bitmap_t *mask);
 
 typedef struct {
     union {

shared-module/bitmaptools/__init__.c

@@ -857,23 +857,36 @@ void common_hal_bitmaptools_dither(displayio_bitmap_t *dest_bitmap, displayio_bi
 }
 
 void common_hal_bitmaptools_alphablend(displayio_bitmap_t *dest, displayio_bitmap_t *source1, displayio_bitmap_t *source2, displayio_colorspace_t colorspace, mp_float_t factor1, mp_float_t factor2,
-    bitmaptools_blendmode_t blendmode, uint32_t skip_source1_index, bool skip_source1_index_none, uint32_t skip_source2_index, bool skip_source2_index_none) {
+    bitmaptools_blendmode_t blendmode, uint32_t skip_source1_index, bool skip_source1_index_none, uint32_t skip_source2_index, bool skip_source2_index_none,
+    displayio_bitmap_t *mask) {
     displayio_area_t a = {0, 0, dest->width, dest->height, NULL};
     displayio_bitmap_set_dirty_area(dest, &a);
 
-    int ifactor1 = (int)(factor1 * 256);
-    int ifactor2 = (int)(factor2 * 256);
+    int ifactor1_base = (int)(factor1 * 256);
+    int ifactor2_base = (int)(factor2 * 256);
+    int ifactor1 = ifactor1_base;
+    int ifactor2 = ifactor2_base;
     bool blend_source1, blend_source2;
 
     if (colorspace == DISPLAYIO_COLORSPACE_L8) {
         for (int y = 0; y < dest->height; y++) {
             uint8_t *dptr = (uint8_t *)(dest->data + y * dest->stride);
             uint8_t *sptr1 = (uint8_t *)(source1->data + y * source1->stride);
             uint8_t *sptr2 = (uint8_t *)(source2->data + y * source2->stride);
+            uint8_t *mptr = mask ? (uint8_t *)(mask->data + y * mask->stride) : NULL;
             int pixel;
             for (int x = 0; x < dest->width; x++) {
                 blend_source1 = skip_source1_index_none || *sptr1 != (uint8_t)skip_source1_index;
                 blend_source2 = skip_source2_index_none || *sptr2 != (uint8_t)skip_source2_index;
+                if (mptr) {
+                    uint8_t m = *mptr;
+                    // Scale source2's contribution by the mask (0..255)
+                    ifactor2 = (ifactor2_base * m + 127) / 255;
+                    if (m == 0) {
+                        // Mask says fully transparent: drop source2 entirely
+                        blend_source2 = false;
+                    }
+                }
                 if (blend_source1 && blend_source2) {
                     // Premultiply by the alpha factor
                     int sda = *sptr1++ *ifactor1;
@@ -886,7 +899,8 @@ void common_hal_bitmaptools_alphablend(displayio_bitmap_t *dest, displayio_bitma
                         blend = sca + sda * (256 - ifactor2) / 256;
                     }
                     // Divide by the alpha factor
-                    pixel = (blend / (ifactor1 + ifactor2 - ifactor1 * ifactor2 / 256));
+                    int denom = ifactor1 + ifactor2 - ifactor1 * ifactor2 / 256;
+                    pixel = (denom > 0) ? (blend / denom) : 0;
                 } else if (blend_source1) {
                     // Apply iFactor1 to source1 only
                     pixel = *sptr1++ *ifactor1 / 256;
@@ -898,6 +912,9 @@ void common_hal_bitmaptools_alphablend(displayio_bitmap_t *dest, displayio_bitma
                     pixel = *dptr;
                 }
                 *dptr++ = MIN(255, MAX(0, pixel));
+                if (mptr) {
+                    mptr++;
+                }
             }
         }
     } else {
@@ -907,6 +924,7 @@ void common_hal_bitmaptools_alphablend(displayio_bitmap_t *dest, displayio_bitma
             uint16_t *dptr = (uint16_t *)(dest->data + y * dest->stride);
             uint16_t *sptr1 = (uint16_t *)(source1->data + y * source1->stride);
             uint16_t *sptr2 = (uint16_t *)(source2->data + y * source2->stride);
+            uint8_t *mptr = mask ? (uint8_t *)(mask->data + y * mask->stride) : NULL;
             for (int x = 0; x < dest->width; x++) {
                 int spix1 = *sptr1++;
                 int spix2 = *sptr2++;
@@ -922,11 +940,24 @@ void common_hal_bitmaptools_alphablend(displayio_bitmap_t *dest, displayio_bitma
                 blend_source1 = skip_source1_index_none || spix1 != (int)skip_source1_index;
                 blend_source2 = skip_source2_index_none || spix2 != (int)skip_source2_index;
 
+                if (mptr) {
+                    uint8_t m = *mptr++;
+                    ifactor2 = (ifactor2_base * m + 127) / 255;
+                    if (m == 0) {
+                        blend_source2 = false;
+                    }
+                }
+
                 if (blend_source1 && blend_source2) {
                     // Blend based on the SVG alpha compositing specs
                     // https://dev.w3.org/SVG/modules/compositing/master/#alphaCompositing
 
                     int ifactor_blend = ifactor1 + ifactor2 - ifactor1 * ifactor2 / 256;
+                    if (ifactor_blend <= 0) {
+                        // Both factors are zero at this pixel; keep destination.
+                        dptr++;
+                        continue;
+                    }
 
                     // Premultiply the colors by the alpha factor
                     int red_dca = ((spix1 & r_mask) >> 8) * ifactor1;