Add some direct screen buffer writer methods to SSD13xx (#223)

Author: SandorDobos

devices/Ssd13xx/README.md

@@ -27,3 +27,61 @@ The following connection types are supported by this binding.
 
 - [X] I2C
 - [ ] SPI
+
+## Usage notes
+
+There are two groups of drawing methods.
+
+1. Various specialized drawing methods allowing to draw on screen pixel-by-pixel, like:
+    - ````DrawPixel(...)````: draws one pixel
+    - ````DrawHorizontalLine(...)````: draws a horizontal line
+    - ````DrawVerticalLine(...)````: draws a vertical line
+    - ````DrawFilledRectangle(...)````: draws a filled rectangle
+    - ````DrawBitmap(...)````: draws a bitmap
+    - ````DrawString(...)````: draws a string with preset font
+    
+    Using these methods you do not need to care about any technique the driver uses to display 
+    your drawing instructions.
+   
+2. Methods allowing to modify screen content by blocks of internal representation (screen buffer), like:
+    - ````DrawDirectAligned(...)````: overwrites screen buffer with given content
+    - ````ClearDirectAligned(...)````: clears out (with 0x00) given part of screen buffer
+    
+    These methods allow faster (~100 times) display access but with some constraints. 
+    - bitmaps handed over here must be in appropriate format (see SSD13xx docs for "GDDRAM" and "Horizontal addressing mode").
+    - no bit operations occure with existing buffer data (with pixels drawn via other means), the new data will overwrite the pixels "below" newly drawed content.
+    - the "y" coordinate and the bitmap height must be byte aligned with screen buffer (again, see above docs)
+
+The use of two groups can be freely mixed (e.g. display text via ````DrawString(...)```` and displaying an image below via ````DrawDirectAligned(...)````)
+
+Examples for 1. can be found in ````samples```` folder.
+
+Example for 2. follows here.
+
+````csharp
+// There are superb online helpers like the one below which are able to
+// create an appropriate byte array from an image in code use ready format.
+// https://www.mischianti.org/images-to-byte-array-online-converter-cpp-arduino/
+// On the site above use these settings to get bytes needed here:
+// - "plain bytes"
+// - "vertical - 1 bit per pixel"
+var buffer = new byte[] { ... }; 
+var width = 16;
+var height = 16;
+
+// instantiation example
+var ssd1306 = new Ssd1306(
+    I2cDevice.Create(
+        new I2cConnectionSettings(
+            1, 
+            Ssd1306.DefaultI2cAddress, 
+            I2cBusSpeed.FastMode)), 
+    Ssd13xx.DisplayResolution.OLED128x64);
+
+// this line sends the image data to the screen
+ssd1306.DrawDirectAligned(x, y, width, height, buffer);
+
+// this one wipes its place to blank
+ssd1306.ClearDirectAligned(x, y, width, height);
+
+````

devices/Ssd13xx/Ssd13xx.cs

@@ -145,6 +145,72 @@ protected SpanByte SliceGenericBuffer(int start, int length)
             return _genericBuffer;
         }
 
+        /// <summary>
+        /// Copies buffer content directly to display buffer.
+        /// Y and height must be byte aligned because buffer will 
+        /// be copied without any logical operations on existing content.
+        /// </summary>
+        /// <param name="x">The x coordinate on the screen.</param>
+        /// <param name="y">The y coordinate on the screen.</param>
+        /// <param name="width">Width of buffer content in pixels.</param>
+        /// <param name="height">Height of buffer content in pixels.</param>
+        /// <param name="buffer">Data to copy. Buffer size must be equal to height * width / 8.</param>
+        public void DrawDirectAligned(int x, int y, int width, int height, byte[] buffer)
+        {
+            if ((y % 8) != 0)
+            {
+                throw new ArgumentException("Y must be aligned to byte boundary.");
+            }
+            if ((height % 8) != 0)
+            {
+                throw new ArgumentException("Height must be aligned to byte boundary.");
+            }
+
+            var dataHeightInBytes = height / 8;
+            if ((dataHeightInBytes * width) != buffer.Length)
+            {
+                throw new ArgumentException("Width and height do not match the bitmap size.");
+            }
+
+            var genericBufferIdx = y / 8 * Width + x;
+            var srcIdx = 0;
+            for (int i = 0; i < dataHeightInBytes; i++)
+            {
+                Array.Copy(buffer, srcIdx, _genericBuffer, genericBufferIdx, width);
+                srcIdx += width;
+                genericBufferIdx += Width;
+            }
+        }
+
+        /// <summary>
+        /// Clears portion of display via writing 0x00 directly to display buffer.
+        /// Y and height must be byte aligned because bytes will 
+        /// be written without any logical operations on existing content.
+        /// </summary>
+        /// <param name="x">The x coordinate on the screen.</param>
+        /// <param name="y">The y coordinate on the screen.</param>
+        /// <param name="width">Width of area in pixels.</param>
+        /// <param name="height">Height of area in pixels.</param>
+        public void ClearDirectAligned(int x, int y, int width, int height)
+        {
+            if ((y % 8) != 0)
+            {
+                throw new ArgumentException("Y must be aligned to byte boundary.");
+            }
+            if ((height % 8) != 0)
+            {
+                throw new ArgumentException("Height must be aligned to byte boundary.");
+            }
+
+            var dataHeightInBytes = height / 8;
+            var genericBufferIdx = y / 8 * Width + x;
+            for (int i = 0; i < dataHeightInBytes; i++)
+            {
+                Array.Clear(_genericBuffer, genericBufferIdx, width);
+                genericBufferIdx += Width;
+            }
+        }
+
         /// <summary>
         /// Draws a pixel on the screen.
         /// </summary>