Font Handling

[oclyke]

How Should HyperDisplay Support Fonts?

This is intended to be a discussion about how HyperDisplay should support fonts, prompted by issue #2 and PR #3.

HyperDisplay Philosophy

Above all else the solution to font handling in HD should not conflict with the design philosophy. The primary concerns of HD are:

• Portability
• Independence (decoupled)
• General
• Extensible

Portability
HyperDisplay shall be written in standard C++ that can be easily ported and compiled on the majority of build systems. It shall make no special accommodations for particular host platforms within the source code (however it may provide the extensible ability to do so in a platform-agnostic way)

Independence
HyperDisplay shall be decoupled from other problem spaces. The intent is first and foremost to provide a suite of common graphical functions with great portability and extensibility. An exceptionally strong argument must be made for including any additional / extraneous features such as user input handling or image processing. The other side of that coin is that HD should be designed to easily interface with other libraries that do handle those functionalities.

Generality
Within reasonable limits HyperDisplay shall provide the most general solution to the problem. It is acceptable to provide a specialized capability as a subset of a generalized capability. For example a monochrome line with a fixed width is a specialized form of a general line. The generalized line, with color sequence and width options, is the preferred solution.

Extensibility
Tightly related to generality -- HyperDisplay shall be easy to extend by pairing it with additional libraries and source code. Currently this is where font handling fits best into HD.

Why Support Fonts?

Fonts are sets of graphical icons that are used to display a human language on a screen. Of course the capability to display written language will be desirable in a majority of graphical projects.

Additionally users of a graphics library would rightfully expect it to be easy to show text in their language of choice. If HD were not to support fonts it would not be regarded as a functional package for most applications.

Challenges

Adding font support in a manner that aligns with the goals of HD is no easy task. For example:

• There are nearly unlimited possibilities for what a user might expect from a font. Thousands of languages, thousands of unique styles possible at many different sizes, and even fonts that are entirely original by the user. Making concessions to any limited number of fonts violates the "portability" and "generality" philosophies - not to mention clutters up the codebase.

• There are many possible technologies associated with fonts. One example may be the use of "avr/pgmspace" in the (one and only) default font for HD. This is not portable. Additionally there are a host of advanced features that may be desired in some fonts such as Subpixel Rendering, Font Hinting, and Typographic Ligature. According to the design intent of HD all of these should be possible but none should be required.

• Maintenance of any library is challenging, but in order not to have preference to one font over another there must be a good way for users to share fonts that are compatible with HD. This will come with more associated work.

Open Table

Are there any interested parties that would like input on how fonts are handled in HyperDisplay? If so now is the time to speak up. Let's work together to make this great.

[abenstirling]

Hi there just had a question pertaining to rotating the text. Has that been integrated yet? If not do you have a suggestion how to integrate that feature?

[oclyke]

There is no rotation provided for by the default font. However you could make a custom font that handles rotation.

The difficulty of this could land in two places: either 'pretty easy' TM or 'very hard' (R)

If you want 90 degree rotations that should be easy and I'd recommend copying the default font (as a starting point). You'll have to modify at least

1. Which direction (x or y) is incremented by the character width (and the sign of that increment)
2. The mapping of how the character is drawn to the screen. (So that rows becomes columns and vice-versa)

There should be some custom font examples. I will try to find the links.

If you want any arbitrary rotation that will be hard because you'll have to re-implement how characters are drawn (how do you decide which pixels to light up?) as well as how to move the next character location (current framework assumes you will move in only x and y directions by integer amounts. (Currently you can move in both x and y at the same time if you want, but the smallest diagonal step is (1,1) and you might end up wanting finer control than that)

[abenstirling]

Well i was planning on having the display vertical, so I guess the solution would have to be the ladder... Thanks for the quick response and information, I will publish the code when finished.

[oclyke]

@antevens filed a related issue. ((#5) The main point I got from it was that the failure is too quiet - nothing to tell the user that printing is not supported. I definitely agree that this (nearly) silent failure can be problematic and frustrating.

What's currently in place to warn people:

1. Compiler warnings (unfortunately you have to watch compiler output to see them)
2. Fallback to printing over Serial object. (Probably just adds confusion b/c it does not say anything about being a warning)

Any suggestions on what would be a better warning method?

[antevens]

I presumed that the feature request @oclyke added to the arduino-cli project would eventually address this since it would allow raising exceptions during compilation if a sketch attempts to use features which are not included no?

arduino/arduino-cli#501

[dani0303]

would it be possible if you can post an example of the write function on one of your repos for the hyper display library. I'm an intermediate level kid with experience with arduino and raspi but I'm having difficulty understanding how to write text

[antevens]

Hey Dani,

Perhaps this would help, it's a project I'm working on and it uses hyperdisplay to render text

https://github.com/antevens/dromedary/blob/master/hud/sensors/sensors.ino

[dani0303]

thank you for the quick response. this is what i needed

[antevens]

You're welcome, I should mention that the official library does not have windowZero.clearCharacterArea, that's something I added to my own branch but if you comment it out things should work :)

[oclyke]

@dani0303 I added a (very rough) example to teach more about fonts in HyperDisplay.

Here it is:
Example3_FontHandling - Keep in mind that it doesn't work with any actual displays - it just goes over a theoretical implementation.

TLDR:
Either 1) implement the getCharInfo function or 2) just re-write your won write() function in a derived driver class.

For exmample, if you were using the Transparent Graphical OLED that antevens is using you might do something along the lines of:

// myDisplayWithFont.h
#include "HyperDisplay_UG2856KLBAG01.h"

// Derive a new class that has your own special printing capabilities:
class UG2856KLBAG01_I2C_WITH_MY_FONT : public UG2856KLBAG01_I2C{
private:
protected:
public:
	void getCharInfo(uint8_t character, char_info_t * pchar);	// this would get used by the default HyperDisplay 'write()' function except that this class actually provides its own specialization of 'write()'
	size_t write(uint8_t val); // since you are re-implementing the write function it will be used instead of the default. You have access to all the normal HyperDisplay drawing functions within it

// myDisplayWithFont.cpp
size_t UG2856KLBAG01_I2C_WITH_MY_FONT ::write(uint8_t val){
	// You can write any code you want here to respond to the character 'val'

	if(val == 'O'){
		circle(10, 10, 5, true); // draw a circle when the character 'O' comes through...
	}
}

The beauty of that is that you get to piggy back off the existing driver UG2856KLBAG01_I2C so it should 'just work (tm).'

Have fun! Don't hesitate to ask more questions!