Remove display.animate() and update docs.

Author: markshannon

docs/display.rst

@@ -25,13 +25,6 @@ Functions
 
     Set the brightness of all LEDs to 0.
 
-
-.. py:function:: show(string, delay=400)
-
-    Display the ``string`` one letter at a time, with ``delay`` milliseconds
-    between each pair of letters.
-
-
 .. py:function:: show(image)
 
     Display the ``image``.
@@ -43,25 +36,14 @@ Functions
     ``delay`` parameter controls how fast the text is scrolling. This function
     blocks until it is finished.
 
+.. py:function:: show(iterable, delay, wait=True, loop=False, clear=False)
 
-.. py:function:: animate(image, delay, stride, start, wait=True, loop=False)
-
-    Display the ``image`` starting with its ``start`` column, and scroll
-    it every ``delay`` milliseconds to the right by ``stride`` columns, until
-    the last column of the image is displayed.
-
-    If ``wait`` is ``True``, this function will block until the animation is
-    finished, otherwise the animation will happen in the background.
-
-    If ``loop`` is ``True``, the animation will repeat forever.
-
-
-.. py:function:: animate(iterable, delay, wait=True, loop=False)
-
-    Display images from the ``iterable`` in sequence, with ``delay``
+    Display images or letters from the ``iterable`` in sequence, with ``delay``
     milliseconds between them.
 
     If ``wait`` is ``True``, this function will block until the animation is
     finished, otherwise the animation will happen in the background.
 
     If ``loop`` is ``True``, the animation will repeat forever.
+
+    If ``clear`` is ``True``, the display will be cleared after the iterable has finished.

docs/microbit_micropython_api.rst

@@ -41,11 +41,9 @@ The LED display is exposed via the `display` object::
     display.get_pixel(x, y) # gets the brightness of the pixel (x,y)
     display.set_pixel(x, y, val) # sets the brightness of the pixel (x,y) to val (between 0 and 9, inclusive)
     display.clear() # clears the display
-    display.show(string, delay=400) # prints the string to the display one character at a time
-    display.show(image, delay=400) # shows the image on the screen.
-    display.scroll(string, delay=400) # scrolls a string across the display (more exciting than display.print)
-    display.animate(image, delay, stride, start, wait=True, loop=False)
-    display.animate(iterable, delay, wait=True, loop=False)
+    display.show(image, delay=0, wait=True, loop=False, clear=False) # shows the image
+    display.show(iterable, delay=400, wait=True, loop=False, clear=False) # shows each image or letter in the iterable, with delay ms. in between each.
+    display.scroll(string, delay=400) # scrolls a string across the display (more exciting than display.show)
 
 Pins
 ----

inc/genhdr/qstrdefs.generated.h

@@ -408,7 +408,6 @@ QDEF(MP_QSTR_delay, (const byte*)"\x50\x05" "delay")
 QDEF(MP_QSTR_stride, (const byte*)"\xb8\x06" "stride")
 QDEF(MP_QSTR_wait, (const byte*)"\x8e\x04" "wait")
 QDEF(MP_QSTR_loop, (const byte*)"\x39\x04" "loop")
-QDEF(MP_QSTR_animate, (const byte*)"\x3e\x07" "animate")
 QDEF(MP_QSTR_crop, (const byte*)"\x0b\x04" "crop")
 QDEF(MP_QSTR_text, (const byte*)"\x98\x04" "text")
 QDEF(MP_QSTR_SlicedImage, (const byte*)"\xf6\x0b" "SlicedImage")

inc/lib/utils/iters.h inc/lib/iters.hinc/lib/utils/iters.h renamed to inc/lib/iters.h

@@ -175,7 +175,6 @@ MP_DECLARE_CONST_FUN_OBJ(microbit_compass_get_z_obj);
 MP_DECLARE_CONST_FUN_OBJ(microbit_display_show_obj);
 MP_DECLARE_CONST_FUN_OBJ(microbit_display_scroll_obj);
 MP_DECLARE_CONST_FUN_OBJ(microbit_display_clear_obj);
-MP_DECLARE_CONST_FUN_OBJ(microbit_display_animate_obj);
 MP_DECLARE_CONST_FUN_OBJ(microbit_display_get_pixel_obj);
 MP_DECLARE_CONST_FUN_OBJ(microbit_display_set_pixel_obj);
 MP_DECLARE_CONST_FUN_OBJ(microbit_pin_read_digital_obj);

inc/microbit/modmicrobit.h

@@ -142,7 +142,6 @@ Q(stride)
 Q(start)
 Q(wait)
 Q(loop)
-Q(animate)
 Q(copy)
 Q(crop)
 Q(slice)

inc/microbit/qstrdefsport.h

@@ -25,7 +25,7 @@
  */
 
 #include "py/runtime.h"
