Merge pull request #1510 from tannewt/terminalio

Add a terminal that shows by default on displays.

9 files changed, 366 insertions, 273 deletions

diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c
index d61732f6f..109df8af4 100644
--- a/shared-bindings/displayio/Display.c
+++ b/shared-bindings/displayio/Display.c
@@ -84,9 +84,10 @@
 //|   :param int set_column_command: Command used to set the start and end columns to update
 //|   :param int set_row_command: Command used so set the start and end rows to update
 //|   :param int write_ram_command: Command used to write pixels values into the update region
+//|   :param microcontroller.Pin backlight_pin: Pin connected to the display's backlight
 //|
 STATIC mp_obj_t displayio_display_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    enum { ARG_display_bus, ARG_init_sequence, ARG_width, ARG_height, ARG_colstart, ARG_rowstart, ARG_color_depth, ARG_set_column_command, ARG_set_row_command, ARG_write_ram_command };
+    enum { ARG_display_bus, ARG_init_sequence, ARG_width, ARG_height, ARG_colstart, ARG_rowstart, ARG_color_depth, ARG_set_column_command, ARG_set_row_command, ARG_write_ram_command, ARG_backlight_pin };
     static const mp_arg_t allowed_args[] = {
         { MP_QSTR_display_bus, MP_ARG_REQUIRED | MP_ARG_OBJ },
         { MP_QSTR_init_sequence, MP_ARG_REQUIRED | MP_ARG_OBJ },
@@ -98,6 +99,7 @@ STATIC mp_obj_t displayio_display_make_new(const mp_obj_type_t *type, size_t n_a
         { MP_QSTR_set_column_command, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0x2a} },
         { MP_QSTR_set_row_command, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0x2b} },
         { MP_QSTR_write_ram_command, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0x2c} },
