From 485924896edc917dbfbf60313a1796388bf046ee Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Tue, 22 Aug 2023 10:30:57 -0500 Subject: [PATCH 1/5] RGBMatrix: document constructor arguments Closes: #8283 --- shared-bindings/rgbmatrix/RGBMatrix.c | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/shared-bindings/rgbmatrix/RGBMatrix.c b/shared-bindings/rgbmatrix/RGBMatrix.c index 0f5cc91fc7..9166241a24 100644 --- a/shared-bindings/rgbmatrix/RGBMatrix.c +++ b/shared-bindings/rgbmatrix/RGBMatrix.c @@ -186,7 +186,22 @@ STATIC void preflight_pins_or_throw(uint8_t clock_pin, uint8_t *rgb_pins, uint8_ //| flicker during updates. //| //| A RGBMatrix is often used in conjunction with a -//| `framebufferio.FramebufferDisplay`.""" +//| `framebufferio.FramebufferDisplay`. +//| +//| :param int width: The overall width of the display in pixels +//| :param int height: The overall height of all displays in pixels +//| :param int tile: In a multi-row display, the number of rows of panels +//| :param int bit_depth: The color depth of the display. A value of 1 gives 8 colors, a value of 2 gives 64 colors, and so on. Increasing bit depth increases the CPU and RAM usage of the RGBMatrix, and may lower the panel refresh rate. The framebuffer is always in RGB565 format regardless of the bit depth setting +//| :param bool serpentine: In a multi-row display, True when alternate rows are rotated 180°, which can reduce wiring length +//| :param Sequence[digitalio.DigitalInOut] rgb_pins: The display's "RGB pins" +//| :param Sequence[digitalio.DigitalInOut] addr_pins: The display's "address pins" +//| :param digitalio.DigitalInOut clock_pin: The display's "clock pin" +//| :param digitalio.DigitalInOut latch_pin: The display's "latch pin" +//| :param digitalio.DigitalInOut output_enable_pin: The display's "output enable" pin +//| :param bool doublebuffer: True if the output is double-buffered +//| :param Optional[WriteableBuffer] framebuffer: A pre-allocated framebuffer to use. If unspecified, a framebuffer is allocated +//| +//| """ STATIC mp_obj_t rgbmatrix_rgbmatrix_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) { enum { ARG_width, ARG_bit_depth, ARG_rgb_list, ARG_addr_list, From 81ad2e05bae637c99546b7940b72e2c500dfa622 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Tue, 22 Aug 2023 10:44:35 -0500 Subject: [PATCH 2/5] address review comments --- shared-bindings/rgbmatrix/RGBMatrix.c | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/shared-bindings/rgbmatrix/RGBMatrix.c b/shared-bindings/rgbmatrix/RGBMatrix.c index 9166241a24..0aa7e581b0 100644 --- a/shared-bindings/rgbmatrix/RGBMatrix.c +++ b/shared-bindings/rgbmatrix/RGBMatrix.c @@ -188,16 +188,16 @@ STATIC void preflight_pins_or_throw(uint8_t clock_pin, uint8_t *rgb_pins, uint8_ //| A RGBMatrix is often used in conjunction with a //| `framebufferio.FramebufferDisplay`. //| -//| :param int width: The overall width of the display in pixels -//| :param int height: The overall height of all displays in pixels -//| :param int tile: In a multi-row display, the number of rows of panels -//| :param int bit_depth: The color depth of the display. A value of 1 gives 8 colors, a value of 2 gives 64 colors, and so on. Increasing bit depth increases the CPU and RAM usage of the RGBMatrix, and may lower the panel refresh rate. The framebuffer is always in RGB565 format regardless of the bit depth setting -//| :param bool serpentine: In a multi-row display, True when alternate rows are rotated 180°, which can reduce wiring length -//| :param Sequence[digitalio.DigitalInOut] rgb_pins: The display's "RGB pins" -//| :param Sequence[digitalio.DigitalInOut] addr_pins: The display's "address pins" -//| :param digitalio.DigitalInOut clock_pin: The display's "clock pin" -//| :param digitalio.DigitalInOut latch_pin: The display's "latch pin" -//| :param digitalio.DigitalInOut output_enable_pin: The display's "output enable" pin +//| :param int width: The overall width of the whole matrix in pixels +//| :param int height: The overall height of the whole matrix in pixels +//| :param int tile: In a multi-row matrix, the number of rows of panels +//| :param int bit_depth: The color depth of the matrix. A value of 1 gives 8 colors, a value of 2 gives 64 colors, and so on. Increasing bit depth increases the CPU and RAM usage of the RGBMatrix, and may lower the panel refresh rate. The framebuffer is always in RGB565 format regardless of the bit depth setting +//| :param bool serpentine: In a multi-row matrix, True when alternate rows of panels are rotated 180°, which can reduce wiring length +//| :param Sequence[digitalio.DigitalInOut] rgb_pins: The matrix's RGB pins +//| :param Sequence[digitalio.DigitalInOut] addr_pins: The matrix's address pins +//| :param digitalio.DigitalInOut clock_pin: The matrix's clock pin +//| :param digitalio.DigitalInOut latch_pin: The matrix's latch pin +//| :param digitalio.DigitalInOut output_enable_pin: The matrix's output enable pin //| :param bool doublebuffer: True if the output is double-buffered //| :param Optional[WriteableBuffer] framebuffer: A pre-allocated framebuffer to use. If unspecified, a framebuffer is allocated //| From 2dcc0d2a62c20ad7684e53db6b9d5c8b832e2511 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Tue, 22 Aug 2023 10:46:34 -0500 Subject: [PATCH 3/5] further explain width and height, it can't hurt --- shared-bindings/rgbmatrix/RGBMatrix.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/shared-bindings/rgbmatrix/RGBMatrix.c b/shared-bindings/rgbmatrix/RGBMatrix.c index 0aa7e581b0..4b044eac5a 100644 --- a/shared-bindings/rgbmatrix/RGBMatrix.c +++ b/shared-bindings/rgbmatrix/RGBMatrix.c @@ -188,8 +188,8 @@ STATIC void preflight_pins_or_throw(uint8_t clock_pin, uint8_t *rgb_pins, uint8_ //| A RGBMatrix is often used in conjunction with a //| `framebufferio.FramebufferDisplay`. //| -//| :param int width: The overall width of the whole matrix in pixels -//| :param int height: The overall height of the whole matrix in pixels +//| :param int width: The overall width of the whole matrix in pixels. For a matrix with multiple panels in row, this is the width of a single panel times the number of panels across. +//| :param int height: The overall height of the whole matrix in pixels. For a matrix with multiple rows of panels, this is the height of a single panel times the number of panels down. //| :param int tile: In a multi-row matrix, the number of rows of panels //| :param int bit_depth: The color depth of the matrix. A value of 1 gives 8 colors, a value of 2 gives 64 colors, and so on. Increasing bit depth increases the CPU and RAM usage of the RGBMatrix, and may lower the panel refresh rate. The framebuffer is always in RGB565 format regardless of the bit depth setting //| :param bool serpentine: In a multi-row matrix, True when alternate rows of panels are rotated 180°, which can reduce wiring length From e336dc90cf15ef61b235e3d6ad4fc435e6c61320 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Tue, 22 Aug 2023 10:53:10 -0500 Subject: [PATCH 4/5] update explanation of height; it is optional --- shared-bindings/rgbmatrix/RGBMatrix.c | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/shared-bindings/rgbmatrix/RGBMatrix.c b/shared-bindings/rgbmatrix/RGBMatrix.c index 4b044eac5a..c68798e352 100644 --- a/shared-bindings/rgbmatrix/RGBMatrix.c +++ b/shared-bindings/rgbmatrix/RGBMatrix.c @@ -189,7 +189,6 @@ STATIC void preflight_pins_or_throw(uint8_t clock_pin, uint8_t *rgb_pins, uint8_ //| `framebufferio.FramebufferDisplay`. //| //| :param int width: The overall width of the whole matrix in pixels. For a matrix with multiple panels in row, this is the width of a single panel times the number of panels across. -//| :param int height: The overall height of the whole matrix in pixels. For a matrix with multiple rows of panels, this is the height of a single panel times the number of panels down. //| :param int tile: In a multi-row matrix, the number of rows of panels //| :param int bit_depth: The color depth of the matrix. A value of 1 gives 8 colors, a value of 2 gives 64 colors, and so on. Increasing bit depth increases the CPU and RAM usage of the RGBMatrix, and may lower the panel refresh rate. The framebuffer is always in RGB565 format regardless of the bit depth setting //| :param bool serpentine: In a multi-row matrix, True when alternate rows of panels are rotated 180°, which can reduce wiring length @@ -200,7 +199,7 @@ STATIC void preflight_pins_or_throw(uint8_t clock_pin, uint8_t *rgb_pins, uint8_ //| :param digitalio.DigitalInOut output_enable_pin: The matrix's output enable pin //| :param bool doublebuffer: True if the output is double-buffered //| :param Optional[WriteableBuffer] framebuffer: A pre-allocated framebuffer to use. If unspecified, a framebuffer is allocated -//| +//| :param int height: The optional overall height of the whole matrix in pixels. This value is not required because it can be calculated as described above. //| """ STATIC mp_obj_t rgbmatrix_rgbmatrix_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) { From c1dce99be97aa8a12d8e12f3a9d634e660e555c7 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Tue, 22 Aug 2023 10:55:55 -0500 Subject: [PATCH 5/5] Link to dedicated guide for rgbmatrix --- shared-bindings/rgbmatrix/__init__.c | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/shared-bindings/rgbmatrix/__init__.c b/shared-bindings/rgbmatrix/__init__.c index 1e9099adb6..62fb4abd59 100644 --- a/shared-bindings/rgbmatrix/__init__.c +++ b/shared-bindings/rgbmatrix/__init__.c @@ -31,7 +31,11 @@ #include "shared-bindings/rgbmatrix/RGBMatrix.h" -//| """Low-level routines for bitbanged LED matrices""" +//| """Low-level routines for bitbanged LED matrices +//| +//| For more information about working with RGB matrix panels in CircuitPython, see +//| `the dedicated learn guide `_. +//| """ STATIC const mp_rom_map_elem_t rgbmatrix_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_rgbmatrix) },