Everything You Should Know About HyperDisplay

Contributors: Liquid Soulder

Using Windows

If you've only tried out the functions that have been presented so far (and haven't done any super-sleuthing in the source code) then you've just put pixels right where they ought to go in terms of the physical screen... Well I'm here to tell you that it doesn't have to be that way!

When we designed HyperDisplay, we wanted to make it better than the other options available for small-ish microcontrollers. One thing that always bugged me was having to write complicated expressions for my X and Y coordinates to account for other things on the screen, particularly when they might move. The solution is to allow things to be drawn in windows. So anything that needs to stay in one position with respect to another element can be grouped into a window, and then that window can be moved around easily.

When using a drawing function, you are drawing into the currently selected window for the display and if left untouched that window is equivalent to the physical hardware of the display so HD feels like any other graphics library.

Window Info Structure

The wind_info_t type contains information about location, text printing, color sequence, and memory.

language:c
  typedef struct window_info{
    hd_hw_extent_t  xMin;                      // FYI window min/max use the hardware frame of reference
    hd_hw_extent_t  xMax;         
    hd_hw_extent_t  yMin;         
    hd_hw_extent_t  yMax;       
    hd_extent_t     cursorX;                  // Where the cursor is currently in window-coordinates
    hd_extent_t     cursorY;                  
    hd_extent_t     xReset;                 
    hd_extent_t     yReset;                  
    char_info_t     lastCharacter;           
    color_t         currentSequenceData;      // The data that is used as the default color sequence
    hd_colors_t     currentColorCycleLength;  
    hd_colors_t     currentColorOffset;       
    bool            buffer;                   // Indicates either buffer or direct mode (direct is default)
    color_t         data;                     
    hd_pixels_t    numPixels;                
    bool            dynamic;                  
  }wind_info_t;                               // Window infomation structure for placing objects on the display 

Window Location Variables

The location variables are specified in terms of the physical hardware coordinates of the display - this is how you set the size and position of the window. When windows don't match the screen dimensions they will restrict drawing to within their bounds so it is OK to present negative or large values as arguments to drawing functions. Additionally, windows are allowed to run off of the screen, in which case pixels drawn off of the hardware will not be shown (so there is no need to worry about incorrect hardware access). The location of the window is specified by:

• xMin
• xMax
• yMin
• yMax

Text Tracking

Next in the list are five parameters that are used to track text. These values are in window coordinates so that (0, 0) is always in the upper-left corner of the window, no matter where on the screen the window is. Variables 'cursorX' and 'cursorY' keep track of where the next character will try to be printed. On the other hand 'xReset' and 'yReset' keep track of where the cursor will be after a reset. Finally 'lastCharacter' is used to keep track of what the previous character was - currently it is used to avoid performing two newlines when a newline needs to wrap around the window.

• cursorX
• cursorY
• xReset
• yReset

• lastCharacter

• You can use setTextCursor( int32_t x0, int32_t y0, wind_info_t * window = NULL); to modify the current cursor location of a given window (current window by default).

• You can use resetTextCursor( wind_info_t * window = NULL); to put the cursor back to the reset location.

Default Color Cycle

Window information structures also keep track of the default color cycle to use if none is given for a drawing function. These three variables are just like those three that can be passed into the drawing functions:

• currentSequenceData
• currentColorCycleLength

• currentColorOffset

• setWindowColorSequence( wind_info_t * wind, color_t data = NULL, hd_colors_t colorCycleLength = 1, hd_colors_t startColorOffset = 0); is used to set the current color cycle for a given window. and

• setCurrentWindowColorSequence( color_t data = NULL, hd_colors_t colorCycleLength = 1, hd_colors_t startColorOffset = 0); will set the current color cycle for the current window.

Buffering

The last job of the window information structure is to hold information about buffering, which we will discuss in the next section so sit tight.

The best way to learn about the windows feature of HyperDisplay is to try it out, but here's an incomplete list of things you can do:

• Simplify drawing by using a default color
• Create simple animations of complex arrangements
• Overlay text onto images
• Create easier GUIs

Characters

HyperDisplay comes with a default font but like everything else in HD it is totally customizable by YOU! When you call a 'print' function (they are just like the normal Arduino print functions) it in turn calls a 'write' function for each character that is handled by HyperDisplay. In 'write()' hyperdisplay uses a char_info_t object to figure out what to do next, such as show the character, skip it, or cause a newline. Additionally the object describes how to construct the character. To get the information for the character information structure HD uses a function called 'getCharInfo().'

• virtual void getCharInfo( uint8_t character, char_info_t * pchar);

By rewriting this function you can cause any symbol to be printed out for any character that might be requested, as long as the symbol can be drawn in a rectangular area. To implement the function you will need to fill out the char_info_t object that the 'pchar' pointer points to with the information that you want.

A full example of creating your own font doesn't exist yet but may be added in the future. If you're feeling brave we'd certainly appreciate a pull request on the HyperDisplay Repo!

language:c
typedef struct character_info{
    color_t             data;                       // The data that is used to fill the character frame
    hd_font_extent_t*   xLoc;                       // x location data relative to the upper left-corner of the character area
    hd_font_extent_t*   yLoc;                       // y location data relative to the upper left-corner of the character area
    hd_font_extent_t    xDim;                       // The maximum value of xLoc
    hd_font_extent_t    yDim;                       // The maximum value of yLoc - also the number of pixels to move down for characters that cause new lines
    hd_pixels_t         numPixels;                  // The number of color_t types that pdata points to
    bool                show;                       // Whether or not to actually show the character
    bool                causesNewline;              // This indicates if the given chracter is meant to cause a newline
}char_info_t;                               // Character information structure for placing pixels in a window

Windowed Drawing Output from TFT Examples

Okay, windows are neat and all but it's a bummer that they don't have any memory of what was drawn in them, right? Actually they can! Read on to figure that one out.