Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

SenseHat LED matrix text rendering model #2324

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

SenseHat LED matrix text rendering model #2324

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fca48e2
SenseHat LED matrix text rendering model
logicaloud Jun 8, 2024
8b0c81a
refactor text render frame locking
logicaloud Jun 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/devices/SenseHat/SenseHat.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,9 @@ public SenseHat(I2cBus? i2cBus = null, bool shouldDispose = false)
/// <inheritdoc/>
public void Dispose()
{
// Terminate text animation timer if active
LedMatrix?.Terminate();

if (_shouldDispose)
{
_i2cBus?.Dispose();
Expand Down
250 changes: 250 additions & 0 deletions src/devices/SenseHat/SenseHatLedMatrix.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,14 @@
using System.Diagnostics;
using System.Drawing;
using System.Runtime.CompilerServices;
using System.Device.Model;

namespace Iot.Device.SenseHat
{
/// <summary>
/// Base class for SenseHAT LED matrix
/// </summary>
[Interface("SenseHat LED Matrix")]
public abstract class SenseHatLedMatrix : IDisposable
{
/// <summary>
Expand All @@ -32,6 +34,45 @@ public abstract class SenseHatLedMatrix : IDisposable
/// </summary>
protected const int NumberOfPixelsPerColumn = 8;

/// <summary>
/// Lazily intialized pixel font reference. Initialized when rendering text.
/// </summary>
protected SenseHatTextFont? _pixelFont = null;
Copy link
Member

@krwq krwq Jul 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do like the fact that we're extending this to support text scrolling etc but I'd prefer this logic was reusable to any LED matrix. Here is how I'd imagine this would work:

  • this class remains mostly untouched (unless you need to add extra API or whatever to make text work then those changes are ok but nothing directly text related)
  • text scrolling / setting is an abstraction which takes abstract display (or couple of Action/Func for each needed operation)

the usage would be more or less like this (you might have better ideas but this is bare minimum to isolate this utility):

SenseHatLedMatrix matrix = ...;
LedMatrixTextScroller textScroller = new(width, height, (x, y, color) => matrix.DrawPixel(x, y, color));
textScroller.Start();
textScroller.SetText("hello");
textScroller.Stop();
// Start could also happen automatically and Dispose could make it stop - don't care much about specific design choice

Note: I don't expect you to integrate this utility anywhere else (so there is no need to move it outside of SenseHat project but it might be a good idea to do so if you feel like it) but if anyone else asks or tries to add something similar I'll point them in this direction so they can re-use this code. Ideally I'd imagine this utility somewhere next to BdfFont

Copy link
Member

@krwq krwq Jul 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The callback could also draw entire buffer or whatever, pick a design which feels easiest to use from user perspective but is not unreasonably slow - I think for small matrix like this it doesn't matter if you draw by pixel or screen but for larger one by pixel might be a bit too slow but if library is not meant for large screens then that argument goes away - I think reasonably largest screen would be 64x64 so that gives you about 4k calls per 20ms which is around 200k operations per second - that might be good enough for Raspberry Pi 3. If we pick DrawPixel now worst case scenario we can always add extra ctor overload to the scroller in the future with entire screen callback and for existing ctor just translate DrawPixel into DrawBuffer callback (basically you'd wrap user passed callback with your own which utilizes that to draw a screen). If we do reverse it will be much harder to simplify this later and DrawPixel is so much easier to use than DrawBuffer

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "text scroller" in this instance is very simple: It increments a value (in the timer events) that is the horizontal offset position of the pre-rendered text (in SenseHatTextRenderMatrix) from where bits should be copied to the LED matrix display. It may be possible to generalize the use for small, single-line LED displays. Larger displays will probably lead to different design choices. My suggestion would be to possibly add an issue "generalize text rendering and scrolling for single line LED displays" or similar, that could be picked up by someone who has such a device, otherwise there may be a bit of guessing of what is feasible. This pull request could go into a different branch in the mean time, but I think it would not be too much work to refactor for generalization later. I'd be happy to test the generalized solution on SenseHat if/when available.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There was a noticeable difference (smoother scrolling) when setting the pixels with a single Write operation vs multiple SetPixel (Pi 4, 8GB), although I can't recall whether I have visually compared in Debug mode only. Maybe optimization here could also be left until implementation for another LED display is attempted?


/// <summary>
/// Lazily initialized text render state. Initialized when rendering text.
/// </summary>
protected SenseHatTextRenderMatrix? _textRenderMatrix = null;

/// <summary>
/// Text color when rendering text. Null for "no color".
logicaloud marked this conversation as resolved.
Show resolved Hide resolved
/// </summary>
protected Color _textColor = Color.DarkBlue;

/// <summary>
/// Text background color when rendering text. Null for "no color".
logicaloud marked this conversation as resolved.
Show resolved Hide resolved
/// </summary>
protected Color _textBackgroundColor = Color.Black;

/// <summary>
/// Text rotation, counterclockwise.
/// </summary>
protected SenseHatTextRotation _textRotation = SenseHatTextRotation.Rotate_0_Degrees;

/// <summary>
/// Text scroll speed when the rendered text does not fit the 8x8 LED matrix
/// </summary>
protected double _textScrollPixelsPerSecond = 1;

/// <summary>
/// Timer used for text animation (scrolling). Lazily initialized as required.
/// </summary>
protected System.Timers.Timer? _textAnimationTimer = null;

// Lock object to prevent i2c disposal during render.
// "Terminate" must be called for clean termination of text animation.
private object _lockTextRender = new();

/// <summary>
/// Constructs SenseHatLedMatrix instance
/// </summary>
Expand Down Expand Up @@ -81,12 +122,14 @@ public static int PositionToIndex(int x, int y)
/// Write colors to the device
/// </summary>
/// <param name="colors">Array of colors</param>
[Command]
public abstract void Write(ReadOnlySpan<Color> colors);

/// <summary>
/// Fill LED matrix with a specific color
/// </summary>
/// <param name="color">Color to fill the device with</param>
[Command]
public abstract void Fill(Color color = default(Color));

/// <summary>
Expand All @@ -95,9 +138,216 @@ public static int PositionToIndex(int x, int y)
/// <param name="x">X coordinate</param>
/// <param name="y">Y coordinate</param>
/// <param name="color">Color to be set in the specified position</param>
[Command]
public abstract void SetPixel(int x, int y, Color color);

/// <summary>
/// Stop animation effects if active.
/// </summary>
public void Terminate()
{
lock (_lockTextRender)
{
_textRenderMatrix = null;
StopTextAnimationTimer();
}
}

/// <inheritdoc/>
public abstract void Dispose();

/// <summary>
/// Renders text on the LED display.
/// </summary>
/// <param name="text">Text to render. Set to empty string to stop rendering text.</param>
[Command]
public void SetText(string text)
{
if (string.IsNullOrEmpty(text))
{
StopTextAnimationTimer();
Fill(_textBackgroundColor);
return;
}

if (_pixelFont == null)
{
_pixelFont = new SenseHatTextFont();
}

_textRenderMatrix = _pixelFont.RenderText(text);

RenderText();

StartOrStopTextScrolling();
}

/// <summary>
/// Text color when rendering text.
/// </summary>
[Property]
public Color TextColor
{
get
{
return _textColor;
}
set
logicaloud marked this conversation as resolved.
Show resolved Hide resolved
{
_textColor = value;
RenderText();
}
}

/// <summary>
/// Text background color when rendering text.
/// </summary>
[Property]
public Color TextBackgroundColor
{
get
{
return _textBackgroundColor;
}
set
{
_textBackgroundColor = value;
RenderText();
}
}

/// <summary>
/// Text background color when rendering text.
/// </summary>
[Property]
public double TextScrollPixelsPerSecond
Copy link
Member

@krwq krwq Jul 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note: if you're isolating this class but would like to utilize PropertyAttribute (although I don't ask you to do it in this PR) with the class you'd need to create a wrapper for the TextScroller, i.e. SenseHatLedMatrixTextScroller which would be just a tiny class which allow you to only do text writing (drawing and text scroller shouldn't be used together anyway because it will just look like bogus pixels showing up). For now I'd prefer to not add that though.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The design objective was to keep things simple for the user, and text simply starts scrolling as soon as the there is more than one character to display, using the default TextScrollPixelsPerSecond (1 pixel per second). Separating the scrolling out is a possibility of course. Something to consider for a possible generalization maybe, that it should be possible to retain "automatically scroll long text" for tiny LED displays, which could be a property set in a base class with whatever default makes sense for the LED display at hand.

{
get
{
return _textScrollPixelsPerSecond;
}
set
{
_textScrollPixelsPerSecond = value;
StartOrStopTextScrolling();
}
}

/// <summary>
/// Text rotation, counterclockwise.
/// </summary>
[Property]
public SenseHatTextRotation TextRotation
{
get
{
return _textRotation;
}
set
{
_textRotation = value;
RenderText();
}
}

private void StartOrStopTextScrolling()
{
var renderMatrix = _textRenderMatrix;
int millisecondsPerPixel;
if (renderMatrix == null || renderMatrix.Text.Length == 0 || _textScrollPixelsPerSecond <= 0)
{
millisecondsPerPixel = 0;
}
else
{
millisecondsPerPixel = (int)(1000 / _textScrollPixelsPerSecond);
}

if (millisecondsPerPixel <= 0)
{
StopTextAnimationTimer();
}
else
{
// Calculate the number of milliseconds for one pixel shift
StartTextAnimationTimer((int)millisecondsPerPixel);
}
}

private void StartTextAnimationTimer(int intervalMs)
{
StopTextAnimationTimer();
_textAnimationTimer = new System.Timers.Timer(intervalMs);
_textAnimationTimer.Elapsed += TextAnimationTimer_Elapsed;
_textAnimationTimer.Start();
}

private void StopTextAnimationTimer()
{
if (_textAnimationTimer != null)
{
_textAnimationTimer.Stop();
_textAnimationTimer.Elapsed -= TextAnimationTimer_Elapsed;
_textAnimationTimer.Dispose();
_textAnimationTimer = null;
}
}

private void TextAnimationTimer_Elapsed(object? sender, System.Timers.ElapsedEventArgs e)
Copy link
Member

@krwq krwq Jul 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than timer consider allowing user pick when drawing happens. I.e.:

TextScroller scroller = ....;

while (true)
{
  scroller.DrawFrameIfNecessary(); // note that you should keep track of time separately inside of this method so it doesn't move inconsistently when user calls this at not equal intervals
  // also this could return true/false depending if it actually draw or skipped this frame (because i.e. update wasn't necessary for whatever reason)
  Thread.Sleep(20);
}

this kind of design is usually more flexible and will also help us port this to nano framework which might not have timer implementation.

This design also allows you to easily pause text independently of drawing (you can still draw frame it will just no-op)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And note - if you make this design the way I described above you can still use Timer in your app but it won't be necessary for scroller to have dependency on it - you'd just call DrawFrameIfNecessary inside of the timer callback

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(of course pick better names if you have any idea but ideally it should be straight forward to understand what the method is doing by just looking at the name)

Copy link
Author

@logicaloud logicaloud Jul 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe this could be an extended feature in the future, where the user can toggle between automatic scrolling and manual scrolling? For SenseHat, there is probably not much gain in pausing text, because only one character (or parts of two) are visible at a time, but it would be a good thing to have for longer displays.

{
var renderMatrix = _textRenderMatrix;
if (renderMatrix != null && renderMatrix.Text.Length > 1)
{
renderMatrix.ScrollByOnePixel();
RenderText();
}
}

private void RenderText()
{
lock (_lockTextRender)
logicaloud marked this conversation as resolved.
Show resolved Hide resolved
{
if (_textRenderMatrix == null)
{
return;
}

// Render the 8x8 matrix
for (var x = 0; x < NumberOfPixelsPerColumn; x++)
{
for (var y = 0; y < NumberOfPixelsPerRow; y++)
{
int tx = x;
int ty = y;
switch (_textRotation)
{
case SenseHatTextRotation.Rotate_0_Degrees:
break;
case SenseHatTextRotation.Rotate_90_Degrees:
tx = y;
ty = NumberOfPixelsPerColumn - x - 1;
break;
case SenseHatTextRotation.Rotate_180_Degrees:
tx = NumberOfPixelsPerColumn - x - 1;
ty = NumberOfPixelsPerRow - y - 1;
break;
case SenseHatTextRotation.Rotate_270_Degrees:
tx = NumberOfPixelsPerColumn - y - 1;
ty = x;
break;
}

if (_textRenderMatrix.IsPixelSet(x, y))
{
SetPixel(tx, ty, _textColor);
}
else
{
SetPixel(tx, ty, _textBackgroundColor);
}
}
}
}
}
}
}
93 changes: 93 additions & 0 deletions src/devices/SenseHat/SenseHatTextFont.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System;
using System.Collections.Generic;