+        { MP_QSTR_backlight_pin, MP_ARG_OBJ | MP_ARG_KW_ONLY, {.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);
@@ -107,6 +109,14 @@ STATIC mp_obj_t displayio_display_make_new(const mp_obj_type_t *type, size_t n_a
     mp_buffer_info_t bufinfo;
     mp_get_buffer_raise(args[ARG_init_sequence].u_obj, &bufinfo, MP_BUFFER_READ);
 
+    mp_obj_t backlight_pin_obj = args[ARG_backlight_pin].u_obj;
+    assert_pin(backlight_pin_obj, true);
+    const mcu_pin_obj_t* backlight_pin = NULL;
+    if (backlight_pin_obj != NULL && backlight_pin_obj != mp_const_none) {
+        backlight_pin = MP_OBJ_TO_PTR(backlight_pin_obj);
+        assert_pin_free(backlight_pin);
+    }
+
     displayio_display_obj_t *self = NULL;
     for (uint8_t i = 0; i < CIRCUITPY_DISPLAY_LIMIT; i++) {
         if (displays[i].display.base.type == NULL ||
@@ -122,22 +132,27 @@ STATIC mp_obj_t displayio_display_make_new(const mp_obj_type_t *type, size_t n_a
     common_hal_displayio_display_construct(self,
             display_bus, args[ARG_width].u_int, args[ARG_height].u_int, args[ARG_colstart].u_int, args[ARG_rowstart].u_int,
             args[ARG_color_depth].u_int, args[ARG_set_column_command].u_int, args[ARG_set_row_command].u_int,
-            args[ARG_write_ram_command].u_int, bufinfo.buf, bufinfo.len);
+            args[ARG_write_ram_command].u_int, bufinfo.buf, bufinfo.len, MP_OBJ_TO_PTR(backlight_pin));
 
     return self;
 }
 
 //|   .. method:: show(group)
 //|
-//|     Switches to displaying the given group of layers.
+//|     Switches to displaying the given group of layers. When group is None, the default
+//|     CircuitPython terminal will be shown.
 //|
 STATIC mp_obj_t displayio_display_obj_show(mp_obj_t self_in, mp_obj_t group_in) {
     displayio_display_obj_t *self = MP_OBJ_TO_PTR(self_in);
-    mp_obj_t native_layer = mp_instance_cast_to_native_base(group_in, &displayio_group_type);
-    if (native_layer == MP_OBJ_NULL) {
-        mp_raise_ValueError(translate("Must be a Group subclass."));
+    displayio_group_t* group = NULL;
+    if (group_in != mp_const_none) {
+        mp_obj_t native_layer = mp_instance_cast_to_native_base(group_in, &displayio_group_type);
+        if (native_layer == MP_OBJ_NULL) {
+            mp_raise_ValueError(translate("Must be a Group subclass."));
+        }
+        group = MP_OBJ_TO_PTR(native_layer);
     }
-    displayio_group_t* group = MP_OBJ_TO_PTR(native_layer);
+
     common_hal_displayio_display_show(self, group);
     return mp_const_none;
 }
@@ -165,11 +180,72 @@ STATIC mp_obj_t displayio_display_obj_wait_for_frame(mp_obj_t self_in) {
 }
 MP_DEFINE_CONST_FUN_OBJ_1(displayio_display_wait_for_frame_obj, displayio_display_obj_wait_for_frame);
 
+//|   .. attribute:: brightness
+//|
+//|     The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When
+//|     `auto_brightness` is True this value will change automatically and setting it will have no
+//|     effect. To control the brightness, auto_brightness must be false.
+//|
+STATIC mp_obj_t displayio_display_obj_get_brightness(mp_obj_t self_in) {
+    displayio_display_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    mp_float_t brightness = common_hal_displayio_display_get_brightness(self);
+    if (brightness < 0) {
+        mp_raise_RuntimeError(translate("Brightness not adjustable"));
+    }
+    return mp_obj_new_float(brightness);
+}
+MP_DEFINE_CONST_FUN_OBJ_1(displayio_display_get_brightness_obj, displayio_display_obj_get_brightness);
+
+STATIC mp_obj_t displayio_display_obj_set_brightness(mp_obj_t self_in, mp_obj_t brightness) {
+    displayio_display_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    bool ok = common_hal_displayio_display_set_brightness(self, mp_obj_get_float(brightness));
+    if (!ok) {
+        mp_raise_RuntimeError(translate("Brightness not adjustable"));
+    }
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(displayio_display_set_brightness_obj, displayio_display_obj_set_brightness);
+
+const mp_obj_property_t displayio_display_brightness_obj = {
+    .base.type = &mp_type_property,
+    .proxy = {(mp_obj_t)&displayio_display_get_brightness_obj,
+              (mp_obj_t)&displayio_display_set_brightness_obj,
+              (mp_obj_t)&mp_const_none_obj},
+};
+
+//|   .. attribute:: auto_brightness
+//|
+//|     True when the display brightness is auto adjusted.
+//|
+STATIC mp_obj_t displayio_display_obj_get_auto_brightness(mp_obj_t self_in) {
+    displayio_display_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    return mp_obj_new_bool(common_hal_displayio_display_get_auto_brightness(self));
+}
+MP_DEFINE_CONST_FUN_OBJ_1(displayio_display_get_auto_brightness_obj, displayio_display_obj_get_auto_brightness);
+
+STATIC mp_obj_t displayio_display_obj_set_auto_brightness(mp_obj_t self_in, mp_obj_t auto_brightness) {
+    displayio_display_obj_t *self = MP_OBJ_TO_PTR(self_in);
+
+    common_hal_displayio_display_set_auto_brightness(self, mp_obj_is_true(auto_brightness));
+
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(displayio_display_set_auto_brightness_obj, displayio_display_obj_set_auto_brightness);
+
+const mp_obj_property_t displayio_display_auto_brightness_obj = {
+    .base.type = &mp_type_property,
+    .proxy = {(mp_obj_t)&displayio_display_get_auto_brightness_obj,
+              (mp_obj_t)&displayio_display_set_auto_brightness_obj,
+              (mp_obj_t)&mp_const_none_obj},
+};
 
 STATIC const mp_rom_map_elem_t displayio_display_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_show), MP_ROM_PTR(&displayio_display_show_obj) },
     { MP_ROM_QSTR(MP_QSTR_refresh_soon), MP_ROM_PTR(&displayio_display_refresh_soon_obj) },
     { MP_ROM_QSTR(MP_QSTR_wait_for_frame), MP_ROM_PTR(&displayio_display_wait_for_frame_obj) },
+
+    { MP_ROM_QSTR(MP_QSTR_brightness), MP_ROM_PTR(&displayio_display_brightness_obj) },
+    { MP_ROM_QSTR(MP_QSTR_auto_brightness), MP_ROM_PTR(&displayio_display_auto_brightness_obj) },
 };
 STATIC MP_DEFINE_CONST_DICT(displayio_display_locals_dict, displayio_display_locals_dict_table);
 
diff --git a/shared-bindings/displayio/Display.h b/shared-bindings/displayio/Display.h
index 4cec66058..906c3620d 100644
--- a/shared-bindings/displayio/Display.h
+++ b/shared-bindings/displayio/Display.h
@@ -40,7 +40,7 @@ void common_hal_displayio_display_construct(displayio_display_obj_t* self,
     mp_obj_t bus, uint16_t width, uint16_t height,
     int16_t colstart, int16_t rowstart, uint16_t color_depth,
     uint8_t set_column_command, uint8_t set_row_command, uint8_t write_ram_command,
-    uint8_t* init_sequence, uint16_t init_sequence_len);
+    uint8_t* init_sequence, uint16_t init_sequence_len, const mcu_pin_obj_t* backlight_pin);
 
 int32_t common_hal_displayio_display_wait_for_frame(displayio_display_obj_t* self);
 
@@ -56,4 +56,10 @@ bool displayio_display_refresh_queued(displayio_display_obj_t* self);
 void displayio_display_finish_refresh(displayio_display_obj_t* self);
 bool displayio_display_send_pixels(displayio_display_obj_t* self, uint32_t* pixels, uint32_t length);
 
+bool common_hal_displayio_display_get_auto_brightness(displayio_display_obj_t* self);
+void common_hal_displayio_display_set_auto_brightness(displayio_display_obj_t* self, bool auto_brightness);
+
+mp_float_t common_hal_displayio_display_get_brightness(displayio_display_obj_t* self);
+bool common_hal_displayio_display_set_brightness(displayio_display_obj_t* self, mp_float_t brightness);
+
 #endif // MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYBUSIO_DISPLAY_H
diff --git a/shared-bindings/displayio/FourWire.c b/shared-bindings/displayio/FourWire.c
index dceb4fe69..eab3bd57a 100644
--- a/shared-bindings/displayio/FourWire.c
+++ b/shared-bindings/displayio/FourWire.c
@@ -98,19 +98,7 @@ STATIC mp_obj_t displayio_fourwire_make_new(const mp_obj_type_t *type, size_t n_
     return self;
 }
 
-
-//|   .. method:: send(command, data)
-//|
-//|
-STATIC mp_obj_t displayio_fourwire_obj_send(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    mp_raise_NotImplementedError(translate("displayio is a work in progress"));
-
-    return mp_const_none;
-}
-MP_DEFINE_CONST_FUN_OBJ_KW(displayio_fourwire_send_obj, 1, displayio_fourwire_obj_send);
-
 STATIC const mp_rom_map_elem_t displayio_fourwire_locals_dict_table[] = {
-    { MP_ROM_QSTR(MP_QSTR_send), MP_ROM_PTR(&displayio_fourwire_send_obj) },
 };
 STATIC MP_DEFINE_CONST_DICT(displayio_fourwire_locals_dict, displayio_fourwire_locals_dict_table);
 
diff --git a/shared-bindings/displayio/ParallelBus.c b/shared-bindings/displayio/ParallelBus.c
index 916c5f852..1ce1e2aff 100644
--- a/shared-bindings/displayio/ParallelBus.c
+++ b/shared-bindings/displayio/ParallelBus.c
@@ -102,19 +102,7 @@ STATIC mp_obj_t displayio_parallelbus_make_new(const mp_obj_type_t *type, size_t
     return self;
 }
 
-
-//|   .. method:: send(command, data)
-//|
-//|
-STATIC mp_obj_t displayio_parallelbus_obj_send(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    mp_raise_NotImplementedError(translate("displayio is a work in progress"));
-
-    return mp_const_none;
-}
-MP_DEFINE_CONST_FUN_OBJ_KW(displayio_parallelbus_send_obj, 1, displayio_parallelbus_obj_send);
-
 STATIC const mp_rom_map_elem_t displayio_parallelbus_locals_dict_table[] = {
-    { MP_ROM_QSTR(MP_QSTR_send), MP_ROM_PTR(&displayio_parallelbus_send_obj) },
 };
 STATIC MP_DEFINE_CONST_DICT(displayio_parallelbus_locals_dict, displayio_parallelbus_locals_dict_table);
 
diff --git a/shared-bindings/displayio/Sprite.c b/shared-bindings/displayio/Sprite.c
deleted file mode 100644
index 6f4704e45..000000000
--- a/shared-bindings/displayio/Sprite.c
+++ /dev/null
@@ -1,195 +0,0 @@
-/*
- * This file is part of the Micro Python project, http://micropython.org/
- *
- * The MIT License (MIT)
- *
- * Copyright (c) 2018 Scott Shawcroft for Adafruit Industries
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
- */
-
-#include "shared-bindings/displayio/Sprite.h"
-
-#include <stdint.h>
-
-#include "lib/utils/context_manager_helpers.h"
-#include "py/binary.h"
-#include "py/objproperty.h"
-#include "py/runtime.h"
-#include "shared-bindings/displayio/Bitmap.h"
-#include "shared-bindings/displayio/ColorConverter.h"
-#include "shared-bindings/displayio/OnDiskBitmap.h"
-#include "shared-bindings/displayio/Palette.h"
-#include "shared-bindings/displayio/Shape.h"
-#include "supervisor/shared/translate.h"
-
-void unpack_position(mp_obj_t position_obj, int16_t* x, int16_t* y) {
-    // TODO(tannewt): Support any value sequence such as bytearray or bytes.
-    mp_obj_tuple_t *position = MP_OBJ_TO_PTR(position_obj);
-    if (MP_OBJ_IS_TYPE(position_obj, &mp_type_tuple) && position->len == 2) {
-        *x = mp_obj_get_int(position->items[0]);
-        *y = mp_obj_get_int(position->items[1]);
-    } else if (position != mp_const_none) {
-        mp_raise_TypeError(translate("position must be 2-tuple"));
-    }
-}
-
-//| .. currentmodule:: displayio
-//|
-//| :class:`Sprite` -- A particular copy of an image to display
-//| ==========================================================================
-//|
-//| Position a particular image and pixel_shader combination. Multiple sprites can share bitmaps
-//| pixel shaders.
-//|
-//| .. warning:: This will be changed before 4.0.0. Consider it very experimental.
-//|
-//| .. class:: Sprite(bitmap, *, pixel_shader, position, width, height)
-//|
-//|   Create a Sprite object. The bitmap is source for 2d pixels. The pixel_shader is used to
-//|   convert the value and its location to a display native pixel color. This may be a simple color
-//|   palette lookup, a gradient, a pattern or a color transformer.
-//|
-//|
-STATIC mp_obj_t displayio_sprite_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    enum { ARG_bitmap, ARG_pixel_shader, ARG_position, ARG_width, ARG_height };
-    static const mp_arg_t allowed_args[] = {
-        { MP_QSTR_bitmap, MP_ARG_REQUIRED | MP_ARG_OBJ },
-        { MP_QSTR_pixel_shader, MP_ARG_OBJ | MP_ARG_KW_ONLY },
-        { MP_QSTR_position, MP_ARG_OBJ | MP_ARG_KW_ONLY },
-        { MP_QSTR_width, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = -1} },
-        { MP_QSTR_height, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = -1} },
-    };
-    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);
-
-    mp_obj_t bitmap = args[ARG_bitmap].u_obj;
-
-    uint16_t width;
-    uint16_t height;
-    mp_obj_t native = mp_instance_cast_to_native_base(bitmap, &displayio_shape_type);
-    if (native != MP_OBJ_NULL) {
-        displayio_shape_t* bmp = MP_OBJ_TO_PTR(native);
-        width = bmp->width;
-        height = bmp->height;
-    } else if (MP_OBJ_IS_TYPE(bitmap, &displayio_bitmap_type)) {
-        displayio_bitmap_t* bmp = MP_OBJ_TO_PTR(bitmap);
-        native = bitmap;
-        width = bmp->width;
-        height = bmp->height;
-    } else if (MP_OBJ_IS_TYPE(bitmap, &displayio_ondiskbitmap_type)) {
-        displayio_ondiskbitmap_t* bmp = MP_OBJ_TO_PTR(bitmap);
-        native = bitmap;
-        width = bmp->width;
-        height = bmp->height;
-    } else {
-        mp_raise_TypeError(translate("unsupported bitmap type"));
-    }
-    int16_t x = 0;
-    int16_t y = 0;
-    mp_obj_t position_obj = args[ARG_position].u_obj;
-    unpack_position(position_obj, &x, &y);
-
-    displayio_sprite_t *self = m_new_obj(displayio_sprite_t);
-    self->base.type = &displayio_sprite_type;
-    common_hal_displayio_sprite_construct(self, native, args[ARG_pixel_shader].u_obj,
-            width, height, x, y);
-    return MP_OBJ_FROM_PTR(self);
-}
-
-//|   .. attribute:: position
-//|
-//|     The position of the top-left corner of the sprite.
-//|
-STATIC mp_obj_t displayio_sprite_obj_get_position(mp_obj_t self_in) {
-    displayio_sprite_t *self = MP_OBJ_TO_PTR(self_in);
-    int16_t x;
-    int16_t y;
-    common_hal_displayio_sprite_get_position(self, &x, &y);
-
-    mp_obj_t coords[2];
-    coords[0] = mp_obj_new_int(x);
-    coords[1] = mp_obj_new_int(y);
-
-    return mp_obj_new_tuple(2, coords);
-}
-MP_DEFINE_CONST_FUN_OBJ_1(displayio_sprite_get_position_obj, displayio_sprite_obj_get_position);
-
-STATIC mp_obj_t displayio_sprite_obj_set_position(mp_obj_t self_in, mp_obj_t value) {
-    displayio_sprite_t *self = MP_OBJ_TO_PTR(self_in);
-
-    int16_t x = 0;
-    int16_t y = 0;
-    unpack_position(value, &x, &y);
-
-    common_hal_displayio_sprite_set_position(self, x, y);
-
-    return mp_const_none;
-}
-MP_DEFINE_CONST_FUN_OBJ_2(displayio_sprite_set_position_obj, displayio_sprite_obj_set_position);
-
-const mp_obj_property_t displayio_sprite_position_obj = {
-    .base.type = &mp_type_property,
-    .proxy = {(mp_obj_t)&displayio_sprite_get_position_obj,
-              (mp_obj_t)&displayio_sprite_set_position_obj,
-              (mp_obj_t)&mp_const_none_obj},
-};
-
-//|   .. attribute:: pixel_shader
-//|
-//|     The pixel shader of the sprite.
-//|
-STATIC mp_obj_t displayio_sprite_obj_get_pixel_shader(mp_obj_t self_in) {
-    displayio_sprite_t *self = MP_OBJ_TO_PTR(self_in);
-    return common_hal_displayio_sprite_get_pixel_shader(self);
-}
-MP_DEFINE_CONST_FUN_OBJ_1(displayio_sprite_get_pixel_shader_obj, displayio_sprite_obj_get_pixel_shader);
-
-STATIC mp_obj_t displayio_sprite_obj_set_pixel_shader(mp_obj_t self_in, mp_obj_t pixel_shader) {
-    displayio_sprite_t *self = MP_OBJ_TO_PTR(self_in);
-    if (!MP_OBJ_IS_TYPE(pixel_shader, &displayio_palette_type) && !MP_OBJ_IS_TYPE(pixel_shader, &displayio_colorconverter_type)) {
-        mp_raise_TypeError(translate("pixel_shader must be displayio.Palette or displayio.ColorConverter"));
-    }
-
-    common_hal_displayio_sprite_set_pixel_shader(self, pixel_shader);
-
-    return mp_const_none;
-}
-MP_DEFINE_CONST_FUN_OBJ_2(displayio_sprite_set_pixel_shader_obj, displayio_sprite_obj_set_pixel_shader);
-
-const mp_obj_property_t displayio_sprite_pixel_shader_obj = {
-    .base.type = &mp_type_property,
-    .proxy = {(mp_obj_t)&displayio_sprite_get_pixel_shader_obj,
-              (mp_obj_t)&displayio_sprite_set_pixel_shader_obj,
-              (mp_obj_t)&mp_const_none_obj},
-};
-
-STATIC const mp_rom_map_elem_t displayio_sprite_locals_dict_table[] = {
-    // Properties
-    { MP_ROM_QSTR(MP_QSTR_position),          MP_ROM_PTR(&displayio_sprite_position_obj) },
-    { MP_ROM_QSTR(MP_QSTR_pixel_shader),          MP_ROM_PTR(&displayio_sprite_pixel_shader_obj) },
-};
-STATIC MP_DEFINE_CONST_DICT(displayio_sprite_locals_dict, displayio_sprite_locals_dict_table);
-
-const mp_obj_type_t displayio_sprite_type = {
-    { &mp_type_type },
-    .name = MP_QSTR_Sprite,
-    .make_new = displayio_sprite_make_new,
-    .locals_dict = (mp_obj_dict_t*)&displayio_sprite_locals_dict,
-};
diff --git a/shared-bindings/displayio/Sprite.h b/shared-bindings/displayio/Sprite.h
deleted file mode 100644
index 1944e1d74..000000000
--- a/shared-bindings/displayio/Sprite.h
+++ /dev/null
@@ -1,43 +0,0 @@
-/*
- * This file is part of the Micro Python project, http://micropython.org/
- *
- * The MIT License (MIT)
- *
- * Copyright (c) 2018 Scott Shawcroft for Adafruit Industries
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
- */
-
-#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_SPRITE_H
-#define MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_SPRITE_H
-
-#include "shared-module/displayio/Sprite.h"
-
-extern const mp_obj_type_t displayio_sprite_type;
-
-void common_hal_displayio_sprite_construct(displayio_sprite_t *self, mp_obj_t bitmap,
-        mp_obj_t pixel_shader, uint16_t width, uint16_t height, uint16_t x, uint16_t y);
-
-void common_hal_displayio_sprite_get_position(displayio_sprite_t *self, int16_t* x, int16_t* y);
-void common_hal_displayio_sprite_set_position(displayio_sprite_t *self, int16_t x, int16_t y);
-
-mp_obj_t common_hal_displayio_sprite_get_pixel_shader(displayio_sprite_t *self);
-void common_hal_displayio_sprite_set_pixel_shader(displayio_sprite_t *self, mp_obj_t pixel_shader);
-
-#endif // MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_SPRITE_H
diff --git a/shared-bindings/displayio/TileGrid.c b/shared-bindings/displayio/TileGrid.c
new file mode 100644
index 000000000..d0be43fbf
--- /dev/null
+++ b/shared-bindings/displayio/TileGrid.c
@@ -0,0 +1,226 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "shared-bindings/displayio/TileGrid.h"
+
+#include <stdint.h>
+
+#include "lib/utils/context_manager_helpers.h"
+#include "py/binary.h"
+#include "py/objproperty.h"
+#include "py/runtime.h"
+#include "shared-bindings/displayio/Bitmap.h"
+#include "shared-bindings/displayio/ColorConverter.h"
+#include "shared-bindings/displayio/OnDiskBitmap.h"
+#include "shared-bindings/displayio/Palette.h"
+#include "shared-bindings/displayio/Shape.h"
+#include "supervisor/shared/translate.h"
+
+static void unpack_position(mp_obj_t position_obj, int16_t* x, int16_t* y) {
+    // TODO(tannewt): Support any value sequence such as bytearray or bytes.
+    mp_obj_tuple_t *position = MP_OBJ_TO_PTR(position_obj);
+    if (MP_OBJ_IS_TYPE(position_obj, &mp_type_tuple) && position->len == 2) {
+        *x = mp_obj_get_int(position->items[0]);
+        *y = mp_obj_get_int(position->items[1]);
+    } else if (position != mp_const_none) {
+        mp_raise_TypeError(translate("position must be 2-tuple"));
+    }
+}
+
+//| .. currentmodule:: displayio
+//|
+//| :class:`TileGrid` -- 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.
+//|
+//| .. warning:: This will be changed before 4.0.0. Consider it very experimental.
+//|
+//| .. class:: TileGrid(bitmap, *, pixel_shader, position, width=1, height=1, tile_width=None, tile_height=None, default_tile=0)
+//|
+//|   Create a TileGrid object. The bitmap is source for 2d pixels. The pixel_shader is used to
+//|   convert the value and its location to a display native pixel color. This may be a simple color
+//|   palette lookup, a gradient, a pattern or a color transformer.
+//|
+//|   tile_width and tile_height match the height of the bitmap by default.
+//|
+//|   :param displayio.Bitmap bitmap: The bitmap storing one or more tiles.
+//|   :param displayio.Palette pixel_shader: The pixel shader that produces colors from values
+//|   :param tuple position: Upper left corner of the grid
+//|   :param int width: Width of the grid in tiles.
+//|   :param int height: Height of the grid in tiles.
+//|   :param int tile_width: Width of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions.
+//|   :param int tile_height: Height of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions.
+//|   :param in default_tile: Default tile index to show.
+//|
+STATIC mp_obj_t displayio_tilegrid_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    enum { ARG_bitmap, ARG_pixel_shader, ARG_position, ARG_width, ARG_height, ARG_tile_width, ARG_tile_height, ARG_default_tile };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_bitmap, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_pixel_shader, MP_ARG_OBJ | MP_ARG_KW_ONLY | MP_ARG_REQUIRED },
+        { MP_QSTR_position, MP_ARG_OBJ | MP_ARG_KW_ONLY | MP_ARG_REQUIRED },
+        { MP_QSTR_width, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 1} },
+        { MP_QSTR_height, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 1} },
+        { MP_QSTR_tile_width, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0} },
+        { MP_QSTR_tile_height, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0} },
+        { MP_QSTR_default_tile, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 0} },
+    };
+    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);
+
+    mp_obj_t bitmap = args[ARG_bitmap].u_obj;
+
+    uint16_t bitmap_width;
+    uint16_t bitmap_height;
+    mp_obj_t native = mp_instance_cast_to_native_base(bitmap, &displayio_shape_type);
+    if (native != MP_OBJ_NULL) {
+        displayio_shape_t* bmp = MP_OBJ_TO_PTR(native);
+        bitmap_width = bmp->width;
+        bitmap_height = bmp->height;
+    } else if (MP_OBJ_IS_TYPE(bitmap, &displayio_bitmap_type)) {
+        displayio_bitmap_t* bmp = MP_OBJ_TO_PTR(bitmap);
+        native = bitmap;
+        bitmap_width = bmp->width;
+        bitmap_height = bmp->height;
+    } else if (MP_OBJ_IS_TYPE(bitmap, &displayio_ondiskbitmap_type)) {
+        displayio_ondiskbitmap_t* bmp = MP_OBJ_TO_PTR(bitmap);
+        native = bitmap;
+        bitmap_width = bmp->width;
+        bitmap_height = bmp->height;
+    } else {
+        mp_raise_TypeError(translate("unsupported bitmap type"));
+    }
+    uint16_t tile_width = args[ARG_tile_width].u_int;
+    if (tile_width == 0) {
+        tile_width = bitmap_width;
+    }
+    uint16_t tile_height = args[ARG_tile_height].u_int;
+    if (tile_height == 0) {
+        tile_height = bitmap_height;
+    }
+    if (bitmap_width % tile_width != 0) {
+        mp_raise_ValueError(translate("Tile width must exactly divide bitmap width"));
+    }
+    if (bitmap_height % tile_height != 0) {
+        mp_raise_ValueError(translate("Tile height must exactly divide bitmap height"));
+    }
+
+    int16_t x = 0;
+    int16_t y = 0;
+    mp_obj_t position_obj = args[ARG_position].u_obj;
+    unpack_position(position_obj, &x, &y);
+
+    displayio_tilegrid_t *self = m_new_obj(displayio_tilegrid_t);
+    self->base.type = &displayio_tilegrid_type;
+    common_hal_displayio_tilegrid_construct(self, native, bitmap_width / tile_width,
+        args[ARG_pixel_shader].u_obj, args[ARG_width].u_int, args[ARG_height].u_int,
+        tile_width, tile_height, x, y, args[ARG_default_tile].u_int);
+    return MP_OBJ_FROM_PTR(self);
+}
+
+//|   .. attribute:: position
+//|
+//|     The position of the top-left corner of the tilegrid.
+//|
+STATIC mp_obj_t displayio_tilegrid_obj_get_position(mp_obj_t self_in) {
+    displayio_tilegrid_t *self = MP_OBJ_TO_PTR(self_in);
+    int16_t x;
+    int16_t y;
+    common_hal_displayio_tilegrid_get_position(self, &x, &y);
+
+    mp_obj_t coords[2];
+    coords[0] = mp_obj_new_int(x);
+    coords[1] = mp_obj_new_int(y);
+
+    return mp_obj_new_tuple(2, coords);
+}
+MP_DEFINE_CONST_FUN_OBJ_1(displayio_tilegrid_get_position_obj, displayio_tilegrid_obj_get_position);
+
+STATIC mp_obj_t displayio_tilegrid_obj_set_position(mp_obj_t self_in, mp_obj_t value) {
+    displayio_tilegrid_t *self = MP_OBJ_TO_PTR(self_in);
+
+    int16_t x = 0;
+    int16_t y = 0;
+    unpack_position(value, &x, &y);
+
+    common_hal_displayio_tilegrid_set_position(self, x, y);
+
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(displayio_tilegrid_set_position_obj, displayio_tilegrid_obj_set_position);
+
+const mp_obj_property_t displayio_tilegrid_position_obj = {
+    .base.type = &mp_type_property,
+    .proxy = {(mp_obj_t)&displayio_tilegrid_get_position_obj,
+              (mp_obj_t)&displayio_tilegrid_set_position_obj,
+              (mp_obj_t)&mp_const_none_obj},
+};
+
+//|   .. attribute:: pixel_shader
+//|
+//|     The pixel shader of the tilegrid.
+//|
+STATIC mp_obj_t displayio_tilegrid_obj_get_pixel_shader(mp_obj_t self_in) {
+    displayio_tilegrid_t *self = MP_OBJ_TO_PTR(self_in);
+    return common_hal_displayio_tilegrid_get_pixel_shader(self);
+}
+MP_DEFINE_CONST_FUN_OBJ_1(displayio_tilegrid_get_pixel_shader_obj, displayio_tilegrid_obj_get_pixel_shader);
+
+STATIC mp_obj_t displayio_tilegrid_obj_set_pixel_shader(mp_obj_t self_in, mp_obj_t pixel_shader) {
+    displayio_tilegrid_t *self = MP_OBJ_TO_PTR(self_in);
+    if (!MP_OBJ_IS_TYPE(pixel_shader, &displayio_palette_type) && !MP_OBJ_IS_TYPE(pixel_shader, &displayio_colorconverter_type)) {
+        mp_raise_TypeError(translate("pixel_shader must be displayio.Palette or displayio.ColorConverter"));
+    }
+
+    common_hal_displayio_tilegrid_set_pixel_shader(self, pixel_shader);
+
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(displayio_tilegrid_set_pixel_shader_obj, displayio_tilegrid_obj_set_pixel_shader);
+
+const mp_obj_property_t displayio_tilegrid_pixel_shader_obj = {
+    .base.type = &mp_type_property,
+    .proxy = {(mp_obj_t)&displayio_tilegrid_get_pixel_shader_obj,
+              (mp_obj_t)&displayio_tilegrid_set_pixel_shader_obj,
+              (mp_obj_t)&mp_const_none_obj},
+};
+
+STATIC const mp_rom_map_elem_t displayio_tilegrid_locals_dict_table[] = {
+    // Properties
+    { MP_ROM_QSTR(MP_QSTR_position),          MP_ROM_PTR(&displayio_tilegrid_position_obj) },
+    { MP_ROM_QSTR(MP_QSTR_pixel_shader),          MP_ROM_PTR(&displayio_tilegrid_pixel_shader_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(displayio_tilegrid_locals_dict, displayio_tilegrid_locals_dict_table);
+
+const mp_obj_type_t displayio_tilegrid_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_TileGrid,
+    .make_new = displayio_tilegrid_make_new,
+    .locals_dict = (mp_obj_dict_t*)&displayio_tilegrid_locals_dict,
+};
diff --git a/shared-bindings/displayio/TileGrid.h b/shared-bindings/displayio/TileGrid.h
new file mode 100644
index 000000000..2260db413
--- /dev/null
+++ b/shared-bindings/displayio/TileGrid.h
@@ -0,0 +1,47 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2019 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_TILEGRID_H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_TILEGRID_H
+
+#include "shared-module/displayio/TileGrid.h"
+
+extern const mp_obj_type_t displayio_tilegrid_type;
+
+void common_hal_displayio_tilegrid_construct(displayio_tilegrid_t *self, mp_obj_t bitmap,
+        uint16_t bitmap_width_in_tiles, mp_obj_t pixel_shader, uint16_t width, uint16_t height,
+        uint16_t tile_width, uint16_t tile_height, uint16_t x, uint16_t y, uint8_t default_tile);
+
+void common_hal_displayio_tilegrid_get_position(displayio_tilegrid_t *self, int16_t* x, int16_t* y);
+void common_hal_displayio_tilegrid_set_position(displayio_tilegrid_t *self, int16_t x, int16_t y);
+
+mp_obj_t common_hal_displayio_tilegrid_get_pixel_shader(displayio_tilegrid_t *self);
+void common_hal_displayio_tilegrid_set_pixel_shader(displayio_tilegrid_t *self, mp_obj_t pixel_shader);
+
+void common_hal_displayio_textgrid_set_tile(displayio_tilegrid_t *self, uint16_t x, uint16_t y, uint8_t tile_index);
+void common_hal_displayio_textgrid_set_top_left(displayio_tilegrid_t *self, uint16_t x, uint16_t y);
+
+#endif // MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_TILEGRID_H
diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c
index 6ed1218b2..df7162cf1 100644
--- a/shared-bindings/displayio/__init__.c
+++ b/shared-bindings/displayio/__init__.c
@@ -39,7 +39,7 @@
 #include "shared-bindings/displayio/Palette.h"
 #include "shared-bindings/displayio/ParallelBus.h"
 #include "shared-bindings/displayio/Shape.h"
-#include "shared-bindings/displayio/Sprite.h"
+#include "shared-bindings/displayio/TileGrid.h"
 
 //| :mod:`displayio` --- Native display driving
 //| =========================================================================
@@ -67,7 +67,7 @@
 //|     Palette
 //|     ParallelBus
 //|     Shape
-//|     Sprite
+//|     TileGrid
 //|
 //| All libraries change hardware state but are never deinit
 //|
@@ -94,7 +94,7 @@ STATIC const mp_rom_map_elem_t displayio_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_OnDiskBitmap), MP_ROM_PTR(&displayio_ondiskbitmap_type) },
     { MP_ROM_QSTR(MP_QSTR_Palette), MP_ROM_PTR(&displayio_palette_type) },
     { MP_ROM_QSTR(MP_QSTR_Shape), MP_ROM_PTR(&displayio_shape_type) },
-    { MP_ROM_QSTR(MP_QSTR_Sprite), MP_ROM_PTR(&displayio_sprite_type) },
+    { MP_ROM_QSTR(MP_QSTR_TileGrid), MP_ROM_PTR(&displayio_tilegrid_type) },
 
     { MP_ROM_QSTR(MP_QSTR_FourWire), MP_ROM_PTR(&displayio_fourwire_type) },
     { MP_ROM_QSTR(MP_QSTR_ParallelBus), MP_ROM_PTR(&displayio_parallelbus_type) },