From 57c8fe5be6c642190c2e4dc6b998346aabdb5dc2 Mon Sep 17 00:00:00 2001 From: Sassan Haradji Date: Tue, 29 Oct 2024 16:55:53 +0400 Subject: [PATCH] docs: update README.md with the new features --- CHANGELOG.md | 4 ++++ README.md | 42 +++++++++++++++++++++++++++++++---------- headless_kivy/_debug.py | 6 +++--- headless_kivy/config.py | 6 +++--- 4 files changed, 42 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 22844f4..f803e56 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## Upcoming + +- docs: update README.md with the new features + ## Version 0.12.0 - feat: divide each frame into multiple rectangles, compare rectangle with the same rectangle in the previous frame and update only the changed ones diff --git a/README.md b/README.md index b9383db..95f3061 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,18 @@ -# Kivy Headless Renderer +# Headless Kivy -This project provides utilities to render Kivy applications headlessly. It can be -used in test environments, it also provides tools for snapshot testing. -It can also be used on a Raspberry Pi or similar devices to render the Kivy application -on a custom display like an SPI display. +Provides utilities to render Kivy applications headlessly. It calls a callback whenever something has changed in the framebuffer in a locality. -The renderer is optimized to not schedule a render when nothing has changed since -the last rendered frame. +It can be used to render the Kivy application on a custom display like an SPI display, it provides tools for local updates, limiting the bandwidth and limiting the fps based on the spec of the display. + +It can also be used in test environments with it tools for snapshot testing. + +You can control the orientation of the display and flipping the display horizontally and vertically. + +The renderer is optimized to not schedule a render when nothing has changed since the last rendered frame, by default it divides the screen into tiles and checks each tile for changes separately. + +It can be configured to use double buffering, so that the next frame is generated while the last frame is being transmitted to the display. + +You can have multiple instances of the headless renderer in the same application, each works as a portal to your display (or multiple different displays). ## 📦 Installation @@ -17,7 +23,7 @@ pip install headless-kivy To use its test tools, you can install it with the following command: ```sh -pip install headless-kivy[dev] +pip install headless-kivy[test] ``` ## 🛠 Usage @@ -31,9 +37,13 @@ pip install headless-kivy[dev] setup_headless( width=240, height=240, + bandwidth_limit=1000000, # number of pixels per second + bandwidth_limit_window=.1, # allow bandwidth_limit x bandwidth_limit_window pixels to be transmitted in bandwidth_limit_window seconds + bandwidth_limit_overhead=1000, # each draw command, regardless of the size, has equivalent of this many pixels of cost in bandwidth is_debug_mode=False, - display_class=ST7789, - double_buffering=True, + rotation=1, # gets multiplied by 90 degrees + flip_horizontal=True, + double_buffering=True, # let headless kivy generate the next frame while the previous callback is still running ) ``` @@ -80,6 +90,18 @@ and debugging purposes. It always runs in a new thread, the previous thread is provided so that it can call its `join` if desired. +#### `bandwidth_limit` + +Maximum bandwidth usage in pixels per second, no limit if set to 0. + +#### `bandwidth_limit_window` + +Length of the time window in seconds to check the bandwidth limit. + +#### `bandwidth_limit_overhead` + +The overhead of each draw command in pixels, regardless of its size. + #### `width` The width of the display in pixels. diff --git a/headless_kivy/_debug.py b/headless_kivy/_debug.py index 3736e23..16fa2a7 100644 --- a/headless_kivy/_debug.py +++ b/headless_kivy/_debug.py @@ -65,20 +65,20 @@ def render_debug_info( for rect in regions: self.update_region_seed = (self.update_region_seed + 1) % 3 data[ - rect[1] : rect[3], rect[0] : rect[2], + rect[1] : rect[3], :, ] = ( data[ - rect[1] : rect[3], rect[0] : rect[2], + rect[1] : rect[3], :, ] * 0.5 ).astype(np.uint8) data[ - rect[1] : rect[3], rect[0] : rect[2], + rect[1] : rect[3], [(rect[0] + rect[1] + self.update_region_seed) % 7 % 3, 3], ] += 127 if config.is_debug_mode(): diff --git a/headless_kivy/config.py b/headless_kivy/config.py index 07137f4..f355be4 100644 --- a/headless_kivy/config.py +++ b/headless_kivy/config.py @@ -40,11 +40,11 @@ class SetupHeadlessConfig(TypedDict): callback: `Callback` The callback function that will render the data to the screen. bandwidth_limit: `int`, optional - Maximum bandwidth limit in pixels per second, no limit if set to 0. + Maximum bandwidth usage in pixels per second, no limit if set to 0. bandwidth_limit_window: `float`, optional - Length of the window in seconds to check the bandwidth limit. + Length of the time window in seconds to check the bandwidth limit. bandwidth_limit_overhead: `int`, optional - Bandwidth overhead of each draw regardless of the region size. + The overhead of each draw command in pixels, regardless of its size. width: `int`, optional The width of the display in pixels. height: `int`, optional