namespace Iot.Device.SenseHat
{
/// <summary>
/// 5x8 font adaptor to render font glyphs into the text render matrix.
/// </summary>
public class SenseHatTextFont
{
private const int CharGap = 2;
private const int WordGap = 4; // Reduced space between words
private const int CharHeight = 8;
// Limit length of text when rendering
private const int MaxTextLength = 128;
// Using Font5x8
private Graphics.Font5x8 _font = new Graphics.Font5x8();

/// <summary>
/// Generates a byte matrix containing the bit pattern for the rendered text.
/// </summary>
/// <param name="text">The text to render</param>
/// <returns>The initial renderMatrix including matrix dimension.</returns>
public SenseHatTextRenderMatrix RenderText(string text)
{
if (string.IsNullOrWhiteSpace(text))
{
// nothing to render
return new SenseHatTextRenderMatrix(text, new byte[0], 0);
}

if (text.Length > MaxTextLength)
{
text = "Text is too long";
}

// Calculate "bitmap" width for mono space font
var renderWidth = 0;
foreach (var c in text)
{
if (c == ' ')
{
renderWidth += WordGap;
}
else
{
renderWidth += _font.Width + CharGap;
}
}

// remove last gap
renderWidth -= CharGap;

// Reserve space for the rendered bitmap
var matrix = new byte[renderWidth * CharHeight];

var x = 0;
foreach (var c in text)
{
if (c == ' ')
{
x += WordGap;
continue;
}

_font.GetCharData(c, out var glyph);
for (var cy = 0; cy < _font.Height; cy++)
{
var bitPattern = glyph[cy];
// The letter is right-aligned within the 8x8 matrix; evaluate from bit 3 onward
byte flag = 0x80 >> 3;
for (var cx = 3; cx < 8; cx++)
{
if ((bitPattern & flag) != 0)
{
// Set value to 1 to indicate that a pixel should be "on".
matrix[x + cx - 3 + cy * renderWidth] = 1;
}

flag >>= 1;
}
}

x += _font.Width + CharGap;
}

return new SenseHatTextRenderMatrix(text, matrix, renderWidth);
}
}
}
Loading