Merge pull request #191 from WildernessLabs/ipixeldisplay

Move display contracts and enums from foundation to contracts

Source/Meadow.Contracts/Peripherals/Displays/ColorMode.cs

@@ -0,0 +1,63 @@
+using System;
+
+namespace Meadow.Peripherals.Displays;
+
+/// <summary>
+/// Enum for Display color mode, defines bit depth and RGB order
+/// </summary>
+[Flags]
+public enum ColorMode : int
+{
+    /// <summary>
+    /// 1-bit color
+    /// </summary>
+    Format1bpp = 1 << 0,
+    /// <summary>
+    /// 2-bit color
+    /// </summary>
+    Format2bpp = 1 << 1,
+    /// <summary>
+    /// 4-bit grayscale
+    /// </summary>
+    Format4bppGray = 1 << 2,
+    /// <summary>
+    /// 4-bit grayscale
+    /// </summary>
+    Format4bppIndexed = 1 << 3,
+    /// <summary>
+    /// 8-bit grayscale
+    /// </summary>
+    Format8bppGray = 1 << 4,
+    /// <summary>
+    /// 8-bit color
+    /// </summary>
+    Format8bppRgb332 = 1 << 5,
+    /// <summary>
+    /// 12-bit color
+    /// </summary>
+    Format12bppRgb444 = 1 << 6,
+    /// <summary>
+    /// 15-bit color
+    /// </summary>
+    Format16bppRgb555 = 1 << 7,
+    /// <summary>
+    /// 16-bit color
+    /// </summary>
+    Format16bppRgb565 = 1 << 8,
+    /// <summary>
+    /// 18-bit color
+    /// </summary>
+    Format18bppRgb666 = 1 << 9,
+    /// <summary>
+    /// 24-bit color
+    /// </summary>
+    Format24bppRgb888 = 1 << 10,
+    /// <summary>
+    /// 24-bit color
+    /// </summary>
+    Format24bppGrb888 = 1 << 11,
+    /// <summary>
+    /// 32-bit color
+    /// </summary>
+    Format32bppRgba8888 = 1 << 12,
+}

Source/Meadow.Contracts/Peripherals/Displays/IPixelBuffer.cs

@@ -0,0 +1,112 @@
+namespace Meadow.Peripherals.Displays;
+
+/// <summary>
+/// IPixelBuffer provides a standard interface for
+/// representing the display state of a device capable of
+/// displaying pixels. It specifies methods for performing
+/// common primitive operations on a buffer of pixel data.
+/// 
+/// Conceptually, implementing classes should:
+/// 
+/// 1. Specify a bit depth for pixels
+/// 2. Specify a color mode
+/// 3. Preserve the display state as a byte[] in the PixelBuffer
+/// 4. Optimize primitive drawing methods for the bit depth of pixels
+/// 5. Be abstracted/decoupled from a specific device driver
+/// </summary>
+public interface IPixelBuffer
+{
+    /// <summary>
+    /// The width of the pixel buffer
+    /// </summary>
+    int Width { get; }
+
+    /// <summary>
+    /// The height of the pixel buffer
+    /// </summary>
+    int Height { get; }
+
+    /// <summary>
+    /// The ColorMode of the pixel buffer
+    /// </summary>
+    ColorMode ColorMode { get; }
+
+    /// <summary>
+    /// The BitDepth of the chosen ColorMode
+    /// </summary>
+    int BitDepth { get; }
+
+    /// <summary>
+    /// The number of bytes in this pixel buffer
+    /// </summary>
+    int ByteCount { get; }
+
+    /// <summary>
+    /// The byte array that holds all pixel data
+    /// </summary>
+    byte[] Buffer { get; }
+
+    /// <summary>
+    /// Set the color of the pixel at the provided coordinates
+    /// </summary>
+    /// <param name="x">X coordinate of the pixel: 0,0 at top left</param>
+    /// <param name="y">Y coordinate of the pixel: 0,0 at top left</param>
+    /// <param name="color">The pixel color</param>
+    void SetPixel(int x, int y, Color color);
+
+    /// <summary>
+    /// Get the color of a pixel - may be scaled based on buffer color depth
+    /// </summary>
+    /// <param name="x">X coordinate of the pixel: 0,0 at top left</param>
+    /// <param name="y">Y coordinate of the pixel: 0,0 at top left</param>
+    Color GetPixel(int x, int y);
+
+    /// <summary>
+    /// Invert the color of a pixel at the provided location
+    /// </summary>
+    /// <param name="x">The X coord to invert</param>
+    /// <param name="y">The Y coord to invert</param>
+    void InvertPixel(int x, int y);
+
+    /// <summary>
+    /// Writes another pixel buffer into this buffer.
+    /// </summary>
+    /// <param name="originX">The X origin to start writing</param>
+    /// <param name="originY">The Y origin to start writing</param>
+    /// <param name="buffer">The buffer to write into this buffer</param>
+    /// <returns></returns>
+    void WriteBuffer(int originX, int originY, IPixelBuffer buffer);
+
+    /// <summary>
+    /// Fills the buffer with the provided color
+    /// </summary>
+    /// <param name="color">The color to fill</param>
+    void Fill(Color color);
+
+    /// <summary>
+    /// Fills part of the buffer with the provided color
+    /// </summary>
+    /// <param name="originX">The X coord to start filling</param>
+    /// <param name="originY">The Y coord to start filling</param>
+    /// <param name="width">The width to fill</param>
+    /// <param name="height">The height to fill</param>
+    /// <param name="color">The color to fill</param>
+    void Fill(int originX, int originY, int width, int height, Color color);
+
+    /// <summary>
+    /// Clears the buffer (writes 0s to the byte array)
+    /// </summary>
+    void Clear();
+
+    /// <summary>
+    /// Clears a region of the buffer (writes 0s to the byte array)
+    /// </summary>
+    /// <param name="originX">The X coord to start</param>
+    /// <param name="originY">The Y coord to start</param>
+    /// <param name="width">The width of the region to clear</param>
+    /// <param name="height">The height of the region to clear</param>
+    void Clear(int originX, int originY, int width, int height)
+    {
+        Fill(originX, originY, width, height, Color.Black);
+    }
+}

