summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorRichard <rich@brickbots.com>2020-08-24 07:40:45 -0700
committerJames Young <18669334+noroadsleft@users.noreply.github.com>2020-08-29 14:30:02 -0700
commitfa6cf8572736f16d2fe076c21546d08f258e145f (patch)
tree55809744c500176384f0550c9c2db629979a1d9f /docs
parent92385b3fb617326b129609726020453c8949c7f8 (diff)
Add a method to read the OLED display buffer from user space (#8777)
* Adding extern and declaration * Change to mediated buffer read * Adding raw byte read * Restore write raw... D'Oh * Working struct return * Pack that struct * Remove conditional packing and add example to docs * Cleanup tab/spaces * Update docs/feature_oled_driver.md Prettify formatting * Update drivers/oled/oled_driver.h Prettify formatting
Diffstat (limited to 'docs')
-rw-r--r--docs/feature_oled_driver.md41
1 files changed, 41 insertions, 0 deletions
diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md
index 5f3095198f..d106d3d13e 100644
--- a/docs/feature_oled_driver.md
+++ b/docs/feature_oled_driver.md
@@ -72,6 +72,43 @@ static void render_logo(void) {
}
```
+## Buffer Read Example
+For some purposes, you may need to read the current state of the OLED display
+buffer. The `oled_read_raw` function can be used to safely read bytes from the
+buffer.
+
+In this example, calling `fade_display` in the `oled_task_user` function will
+slowly fade away whatever is on the screen by turning random pixels black over
+time.
+```c
+//Setup some mask which can be or'd with bytes to turn off pixels
+const uint8_t single_bit_masks[8] = {127, 191, 223, 239, 247, 251, 253, 254};
+
+static void fade_display(void) {
+ //Define the reader structure
+ oled_buffer_reader_t reader;
+ uint8_t buff_char;
+ if (random() % 30 == 0) {
+ srand(timer_read());
+ // Fetch a pointer for the buffer byte at index 0. The return structure
+ // will have the pointer and the number of bytes remaining from this
+ // index position if we want to perform a sequential read by
+ // incrementing the buffer pointer
+ reader = oled_read_raw(0);
+ //Loop over the remaining buffer and erase pixels as we go
+ for (uint16_t i = 0; i < reader.remaining_element_count; i++) {
+ //Get the actual byte in the buffer by dereferencing the pointer
+ buff_char = *reader.current_element;
+ if (buff_char != 0) {
+ oled_write_raw_byte(buff_char & single_bit_masks[rand() % 8], i);
+ }
+ //increment the pointer to fetch a new byte during the next loop
+ reader.current_element++;
+ }
+ }
+}
+```
+
## Other Examples
In split keyboards, it is very common to have two OLED displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
@@ -238,6 +275,10 @@ void oled_write_P(const char *data, bool invert);
// Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM
void oled_write_ln_P(const char *data, bool invert);
+// Returns a pointer to the requested start index in the buffer plus remaining
+// buffer length as struct
+oled_buffer_reader_t oled_read_raw(uint16_t start_index);
+
// Writes a string to the buffer at current cursor position
void oled_write_raw(const char *data, uint16_t size);