From 468c6f9da147d6e752e437a32211e317a116b6df Mon Sep 17 00:00:00 2001
From: Peter Hinch <peter@hinch.me.uk>
Date: Sat, 1 Apr 2017 07:00:09 +0100
Subject: [PATCH] extmod/modframebuf: Make monochrome bitmap formats start with
 MONO_.

MONO_xxx is much easier to read if you're not familiar with the code.
MVLSB is deprecated but kept for backwards compatibility, for the time
being.

This patch also updates the associated docs and tests.
---
 docs/library/framebuf.rst     | 25 ++++++++++++++++++++++++-
 extmod/modframebuf.c          |  5 +++--
 tests/extmod/framebuf1.py     |  7 ++++---
 tests/extmod/framebuf1.py.exp |  7 ++++---
 4 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst
index 91fc362fdd..61f0635f36 100644
--- a/docs/library/framebuf.rst
+++ b/docs/library/framebuf.rst
@@ -116,9 +116,32 @@ Other methods
 Constants
 ---------
 
-.. data:: framebuf.MVLSB
+.. data:: framebuf.MONO_VLSB
 
     Monochrome (1-bit) color format
+    This defines a mapping where the bits in a byte are vertically mapped with
+    bit 0 being nearest the top of the screen. Consequently each byte occupies
+    8 vertical pixels. Subsequent bytes appear at successive horizontal
+    locations until the rightmost edge is reached. Further bytes are rendered
+    at locations starting at the leftmost edge, 8 pixels lower.
+
+.. data:: framebuf.MONO_HLSB
+
+    Monochrome (1-bit) color format
+    This defines a mapping where the bits in a byte are horizontally mapped.
+    Each byte occupies 8 horizontal pixels with bit 0 being the leftmost.
+    Subsequent bytes appear at successive horizontal locations until the
+    rightmost edge is reached. Further bytes are rendered on the next row, one
+    pixel lower.
+
+.. data:: framebuf.MONO_HMSB
+
+    Monochrome (1-bit) color format
+    This defines a mapping where the bits in a byte are horizontally mapped.
+    Each byte occupies 8 horizontal pixels with bit 7 being the leftmost.
+    Subsequent bytes appear at successive horizontal locations until the
+    rightmost edge is reached. Further bytes are rendered on the next row, one
+    pixel lower.
 
 .. data:: framebuf.RGB565
 
diff --git a/extmod/modframebuf.c b/extmod/modframebuf.c
index 33985dd00a..b8e84fe1c6 100644
--- a/extmod/modframebuf.c
+++ b/extmod/modframebuf.c
@@ -579,10 +579,11 @@ STATIC const mp_rom_map_elem_t framebuf_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_FrameBuffer), MP_ROM_PTR(&mp_type_framebuf) },
     { MP_ROM_QSTR(MP_QSTR_FrameBuffer1), MP_ROM_PTR(&legacy_framebuffer1_obj) },
     { MP_ROM_QSTR(MP_QSTR_MVLSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MVLSB) },
+    { MP_ROM_QSTR(MP_QSTR_MONO_VLSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MVLSB) },
     { MP_ROM_QSTR(MP_QSTR_RGB565), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_RGB565) },
     { MP_ROM_QSTR(MP_QSTR_GS4_HMSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_GS4_HMSB) },
-    { MP_ROM_QSTR(MP_QSTR_MHLSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MHLSB) },
-    { MP_ROM_QSTR(MP_QSTR_MHMSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MHMSB) },
+    { MP_ROM_QSTR(MP_QSTR_MONO_HLSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MHLSB) },
+    { MP_ROM_QSTR(MP_QSTR_MONO_HMSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MHMSB) },
 };
 
 STATIC MP_DEFINE_CONST_DICT(framebuf_module_globals, framebuf_module_globals_table);
diff --git a/tests/extmod/framebuf1.py b/tests/extmod/framebuf1.py
index 0a8e1ae550..990b0b120d 100644
--- a/tests/extmod/framebuf1.py
+++ b/tests/extmod/framebuf1.py
@@ -9,9 +9,9 @@ w = 5
 h = 16
 size = w * h // 8
 buf = bytearray(size)
-maps = {framebuf.MVLSB : 'MVLSB',
-        framebuf.MHLSB : 'MHLSB',
-        framebuf.MHMSB : 'MHMSB'}
+maps = {framebuf.MONO_VLSB : 'MONO_VLSB',
+        framebuf.MONO_HLSB : 'MONO_HLSB',
+        framebuf.MONO_HMSB : 'MONO_HMSB'}
 
 for mapping in maps.keys():
     for x in range(size):
@@ -107,3 +107,4 @@ except ValueError:
 # test legacy constructor
 fbuf = framebuf.FrameBuffer1(buf, w, h)
 fbuf = framebuf.FrameBuffer1(buf, w, h, w)
+print(framebuf.MVLSB == framebuf.MONO_VLSB)
diff --git a/tests/extmod/framebuf1.py.exp b/tests/extmod/framebuf1.py.exp
index 736ad7a454..d954623dee 100644
--- a/tests/extmod/framebuf1.py.exp
+++ b/tests/extmod/framebuf1.py.exp
@@ -1,4 +1,4 @@
-MVLSB
+MONO_VLSB
 0
 bytearray(b'\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff')
 bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
@@ -20,7 +20,7 @@ bytearray(b'\x00\x7f\x7f\x04\x04\x00\x00\x00\x00\x00')
 bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
 bytearray(b'\xaaU\xaaU\xaa\x00\x00\x00\x00\x00')
 
-MHLSB
+MONO_HLSB
 0
 bytearray(b'\xf8\xf8\xf8\xf8\xf8\xf8\xf8\xf8\xf8\xf8')
 bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
@@ -42,7 +42,7 @@ bytearray(b'``x````\x00\x00\x00')
 bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
 bytearray(b'P\xa8P\xa8P\xa8P\xa8\x00\x00')
 
-MHMSB
+MONO_HMSB
 0
 bytearray(b'\x1f\x1f\x1f\x1f\x1f\x1f\x1f\x1f\x1f\x1f')
 bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
@@ -65,3 +65,4 @@ bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
 bytearray(b'\n\x15\n\x15\n\x15\n\x15\x00\x00')
 
 ValueError
+True