Reword screen drivers for managed initialization, support for low memory (#70)

Author: Ellerbach

README.md

@@ -14,6 +14,51 @@
 | nanoFramework.Graphics | [![Build Status](https://dev.azure.com/nanoframework/nanoFramework.Graphics/_apis/build/status/nanoframework.lib-nanoFramework.Graphics?branchName=master)](https://dev.azure.com/nanoframework/nanoFramework.Graphics/_build/latest?definitionId=57&branchName=master) | [![NuGet](https://img.shields.io/nuget/v/nanoFramework.Graphics.svg?label=NuGet&style=flat&logo=nuget)](https://www.nuget.org/packages/nanoFramework.Graphics/)  |
 | nanoFramework.Graphics (preview) | [![Build Status](https://dev.azure.com/nanoframework/nanoFramework.Graphics/_apis/build/status/nanoframework.lib-nanoFramework.Graphics?branchName=develop)](https://dev.azure.com/nanoframework/nanoFramework.Graphics/_build/latest?definitionId=57&branchName=develop) | [![](https://badgen.net/badge/NuGet/preview/D7B023?icon=https://simpleicons.now.sh/azuredevops/fff)](https://dev.azure.com/nanoframework/feed/_packaging?_a=package&feed=sandbox&package=nanoFramework.nanoFramework.Graphics&protocolType=NuGet&view=overview) |
 
+## Usage
+
+**Important**:
+
+- This library is still work in progress. There may be breaking changes happening while work on this library progresses.
+- So far only SPI interface has been implemented.
+
+Check the [samples](https://github.com/nanoframework/Samples#graphics-for-screens) for more detailed usage.
+
+### Initializing the screen
+
+It is important to understand that the driver will be loaded when the screen routing will be initialized from the managed code. Also keep in mind that most screens are actually smaller than the size the driver is capable of handling, also that the real screen can start at a position that is not the typical origin (0,0).
+
+You **must** initialize the screen before being able to create a bitmap or display anything.
+
+This code snippet works with the ESP32 WROVER KIT pinout, in this case, the screen size matches the driver size:
+
+```csharp
+
+const int backLightPin = 5;
+const int chipSelect = 22;
+const int dataCommand = 21;
+const int reset = 18;
+const int screenWidth = 320;
+const int screenHeight = 240;
+DisplayControl.Initialize(new SpiConfiguration(1, chipSelect, dataCommand, reset, backLightPin), new ScreenConfiguration(0, 0, screenWidth, screenHeight), screenBufferSize);
+```
+
+This code snippet is for a M5 Stick where the screen size is smaller than the driver size and starts an offset position of X=26 and Y=1 coordinate:
+
+```csharp
+int backLightPin = -1; // Not managed thru ESP32 but thru AXP192
+int chipSelect = 5;
+int dataCommand = 23;
+int reset = 18;
+Configuration.SetPinFunction(4, DeviceFunction.SPI1_MISO); // 4 is unused but necessary
+Configuration.SetPinFunction(15, DeviceFunction.SPI1_MOSI);
+Configuration.SetPinFunction(13, DeviceFunction.SPI1_CLOCK);
+DisplayControl.Initialize(new SpiConfiguration(1, chipSelect, dataCommand, reset, backLightPin), new ScreenConfiguration(26, 1, 80, 160), 10 * 1024);
+```
+
+Note that depending on your target, especially for ESP32, you may have to setup the pins. Even if physically not used, the MISO pin **must** be setup to a valid pin.
+
+As you can see it is possible as well not to define the backlight pin. It is the same for the rest pins. Both can be set to -1. Note that in most of the cases, both are connected and needed. In the case of the M5 Stick, the backlight pin is managed thru an AXP192. If you don't switch on the backlight pin, your screen will always be black. It is important to check how this pin can be switched on.
+
 ## Feedback and documentation
 
 For documentation, providing feedback, issues and finding out how to contribute please refer to the [Home repo](https://github.com/nanoframework/Home).

nanoFramework.Graphics.sln

@@ -1,4 +1,3 @@
-
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 16
 VisualStudioVersion = 16.0.30011.22

nanoFramework.Graphics/Presentation/Media/Color.cs

@@ -52,6 +52,17 @@ public static byte GetBValue(Color color)
         {
             return (byte)(((uint)color >> 16) & 0xff);
         }
+
+        /// <summary>
+        /// Converts color into a 16bit representation.
+        /// </summary>
+        /// <param name="color">A color.</param>
+        /// <returns>a 16 bit encoded representation.</returns>
+        public static ushort To16Bpp(Color color)
+        {
+            // 16 bit colour  RRRRRGGGGGGBBBBB mode 565
+            return (ushort)((((uint)color & 0xFF0000) >> 19) | ((((uint)color & 0x00FF00) >> 10) << 5) | (((uint)color & 0xFF) >> 3) << 11);
+        }
     }
 
     /// <summary>

nanoFramework.Graphics/Primitive/DisplayControl.cs

@@ -4,6 +4,8 @@
 // See LICENSE file in the project root for full license information.
 //
 
+using nanoFramework.Presentation.Media;
+using System.Diagnostics;
 using System.Runtime.CompilerServices;
 
 namespace nanoFramework.UI
@@ -14,19 +16,19 @@ namespace nanoFramework.UI
     public enum DisplayOrientation : int
     {
         /// <summary>
-        ///     Portrait
+        /// Portrait
         /// </summary>
         PORTRAIT,
         /// <summary>
-        ///     Portrait 180
+        /// Portrait 180
         /// </summary>
         PORTRAIT180,
         /// <summary>
-        ///     Landscape
+        /// Landscape
         /// </summary>
         LANDSCAPE,
         /// <summary>
-        ///     Landscape 180
+        /// Landscape 180
         /// </summary>
         LANDSCAPE180
     };
@@ -36,23 +38,70 @@ public enum DisplayOrientation : int
     /// </summary>
     public static class DisplayControl
     {
-        static Bitmap _fullScreen = null;
+        static private Bitmap _fullScreen = null;
+        static private ushort[] _point = new ushort[1];
+
+        /// <summary>
+        /// The maximum buffer size for Bitmap in bytes.
+        /// </summary>
+        public static uint MaximumBufferSize { get; internal set; }
+
+        /// <summary>
+        /// Initializes the screen for use with Spi configuration.
+        /// </summary>
+        /// <param name="spi">Spi configuration.</param>
+        /// <param name="screen">A screen configuration.</param>
+        /// <param name="bufferSize">The desired buffer size allocation, 0 for default.</param>
+        /// <remarks>You may have to configure the pins properly for the Spi configuration to be valid before initializing your screen.</remarks>
+        /// <returns>The maximum buffer size possible allocation in bytes.</returns>
+        public static uint Initialize(SpiConfiguration spi, ScreenConfiguration screen, uint bufferSize = 20 * 1024)
+        {
+            MaximumBufferSize = NativeInitSpi(spi, screen, bufferSize);
+            return MaximumBufferSize;
+        }
+
+        /// <summary>
+        /// Initializes the screen to use with I2C configuration.
+        /// </summary>
+        /// <param name="i2c"></param>
+        /// <param name="screen">A screen configuration.</param>
+        /// <param name="bufferSize">The desired buffer size allocation, 0 for default.</param>
+        /// <remarks>You may have to configure the pins properly for the I2C configuration to be valid before initializing your screen.</remarks>
+        /// <returns>The maximum buffer size possible allocation in bytes.</returns>
+        public static uint Initialize(I2cConfiguration i2c, ScreenConfiguration screen, uint bufferSize = 20 * 1024)
+        {
+            MaximumBufferSize = NativeInitI2c(i2c, screen, bufferSize);
+            return MaximumBufferSize;
+        }
 
         /// <summary>
         /// Returns a bitmap the size of the current display. 
         /// </summary>
+        /// <remarks>Please make sure you check if you have enough memory with IsFullScreenBufferAvailable.
+        /// If you don't have enough, the BitMap won't get initialized and will be null.</remarks>
         public static Bitmap FullScreen
         {
             get
             {
+                if (!IsFullScreenBufferAvailable)
+                {
+                    return null;
+                }
+
                 if (_fullScreen == null)
                 {
                     _fullScreen = new Bitmap(ScreenWidth, ScreenHeight);
                 }
+
                 return _fullScreen;
             }
         }
 
+        /// <summary>
+        /// True if a full size buffer is available
+        /// </summary>
+        public static bool IsFullScreenBufferAvailable => ScreenWidth * ScreenHeight * 3 / 8 <= MaximumBufferSize; // Internal bit per pixel is 3 bytes
+
         /// <summary>
         /// The screens number of pixels for the longer side.
         /// </summary>
@@ -125,11 +174,62 @@ static public bool ChangeOrientation(DisplayOrientation Orientation)
                 _fullScreen.Dispose();
                 _fullScreen = null;
             }
+
             return result;
         }
 
+        /// <summary>
+        /// Write a point directly on the screen.
+        /// </summary>
+        /// <param name="x">The x coordinate.</param>
+        /// <param name="y">The y coordinate.</param>
+        /// <param name="color">The 16 bits color.</param>
+        public static void WritePoint(ushort x, ushort y, ushort color)
+        {
+            _point[0] = color;
+            Write(x, y, 1, 1, _point);
+        }
+
+        /// <summary>
+        /// Clears the screen.
+        /// </summary>
+        [MethodImplAttribute(MethodImplOptions.InternalCall)]
+        public extern static void Clear();
+
+        /// <summary>
+        /// Directly write in the screen at coordinate x,y a width,height buffer of 16 bits colors.
+        /// </summary>
+        /// <param name="x">The x coordinate.</param>
+        /// <param name="y">The y coordinate.</param>
+        /// <param name="width">The width of the area to display.</param>
+        /// <param name="height">The height of the area to display.</param>
+        /// <param name="colors">A 16 bits color</param>
+        [MethodImplAttribute(MethodImplOptions.InternalCall)]
+        public extern static void Write(ushort x, ushort y, ushort width, ushort height, ushort[] colors);
+
+        /// <summary>
+        /// Directly write on the screen a text at coordinate x,y a width,height with a background and foreground color.
+        /// </summary>
+        /// <param name="text">The text to write.</param>
+        /// <param name="x">The x coordinate.</param>
+        /// <param name="y">The y coordinate.</param>
+        /// <param name="width">The width of the area to display.</param>
+        /// <param name="height">The height of the area to display.</param>
+        /// <param name="font">The font to use.</param>
+        /// <param name="foreground">Foreground color.</param>
+        /// <param name="background">Background color.</param>
+        [MethodImplAttribute(MethodImplOptions.InternalCall)]
+        public extern static void Write(string text, ushort x, ushort y, ushort width, ushort height, Font font, Color foreground, Color background);
+
         [MethodImplAttribute(MethodImplOptions.InternalCall)]
         private extern static bool NativeChangeOrientation(DisplayOrientation Orientation);
+
+        [MethodImplAttribute(MethodImplOptions.InternalCall)]
+        private extern static uint NativeInitSpi(SpiConfiguration spi, ScreenConfiguration screen, uint bufferSize);
+
+        [MethodImplAttribute(MethodImplOptions.InternalCall)]
+        private extern static uint NativeInitI2c(I2cConfiguration i2c, ScreenConfiguration screen, uint bufferSize);
+
     }
 }
 

nanoFramework.Graphics/Primitive/DisplayInterfaceConfig.cs

@@ -0,0 +1,143 @@
+using System;
+
+namespace nanoFramework.UI
+{
+    /// <summary>
+    /// The Spi configuration for the scressn
+    /// </summary>
+    public struct SpiConfiguration
+    {
+        private byte _spiBus;
+        private int _chipSelect;
+        private int _dataCommand;
+        private int _reset;
+        private int _backLight;
+
+        /// <summary>
+        /// Creates a Spi configuration.
+        /// </summary>
+        /// <param name="spiBus">Spi bus.</param>
+        /// <param name="chipselect">Chip select.</param>
+        /// <param name="dataCommand">Data command.</param>
+        /// <param name="reset">Reset.</param>
+        /// <param name="backLight">Back light.</param>
+        public SpiConfiguration(byte spiBus, int chipselect, int dataCommand, int reset, int backLight)
+        {
+            _spiBus = spiBus;
+            _chipSelect = chipselect;
+            _dataCommand = dataCommand;
+            _reset = reset;
+            _backLight = backLight;
+        }
+
+        /// <summary>Z
+        /// Spi bus.
+        /// </summary>
+        public byte SpiBus { get => _spiBus; set => _spiBus = value; }
+
+        /// <summary>
+        /// Chip select.
+        /// </summary>
+        public int ChipSelect { get => _chipSelect; set => _chipSelect = value; }
+
+        /// <summary>
+        /// Data command.
+        /// </summary>
+        public int DataCommand { get => _dataCommand; set => _dataCommand = value; }
+
+        /// <summary>
+        /// Reset.
+        /// </summary>
+        public int Reset { get => _reset; set => _reset = value; }
+
+        /// <summary>
+        /// Back light
+        /// </summary>
+        public int BackLight { get => _backLight; set => _backLight = value; }
+    }
+
+    /// <summary>
+    /// I2C configuration.
+    /// </summary>
+    public struct I2cConfiguration
+    {
+        private byte _i2cBus;
+        private byte _address;
+        private bool _fastMode;
+
+        /// <summary>
+        /// Creates an I2C configuration.
+        /// </summary>
+        /// <param name="i2cBus">I2C bus.</param>
+        /// <param name="address">Address.</param>
+        /// <param name="fastMode">True for I2C fast mode.</param>
+        public I2cConfiguration(byte i2cBus, byte address, bool fastMode)
+        {
+            _i2cBus = i2cBus;
+            _address = address;
+            _fastMode = fastMode;
+        }
+
+        /// <summary>
+        /// I2C bus.
+        /// </summary>
+        public byte I2cBus { get => _i2cBus; set => _i2cBus = value; }
+
+        /// <summary>
+        /// Address.
+        /// </summary>
+        public byte Address { get => _address; set => _address = value; }
+
+        /// <summary>
+        /// True for I2C fast mode.
+        /// </summary>
+        public bool FastMode { get => _fastMode; set => _fastMode = value; }
+    }
+
+    /// <summary>
+    /// The screen configuration in the driver.
+    /// </summary>
+    public struct ScreenConfiguration
+    {
+        private ushort _x;
+        private ushort _y;
+        private ushort _width;
+        private ushort _height;
+
+        /// <summary>
+        /// Creates a screen configuration.
+        /// </summary>
+        /// <param name="x">The x position the screen starts in the driver.</param>
+        /// <param name="y">The y position the screen starts in the driver.</param>
+        /// <param name="width">The width of the screen starts in the driver.</param>
+        /// <param name="height">The height of the screen starts in the driver.</param>
+        public ScreenConfiguration(ushort x, ushort y, ushort width, ushort height)
+        {
+            _x = x;
+            _y = y;
+            _width = width;
+            _height = height;
+        }
+
+        /// <summary>
+        /// The x position the screen starts in the driver.
+        /// </summary>
+        public ushort X { get => _x; set => _x = value; }
+
+        /// <summary>
+        /// The y position the screen starts in the driver.
+        /// </summary>
+        public ushort Y { get => _y; set => _y = value; }
+
+        /// <summary>
+        /// The width of the screen starts in the driver.
+        /// </summary>
+        public ushort Width { get => _width; set => _width = value; }
+
+        /// <summary>
+        /// The height of the screen starts in the driver.
+        /// </summary>
+        public ushort Height { get => _height; set => _height = value; }
+
+    }
+}

nanoFramework.Graphics/Properties/AssemblyInfo.cs

@@ -11,7 +11,7 @@
 
 ////////////////////////////////////////////////////////////////
 // update this whenever the native assembly signature changes //
-[assembly: AssemblyNativeVersion("100.0.0.2")]
+[assembly: AssemblyNativeVersion("100.0.0.3")]
 ////////////////////////////////////////////////////////////////
 
 // Setting ComVisible to false makes the types in this assembly not visible