:mod:`displayio`
================

.. py:module:: displayio

.. autoapi-nested-parse::

   Native helpers for driving displays

   The `displayio` module contains classes to manage display output
   including synchronizing with refresh rates and partial updating.





.. function:: release_displays() -> Any

   Releases any actively used displays so their busses and pins can be used again. This will also
   release the builtin display on boards that have one. You will need to reinitialize it yourself
   afterwards. This may take seconds to complete if an active EPaperDisplay is refreshing.

   Use this once in your code.py if you initialize a display. Place it right before the
   initialization so the display is active as long as possible.


.. py:class:: Bitmap(width: int, height: int, value_count: int)

   Stores values of a certain size in a 2D array

   .. attribute:: width
      :annotation: :Any

      Width of the bitmap. (read only)


   .. attribute:: height
      :annotation: :Any

      Height of the bitmap. (read only)


   .. method:: __getitem__(self, index: Any)


      Returns the value at the given index. The index can either be an x,y tuple or an int equal
      to ``y * width + x``.

      This allows you to::

        print(bitmap[0,1])


   .. method:: __setitem__(self, index: Any, value: Any)


      Sets the value at the given index. The index can either be an x,y tuple or an int equal
      to ``y * width + x``.

      This allows you to::

        bitmap[0,1] = 3


   .. method:: fill(self, value: Any)


      Fills the bitmap with the supplied palette index value.



.. py:class:: ColorConverter(*, dither: bool = False)

   Converts one color format to another.

   .. attribute:: dither
      :annotation: :Any

      When true the color converter dithers the output by adding random noise when
      truncating to display bitdepth


   .. method:: convert(self, color: Any)


      Converts the given RGB888 color to RGB565



.. py:class:: Display(display_bus: Any, init_sequence: buffer, *, width: int, height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, color_depth: int = 16, grayscale: bool = False, pixels_in_byte_share_row: bool = True, bytes_per_cell: int = 1, reverse_pixels_in_byte: bool = False, set_column_command: int = 42, set_row_command: int = 43, write_ram_command: int = 44, set_vertical_scroll: int = 0, backlight_pin: microcontroller.Pin = None, brightness_command: int = None, brightness: bool = 1.0, auto_brightness: bool = False, single_byte_bounds: bool = False, data_as_commands: bool = False, auto_refresh: bool = True, native_frames_per_second: int = 60)

   Manage updating a display over a display bus

   This initializes a display and connects it into CircuitPython. Unlike other
   objects in CircuitPython, Display objects live until `displayio.release_displays()`
   is called. This is done so that CircuitPython can use the display itself.

   Most people should not use this class directly. Use a specific display driver instead that will
   contain the initialization sequence at minimum.

   .. attribute:: auto_refresh
      :annotation: :Any

      True when the display is refreshed automatically.


   .. attribute:: brightness
      :annotation: :Any

      The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When
      `auto_brightness` is True, the value of `brightness` will change automatically.
      If `brightness` is set, `auto_brightness` will be disabled and will be set to False.


   .. attribute:: auto_brightness
      :annotation: :Any

      True when the display brightness is adjusted automatically, based on an ambient
      light sensor or other method. Note that some displays may have this set to True by default,
      but not actually implement automatic brightness adjustment. `auto_brightness` is set to False
      if `brightness` is set manually.


   .. attribute:: width
      :annotation: :Any

      

   .. attribute:: height
      :annotation: :Any

      

   .. attribute:: rotation
      :annotation: :Any

      The rotation of the display as an int in degrees.


   .. attribute:: bus
      :annotation: :Any

      

   .. method:: show(self, group: Group)


      Switches to displaying the given group of layers. When group is None, the default
      CircuitPython terminal will be shown.

      :param Group group: The group to show.


   .. method:: refresh(self, *, target_frames_per_second: int = 60, minimum_frames_per_second: int = 1)


      When auto refresh is off, waits for the target frame rate and then refreshes the display,
      returning True. If the call has taken too long since the last refresh call for the given
      target frame rate, then the refresh returns False immediately without updating the screen to
      hopefully help getting caught up.

      If the time since the last successful refresh is below the minimum frame rate, then an
      exception will be raised. Set minimum_frames_per_second to 0 to disable.

      When auto refresh is on, updates the display immediately. (The display will also update
      without calls to this.)

      :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated.
      :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second.


   .. method:: fill_row(self, y: int, buffer: bytearray)


      Extract the pixels from a single row

      :param int y: The top edge of the area
      :param bytearray buffer: The buffer in which to place the pixel data



