displayio/display.py

   1 # The MIT License (MIT)
   2 #
   3 # Copyright (c) 2020 Melissa LeBlanc-Williams for Adafruit Industries
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining a copy
   6 # of this software and associated documentation files (the "Software"), to deal
   7 # in the Software without restriction, including without limitation the rights
   8 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 # copies of the Software, and to permit persons to whom the Software is
  10 # furnished to do so, subject to the following conditions:
  11 #
  12 # The above copyright notice and this permission notice shall be included in
  13 # all copies or substantial portions of the Software.
  14 #
  15 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  21 # THE SOFTWARE.
  22
  23 """
  24 `displayio.display`
  25 ================================================================================
  26
  27 displayio for Blinka
  28
  29 **Software and Dependencies:**
  30
  31 * Adafruit Blinka:
  32   https://github.com/adafruit/Adafruit_Blinka/releases
  33
  34 * Author(s): Melissa LeBlanc-Williams
  35
  36 """
  37
  38 import time
  39 import struct
  40 import threading
  41 import digitalio
  42 from PIL import Image
  43 import numpy
  44 from recordclass import recordclass
  45
  46 __version__ = "0.0.0-auto.0"
  47 __repo__ = "https://github.com/adafruit/Adafruit_Blinka_displayio.git"
  48
  49 Rectangle = recordclass("Rectangle", "x1 y1 x2 y2")
  50 displays = []
  51
  52 BACKLIGHT_IN_OUT = 1
  53 BACKLIGHT_PWM = 2
  54
  55 # pylint: disable=unnecessary-pass, unused-argument
  56
  57 # pylint: disable=too-many-instance-attributes
  58 class Display:
  59     """This initializes a display and connects it into CircuitPython. Unlike other objects
  60     in CircuitPython, Display objects live until ``displayio.release_displays()`` is called.
  61     This is done so that CircuitPython can use the display itself.
  62
  63     Most people should not use this class directly. Use a specific display driver instead
  64     that will contain the initialization sequence at minimum.
  65
  66     .. class::
  67         Display(display_bus, init_sequence, *, width, height, colstart=0, rowstart=0, rotation=0,
  68         color_depth=16, grayscale=False, pixels_in_byte_share_row=True, bytes_per_cell=1,
  69         reverse_pixels_in_byte=False, set_column_command=0x2a, set_row_command=0x2b,
  70         write_ram_command=0x2c, set_vertical_scroll=0, backlight_pin=None, brightness_command=None,
  71         brightness=1.0, auto_brightness=False, single_byte_bounds=False, data_as_commands=False,
  72         auto_refresh=True, native_frames_per_second=60)
  73     """
  74
  75     # pylint: disable=too-many-locals
  76     def __init__(
  77         self,
  78         display_bus,
  79         init_sequence,
  80         *,
  81         width,
  82         height,
  83         colstart=0,
  84         rowstart=0,
  85         rotation=0,
  86         color_depth=16,
  87         grayscale=False,
  88         pixels_in_byte_share_row=True,
  89         bytes_per_cell=1,
  90         reverse_pixels_in_byte=False,
  91         set_column_command=0x2A,
  92         set_row_command=0x2B,
  93         write_ram_command=0x2C,
  94         set_vertical_scroll=0,
  95         backlight_pin=None,
  96         brightness_command=None,
  97         brightness=1.0,
  98         auto_brightness=False,
  99         single_byte_bounds=False,
 100         data_as_commands=False,
 101         auto_refresh=True,
 102         native_frames_per_second=60
 103     ):
 104         """Create a Display object on the given display bus (`displayio.FourWire` or
 105         `displayio.ParallelBus`).
 106
 107         The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins
 108         with a command byte followed by a byte to determine the parameter count and if a
 109         delay is need after. When the top bit of the second byte is 1, the next byte will be
 110         the delay time in milliseconds. The remaining 7 bits are the parameter count
 111         excluding any delay byte. The third through final bytes are the remaining command
 112         parameters. The next byte will begin a new command definition. Here is a portion of
 113         ILI9341 init code:
 114         .. code-block:: python
 115
 116             init_sequence = (
 117                 b"\xe1\x0f\x00\x0E\x14\x03\x11\x07\x31\xC1\x48\x08\x0F\x0C\x31\x36\x0F"
 118                 b"\x11\x80\x78"# Exit Sleep then delay 0x78 (120ms)
 119                 b"\x29\x80\x78"# Display on then delay 0x78 (120ms)
 120             )
 121             display = displayio.Display(display_bus, init_sequence, width=320, height=240)
 122
 123         The first command is 0xe1 with 15 (0xf) parameters following. The second and third
 124         are 0x11 and 0x29 respectively with delays (0x80) of 120ms (0x78) and no parameters.
 125         Multiple byte literals (b”“) are merged together on load. The parens are needed to
 126         allow byte literals on subsequent lines.
 127
 128         The initialization sequence should always leave the display memory access inline with
 129         the scan of the display to minimize tearing artifacts.
 130         """
 131         self._bus = display_bus
 132         self._set_column_command = set_column_command
 133         self._set_row_command = set_row_command
 134         self._write_ram_command = write_ram_command
 135         self._brightness_command = brightness_command
 136         self._data_as_commands = data_as_commands
 137         self._single_byte_bounds = single_byte_bounds
 138         self._width = width
 139         self._height = height
 140         self._colstart = colstart
 141         self._rowstart = rowstart
 142         self._rotation = rotation
 143         self._auto_brightness = auto_brightness
 144         self._brightness = 1.0
 145         self._auto_refresh = auto_refresh
 146         self._initialize(init_sequence)
 147         self._buffer = Image.new("RGB", (width, height))
 148         self._subrectangles = []
 149         self._bounds_encoding = ">BB" if single_byte_bounds else ">HH"
 150         self._current_group = None
 151         displays.append(self)
 152         self._refresh_thread = None
 153         if self._auto_refresh:
 154             self.auto_refresh = True
 155
 156         self._backlight_type = None
 157         if backlight_pin is not None:
 158             self._backlight_type = BACKLIGHT_IN_OUT
 159             self._backlight = digitalio.DigitalInOut(backlight_pin)
 160             self._backlight.switch_to_output()
 161             self.brightness = brightness
 162
 163     # pylint: enable=too-many-locals
 164
 165     def _initialize(self, init_sequence):
 166         i = 0
 167         while i < len(init_sequence):
 168             command = init_sequence[i]
 169             data_size = init_sequence[i + 1]
 170             delay = (data_size & 0x80) > 0
 171             data_size &= ~0x80
 172
 173             self._write(command, init_sequence[i + 2 : i + 2 + data_size])
 174             delay_time_ms = 10
 175             if delay:
 176                 data_size += 1
 177                 delay_time_ms = init_sequence[i + 1 + data_size]
 178                 if delay_time_ms == 255:
 179                     delay_time_ms = 500
 180             time.sleep(delay_time_ms / 1000)
 181             i += 2 + data_size
 182
 183     def _write(self, command, data):
 184         self._bus.begin_transaction()
 185         if self._data_as_commands:
 186             if command is not None:
 187                 self._bus.send(True, bytes([command]), toggle_every_byte=True)
 188             self._bus.send(command is not None, data)
 189         else:
 190             self._bus.send(True, bytes([command]), toggle_every_byte=True)
 191             self._bus.send(False, data)
 192         self._bus.end_transaction()
 193
 194     def _release(self):
 195         self._bus.release()
 196         self._bus = None
 197
 198     def show(self, group):
 199         """Switches to displaying the given group of layers. When group is None, the
 200         default CircuitPython terminal will be shown.
 201         """
 202         self._current_group = group
 203
 204     def refresh(self, *, target_frames_per_second=60, minimum_frames_per_second=1):
 205         """When auto refresh is off, waits for the target frame rate and then refreshes the
 206         display, returning True. If the call has taken too long since the last refresh call
 207         for the given target frame rate, then the refresh returns False immediately without
 208         updating the screen to hopefully help getting caught up.
 209
 210         If the time since the last successful refresh is below the minimum frame rate, then
 211         an exception will be raised. Set minimum_frames_per_second to 0 to disable.
 212
 213         When auto refresh is on, updates the display immediately. (The display will also
 214         update without calls to this.)
 215         """
 216         # Go through groups and and add each to buffer
 217         if self._current_group is not None:
 218             buffer = Image.new("RGBA", (self._width, self._height))
 219             # Recursively have everything draw to the image
 220             self._current_group._fill_area(buffer)  # pylint: disable=protected-access
 221             # save image to buffer (or probably refresh buffer so we can compare)
 222             self._buffer.paste(buffer)
 223
 224         # Eventually calculate dirty rectangles here
 225         self._subrectangles.append(Rectangle(0, 0, self._width, self._height))
 226
 227         for area in self._subrectangles:
 228             self._refresh_display_area(area)
 229
 230     def _refresh_loop(self):
 231         while self._auto_refresh:
 232             self.refresh()
 233
 234     def _refresh_display_area(self, rectangle):
 235         """Loop through dirty rectangles and redraw that area."""
 236
 237         img = self._buffer.convert("RGB").crop(rectangle)
 238         img = img.rotate(self._rotation, expand=True)
 239
 240         display_rectangle = self._apply_rotation(rectangle)
 241         img = img.crop(self._clip(display_rectangle))
 242
 243         data = numpy.array(img).astype("uint16")
 244         color = (
 245             ((data[:, :, 0] & 0xF8) << 8)
 246             | ((data[:, :, 1] & 0xFC) << 3)
 247             | (data[:, :, 2] >> 3)
 248         )
 249
 250         pixels = list(
 251             numpy.dstack(((color >> 8) & 0xFF, color & 0xFF)).flatten().tolist()
 252         )
 253
 254         self._write(
 255             self._set_column_command,
 256             self._encode_pos(
 257                 display_rectangle.x1 + self._colstart,
 258                 display_rectangle.x2 + self._colstart - 1,
 259             ),
 260         )
 261         self._write(
 262             self._set_row_command,
 263             self._encode_pos(
 264                 display_rectangle.y1 + self._rowstart,
 265                 display_rectangle.y2 + self._rowstart - 1,
 266             ),
 267         )
 268
 269         if self._data_as_commands:
 270             self._write(None, pixels)
 271         else:
 272             self._write(self._write_ram_command, pixels)
 273
 274     def _clip(self, rectangle):
 275         if self._rotation in (90, 270):
 276             width, height = self._height, self._width
 277         else:
 278             width, height = self._width, self._height
 279
 280         if rectangle.x1 < 0:
 281             rectangle.x1 = 0
 282         if rectangle.y1 < 0:
 283             rectangle.y1 = 0
 284         if rectangle.x2 > width:
 285             rectangle.x2 = width
 286         if rectangle.y2 > height:
 287             rectangle.y2 = height
 288
 289         return rectangle
 290
 291     def _apply_rotation(self, rectangle):
 292         """Adjust the rectangle coordinates based on rotation"""
 293         if self._rotation == 90:
 294             return Rectangle(
 295                 self._height - rectangle.y2,
 296                 rectangle.x1,
 297                 self._height - rectangle.y1,
 298                 rectangle.x2,
 299             )
 300         if self._rotation == 180:
 301             return Rectangle(
 302                 self._width - rectangle.x2,
 303                 self._height - rectangle.y2,
 304                 self._width - rectangle.x1,
 305                 self._height - rectangle.y1,
 306             )
 307         if self._rotation == 270:
 308             return Rectangle(
 309                 rectangle.y1,
 310                 self._width - rectangle.x2,
 311                 rectangle.y2,
 312                 self._width - rectangle.x1,
 313             )
 314         return rectangle
 315
 316     def _encode_pos(self, x, y):
 317         """Encode a postion into bytes."""
 318         return struct.pack(self._bounds_encoding, x, y)
 319
 320     def fill_row(self, y, buffer):
 321         """Extract the pixels from a single row"""
 322         pass
 323
 324     @property
 325     def auto_refresh(self):
 326         """True when the display is refreshed automatically."""
 327         return self._auto_refresh
 328
 329     @auto_refresh.setter
 330     def auto_refresh(self, value):
 331         self._auto_refresh = value
 332         if self._refresh_thread is None:
 333             self._refresh_thread = threading.Thread(
 334                 target=self._refresh_loop, daemon=True
 335             )
 336         if value and not self._refresh_thread.is_alive():
 337             # Start the thread
 338             self._refresh_thread.start()
 339         elif not value and self._refresh_thread.is_alive():
 340             # Stop the thread
 341             self._refresh_thread.join()
 342
 343     @property
 344     def brightness(self):
 345         """The brightness of the display as a float. 0.0 is off and 1.0 is full `brightness`.
 346         When `auto_brightness` is True, the value of `brightness` will change automatically.
 347         If `brightness` is set, `auto_brightness` will be disabled and will be set to False.
 348         """
 349         return self._brightness
 350
 351     @brightness.setter
 352     def brightness(self, value):
 353         if 0 <= float(value) <= 1.0:
 354             self._brightness = value
 355             if self._backlight_type == BACKLIGHT_IN_OUT:
 356                 self._backlight.value = int(round(self._brightness))
 357             # PWM not currently implemented
 358             # Command-based brightness not implemented
 359         else:
 360             raise ValueError("Brightness must be between 0.0 and 1.0")
 361
 362     @property
 363     def auto_brightness(self):
 364         """True when the display brightness is adjusted automatically, based on an ambient
 365         light sensor or other method. Note that some displays may have this set to True by
 366         default, but not actually implement automatic brightness adjustment.
 367         `auto_brightness` is set to False if `brightness` is set manually.
 368         """
 369         return self._auto_brightness
 370
 371     @auto_brightness.setter
 372     def auto_brightness(self, value):
 373         self._auto_brightness = value
 374
 375     @property
 376     def width(self):
 377         """Display Width"""
 378         return self._width
 379
 380     @property
 381     def height(self):
 382         """Display Height"""
 383         return self._height
 384
 385     @property
 386     def rotation(self):
 387         """The rotation of the display as an int in degrees."""
 388         return self._rotation
 389
 390     @rotation.setter
 391     def rotation(self, value):
 392         if value not in (0, 90, 180, 270):
 393             raise ValueError("Rotation must be 0/90/180/270")
 394         self._rotation = value
 395
 396     @property
 397     def bus(self):
 398         """Current Display Bus"""
 399         return self._bus
 400
 401
 402 # pylint: enable=too-many-instance-attributes