Source/Meadow.Contracts/Peripherals/Displays/IPixelDisplay.cs

@@ -0,0 +1,124 @@
+using System;
+
+namespace Meadow.Peripherals.Displays;
+
+/// <summary>
+/// Represents a pixel based graphics display
+/// </summary>
+public interface IPixelDisplay : IDisplay
+{
+    /// <summary>
+    /// The currently set color mode for the display
+    /// </summary>
+    public ColorMode ColorMode { get; }
+
+    /// <summary>
+    /// The Color mode supported by the display
+    /// </summary>
+    public ColorMode SupportedColorModes { get; }
+
+    /// <summary>
+    /// Is the color mode supported on this display
+    /// </summary>
+    /// <param name="mode">The color mode</param>
+    public bool IsColorTypeSupported(ColorMode mode)
+    {
+        return (SupportedColorModes | mode) != 0;
+    }
+
+    /// <summary>
+    /// Set the color mode for the display
+    /// </summary>
+    public void SetColorMode(ColorMode mode)
+    {
+        throw new ArgumentException("Display does not support color mode changes");
+    }
+
+    /// <summary>
+    /// Width of the display in pixels
+    /// </summary>
+    public int Width { get; }
+
+    /// <summary>
+    /// Height of the display in pixels
+    /// </summary>
+    public int Height { get; }
+
+    /// <summary>
+    /// Provide a buffer that matches this display's color depth, height, and width
+    /// This should be the buffer that is sent to the device when Show is called
+    /// </summary>
+    public IPixelBuffer PixelBuffer { get; }
+
+    /// <summary>
+    /// The color to draw when a pixel is enabled
+    /// </summary>
+    public Color EnabledColor => Color.White;
+
+    /// <summary>
+    /// The color to draw when a pixel is disabled
+    /// </summary>
+    public Color DisabledColor => Color.Black;
+
+    /// <summary>
+    /// Transfer the contents of the buffer to the display
+    /// </summary>
+    public void Show();
+
+    /// <summary>
+    /// Transfer part of the contents of the buffer to the display
+    /// bounded by left, top, right and bottom
+    /// </summary>
+    public void Show(int left, int top, int right, int bottom);
+
+    /// <summary>
+    /// Clear the display
+    /// </summary>
+    /// <param name="updateDisplay">Update the display once the buffer has been cleared when true</param>
+    public void Clear(bool updateDisplay = false);
+
+    /// <summary>
+    /// Clear the display
+    /// </summary>
+    /// <param name="fillColor">The color used to fill the display buffer</param>
+    /// <param name="updateDisplay">Update the display once the buffer has been cleared when true</param>
+    public void Fill(Color fillColor, bool updateDisplay = false);
+
+    /// <summary>
+    /// Clear the display
+    /// </summary>
+    /// <param name="x">x position in pixels</param>
+    /// <param name="y">y position in pixels</param>
+    /// <param name="width">width to fill in pixels</param>
+    /// <param name="height">height to fill in pixels</param>
+    /// <param name="fillColor">The color used to fill the display buffer</param>
+    public abstract void Fill(int x, int y, int width, int height, Color fillColor);
+
+    /// <summary>
+    /// Draw a single pixel at the specified color
+    /// </summary>
+    /// <param name="x">x position in pixels</param>
+    /// <param name="y">y position in pixels</param>
+    /// <param name="color">The Meadow Foundation color of the pixel</param>
+    public abstract void DrawPixel(int x, int y, Color color);
+
+    /// <summary>
+    /// Enable or disable a single pixel (used for 1bpp displays)
+    /// </summary>
+    /// <param name="x">x position in pixels</param>
+    /// <param name="y">y position in pixels</param>
+    /// <param name="enabled">On if true, off if false</param>
+    public abstract void DrawPixel(int x, int y, bool enabled);
+
+    /// <summary>
+    /// Invert the color of a single pixel
+    /// </summary>
+    /// <param name="x">x position in pixels</param>
+    /// <param name="y">y position in pixels</param>
+    public abstract void InvertPixel(int x, int y);
+
+    /// <summary>
+    /// Draw a buffer to the display
+    /// </summary>
+    public abstract void WriteBuffer(int x, int y, IPixelBuffer displayBuffer);
+}