.. py:class:: EPaperDisplay(display_bus: Any, start_sequence: buffer, stop_sequence: buffer, *, width: int, height: int, ram_width: int, ram_height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, set_column_window_command: int = None, set_row_window_command: int = None, single_byte_bounds: Any = False, write_black_ram_command: int, black_bits_inverted: bool = False, write_color_ram_command: int = None, color_bits_inverted: bool = False, highlight_color: int = 0, refresh_display_command: int, refresh_time: float = 40, busy_pin: microcontroller.Pin = None, busy_state: bool = True, seconds_per_frame: float = 180, always_toggle_chip_select: bool = False)

   Manage updating an epaper display over a display bus

   This initializes an epaper display and connects it into CircuitPython. Unlike other
   objects in CircuitPython, EPaperDisplay objects live until `displayio.release_displays()`
   is called. This is done so that CircuitPython can use the display itself.

   Most people should not use this class directly. Use a specific display driver instead that will
   contain the startup and shutdown sequences at minimum.

   .. attribute:: time_to_refresh
      :annotation: :Any

      Time, in fractional seconds, until the ePaper display can be refreshed.


   .. attribute:: width
      :annotation: :Any

      Gets the width of the display in pixels


   .. attribute:: height
      :annotation: :Any

      

   .. attribute:: bus
      :annotation: :Any

      

   .. method:: show(self, group: Group)


      Switches to displaying the given group of layers. When group is None, the default
      CircuitPython terminal will be shown.

      :param Group group: The group to show.


   .. method:: refresh(self)


      Refreshes the display immediately or raises an exception if too soon. Use
      ``time.sleep(display.time_to_refresh)`` to sleep until a refresh can occur.



.. py:class:: FourWire(spi_bus: busio.SPI, *, command: microcontroller.Pin, chip_select: microcontroller.Pin, reset: microcontroller.Pin = None, baudrate: int = 24000000, polarity: int = 0, phase: int = 0)

   Manage updating a display over SPI four wire protocol in the background while Python code runs.
   It doesn't handle display initialization.

   .. method:: reset(self)


      Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin
      is available.


   .. method:: send(self, command: Any, data: Any, *, toggle_every_byte: Any = False)


      Sends the given command value followed by the full set of data. Display state, such as
      vertical scroll, set via ``send`` may or may not be reset once the code is done.



.. py:class:: Group(*, max_size: int = 4, scale: int = 1, x: int = 0, y: int = 0)

   Manage a group of sprites and groups and how they are inter-related.

   .. attribute:: hidden
      :annotation: :Any

      True when the Group and all of it's layers are not visible. When False, the Group's layers
      are visible if they haven't been hidden.


   .. attribute:: scale
      :annotation: :Any

      Scales each pixel within the Group in both directions. For example, when scale=2 each pixel
      will be represented by 2x2 pixels.


   .. attribute:: x
      :annotation: :Any

      X position of the Group in the parent.


   .. attribute:: y
      :annotation: :Any

      Y position of the Group in the parent.


   .. method:: append(self, layer: Any)


      Append a layer to the group. It will be drawn above other layers.


   .. method:: insert(self, index: Any, layer: Any)


      Insert a layer into the group.


   .. method:: index(self, layer: Any)


      Returns the index of the first copy of layer. Raises ValueError if not found.


   .. method:: pop(self, i: Any = -1)


      Remove the ith item and return it.


   .. method:: remove(self, layer: Any)


      Remove the first copy of layer. Raises ValueError if it is not present.


   .. method:: __len__(self)


      Returns the number of layers in a Group


   .. method:: __getitem__(self, index: Any)


      Returns the value at the given index.

      This allows you to::

        print(group[0])


   .. method:: __setitem__(self, index: Any, value: Any)


      Sets the value at the given index.

      This allows you to::

        group[0] = sprite


   .. method:: __delitem__(self, index: Any)


      Deletes the value at the given index.

      This allows you to::

        del group[0]



.. py:class:: I2CDisplay(i2c_bus: busio.I2C, *, device_address: int, reset: microcontroller.Pin = None)

   Manage updating a display over I2C in the background while Python code runs.
   It doesn't handle display initialization.

   .. method:: reset(self)


      Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin
      is available.


   .. method:: send(self, command: Any, data: Any)


      Sends the given command value followed by the full set of data. Display state, such as
      vertical scroll, set via ``send`` may or may not be reset once the code is done.



