3 files changed, 58 insertions, 0 deletions

diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md
index 5f3095198..d106d3d13 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);
 
diff --git a/drivers/oled/oled_driver.c b/drivers/oled/oled_driver.c
index f1990567f..bbf010a09 100644
--- a/drivers/oled/oled_driver.c
+++ b/drivers/oled/oled_driver.c
@@ -444,6 +444,14 @@ void oled_pan(bool left) {
     oled_dirty = ~((OLED_BLOCK_TYPE)0);
 }
 
+oled_buffer_reader_t oled_read_raw(uint16_t start_index) {
+    if (start_index > OLED_MATRIX_SIZE) start_index = OLED_MATRIX_SIZE;
+    oled_buffer_reader_t ret_reader;
+    ret_reader.current_element = &oled_buffer[start_index];
+    ret_reader.remaining_element_count = OLED_MATRIX_SIZE - start_index;
+    return ret_reader;
+}
+
 void oled_write_raw_byte(const char data, uint16_t index) {
     if (index > OLED_MATRIX_SIZE) index = OLED_MATRIX_SIZE;
     if (oled_buffer[index] == data) return;
diff --git a/drivers/oled/oled_driver.h b/drivers/oled/oled_driver.h
index 5c21c0cc8..7ec00d66a 100644
--- a/drivers/oled/oled_driver.h
+++ b/drivers/oled/oled_driver.h
@@ -154,6 +154,11 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #    define OLED_I2C_TIMEOUT 100
 #endif
 
+typedef struct __attribute__((__packed__)) {
+    uint8_t  *current_element;
+    uint16_t remaining_element_count;
+} oled_buffer_reader_t;
+
 // OLED Rotation enum values are flags
 typedef enum {
     OLED_ROTATION_0   = 0,
@@ -207,6 +212,10 @@ void oled_write_ln(const char *data, bool invert);
 // Pans the buffer to the right (or left by passing true) by moving contents of the buffer
 void oled_pan(bool left);
 
+// 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);
+
 void oled_write_raw(const char *data, uint16_t size);
 void oled_write_raw_byte(const char data, uint16_t index);