displayio/_displaycore.py

   1 # SPDX-FileCopyrightText: 2021 Melissa LeBlanc-Williams for Adafruit Industries
   2 # SPDX-FileCopyrightText: 2021 James Carr
   3 #
   4 # SPDX-License-Identifier: MIT
   5
   6 """
   7 `displayio._displaycore`
   8 ================================================================================
   9
  10 Super class of the display classes
  11
  12 **Software and Dependencies:**
  13
  14 * Adafruit Blinka:
  15   https://github.com/adafruit/Adafruit_Blinka/releases
  16
  17 * Author(s): James Carr, Melissa LeBlanc-Williams
  18
  19 """
  20
  21 __version__ = "0.0.0+auto.0"
  22 __repo__ = "https://github.com/adafruit/Adafruit_Blinka_Displayio.git"
  23
  24
  25 import time
  26 import struct
  27 from circuitpython_typing import WriteableBuffer, ReadableBuffer
  28 from paralleldisplay import ParallelBus
  29 from ._fourwire import FourWire
  30 from ._group import Group
  31 from ._i2cdisplay import I2CDisplay
  32 from ._structs import ColorspaceStruct, TransformStruct
  33 from ._area import Area
  34 from ._displaybus import _DisplayBus
  35 from ._helpers import bswap16
  36 from ._constants import (
  37     CHIP_SELECT_UNTOUCHED,
  38     CHIP_SELECT_TOGGLE_EVERY_BYTE,
  39     DISPLAY_COMMAND,
  40     DISPLAY_DATA,
  41     NO_COMMAND,
  42 )
  43
  44
  45 class _DisplayCore:
  46     # pylint: disable=too-many-arguments, too-many-instance-attributes, too-many-locals, too-many-branches, too-many-statements
  47
  48     def __init__(
  49         self,
  50         bus,
  51         width: int,
  52         height: int,
  53         ram_width: int,
  54         ram_height: int,
  55         colstart: int,
  56         rowstart: int,
  57         rotation: int,
  58         color_depth: int,
  59         grayscale: bool,
  60         pixels_in_byte_share_row: bool,
  61         bytes_per_cell: int,
  62         reverse_pixels_in_byte: bool,
  63         reverse_bytes_in_word: bool,
  64         column_command: int,
  65         row_command: int,
  66         set_current_column_command: int,
  67         set_current_row_command: int,
  68         data_as_commands: bool,
  69         always_toggle_chip_select: bool,
  70         sh1107_addressing: bool,
  71         address_little_endian: bool,
  72     ):
  73         self.colorspace = ColorspaceStruct(
  74             depth=color_depth,
  75             grayscale=grayscale,
  76             grayscale_bit=8 - color_depth,
  77             pixels_in_byte_share_row=pixels_in_byte_share_row,
  78             bytes_per_cell=bytes_per_cell,
  79             reverse_pixels_in_byte=reverse_pixels_in_byte,
  80             reverse_bytes_in_word=reverse_bytes_in_word,
  81             dither=False,
  82         )
  83         self.current_group = None
  84         self.colstart = colstart
  85         self.rowstart = rowstart
  86         self.last_refresh = 0
  87
  88         self.column_command = column_command
  89         self.row_command = row_command
  90         self.set_current_column_command = set_current_column_command
  91         self.set_current_row_command = set_current_row_command
  92         self.data_as_commands = data_as_commands
  93         self.always_toggle_chip_select = always_toggle_chip_select
  94         self.sh1107_addressing = sh1107_addressing
  95         self.address_little_endian = address_little_endian
  96
  97         self.refresh_in_progress = False
  98         self.full_refresh = False
  99         self.last_refresh = 0
 100
 101         if bus:
 102             if isinstance(bus, (FourWire, I2CDisplay, ParallelBus)):
 103                 self._bus_reset = bus.reset
 104                 self._bus_free = bus._free
 105                 self._begin_transaction = bus._begin_transaction
 106                 self._send = bus._send
 107                 self._end_transaction = bus._end_transaction
 108             else:
 109                 raise ValueError("Unsupported display bus type")
 110
 111         self._bus = bus
 112         self.area = Area(0, 0, width, height)
 113
 114         self.width = width
 115         self.height = height
 116         self.ram_width = ram_width
 117         self.ram_height = ram_height
 118         self.rotation = rotation
 119         self.transform = TransformStruct()
 120
 121     def set_rotation(self, rotation: int) -> None:
 122         """
 123         Sets the rotation of the display as an int in degrees.
 124         """
 125         # pylint: disable=protected-access, too-many-branches
 126         transposed = self.rotation in (90, 270)
 127         will_be_transposed = rotation in (90, 270)
 128         if transposed != will_be_transposed:
 129             self.width, self.height = self.height, self.width
 130
 131         height = self.height
 132         width = self.width
 133
 134         rotation %= 360
 135         self.rotation = rotation
 136         self.transform.x = 0
 137         self.transform.y = 0
 138         self.transform.scale = 1
 139         self.transform.mirror_x = False
 140         self.transform.mirror_y = False
 141         self.transform.transpose_xy = False
 142
 143         if rotation in (0, 180):
 144             if rotation == 180:
 145                 self.transform.mirror_x = True
 146                 self.transform.mirror_y = True
 147         else:
 148             self.transform.transpose_xy = True
 149             if rotation == 270:
 150                 self.transform.mirror_y = True
 151             else:
 152                 self.transform.mirror_x = True
 153
 154         self.area.x1 = 0
 155         self.area.y1 = 0
 156         self.area.next = None
 157
 158         self.transform.dx = 1
 159         self.transform.dy = 1
 160         if self.transform.transpose_xy:
 161             self.area.x2 = height
 162             self.area.y2 = width
 163             if self.transform.mirror_x:
 164                 self.transform.x = height
 165                 self.transform.dx = -1
 166             if self.transform.mirror_y:
 167                 self.transform.y = width
 168                 self.transform.dy = -1
 169         else:
 170             self.area.x2 = width
 171             self.area.y2 = height
 172             if self.transform.mirror_x:
 173                 self.transform.x = width
 174                 self.transform.dx = -1
 175             if self.transform.mirror_y:
 176                 self.transform.y = height
 177                 self.transform.dy = -1
 178
 179         if self.current_group is not None:
 180             self.current_group._update_transform(self.transform)
 181
 182     def set_root_group(self, root_group: Group) -> bool:
 183         """
 184         Switches to displaying the given group of layers. When group is `None`, the
 185         default CircuitPython terminal will be shown.
 186
 187         :param Optional[displayio.Group] root_group: The group to show.
 188         """
 189         # pylint: disable=protected-access
 190
 191         if root_group == self.current_group:
 192             return True
 193
 194         if root_group is not None and root_group._in_group:
 195             return False
 196
 197         if self.current_group is not None:
 198             self.current_group._in_group = False
 199
 200         if root_group is not None:
 201             root_group._update_transform(self.transform)
 202             root_group._in_group = True
 203
 204         self.current_group = root_group
 205         self.full_refresh = True
 206
 207         return True
 208
 209     def start_refresh(self) -> bool:
 210         # pylint: disable=protected-access
 211         """Mark the display core as currently being refreshed"""
 212
 213         if self.refresh_in_progress:
 214             return False
 215
 216         self.refresh_in_progress = True
 217         self.last_refresh = time.monotonic() * 1000
 218         return True
 219
 220     def finish_refresh(self) -> None:
 221         # pylint: disable=protected-access
 222         """Unmark the display core as currently being refreshed"""
 223
 224         if self.current_group is not None:
 225             self.current_group._finish_refresh()
 226
 227         self.full_refresh = False
 228         self.refresh_in_progress = False
 229         self.last_refresh = time.monotonic() * 1000
 230
 231     def release_display_core(self) -> None:
 232         """Release the display from the current group"""
 233         # pylint: disable=protected-access
 234
 235         if self.current_group is not None:
 236             self.current_group._in_group = False
 237
 238     def fill_area(
 239         self,
 240         area: Area,
 241         mask: WriteableBuffer,
 242         buffer: WriteableBuffer,
 243     ) -> bool:
 244         """Call the current group's fill area function"""
 245         if self.current_group is not None:
 246             return self.current_group._fill_area(  # pylint: disable=protected-access
 247                 self.colorspace, area, mask, buffer
 248             )
 249         return False
 250
 251     def clip_area(self, area: Area, clipped: Area) -> bool:
 252         """Shrink the area to the region shared by the two areas"""
 253
 254         overlaps = self.area.compute_overlap(area, clipped)
 255         if not overlaps:
 256             return False
 257
 258         # Expand the area if we have multiple pixels per byte and we need to byte
 259         # align the bounds
 260         if self.colorspace.depth < 8:
 261             pixels_per_byte = (
 262                 8 // self.colorspace.depth * self.colorspace.bytes_per_cell
 263             )
 264             if self.colorspace.pixels_in_byte_share_row:
 265                 if clipped.x1 % pixels_per_byte != 0:
 266                     clipped.x1 -= clipped.x1 % pixels_per_byte
 267                 if clipped.x2 % pixels_per_byte != 0:
 268                     clipped.x2 += pixels_per_byte - clipped.x2 % pixels_per_byte
 269             else:
 270                 if clipped.y1 % pixels_per_byte != 0:
 271                     clipped.y1 -= clipped.y1 % pixels_per_byte
 272                 if clipped.y2 % pixels_per_byte != 0:
 273                     clipped.y2 += pixels_per_byte - clipped.y2 % pixels_per_byte
 274
 275         return True
 276
 277     def set_region_to_update(self, area: Area) -> None:
 278         """Set the region to update"""
 279         region_x1 = area.x1 + self.colstart
 280         region_x2 = area.x2 + self.colstart
 281         region_y1 = area.y1 + self.rowstart
 282         region_y2 = area.y2 + self.rowstart
 283
 284         if self.colorspace.depth < 8:
 285             pixels_per_byte = 8 // self.colorspace.depth
 286             if self.colorspace.pixels_in_byte_share_row:
 287                 region_x1 //= pixels_per_byte * self.colorspace.bytes_per_cell
 288                 region_x2 //= pixels_per_byte * self.colorspace.bytes_per_cell
 289             else:
 290                 region_y1 //= pixels_per_byte * self.colorspace.bytes_per_cell
 291                 region_y2 //= pixels_per_byte * self.colorspace.bytes_per_cell
 292
 293         region_x2 -= 1
 294         region_y2 -= 1
 295
 296         chip_select = CHIP_SELECT_UNTOUCHED
 297         if self.always_toggle_chip_select or self.data_as_commands:
 298             chip_select = CHIP_SELECT_TOGGLE_EVERY_BYTE
 299
 300         # Set column
 301         self.begin_transaction()
 302         data = bytearray([self.column_command])
 303         data_type = DISPLAY_DATA
 304         if not self.data_as_commands:
 305             self.send(DISPLAY_COMMAND, CHIP_SELECT_UNTOUCHED, data)
 306             data = bytearray(0)
 307         else:
 308             data_type = DISPLAY_COMMAND
 309
 310         if self.ram_width < 0x100:  # Single Byte Bounds
 311             data += struct.pack(">BB", region_x1, region_x2)
 312         else:
 313             if self.address_little_endian:
 314                 region_x1 = bswap16(region_x1)
 315                 region_x2 = bswap16(region_x2)
 316             data += struct.pack(">HH", region_x1, region_x2)
 317
 318         # Quirk for SH1107 "SH1107_addressing"
 319         #     Column lower command = 0x00, Column upper command = 0x10
 320         if self.sh1107_addressing:
 321             data = struct.pack(
 322                 ">BB",
 323                 ((region_x1 >> 4) & 0xF0) | 0x10,  # 0x10 to 0x17
 324                 region_x1 & 0x0F,  # 0x00 to 0x0F
 325             )
 326
 327         self.send(data_type, chip_select, data)
 328         self.end_transaction()
 329
 330         if self.set_current_column_command != NO_COMMAND:
 331             self.begin_transaction()
 332             self.send(
 333                 DISPLAY_COMMAND, chip_select, bytes([self.set_current_column_command])
 334             )
 335             # Only send the first half of data because it is the first coordinate.
 336             self.send(DISPLAY_DATA, chip_select, data[: len(data) // 2])
 337             self.end_transaction()
 338
 339         # Set row
 340         self.begin_transaction()
 341         data = bytearray([self.row_command])
 342
 343         if not self.data_as_commands:
 344             self.send(DISPLAY_COMMAND, CHIP_SELECT_UNTOUCHED, data)
 345             data = bytearray(0)
 346         if self.ram_width < 0x100:  # Single Byte Bounds
 347             data += struct.pack(">BB", region_y1, region_y2)
 348         else:
 349             if self.address_little_endian:
 350                 region_y1 = bswap16(region_y1)
 351                 region_y2 = bswap16(region_y2)
 352             data += struct.pack(">HH", region_y1, region_y2)
 353
 354         # Quirk for SH1107 "SH1107_addressing"
 355         #     Page address command = 0xB0
 356         if self.sh1107_addressing:
 357             data = struct.pack(">B", 0xB0 | region_y1)
 358
 359         self.send(data_type, chip_select, data)
 360         self.end_transaction()
 361
 362         if self.set_current_row_command != NO_COMMAND:
 363             self.begin_transaction()
 364             self.send(
 365                 DISPLAY_COMMAND, chip_select, bytes([self.set_current_row_command])
 366             )
 367             # Only send the first half of data because it is the first coordinate.
 368             self.send(DISPLAY_DATA, chip_select, data[: len(data) // 2])
 369             self.end_transaction()
 370
 371     def send(
 372         self,
 373         data_type: int,
 374         chip_select: int,
 375         data: ReadableBuffer,
 376     ) -> None:
 377         """
 378         Send the data to the current bus
 379         """
 380         self._send(data_type, chip_select, data)
 381
 382     def bus_free(self) -> bool:
 383         """
 384         Check if the bus is free
 385         """
 386         return self._bus_free()
 387
 388     def begin_transaction(self) -> bool:
 389         """
 390         Begin Bus Transaction
 391         """
 392         return self._begin_transaction()
 393
 394     def end_transaction(self) -> None:
 395         """
 396         End Bus Transaction
 397         """
 398         self._end_transaction()
 399
 400     def get_width(self) -> int:
 401         """
 402         Gets the width of the display in pixels.
 403         """
 404         return self.width
 405
 406     def get_height(self) -> int:
 407         """
 408         Gets the height of the display in pixels.
 409         """
 410         return self.height
 411
 412     def get_rotation(self) -> int:
 413         """
 414         Gets the rotation of the display as an int in degrees.
 415         """
 416         return self.rotation
 417
 418     def get_bus(self) -> _DisplayBus:
 419         """
 420         The bus being used by the display. [readonly]
 421         """
 422         return self._bus