.. py:class:: OnDiskBitmap(file: file)

   Loads values straight from disk. This minimizes memory use but can lead to
   much slower pixel load times. These load times may result in frame tearing where only part of
   the image is visible.

   It's easiest to use on a board with a built in display such as the `Hallowing M0 Express
   <https://www.adafruit.com/product/3900>`_.

   .. code-block:: Python

     import board
     import displayio
     import time
     import pulseio

     board.DISPLAY.auto_brightness = False
     board.DISPLAY.brightness = 0
     splash = displayio.Group()
     board.DISPLAY.show(splash)

     with open("/sample.bmp", "rb") as f:
         odb = displayio.OnDiskBitmap(f)
         face = displayio.TileGrid(odb, pixel_shader=displayio.ColorConverter())
         splash.append(face)
         # Wait for the image to load.
         board.DISPLAY.refresh(target_frames_per_second=60)

         # Fade up the backlight
         for i in range(100):
             board.DISPLAY.brightness = 0.01 * i
             time.sleep(0.05)

         # Wait forever
         while True:
             pass

   .. attribute:: width
      :annotation: :Any

      Width of the bitmap. (read only)


   .. attribute:: height
      :annotation: :Any

      Height of the bitmap. (read only)



.. py:class:: Palette(color_count: int)

   Map a pixel palette_index to a full color. Colors are transformed to the display's format internally to
   save memory.

   .. method:: __len__(self)


      Returns the number of colors in a Palette


   .. method:: __setitem__(self, index: Any, value: Any)


      Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1.

      The value argument represents a color, and can be from 0x000000 to 0xFFFFFF (to represent an RGB value).
      Value can be an int, bytes (3 bytes (RGB) or 4 bytes (RGB + pad byte)), bytearray,
      or a tuple or list of 3 integers.

      This allows you to::

        palette[0] = 0xFFFFFF                     # set using an integer
        palette[1] = b'\xff\xff\x00'              # set using 3 bytes
        palette[2] = b'\xff\xff\x00\x00'          # set using 4 bytes
        palette[3] = bytearray(b'\x00\x00\xFF')   # set using a bytearay of 3 or 4 bytes
        palette[4] = (10, 20, 30)                 # set using a tuple of 3 integers


   .. method:: make_transparent(self, palette_index: Any)



   .. method:: make_opaque(self, palette_index: Any)




.. py:class:: ParallelBus(*, data0: microcontroller.Pin, command: microcontroller.Pin, chip_select: microcontroller.Pin, write: microcontroller.Pin, read: microcontroller.Pin, reset: microcontroller.Pin)

   Manage updating a display over 8-bit parallel bus in the background while Python code runs. This
   protocol may be refered to as 8080-I Series Parallel Interface in datasheets. It doesn't handle
   display initialization.

   .. method:: reset(self)


      Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin
      is available.


   .. method:: send(self, command: Any, data: Any)


      Sends the given command value followed by the full set of data. Display state, such as
      vertical scroll, set via ``send`` may or may not be reset once the code is done.



.. py:class:: Shape(width: int, height: int, *, mirror_x: bool = False, mirror_y: bool = False)

   Represents a shape made by defining boundaries that may be mirrored.

   .. method:: set_boundary(self, y: Any, start_x: Any, end_x: Any)


      Loads pre-packed data into the given row.



.. py:class:: TileGrid(bitmap: displayio.Bitmap, *, pixel_shader: displayio.Palette, width: int = 1, height: int = 1, tile_width: int = None, tile_height: int = None, default_tile: int = 0, x: int = 0, y: int = 0)

   A grid of tiles sourced out of one bitmap

   Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple grids
   can share bitmaps and pixel shaders.

   A single tile grid is also known as a Sprite.

   .. attribute:: hidden
      :annotation: :Any

      True when the TileGrid is hidden. This may be False even when a part of a hidden Group.


   .. attribute:: x
      :annotation: :Any

      X position of the left edge in the parent.


   .. attribute:: y
      :annotation: :Any

      Y position of the top edge in the parent.


   .. attribute:: flip_x
      :annotation: :Any

      If true, the left edge rendered will be the right edge of the right-most tile.


   .. attribute:: flip_y
      :annotation: :Any

      If true, the top edge rendered will be the bottom edge of the bottom-most tile.


   .. attribute:: transpose_xy
      :annotation: :Any

      If true, the TileGrid's axis will be swapped. When combined with mirroring, any 90 degree
      rotation can be achieved along with the corresponding mirrored version.


   .. attribute:: pixel_shader
      :annotation: :Any

      The pixel shader of the tilegrid.


   .. method:: __getitem__(self, index: Any)


      Returns the tile index at the given index. The index can either be an x,y tuple or an int equal
      to ``y * width + x``.

      This allows you to::

        print(grid[0])


   .. method:: __setitem__(self, index: Any, tile_index: Any)


      Sets the tile index at the given index. The index can either be an x,y tuple or an int equal
      to ``y * width + x``.

      This allows you to::

        grid[0] = 10

      or::

        grid[0,0] = 10