-#include "lib/utils/iters.h"
+#include "lib/iters.h"
 
 typedef struct _repeat_iterator_t {
     mp_obj_base_t base;
@@ -40,7 +40,7 @@ STATIC mp_obj_t microbit_repeat_iter_next(mp_obj_t iter_in) {
         iter->iterator = mp_getiter(iter->iterable);
         result = mp_iternext(iter->iterator);
         if (result == MP_OBJ_STOP_ITERATION) {
-            nlr_raise(mp_obj_new_exception_msg(&mp_type_ValueError, "cannot repeat empty sequence."));
+            nlr_raise(mp_obj_new_exception_msg(&mp_type_ValueError, "cannot repeat empty sequence"));
         }
     }
     return result;

source/lib/utils/iters.c source/lib/iters.csource/lib/utils/iters.c renamed to source/lib/iters.c

@@ -100,10 +100,9 @@ STATIC const mp_doc_t help_table_instances[] = {
     {&microbit_compass_get_z_obj, "Return magnetic field detected along micro:bit's Z axis.\nUsually, the compass returns the earth's magnetic field in micro-Tesla units.\nUnless...a strong magnet is nearby!\n"},
     // Display 5x5 LED grid
     {&microbit_display_obj, "micro:bit's 5x5 LED display.\n"},
-    {&microbit_display_show_obj, "Use show(x) to print the string or image 'x' to the display. Try show('Hi!').\nUse show(s, i) to show string 's', one character at a time with a delay of\n'i' milliseconds.\n"},
+    {&microbit_display_show_obj, "Use show(x) to print the string or images 'x' to the display. Try show('Hi!').\nUse show(s, i) to show string 's', one character at a time with a delay of\n'i' milliseconds.\n"},
     {&microbit_display_scroll_obj, "Use scroll(s) to scroll the string 's' across the display.\nUse scroll(s, i) to scroll string 's' with a delay of 'i' milliseconds after\neach character.\n"},
     {&microbit_display_clear_obj, "Use clear() to clear micro:bit's display.\n"},
-    {&microbit_display_animate_obj, "Use animate(img, delay, stride, start=0, async=False, repeat=False) to animate\nimage 'img' with 'delay' milliseconds and 'stride' pixels offset between\nframes. Optional: 'start' offset from left hand side, 'async' to run in the\nbackground, 'repeat' to loop the animation.\n"},
     {&microbit_display_get_pixel_obj, "Use get_pixel(x, y) to return the display's brightness at LED pixel (x,y).\nBrightness can be from 0 (LED is off) to 9 (maximum LED brightness).\n"},
     {&microbit_display_set_pixel_obj, "Use set_pixel(x, y, b) to set the display at LED pixel (x,y) to brightness 'b'\nwhich can be set between 0 (off) to 9 (full brightness).\n"},
     // Pins

source/microbit/help.c

@@ -34,7 +34,7 @@ extern "C" {
 #include "modmicrobit.h"
 #include "microbitimage.h"
 #include "microbitdisplay.h"
-#include "lib/utils/iters.h"
+#include "lib/iters.h"
 
 void microbit_display_show(microbit_display_obj_t *display, microbit_image_obj_t *image) {
     mp_int_t w = min(image->width(), 5);
@@ -334,39 +334,6 @@ void microbit_display_animate(microbit_display_obj_t *self, mp_obj_t iterable, m
     }
 }
 
-STATIC mp_obj_t microbit_display_animate_func(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    static const mp_arg_t animate_allowed_args[] = {
-        { MP_QSTR_image,    MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} },
-        { MP_QSTR_delay,    MP_ARG_REQUIRED | MP_ARG_INT, {.u_int = 0} },
-        { MP_QSTR_stride,   MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 5} },
-        { MP_QSTR_start,    MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = -5} },
-        { MP_QSTR_wait,     MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = true} },
-        { MP_QSTR_loop,     MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = false} },
-    };
-
-    // Parse the args.
-    microbit_display_obj_t *self = (microbit_display_obj_t*)pos_args[0];
-    mp_arg_val_t args[MP_ARRAY_SIZE(animate_allowed_args)];
-    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(animate_allowed_args), animate_allowed_args, args);
-
-    mp_obj_t arg0 = args[0].u_obj;
-    mp_int_t stride = args[2].u_int;
-    mp_int_t start = args[3].u_int;
-    mp_obj_t iterable;
-    if (mp_obj_get_type(arg0) == &microbit_image_type) {
-        // Convert single image into an iterable of images.
-        iterable = microbit_image_slice((microbit_image_obj_t *)arg0, start, 5 /*width*/, stride);
-    } else {
-        iterable = arg0;
-    }
-    if (args[5].u_bool) { /* loop */
-        iterable = microbit_repeat_iterator(iterable);
-    }
-    microbit_display_animate(self, iterable, args[1].u_int /*delay*/, true/*clear*/, args[4].u_bool /*wait?*/);
-    return mp_const_none;
-}
-MP_DEFINE_CONST_FUN_OBJ_KW(microbit_display_animate_obj, 2, microbit_display_animate_func);
-
 void microbit_display_scroll(microbit_display_obj_t *self, const char* str) {
     mp_obj_t iterable = scrolling_string_image_iterable(str, strlen(str), NULL, false);
     microbit_display_animate(self, iterable, MICROBIT_DEFAULT_SCROLL_SPEED, false, false);
@@ -448,7 +415,6 @@ STATIC const mp_map_elem_t microbit_display_locals_dict_table[] = {
     { MP_OBJ_NEW_QSTR(MP_QSTR_set_pixel),  (mp_obj_t)&microbit_display_set_pixel_obj },
     { MP_OBJ_NEW_QSTR(MP_QSTR_show), (mp_obj_t)&microbit_display_show_obj },
     { MP_OBJ_NEW_QSTR(MP_QSTR_scroll), (mp_obj_t)&microbit_display_scroll_obj },
-    { MP_OBJ_NEW_QSTR(MP_QSTR_animate), (mp_obj_t)&microbit_display_animate_obj },
     { MP_OBJ_NEW_QSTR(MP_QSTR_clear), (mp_obj_t)&microbit_display_clear_obj },
 };
 

source/microbit/microbitdisplay.cpp

@@ -625,96 +625,6 @@ const mp_obj_type_t microbit_image_type = {
     .bases_tuple = MP_OBJ_NULL,
     /* .locals_dict = */ (mp_obj_t)&microbit_image_locals_dict,
 };
-
-
-/* Image slices */
-
-typedef struct _image_slice_t {
-    mp_obj_base_t base; 
-    microbit_image_obj_t *img;
-    mp_int_t start;
-    mp_int_t width;
-    mp_int_t stride;
-} image_slice_t;
-
-typedef struct _image_slice_iterator_t {
-    mp_obj_base_t base; 
-    image_slice_t *slice;
-    mp_int_t next_start;
-} image_slice_iterator_t;
-
-extern const mp_obj_type_t microbit_sliced_image_type;
-extern const mp_obj_type_t microbit_sliced_image_iterator_type;
-
-mp_obj_t microbit_image_slice(microbit_image_obj_t *img, mp_int_t start, mp_int_t width, mp_int_t stride) {
-    image_slice_t *result = m_new_obj(image_slice_t);
-    result->base.type = &microbit_sliced_image_type;
-    result->img = img;
-    result->start = start;
-    result->width = width;
-    result->stride = stride;
-    return result;
-}
-
-STATIC mp_obj_t get_microbit_image_slice_iter(mp_obj_t o_in) {
-    image_slice_t *slice = (image_slice_t *)o_in;
-    image_slice_iterator_t *result = m_new_obj(image_slice_iterator_t);
-    result->base.type = &microbit_sliced_image_iterator_type;
-    result->slice = slice;
-    result->next_start = slice->start;
-    return result;
-}
-
-STATIC mp_obj_t microbit_image_slice_iter_next(mp_obj_t o_in) {
-    image_slice_iterator_t *iter = (image_slice_iterator_t *)o_in;
-    mp_obj_t result;
-    microbit_image_obj_t *img = iter->slice->img;
-    if (iter->slice->stride > 0 && iter->next_start >= img->width()) {
-        return MP_OBJ_STOP_ITERATION;
-    }
-    if (iter->slice->stride < 0 && iter->next_start <= -iter->slice->width) {
-        return MP_OBJ_STOP_ITERATION;
-    }
-    result = image_crop(img, iter->next_start, 0, iter->slice->width, img->height());
-    iter->next_start += iter->slice->stride;
-    return result;
-}
-
-const mp_obj_type_t microbit_sliced_image_type = {
-    { &mp_type_type },
-    .name = MP_QSTR_SlicedImage,
-    .print = NULL,
-    .make_new = NULL,
-    .call = NULL,
-    .unary_op = NULL,
-    .binary_op = NULL,
-    .attr = NULL,
-    .subscr = NULL,
-    .getiter = get_microbit_image_slice_iter,
-    .iternext = NULL,
-    .buffer_p = {NULL},
-    .stream_p = NULL,
-    .bases_tuple = MP_OBJ_NULL,
-    MP_OBJ_NULL
-};
-
-const mp_obj_type_t microbit_sliced_image_iterator_type = {
-    { &mp_type_type },
-    .name = MP_QSTR_iterator,
-    .print = NULL,
-    .make_new = NULL,
-    .call = NULL,
-    .unary_op = NULL,
-    .binary_op = NULL,
-    .attr = NULL,
-    .subscr = NULL,
-    .getiter = mp_identity,
-    .iternext = microbit_image_slice_iter_next,
-    .buffer_p = {NULL},
-    .stream_p = NULL,
-    .bases_tuple = MP_OBJ_NULL,
-    MP_OBJ_NULL
-};
 
 typedef struct _scrolling_string_t {
     mp_obj_base_t base;