Introduce displayio to render graphics to displays.

It's designed to minimize RAM footprint by using Sprites to
represent objects on the screen. The object model also facilitates
partial screen updating which reduces the bandwidth needed to display.

This is all handled in C. Python simply manipulates the objects with
the ability to synchronize to frame timing.

12 files changed, 1012 insertions, 0 deletions

diff --git a/shared-bindings/displayio/Bitmap.c b/shared-bindings/displayio/Bitmap.c
new file mode 100644
index 000000000..b01fe0e0c
--- /dev/null
+++ b/shared-bindings/displayio/Bitmap.c
@@ -0,0 +1,113 @@
+/*
+ * 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/Bitmap.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/microcontroller/Pin.h"
+#include "shared-bindings/util.h"
+#include "supervisor/shared/translate.h"
+
+//| .. currentmodule:: displayio
+//|
+//| :class:`Bitmap` -- Stores values in a 2D array
+//| ==========================================================================
+//|
+//| Stores values of a certain size in a 2D array
+//|
+//| .. warning:: This will likely be changed before 4.0.0. Consider it very experimental.
+//|
+//| .. class:: Bitmap(width, height, value_size)
+//|
+//|   Create a Bitmap object with the given fixed size.
+//|
+//|   :param int width: The number of values wide
+//|   :param int height: The number of values high
+//|   :param int value_size: The value size in bits. Must be power of 2.
+//|
+STATIC mp_obj_t displayio_bitmap_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) {
+    mp_arg_check_num(n_args, n_kw, 3, 3, false);
+    uint32_t width = mp_obj_get_int(pos_args[0]);
+    uint32_t height = mp_obj_get_int(pos_args[1]);
+    uint32_t value_size = mp_obj_get_int(pos_args[2]);
+    uint32_t power_of_two = 1;
+    while (value_size > power_of_two) {
+        power_of_two <<= 1;
+    }
+    if (value_size != power_of_two) {
+        mp_raise_ValueError(translate("value_size must be power of two"));
+    }
+
+    displayio_bitmap_t *self = m_new_obj(displayio_bitmap_t);
+    self->base.type = &displayio_bitmap_type;
+    common_hal_displayio_bitmap_construct(self, width, height, value_size);
+
+    return MP_OBJ_FROM_PTR(self);
+}
+
+
+//|   .. method:: _load_row(y, data)
+//|
+//|     Loads pre-packed data into the given row.
+//|
+STATIC mp_obj_t displayio_bitmap_obj__load_row(mp_obj_t self_in, mp_obj_t y_in, mp_obj_t data_in) {
+    displayio_bitmap_t *self = MP_OBJ_TO_PTR(self_in);
+    mp_int_t y;
+    if (!mp_obj_get_int_maybe(y_in, &y)) {
+        mp_raise_ValueError(translate("y should be an int"));
+    }
+    mp_buffer_info_t bufinfo;
+    if (mp_get_buffer(data_in, &bufinfo, MP_BUFFER_READ)) {
+        if (bufinfo.typecode != 'b' && bufinfo.typecode != 'B' && bufinfo.typecode != BYTEARRAY_TYPECODE) {
+            mp_raise_ValueError(translate("row buffer must be a bytearray or array of type 'b' or 'B'"));
+        }
+        uint8_t* buf = bufinfo.buf;
+        common_hal_displayio_bitmap_load_row(self, y, buf, bufinfo.len);
+    } else {
+        mp_raise_TypeError(translate("row data must be a buffer"));
+    }
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_3(displayio_bitmap__load_row_obj, displayio_bitmap_obj__load_row);
+
+STATIC const mp_rom_map_elem_t displayio_bitmap_locals_dict_table[] = {
+    { MP_ROM_QSTR(MP_QSTR__load_row), MP_ROM_PTR(&displayio_bitmap__load_row_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(displayio_bitmap_locals_dict, displayio_bitmap_locals_dict_table);
+
+const mp_obj_type_t displayio_bitmap_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_Bitmap,
+    .make_new = displayio_bitmap_make_new,
+    // TODO(tannewt): Implement subscr after slices support start, stop and step tuples.
+    // .subscr = displayio_bitmap_subscr,
+    .locals_dict = (mp_obj_dict_t*)&displayio_bitmap_locals_dict,
+};
diff --git a/shared-bindings/displayio/Bitmap.h b/shared-bindings/displayio/Bitmap.h
new file mode 100644
index 000000000..2ae468481
--- /dev/null
+++ b/shared-bindings/displayio/Bitmap.h
@@ -0,0 +1,41 @@
+/*
+ * 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_BITMAP_H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_BITMAP_H
+
+#include "shared-module/displayio/Bitmap.h"
+
+extern const mp_obj_type_t displayio_bitmap_type;
+
+void common_hal_displayio_bitmap_construct(displayio_bitmap_t *self, uint32_t width,
+    uint32_t height, uint32_t value_size);
+
+void common_hal_displayio_bitmap_load_row(displayio_bitmap_t *self, uint16_t y, uint8_t* data,
+                                          uint16_t len);
+uint32_t common_hal_displayio_bitmap_get_pixel(displayio_bitmap_t *bitmap, int16_t x, int16_t y);
+
+#endif // MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_BITMAP_H
diff --git a/shared-bindings/displayio/FourWire.c b/shared-bindings/displayio/FourWire.c
new file mode 100644
index 000000000..c0d60bd3b
--- /dev/null
+++ b/shared-bindings/displayio/FourWire.c
@@ -0,0 +1,118 @@
+/*
+ * 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/FourWire.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/microcontroller/Pin.h"
+#include "shared-bindings/util.h"
+#include "supervisor/shared/translate.h"
+
+//| .. currentmodule:: displayio
+//|
+//| :class:`FourWire` -- Manage updating a display over SPI four wire protocol
+//| ==========================================================================
+//|
+//| Manage updating a display over SPI four wire protocol in the background while Python code runs.
+//| It doesn't handle display initialization.
+//|
+//| .. warning:: This will be changed before 4.0.0. Consider it very experimental.
+//|
+//| .. class:: FourWire(*, clock, data, command, chip_select, width, height, colstart, rowstart,
+//|                     color_depth, set_column_command, set_row_command, write_ram_command)
+//|
+//|   Create a FourWire object associated with the given pins.
+//|
+STATIC mp_obj_t displayio_fourwire_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) {
+    mp_raise_NotImplementedError(translate("displayio is a work in progress"));
+    return mp_const_none;
+}
+
+
+//|   .. 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);
+
+//|   .. method:: show(group)
+//|
+//|     Switches do displaying the given group of elements.
+//|
+STATIC mp_obj_t displayio_fourwire_obj_show(mp_obj_t self_in, mp_obj_t group_in) {
+    displayio_fourwire_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    displayio_group_t* group = MP_OBJ_TO_PTR(group_in);
+    common_hal_displayio_fourwire_show(self, group);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(displayio_fourwire_show_obj, displayio_fourwire_obj_show);
+
+//|   .. method:: refresh_soon()
+//|
+//|     Queues up a display refresh that happens in the background.
+//|
+STATIC mp_obj_t displayio_fourwire_obj_refresh_soon(mp_obj_t self_in) {
+    displayio_fourwire_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    common_hal_displayio_fourwire_refresh_soon(self);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_1(displayio_fourwire_refresh_soon_obj, displayio_fourwire_obj_refresh_soon);
+
+//|   .. method:: wait_for_frame()
+//|
+//|     Waits until the next frame has been transmitted to the display unless the wait count is
+//|     behind the rendered frames. In that case, this will return immediately with the wait count.
+//|
+STATIC mp_obj_t displayio_fourwire_obj_wait_for_frame(mp_obj_t self_in) {
+    displayio_fourwire_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    return MP_OBJ_NEW_SMALL_INT(common_hal_displayio_fourwire_wait_for_frame(self));
+}
+MP_DEFINE_CONST_FUN_OBJ_1(displayio_fourwire_wait_for_frame_obj, displayio_fourwire_obj_wait_for_frame);
+
+
+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) },
+    { MP_ROM_QSTR(MP_QSTR_show), MP_ROM_PTR(&displayio_fourwire_show_obj) },
+    { MP_ROM_QSTR(MP_QSTR_refresh_soon), MP_ROM_PTR(&displayio_fourwire_refresh_soon_obj) },
+    { MP_ROM_QSTR(MP_QSTR_wait_for_frame), MP_ROM_PTR(&displayio_fourwire_wait_for_frame_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(displayio_fourwire_locals_dict, displayio_fourwire_locals_dict_table);
+
+const mp_obj_type_t displayio_fourwire_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_FourWire,
+    .make_new = displayio_fourwire_make_new,
+    .locals_dict = (mp_obj_dict_t*)&displayio_fourwire_locals_dict,
+};
diff --git a/shared-bindings/displayio/FourWire.h b/shared-bindings/displayio/FourWire.h
new file mode 100644
index 000000000..fc51f558d
--- /dev/null
+++ b/shared-bindings/displayio/FourWire.h
@@ -0,0 +1,65 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2017, 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_DISPLAYBUSIO_FOURWIRE_H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYBUSIO_FOURWIRE_H
+
+#include "common-hal/displayio/FourWire.h"
+#include "common-hal/microcontroller/Pin.h"
+
+#include "shared-module/displayio/Group.h"
+
+extern const mp_obj_type_t displayio_fourwire_type;
+
+// TODO(tannewt): Split this apart into FourWire and a Display object because the dimensions and
+// commands are also used for the parallel buses.
+void common_hal_displayio_fourwire_construct(displayio_fourwire_obj_t* self,
+    const mcu_pin_obj_t* clock, const mcu_pin_obj_t* data, const mcu_pin_obj_t* command,
+    const mcu_pin_obj_t* chip_select, const mcu_pin_obj_t* reset, 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);
+
+int32_t common_hal_displayio_fourwire_wait_for_frame(displayio_fourwire_obj_t* self);
+
+bool common_hal_displayio_fourwire_begin_transaction(displayio_fourwire_obj_t* self);
+
+void common_hal_displayio_fourwire_send(displayio_fourwire_obj_t* self, bool command, uint8_t *data, uint32_t data_length);
+
+void common_hal_displayio_fourwire_end_transaction(displayio_fourwire_obj_t* self);
+
+void common_hal_displayio_fourwire_show(displayio_fourwire_obj_t* self, displayio_group_t* root_group);
+
+void common_hal_displayio_fourwire_refresh_soon(displayio_fourwire_obj_t* self);
+
+void displayio_fourwire_start_region_update(displayio_fourwire_obj_t* self, uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1);
+void displayio_fourwire_finish_region_update(displayio_fourwire_obj_t* self);
+bool displayio_fourwire_frame_queued(displayio_fourwire_obj_t* self);
+
+bool displayio_fourwire_refresh_queued(displayio_fourwire_obj_t* self);
+void displayio_fourwire_finish_refresh(displayio_fourwire_obj_t* self);
+bool displayio_fourwire_send_pixels(displayio_fourwire_obj_t* self, uint32_t* pixels, uint32_t length);
+
+#endif // MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYBUSIO_FOURWIRE_H
diff --git a/shared-bindings/displayio/Group.c b/shared-bindings/displayio/Group.c
new file mode 100644
index 000000000..a2a879987
--- /dev/null
+++ b/shared-bindings/displayio/Group.c
@@ -0,0 +1,96 @@
+/*
+ * 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/Group.h"
+
+#include <stdint.h>
+
+#include "lib/utils/context_manager_helpers.h"
+#include "py/binary.h"
+#include "py/objproperty.h"
+#include "py/runtime.h"
+#include "supervisor/shared/translate.h"
+
+//| .. currentmodule:: displayio
+//|
+//| :class:`Group` -- Group together sprites and subgroups
+//| ==========================================================================
+//|
+//| Manage a group of sprites and groups and how they are inter-related.
+//|
+//| .. warning:: This will be changed before 4.0.0. Consider it very experimental.
+//|
+//| .. class:: Group(*, max_size=4)
+//|
+//|   Create a Group of a given size.
+//|
+//|   :param int max_size: The maximum group size.
+//|
+STATIC mp_obj_t displayio_group_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) {
+    mp_arg_check_num(n_args, n_kw, 0, 0, true);
+    mp_map_t kw_args;
+    mp_map_init_fixed_table(&kw_args, n_kw, pos_args + n_args);
+    enum { ARG_max_size };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_max_size, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 4} },
+    };
+    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_int_t max_size = args[ARG_max_size].u_int;
+    if (max_size < 1) {
+        mp_raise_ValueError(translate("Group must have size at least 1"));
+    }
+
+    displayio_group_t *self = m_new_obj(displayio_group_t);
+    self->base.type = &displayio_group_type;
+    common_hal_displayio_group_construct(self, max_size);
+
+    return MP_OBJ_FROM_PTR(self);
+}
+
+//|   .. method:: append(layer)
+//|
+//|     Switches do displaying the given group of elements.
+//|
+STATIC mp_obj_t displayio_group_obj_append(mp_obj_t self_in, mp_obj_t layer) {
+    displayio_group_t *self = MP_OBJ_TO_PTR(self_in);
+    common_hal_displayio_group_append(self, layer);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(displayio_group_append_obj, displayio_group_obj_append);
+
+STATIC const mp_rom_map_elem_t displayio_group_locals_dict_table[] = {
+    { MP_ROM_QSTR(MP_QSTR_append), MP_ROM_PTR(&displayio_group_append_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(displayio_group_locals_dict, displayio_group_locals_dict_table);
+
+const mp_obj_type_t displayio_group_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_Group,
+    .make_new = displayio_group_make_new,
+    .locals_dict = (mp_obj_dict_t*)&displayio_group_locals_dict,
+};
diff --git a/shared-bindings/displayio/Group.h b/shared-bindings/displayio/Group.h
new file mode 100644
index 000000000..aeb5a7b54
--- /dev/null
+++ b/shared-bindings/displayio/Group.h
@@ -0,0 +1,38 @@
+/*
+ * 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_GROUP_H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_GROUP_H
+
+#include "shared-module/displayio/Group.h"
+
+extern const mp_obj_type_t displayio_group_type;
+
+
+void common_hal_displayio_group_construct(displayio_group_t* self, uint32_t max_size);
+void common_hal_displayio_group_append(displayio_group_t* self, mp_obj_t layer);
+
+#endif // MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_GROUP_H
diff --git a/shared-bindings/displayio/Palette.c b/shared-bindings/displayio/Palette.c
new file mode 100644
index 000000000..bb2af9410
--- /dev/null
+++ b/shared-bindings/displayio/Palette.c
@@ -0,0 +1,157 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2017 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/Palette.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/microcontroller/Pin.h"
+#include "shared-bindings/util.h"
+#include "supervisor/shared/translate.h"
+
+//| .. currentmodule:: displayio
+//|
+//| :class:`Palette` -- Stores a mapping from bitmap pixel values to display colors
+//| ===============================================================================
+//|
+//| Manage updating a display over SPI four wire protocol in the background while Python code runs.
+//| It doesn't handle display initialization.
+//|
+//| .. warning:: This will be changed before 4.0.0. Consider it very experimental.
+//|
+//| .. class:: Palette(color_count)
+//|
+//|   Create a Palette object to store a set number of colors.
+//|
+//|   :param int color_count: The number of colors in the Palette
+// TODO(tannewt): Add support for other color formats.
+// TODO(tannewt): Add support for 8-bit alpha blending.
+//|
+STATIC mp_obj_t displayio_palette_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) {
+    mp_arg_check_num(n_args, n_kw, 1, 1, true);
+    mp_map_t kw_args;
+    mp_map_init_fixed_table(&kw_args, n_kw, pos_args + n_args);
+    enum { ARG_color_count };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_color_count, MP_ARG_INT | MP_ARG_REQUIRED },
+    };
+    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);
+
+    displayio_palette_t *self = m_new_obj(displayio_palette_t);
+    self->base.type = &displayio_palette_type;
+    common_hal_displayio_palette_construct(self, args[ARG_color_count].u_int);
+
+    return MP_OBJ_FROM_PTR(self);
+}
+
+STATIC mp_obj_t palette_subscr(mp_obj_t self_in, mp_obj_t index_in, mp_obj_t value) {
+    if (value == MP_OBJ_NULL) {
+        // delete item
+        return MP_OBJ_NULL; // op not supported
+    } else {
+        displayio_palette_t *self = MP_OBJ_TO_PTR(self_in);
+        if (MP_OBJ_IS_TYPE(index_in, &mp_type_slice)) {
+            return MP_OBJ_NULL; // Slicing not supported. Use a duplicate Palette to swap multiple colors atomically.
+        } else {
+            if (value == MP_OBJ_SENTINEL) {
+                return MP_OBJ_NULL; // index read is not supported
+            } else {
+                size_t index = mp_get_index(&displayio_palette_type, self->max_value, index_in, false);
+
+                uint32_t color;
+                mp_int_t int_value;
+                mp_buffer_info_t bufinfo;
+                if (mp_get_buffer(value, &bufinfo, MP_BUFFER_READ)) {
+                    if (bufinfo.typecode != 'b' && bufinfo.typecode != 'B' && bufinfo.typecode != BYTEARRAY_TYPECODE) {
+                        mp_raise_ValueError(translate("color buffer must be a bytearray or array of type 'b' or 'B'"));
+                    }
+                    uint8_t* buf = bufinfo.buf;
+                    if (bufinfo.len == 3 || bufinfo.len == 4) {
+                        color = buf[0] << 16 | buf[1] << 8 | buf[2];
+                    } else {
+                        mp_raise_ValueError(translate("color buffer must be 3 bytes (RGB) or 4 bytes (RGBA)"));
+                    }
+                } else if (mp_obj_get_int_maybe(value, &int_value)) {
+                    if (int_value < 0 || int_value > 0xffffff) {
+                        mp_raise_TypeError(translate("color must be between 0x000000 and 0xffffff"));
+                    }
+                    color = int_value;
+                } else {
+                    mp_raise_TypeError(translate("color buffer must be a buffer or int"));
+                }
+                common_hal_displayio_palette_set_color(self, index, color);
+                return mp_const_none;
+            }
+        }
+    }
+}
+
+//|   .. method:: make_transparent(value)
+//|
+STATIC mp_obj_t displayio_palette_obj_make_transparent(mp_obj_t self_in, mp_obj_t value_obj) {
+    displayio_palette_t *self = MP_OBJ_TO_PTR(self_in);
+
+    mp_int_t value;
+    if (!mp_obj_get_int_maybe(value_obj, &value)) {
+        mp_raise_ValueError(translate("value should be an int"));
+    }
+    common_hal_displayio_palette_make_transparent(self, value);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(displayio_palette_make_transparent_obj, displayio_palette_obj_make_transparent);
+
+//|   .. method:: make_opaque(value)
+//|
+STATIC mp_obj_t displayio_palette_obj_make_opaque(mp_obj_t self_in, mp_obj_t value_obj) {
+    displayio_palette_t *self = MP_OBJ_TO_PTR(self_in);
+
+    mp_int_t value;
+    if (!mp_obj_get_int_maybe(value_obj, &value)) {
+        mp_raise_ValueError(translate("value should be an int"));
+    }
+    common_hal_displayio_palette_make_opaque(self, value);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(displayio_palette_make_opaque_obj, displayio_palette_obj_make_opaque);
+
+STATIC const mp_rom_map_elem_t displayio_palette_locals_dict_table[] = {
+    { MP_ROM_QSTR(MP_QSTR_make_transparent), MP_ROM_PTR(&displayio_palette_make_transparent_obj) },
+    { MP_ROM_QSTR(MP_QSTR_make_opaque), MP_ROM_PTR(&displayio_palette_make_opaque_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(displayio_palette_locals_dict, displayio_palette_locals_dict_table);
+
+const mp_obj_type_t displayio_palette_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_Palette,
+    .make_new = displayio_palette_make_new,
+    .subscr = palette_subscr,
+    .locals_dict = (mp_obj_dict_t*)&displayio_palette_locals_dict,
+};
diff --git a/shared-bindings/displayio/Palette.h b/shared-bindings/displayio/Palette.h
new file mode 100644
index 000000000..fde6ab7d3
--- /dev/null
+++ b/shared-bindings/displayio/Palette.h
@@ -0,0 +1,40 @@
+/*
+ * 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_PALETTE_H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_PALETTE_H
+
+#include "shared-module/displayio/Palette.h"
+
+extern const mp_obj_type_t displayio_palette_type;
+
+void common_hal_displayio_palette_construct(displayio_palette_t* self, uint16_t color_count);
+void common_hal_displayio_palette_set_color(displayio_palette_t* self, uint32_t value, uint32_t color);
+
+void common_hal_displayio_palette_make_opaque(displayio_palette_t* self, uint32_t value);
+void common_hal_displayio_palette_make_transparent(displayio_palette_t* self, uint32_t value);
+
+#endif // MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_PALETTE_H
diff --git a/shared-bindings/displayio/Sprite.c b/shared-bindings/displayio/Sprite.c
new file mode 100644
index 000000000..25ea79f5c
--- /dev/null
+++ b/shared-bindings/displayio/Sprite.c
@@ -0,0 +1,180 @@
+/*
+ * 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 "supervisor/shared/translate.h"
+
+void parse_position(mp_obj_t position_obj, int16_t* x, int16_t* y) {
+    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 palette combination.
+//|
+//| .. warning:: This will be changed before 4.0.0. Consider it very experimental.
+//|
+//| .. class:: Sprite(bitmap, *, palette, position, width, height)
+//|
+//|   Create a Sprite object
+//|
+//|
+STATIC mp_obj_t displayio_sprite_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) {
+    mp_arg_check_num(n_args, n_kw, 1, 4, true);
+    mp_map_t kw_args;
+    mp_map_init_fixed_table(&kw_args, n_kw, pos_args + n_args);
+    enum { ARG_bitmap, ARG_palette, ARG_position, ARG_width, ARG_height };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_bitmap, MP_ARG_OBJ | MP_ARG_REQUIRED },
+        { MP_QSTR_palette, 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;
+    if (MP_OBJ_IS_TYPE(bitmap, &displayio_bitmap_type)) {
+        displayio_bitmap_t* bmp = MP_OBJ_TO_PTR(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;
+    parse_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, bitmap, args[ARG_palette].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;
+    parse_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:: palette
+//|
+//|     The color palette of the sprite.
+//|
+STATIC mp_obj_t displayio_sprite_obj_get_palette(mp_obj_t self_in) {
+    displayio_sprite_t *self = MP_OBJ_TO_PTR(self_in);
+    return common_hal_displayio_sprite_get_palette(self);
+}
+MP_DEFINE_CONST_FUN_OBJ_1(displayio_sprite_get_palette_obj, displayio_sprite_obj_get_palette);
+
+STATIC mp_obj_t displayio_sprite_obj_set_palette(mp_obj_t self_in, mp_obj_t palette_in) {
+    displayio_sprite_t *self = MP_OBJ_TO_PTR(self_in);
+    if (!MP_OBJ_IS_TYPE(palette_in, &displayio_palette_type)) {
+        mp_raise_TypeError(translate("palette must be displayio.Palette"));
+    }
+    displayio_palette_t *palette = MP_OBJ_TO_PTR(palette_in);
+
+    common_hal_displayio_sprite_set_palette(self, palette);
+
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(displayio_sprite_set_palette_obj, displayio_sprite_obj_set_palette);
+
+const mp_obj_property_t displayio_sprite_palette_obj = {
+    .base.type = &mp_type_property,
+    .proxy = {(mp_obj_t)&displayio_sprite_get_palette_obj,
+              (mp_obj_t)&displayio_sprite_set_palette_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_palette),          MP_ROM_PTR(&displayio_sprite_palette_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
new file mode 100644
index 000000000..0bfa40044
--- /dev/null
+++ b/shared-bindings/displayio/Sprite.h
@@ -0,0 +1,43 @@
+/*
+ * 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 palette, 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);
+
+displayio_palette_t* common_hal_displayio_sprite_get_palette(displayio_sprite_t *self);
+void common_hal_displayio_sprite_set_palette(displayio_sprite_t *self, displayio_palette_t* palette);
+
+#endif // MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO_SPRITE_H
diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c
new file mode 100644
index 000000000..73f12db95
--- /dev/null
+++ b/shared-bindings/displayio/__init__.c
@@ -0,0 +1,83 @@
+/*
+ * This file is part of the MicroPython 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 <stdint.h>
+
+#include "py/obj.h"
+#include "py/runtime.h"
+
+#include "shared-bindings/displayio/__init__.h"
+#include "shared-bindings/displayio/Bitmap.h"
+#include "shared-bindings/displayio/FourWire.h"
+#include "shared-bindings/displayio/Group.h"
+#include "shared-bindings/displayio/Palette.h"
+#include "shared-bindings/displayio/Sprite.h"
+
+//| :mod:`displayio` --- Native display driving
+//| =========================================================================
+//|
+//| .. module:: displayio
+//|   :synopsis: Native helpers for driving displays
+//|   :platform: SAMD21, SAMD51
+//|
+//| The `displayio` module contains classes to manage display output
+//| including synchronizing with refresh rates and partial updating. It does
+//| not include display initialization commands. It should live in a Python
+//| driver for use when a display is connected to a board. It should also be
+//| built into the board init when the board has the display on it.
+//|
+//| .. warning:: This will be changed before 4.0.0. Consider it very experimental.
+//|
+//| Libraries
+//|
+//| .. toctree::
+//|     :maxdepth: 3
+//|
+//|     Bitmap
+//|     FourWire
+//|     Group
+//|     Palette
+//|     Sprite
+//|
+//| All libraries change hardware state but are never deinit
+//|
+
+STATIC const mp_rom_map_elem_t displayio_module_globals_table[] = {
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_displayio) },
+    { MP_ROM_QSTR(MP_QSTR_Bitmap), MP_ROM_PTR(&displayio_bitmap_type) },
+    { MP_ROM_QSTR(MP_QSTR_Group), MP_ROM_PTR(&displayio_group_type) },
+    { MP_ROM_QSTR(MP_QSTR_Palette), MP_ROM_PTR(&displayio_palette_type) },
+    { MP_ROM_QSTR(MP_QSTR_Sprite), MP_ROM_PTR(&displayio_sprite_type) },
+
+    { MP_ROM_QSTR(MP_QSTR_FourWire), MP_ROM_PTR(&displayio_fourwire_type) },
+};
+
+STATIC MP_DEFINE_CONST_DICT(displayio_module_globals, displayio_module_globals_table);
+
+const mp_obj_module_t displayio_module = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t*)&displayio_module_globals,
+};
diff --git a/shared-bindings/displayio/__init__.h b/shared-bindings/displayio/__init__.h
new file mode 100644
index 000000000..5c3fc2b55
--- /dev/null
+++ b/shared-bindings/displayio/__init__.h
@@ -0,0 +1,38 @@
+/*
+ * This file is part of the MicroPython 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___INIT___H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO___INIT___H
+
+#include "py/obj.h"
+
+// Nothing now.
+
+// typedef enum {
+//     PIXEL_
+// } displayio_pixel_format;
+
+#endif  // MICROPY_INCLUDED_SHARED_BINDINGS_DISPLAYIO___INIT___H