Source/Meadow.Contracts/Peripherals/Displays/IRotatableDisplay.cs

@@ -0,0 +1,18 @@
+namespace Meadow.Peripherals.Displays;
+
+/// <summary>
+/// Represents a display that supports rotation in 90 degree increments
+/// </summary>
+public interface IRotatableDisplay
+{
+    /// <summary>
+    /// Set the rotation of the display
+    /// </summary>
+    /// <param name="rotation">The rotation</param>
+    public void SetRotation(RotationType rotation);
+
+    /// <summary>
+    /// Gets the current display rotation
+    /// </summary>
+    public RotationType Rotation { get; }
+}

Source/Meadow.Contracts/Peripherals/Displays/ITextDisplay.cs

@@ -1,23 +1,23 @@
 namespace Meadow.Peripherals.Displays;
 
 /// <summary>
-/// Defines a Text Display.
+/// Defines a Text Display
 /// </summary>
-public interface ITextDisplay
+public interface ITextDisplay : IDisplay
 {
     /// <summary>
     /// Gets a Display Configuration
     /// </summary>
     TextDisplayConfig DisplayConfig { get; }
 
     /// <summary>
-    /// Writes the specified string on the display.
+    /// Writes the specified string on the display
     /// </summary>
     /// <param name="text">String to display</param>
     void Write(string text);
 
     /// <summary>
-    /// Writes the specified string to the specified line number on the display.
+    /// Writes the specified string to the specified line number on the display
     /// </summary>
     /// <param name="text">String to display.</param>
     /// <param name="lineNumber">Line Number.</param>
@@ -30,13 +30,13 @@ public interface ITextDisplay
     void ClearLines();
 
     /// <summary>
-    /// Clears the specified line of characters on the display.
+    /// Clears the specified line of characters on the display
     /// </summary>
     /// <param name="lineNumber">Line Number</param>
     void ClearLine(byte lineNumber);
 
     /// <summary>
-    /// Set cursor in the specified row and column.
+    /// Set cursor in the specified row and column
     /// </summary>
     /// <param name="column"></param>
     /// <param name="line"></param>

Source/Meadow.Contracts/Peripherals/Displays/RotationType.cs

@@ -0,0 +1,28 @@
+namespace Meadow.Peripherals.Displays;
+
+/// <summary>
+/// Display rotation 
+/// </summary>
+public enum RotationType : int
+{
+    /// <summary>
+    /// Default or normal orientation
+    /// </summary>
+    Default = 0,
+    /// <summary>
+    /// Default or normal orientation
+    /// </summary>
+    Normal = Default,
+    /// <summary>
+    /// Rotated 90 degrees clockwise
+    /// </summary>
+    _90Degrees = 90,
+    /// <summary>
+    /// Rotated 180 degrees clockwise
+    /// </summary>
+    _180Degrees = 180,
+    /// <summary>
+    /// Rotated 270 degrees clockwise
+    /// </summary>
+    _270Degrees = 270
+}