displayio/_bitmap.py

   1 # SPDX-FileCopyrightText: 2020 Melissa LeBlanc-Williams for Adafruit Industries
   2 #
   3 # SPDX-License-Identifier: MIT
   4
   5 """
   6 `displayio.bitmap`
   7 ================================================================================
   8
   9 displayio for Blinka
  10
  11 **Software and Dependencies:**
  12
  13 * Adafruit Blinka:
  14   https://github.com/adafruit/Adafruit_Blinka/releases
  15
  16 * Author(s): Melissa LeBlanc-Williams
  17
  18 """
  19
  20 from __future__ import annotations
  21 import struct
  22 from array import array
  23 from typing import Union, Tuple
  24 from circuitpython_typing import WriteableBuffer
  25 from ._area import Area
  26
  27 __version__ = "0.0.0+auto.0"
  28 __repo__ = "https://github.com/adafruit/Adafruit_Blinka_displayio.git"
  29
  30
  31 def stride(width: int, bits_per_pixel: int) -> int:
  32     """Return the number of bytes per row of a bitmap with the given width and bits per pixel."""
  33     row_width = width * bits_per_pixel
  34     return (row_width + (31)) // 32
  35
  36
  37 class Bitmap:
  38     """Stores values of a certain size in a 2D array
  39
  40     Bitmaps can be treated as read-only buffers. If the number of bits in a pixel is 8, 16,
  41     or 32; and the number of bytes per row is a multiple of 4, then the resulting memoryview
  42     will correspond directly with the bitmap's contents. Otherwise, the bitmap data is packed
  43     into the memoryview with unspecified padding.
  44
  45     A Bitmap can be treated as a buffer, allowing its content to be
  46     viewed and modified using e.g., with ``ulab.numpy.frombuffer``,
  47     but the `displayio.Bitmap.dirty` method must be used to inform
  48     displayio when a bitmap was modified through the buffer interface.
  49
  50     `bitmaptools.arrayblit` can also be useful to move data efficiently
  51     into a Bitmap."""
  52
  53     def __init__(self, width: int, height: int, value_count: int):
  54         """Create a Bitmap object with the given fixed size. Each pixel stores a value that is
  55         used to index into a corresponding palette. This enables differently colored sprites to
  56         share the underlying Bitmap. value_count is used to minimize the memory used to store
  57         the Bitmap.
  58         """
  59
  60         if not 1 <= value_count <= 65536:
  61             raise ValueError("value_count must be in the range of 1-65536")
  62
  63         bits = 1
  64         while (value_count - 1) >> bits:
  65             if bits < 8:
  66                 bits = bits << 1
  67             else:
  68                 bits += 8
  69
  70         self._from_buffer(width, height, bits, None, False)
  71
  72     def _from_buffer(
  73         self,
  74         width: int,
  75         height: int,
  76         bits_per_value: int,
  77         data: WriteableBuffer,
  78         read_only: bool,
  79     ) -> None:
  80         # pylint: disable=too-many-arguments
  81         self._bmp_width = width
  82         self._bmp_height = height
  83         self._stride = stride(width, bits_per_value)
  84         self._data_alloc = False
  85
  86         if data is None or len(data) == 0:
  87             data = array("L", [0] * self._stride * height)
  88             self._data_alloc = True
  89         self._data = data
  90         self._read_only = read_only
  91         self._bits_per_value = bits_per_value
  92
  93         if (
  94             self._bits_per_value > 8
  95             and self._bits_per_value != 16
  96             and self._bits_per_value != 32
  97         ):
  98             raise NotImplementedError("Invalid bits per value")
  99
 100         # Division and modulus can be slow because it has to handle any integer. We know
 101         # bits_per_value is a power of two. We divide and mod by bits_per_value to compute
 102         # the offset into the byte array. So, we can the offset computation to simplify to
 103         # a shift for division and mask for mod.
 104
 105         # Used to divide the index by the number of pixels per word. It's
 106         # used in a shift which effectively divides by 2 ** x_shift.
 107         self._x_shift = 0
 108
 109         power_of_two = 1
 110         while power_of_two < 32 // bits_per_value:
 111             self._x_shift += 1
 112             power_of_two = power_of_two << 1
 113
 114         self._x_mask = (1 << self._x_shift) - 1  # Used as a modulus on the x value
 115         self._bitmask = (1 << bits_per_value) - 1
 116         self._dirty_area = Area(0, 0, width, height)
 117
 118     def __getitem__(self, index: Union[Tuple[int, int], int]) -> int:
 119         """
 120         Returns the value at the given index. The index can either be
 121         an x,y tuple or an int equal to `y * width + x`.
 122         """
 123         if isinstance(index, (tuple, list)):
 124             x, y = index
 125         elif isinstance(index, int):
 126             x = index % self._bmp_width
 127             y = index // self._bmp_width
 128         else:
 129             raise TypeError("Index is not an int, list, or tuple")
 130
 131         if x > self._bmp_width or x < 0 or y > self._bmp_height or y < 0:
 132             raise ValueError(f"Index {index} is out of range")
 133         return self._get_pixel(x, y)
 134
 135     def _get_pixel(self, x: int, y: int) -> int:
 136         if x >= self._bmp_width or x < 0 or y >= self._bmp_height or y < 0:
 137             return 0
 138         row_start = y * self._stride
 139         bytes_per_value = self._bits_per_value // 8
 140         if bytes_per_value < 1:
 141             word = self._data[row_start + (x >> self._x_shift)]
 142             return (
 143                 word >> (32 - ((x & self._x_mask) + 1) * self._bits_per_value)
 144             ) & self._bitmask
 145         row = memoryview(self._data)[row_start : row_start + self._stride]
 146         if bytes_per_value == 1:
 147             return row[x]
 148         if bytes_per_value == 2:
 149             return struct.unpack_from("<H", row, x * 2)[0]
 150         if bytes_per_value == 4:
 151             return struct.unpack_from("<I", row, x * 4)[0]
 152         return 0
 153
 154     def __setitem__(self, index: Union[Tuple[int, int], int], value: int) -> None:
 155         """
 156         Sets the value at the given index. The index can either be
 157         an x,y tuple or an int equal to `y * width + x`.
 158         """
 159         if self._read_only:
 160             raise RuntimeError("Read-only object")
 161         if isinstance(index, (tuple, list)):
 162             x = index[0]
 163             y = index[1]
 164             index = y * self._bmp_width + x
 165         elif isinstance(index, int):
 166             x = index % self._bmp_width
 167             y = index // self._bmp_width
 168         # update the dirty region
 169         self._set_dirty_area(Area(x, y, x + 1, y + 1))
 170         self._write_pixel(x, y, value)
 171
 172     def _write_pixel(self, x: int, y: int, value: int) -> None:
 173         if self._read_only:
 174             raise RuntimeError("Read-only")
 175
 176         # Writes the color index value into a pixel position
 177         # Must update the dirty area separately
 178
 179         # Don't write if out of area
 180         if x < 0 or x >= self._bmp_width or y < 0 or y >= self._bmp_height:
 181             return
 182
 183         # Update one pixel of data
 184         row_start = y * self._stride
 185         bytes_per_value = self._bits_per_value // 8
 186         if bytes_per_value < 1:
 187             bit_position = 32 - ((x & self._x_mask) + 1) * self._bits_per_value
 188             index = row_start + (x >> self._x_shift)
 189             word = self._data[index]
 190             word &= ~(self._bitmask << bit_position)
 191             word |= (value & self._bitmask) << bit_position
 192             self._data[index] = word
 193         else:
 194             row = memoryview(self._data)[row_start : row_start + self._stride]
 195             if bytes_per_value == 1:
 196                 row[x] = value
 197             elif bytes_per_value == 2:
 198                 struct.pack_into("<H", row, x * 2, value)
 199             elif bytes_per_value == 4:
 200                 struct.pack_into("<I", row, x * 4, value)
 201
 202     def fill(self, value: int) -> None:
 203         """Fills the bitmap with the supplied palette index value."""
 204         if self._read_only:
 205             raise RuntimeError("Read-only")
 206         self._set_dirty_area(Area(0, 0, self._bmp_width, self._bmp_height))
 207
 208         # build the packed word
 209         word = 0
 210         for i in range(32 // self._bits_per_value):
 211             word |= (value & self._bitmask) << (32 - ((i + 1) * self._bits_per_value))
 212
 213         # copy it in
 214         for i in range(self._stride * self._bmp_height):
 215             self._data[i] = word
 216
 217     def dirty(self, x1: int = 0, y1: int = 0, x2: int = -1, y2: int = -1) -> None:
 218         """Inform displayio of bitmap updates done via the buffer protocol."""
 219         # pylint: disable=invalid-name
 220         if x2 == -1:
 221             x2 = self._bmp_width
 222         if y2 == -1:
 223             y2 = self._bmp_height
 224         self._set_dirty_area(Area(x1, y1, x2, y2))
 225
 226     def _set_dirty_area(self, dirty_area: Area) -> None:
 227         if self._read_only:
 228             raise RuntimeError("Read-only")
 229
 230         area = dirty_area
 231         area.canon()
 232         area.union(self._dirty_area, area)
 233         bitmap_area = Area(0, 0, self._bmp_width, self._bmp_height)
 234         area.compute_overlap(bitmap_area, self._dirty_area)
 235
 236     def _finish_refresh(self):
 237         if self._read_only:
 238             return
 239         self._dirty_area.x1 = 0
 240         self._dirty_area.x2 = 0
 241
 242     def _get_refresh_areas(self, areas: list[Area]) -> None:
 243         if self._dirty_area.x1 == self._dirty_area.x2 or self._read_only:
 244             return
 245         areas.append(self._dirty_area)
 246
 247     @property
 248     def width(self) -> int:
 249         """Width of the bitmap. (read only)"""
 250         return self._bmp_width
 251
 252     @property
 253     def height(self) -> int:
 254         """Height of the bitmap. (read only)"""
 255         return self._bmp_height