Sming Graphics Library

An asynchronous graphics management library intended for SPI-based displays. See the Basic Graphics sample application for demonstration of how to use it.

For a discussion about multitasking and how Sming works, see Multitasking.

Getting started

On first use several required python modules must be installed. Try building a sample application:

cd $SMING_HOME
make fetch Graphics
cd Libraries/Graphics/samples/Basic_Graphics
make python-requirements
make

If you get errors relating to tkinter or TkImage then additional system packages may be required.

Debian/Ubuntu:

sudo apt install python3-tk

Fedora:

sudo dnf install python3-tkinter python3-pillow-tk

MacOS:

brew install python-tk

Graphic Editor

This library contains a basic layout editor which may be useful regardless of which graphics library is being used. See Graphical Editor for further details.

Virtual Screen

This is a display device for use by the Host Emulator. The ‘display’ is a python application which communicates with the Sming Graphics::Display::Virtual display driver using a TCP socket. Graphics processing is handled using SDL2.

To start the virtual screen server type make virtual-screen from your project directory. The default TCP port is 7780. If you need to change this, use:

make virtual-screen VSPORT=7780

The screen server’s IP address is shown in the caption bar. Build and run your project in host mode as follows:

make SMING_ARCH=Host
make run VSADDR=192.1.2.3

Some definitions

Graphics::Object

Defines a specific graphical item, such as a line, circle or image.

Graphics::SceneObject

List of objects describing the components of a displayed image (line, rectangle, circle, image, text, etc.) Also contains a list of assets which allows objects to be re-used within a scene.

Applications use methods such as drawCircle to construct a scene.

Graphics::TextBuilder

Helper object to simplify text layout, handling wrapping, alignment etc.

Graphics::Surface

Rectangular array of pixels representing a display or offscreen bitmap

Graphics::Device

A display device. This provides a single Surface for access to the screen.

Graphics::Renderer

Class which performs background rendering tasks such as drawing a sequence of lines, filling a circle, etc. Each renderer performs a single, specific-task. The renderers are created by the Surface which allows display devices to provide customised implementations.

Graphics::PixelFormat

Describes the format of pixel data required by a Surface.

For example, the ILI9341 display uses RGB565 colours (2 bytes) with the MSB first. It can use other pixel formats (RGB 6:6:6), but this is how the driver sets the display up during initialisation.

Applications do not need to be aware of this, however, and simply express colours in a 32-bit Graphics::Color type. This includes an alpha channel, where 255 is fully opaque and 0 is fully transparent. Conversion is handled in a single step (via Graphics::pack()) so further manipulation (even byte-swapping) is not required by the display driver.

Note that the ILI9341 display has another quirk in that display data is always read back in 24-bit format (18 significant bits). This detail is managed by the display driver which does the conversion during read operations. See Graphics::Surface::readDataBuffer().

Graphics::Blend

This is a virtual base class used to implement custom colour blending operations. Currently only supported for memory images using Graphics::ImageSurface.

Resources

Projects describe which fonts and image resources they require in a JSON resource script.

This is compiled to produce two files:
$(OUT_BASE)/resource.h

A header file describing the resources and containing indices and other lookup tables. Include this ONCE from a source file.

$(OUT_BASE)/resource.bin

Contains image data and font glyph bitmaps. This file can be linked into the application or stored in a file. A better approach is to store it in a dedicated partition as this avoids any filing system overhead. The library accesses this as a stream - applications must call Graphics::Resource::init().

The goal is to enable an optimal set of resources to be produced for the target display from original high-quality assets.

Usage

  1. Create a directory to contain project resources, e.g. resource.

  2. Place any custom images, fonts, etc. into this directory

  3. Create a resource script file, e.g. resource/graphics.rc. See below for details on editing this file.

  4. Add an entry to the project component.mk file:

    RESOURCE_SCRIPT := resource/graphics.rc

  5. Optionally, change the directory where compiled resources are written:

    RESOURCE_OUTPUT := out

The general structure of a resource script is:

{
    "resources": {
        "<type>": {
            "<name>": {
                ...
            }
        }
    }
}

Fonts

A Graphics::Font contains up to four typefaces which correspond to the selected style (normal, italic, bold or bold+italic).

The default font is Graphics::LcdFont, a simple Arduino fixed Adafruit GFX font. Only the ‘normal’ typeface is defined. This is linked into the program image.

All other fonts are loaded from resources. These are parsed from their original format and converted to an efficient internal format based on the Arduino GFX font library.

Resource script entries look like this:

Styles are optional but a font must have at least one typeface.

By default, all ASCII characters from 0x20 (space) to 0x7e (~). The codepoints parameter is a comma-separated list of ranges:

a-z,A-Z,0-9,0x4000-0x4050

This overrides the default and includes only characters and digits, plus unicode characters in the given range. The chars parameter is a simple list of characters, e.g. “Include these chars”. Both lists are combined, de-duplicated and sorted in ascending order.

The following font classes are currently supported:

GFX

Adafruit GFX library font files. These are identified using a “gfx/” prefix for the font files. See resource/fonts/GFX.

Linux

Linux console bitmap fonts. These are in .c format, identified by “linux/” path prefix. See resource/fonts/Linux.

PFI

The “.pfi” file extension is a Portable Font Index. Font glyph bitmap information is contained in an associated .pbm file. See resource/fonts/PFI.

VLW

Smoothed fonts produced by the https://processing.org/ library with a “.vlw” file extension. These are from the TFT_eSPI library. See resource/fonts/VLW.

Note that TTF/OTF scalable vector fonts are supported directly by this library so is the preferred format for new fonts.

freetype
Font type is identified from the file extension:
.ttf

TrueType

.otf

OpenType

.pcf, .pcf.gz

X11 bitmap font

The freetype library supports other types so if required these are easily added.

These fonts have some additional parameters:
“mono”: <True/False>

Whether to produce monochrome (1-bit) or grayscale (8-bit alpha) glyphs. If not specified, defaults to grayscale.

“size”: <Point size of font>

e.g. 16, 14.5

Images

Resource script entries look like this:

"image": {
    "<name>": {
        "format": "<target format>", // RGB565, RGB24 or BMP
        "source": "filename" | "url",
        // Optional list of transformations to apply
        "transform": {
            "width": target width,      // Height will be auto-scaled
            "height": target height,    // Width will be auto-scaled
            "crop": "width,height",     // Crop image to given size from (0, 0)
            "crop": "x,y,width,height", // Crop to selected area of image
            "resize": "width,height",   // Resize image
            "flip": "left_right" | "top_bottom", // Flip the image horizontally or vertically
            "rotate": angle in degrees, // Rotate the image
            "color": { // Convert image to grayscale then colorise it
                "black-color": blackpoint, // Color at blackpoint, e.g. "darkblue": 0
                "mid-color": midpoint,     // OPTIONAL
                "white-color": whitepoint  // Color at whitepoint, e.g. "lightred": 255
            }
        }
    }
}

The Python pillow library is used to read and process images.

The format parameter is intended to produce a raw, un-compressed image compatible with the target display device. Alternatively, specify “BMP” to output a standared .bmp file or omit to store the original image contents un-processed.

Scene construction

Instead of writing directly to the display, applications create a Graphics::SceneObject which will contain a description of the scene to be drawn.

The scene can then be constructed using methods such as drawLine, drawRect, etc. These create an object describing the operation and adds it to the scene.

When the scene is fully described, the application calls the display device’s render method and the rendering begins in the background. A callback function may be provided which will be invoked when the scene has been drawn. The application is free to start creating further scenes, etc.

Note: Scenes are never modified during rendering so can be drawn multiple times if required.

Rendering

This is the process of converting the scene objects into pixels which are then drawn into a Graphics::Surface.

Computation and primitive rendering is done in small, manageable chunks via the task queue. Data is sent to the screen using the appropriate display driver. The ILI9341 driver uses interrupts and hardware (SPI) transfers to do its work.

If the primitive object is simple (e.g. block fill, horizontal/vertical line) then it can be written to the display buffer immediately.

More complex shapes (images, text, diagonal lines, rectangles, triangles, circles, etc.) create a specific Graphics::Renderer instance to do the work.

Transparency (alpha-blending) involves a read-modify-write cycle. The ILI9341 driver can also handle small transparent rectangles (including individual pixels) to assist with line drawing. Larger areas are handled by the appropriate renderer.

Shapes such as rectangles, triangles, circles, etc. are described as a set of connected lines and points which is then iterated through and rendered using fill operations.

The standard Graphics::Surface implementation uses a standard set of renderers to do this work, however these can be overridden by display devices to make use of available hardware features.

Transparency

With sufficient RAM this is a trivial exercise as we just render everything to a memory surface then copy it to the display. For updating small areas of the screen this may be the best approach. However, even a small 240x320 pixel display would require 150kBytes with RGB565.

The more general approach adopted by this library is to read a small block of pixels from the display, combine them with new data as required then write the block back to the display. The Graphics::TextRenderer does this by default. The algorithm also ensures that text can be rendered correctly with filled backgrounds (solid, transparent or custom brushes).

Note

It may not be possible to read from some displays. For example, a small 1-inch display is commonly available using the Graphics::Display::ST7789V controller connected in 4-wire mode, but with the SDO line unconnected internally.

In such cases transparency must be handled by the application using memory surfaces.

Display driver

The ILI9341 display driver buffers requests into a set of hardware-specific commands with associated data. When the request buffer is full, it is sent it to the hardware using the HardwareSPI library. This particular display is typically configured in 4-wire SPI mode which requires an additional GPIO to select between command and data transfers. The driver manages this within its interrupt service routines.

Two request buffers are used so that when one buffer has completed transfer the next can begin immediately. This switch is handled within the interrupt service routine, which also schedules a task callback to the renderer so it may re-fill the first request buffer.

Configuration variables

RESOURCE_SCRIPT

Location of .rc resource script for your project, relative to project directory. Define this in your project’s component.mk file.

RESOURCE_OUTPUT

Path to directory where compiled resources will be written, relative to project directory. Default is project build directory, e.g. out/Rp2040/debug/build.

VSADDR

e.g. 192.168.1.105:7780

TCP address of the virtual screen server application, as shown in the title bar.

VSPORT

default: 7780

Port number to use for virtual screen.

ENABLE_GRAPHICS_DEBUG

default 0 (off)

Set to ‘1’ to enable additional debug output from renderers

ENABLE_GRAPHICS_RAM_TRACKING

default 0 (off)

Set to ‘1’ to enable additional diagnistics to assist with tracking RAM usage

Further work

The list of possible updates to the library is endless. Some thoughts:

Text wrapping

Currently wraps at common punctuation characters. Add options to specify how to break text (character boundaries, word boundaries, break characters, etc.)

Rich Text

Add support for HTML, markdown and other suitable formats. This could be handled by the resource compiler by converting to Graphics::Drawing resources.

Transparent bitmaps

Simple transparency can be handled using Blend Images with per-pixel alpha are not currently implemented. The resource compiler would be extended to support creation of images in ARGB format, with appropriate renderer updates.

Text glyph alignment

Text is drawn using the upper-left corner as reference. It may be desirable to change this, using the baseline or bottom corner instead. This can be added as an option.

Metafiles

Rather than describing scenes in code, we should be able to draw them using other tools and export the layouts as metafiles. Similarly, we might like to export our scenes as metafiles for later re-use.

An example use case is for a ‘scribble’ application, recording pen strokes a touch-enabled screen.

The Drawing API is intended for this use, providing a simple Graphics Description Language (GDL). The provided GDRAW_xxx macros allow embedding of these scripts within programs. This feature is restricted so appropriate only for very simple constructions.

Drawings could be described in textual resource files and compiled during build.

A simple utility program can be written to convert between text and binary GDL formats. Other conversion programs then only need to generate the text equivalent. This will allow the binary format to change as required.

It would be highly desirable to give subroutines textual identifiers. These would be resolved into numeric identifiers for the binary format.

Interactive objects

Drawing buttons, for example, might be done by defining the basic button in GDL.

The button routine could use the following:

pen #0: Inactive surround
pen #1: Active surround
brush #0: Inactive fill
brush #1: Active fill

These slots can be set depending on the desired state by program code. It would be more efficient if GDL can do this based on other parameters, or perhaps by registering callbacks or control objects to make these decisions.

For example, a ButtonObject could use GDL to draw itself and provide callbacks to handle state control, etc. This would also be required for control purposes.

To support use of touch screens we need the ability to query scenes and identify objects at a specific position. Those objects may then be adjusted and redrawn to reflect ‘push’ operations, etc.

For example, we might create a button control by defining a scene describing how the button looks, then create an InteractiveObject containing a reference to that scene plus some kind of user identifier and location of the control ‘hot spot’.

Brushes, Gradient fills, etc.

Rectangular gradient fills can be done by creating a custom ImageObject and drawing it. The object just generates the pixel data as requested according to configured parameters.

This is the basis for Brush objects which would be used to render circles, rounded rectangles and glyphs. That would allow for all sorts of useful effects, including clipping images to other shapes.

Tiling an image can be done by filling a rectangle with an ImageBrush, which deals with coordinate wrapping and returns the corresponding region from a source ImageObject.

Cursors, sprites and priority drawing

Response to user input should be prioritised, such as movement of a cursor or mouse pointer.

Cursors are drawn over everything else. Although some hardware may support cursors directly, for now we’ll assume not. Similarly text carets (e.g. ‘_’, ‘>’ prompts) can be drawn with priority so that changes in their position are updated ahead of other items.

A read-xor-write pattern is simple enough to implement within a Command List, so that the XOR operation is done in interrupt context. This should provide sufficient priority.

Sprites can be managed using a Surface filter layer which tracks Address Window operations. If data is written to an area occupied by a sprite, then that data can be modified (using XOR) before passing through to provide flicker-free drawing.

Repeat fills make this a little tricky though. An alternative is to identify when a sprite will be affected and, if so, remove it before drawing the new information then re-draw it afterwards. This could be implemented using Regions so that only the affect portion is updated.

Each sprite must store both its own contents (foreground), plus the original display contents (background) excluding any other sprites. Multiple overlapping are combined at point of rendering.

References

File formats
Fonts
Graphics libraries
Metafiles
Papers

API

namespace Graphics

Typedefs

using AssetType = Asset::Type
using GlyphOptions = TextOptions
using BlendMode = Blend::Mode
using DrawingTarget = Drawing::Target
using CustomObject = ObjectTemplate<Object::Kind::Custom>

Base class for a custom object.

using AssetID = uint16_t

Numeric identifiers for re-useable objects.

using Point = TPoint<int16_t>
using IntPoint = TPoint<int>
using PointF = TPoint<float>
using Range = TRange<uint16_t>
using FontStyles = BitSet<uint16_t, FontStyle, 10>

Enums

enum class BrushStyle

Values:

enumerator FullScreen
enumerator SourceLocal
enum class Color : uint32_t

Standard colour definitions.

Values:

enumerator None
enumerator XX
enumerator XX
enum ColorOrder

Order refers to colour order within bitstream.

Values:

enumerator orderRGB
enumerator orderBGR
enum class PixelFormat : uint8_t

Values:

enumerator None
enumerator XX
enum class InputEvent

Values:

enumerator move
enumerator down
enumerator up
enum class ControlEvent

Values:

enumerator activate
enumerator deactivate
enum class Orientation

Defines orientation of display.

Values:

enumerator normal
enumerator deg0
enumerator deg90
enumerator deg180
enumerator deg270
enum class Align

Values:

enumerator Near
enumerator Centre
enumerator Far
enumerator Left
enumerator Top
enumerator Center
enumerator Right
enumerator Bottom
enum class Origin

Points on a compass.

These are ordered by angles in increments of 45 degrees.

Values:

enumerator E
enumerator NE
enumerator N
enumerator NW
enumerator W
enumerator SW
enumerator S
enumerator SE
enumerator Centre
enumerator TopLeft
enumerator Top
enumerator TopRight
enumerator Left
enumerator Center
enumerator Right
enumerator BottomLeft
enumerator Bottom
enumerator BottomRight
enum class FontStyle

Values:

enumerator XX

Functions

GRAPHICS_VERIFY_SIZE (Brush, 8)
GRAPHICS_VERIFY_SIZE (Pen, 8)
inline constexpr uint32_t getColorValue(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255)

Obtain 24-bit colour value from red, green and blue components.

inline constexpr Color makeColor(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255)

Function to create a custom colour.

inline constexpr Color makeColor(uint32_t color, uint8_t alpha = 255)
inline constexpr Color makeColor(Color color, uint8_t alpha)
inline constexpr uint8_t getAlpha(Color color)
inline constexpr uint8_t getRed(Color color)
inline constexpr uint8_t getGreen(Color color)
inline constexpr uint8_t getBlue(Color color)
bool fromString(const char *s, Color &color)
inline bool fromString(const String &s, Color &color)
inline uint8_t getBytesPerPixel(PixelFormat format)

Get number of bytes required to store a pixel in the given format.

PixelBuffer pack(PixelBuffer src, PixelFormat format)

Convert RGB colour into packed format.

Parameters:

  • color – The RGB colour to convert

  • format – The desired pixel format

Return values:

PackedColor –

inline PackedColor pack(Color color, PixelFormat format)
PixelBuffer unpack(PixelBuffer src, PixelFormat format)

Convert packed colour into RGB.

Parameters:

  • src – PixelBuffer loaded with packed colour

  • format – The exact format of the source colour

Return values:

Color – The corresponding RGB colour

inline Color unpack(PackedColor packed, PixelFormat format)
inline Color unpack(uint32_t packed, PixelFormat format)
size_t writeColor(void *buffer, PackedColor color, PixelFormat format)

Store a packed colour value into memory.

Parameters:

  • buffer – Where to write the colour value

  • color – The value to write

Return values:

size_t – The number of bytes written

inline size_t writeColor(void *buffer, Color color, PixelFormat format)
size_t writeColor(void *buffer, PackedColor color, PixelFormat format, size_t count)

Store a block of packed colours into memory.

Parameters:

  • buffer – Where to write the colour value

  • color – The value to write

  • count – The number of times to repeat the colour

Return values:

size_t – The number of bytes written

inline size_t writeColor(void *buffer, Color color, PixelFormat format, size_t count)
size_t convert(const void *srcData, PixelFormat srcFormat, void *dstBuffer, PixelFormat dstFormat, size_t numPixels)

Convert block of data from one pixel format to another.

void highlightText(SceneObject &scene)

Highlight text segments and print details.

void highlightText(TextObject &object)
uint16_t swapBytes(uint16_t w)
uint32_t makeWord(uint16_t w1, uint16_t w2)
inline Origin opposite(Origin o)

Get the origin for the opposite side of the rectangle.

e.g. E -> W, NE -> SW

inline constexpr Size rotate(Size size, Orientation orientation)
template<typename T, typename Q>
constexpr TPoint<T> operator+(TPoint<T> pt, const Q &other)
template<typename T, typename Q>
constexpr TPoint<T> operator-(TPoint<T> pt, const Q &other)
template<typename T, typename Q>
constexpr TPoint<T> operator*(TPoint<T> pt, const Q &other)
template<typename T>
constexpr TPoint<T> operator*(TPoint<T> pt, const Size &other)
template<typename T, typename Q>
constexpr TPoint<T> operator/(TPoint<T> pt, const Q &other)
template<typename T>
constexpr TPoint<T> operator/(TPoint<T> pt, const Size &other)
template<typename T, typename Q>
constexpr TPoint<T> operator%(TPoint<T> pt, const Q &other)
template<typename T>
Rect operator+(const Rect &rect, const T &other)
inline Rect operator-(const Rect &rect, const Point &offset)
inline Rect intersect(Rect r1, const Rect &r2)
inline Region operator-(const Region &rgn, const Rect &r)
inline uint16_t originToDegrees(Origin origin)

Get corresponding angle for given origin.

Origin degreesToOrigin(uint16_t angle)

Get origin closest to given angle (expressed in degrees)

uint16_t normaliseAngle(int angle)

Make 0 <= angle < 360.

Variables

LcdFont lcdFont
static constexpr uint8_t PIN_NONE = {255}

Undefined I/O pin value.

class VirtualTouch : public Graphics::Touch
#include <VirtualTouch.h>

Public Functions

virtual Size getNativeSize() const override

Get physical size of display.

Return values:

Size – Dimensions for NORMAL orientation

inline virtual State getState() const override

Get current state.

class AbstractDisplay : public Graphics::Device, public Graphics::RenderTarget
#include <AbstractDisplay.h>

Use this class as a base for all types of display drivers.

Subclassed by Graphics::Display::NullDevice, Graphics::Display::Virtual, Graphics::SpiDisplay

struct AddressWindow
#include <AddressWindow.h>

Manages a rectangular area of display memory with position information.

Accesses to display memory is controlled by first setting an active Address Window. This is a rectangular area into which following writes (or reads) will store data.

Although the display hardware usually manages this some operations require tracking the position within the driver.

Public Functions

inline size_t getPixelCount() const

Get remaining pixels in window from current position.

Public Members

Rect bounds = {}

y and h are updated by seek()

uint16_t column = {0}

Relative x position within window.

class Asset : public LinkedObjectTemplate<Asset>, public Graphics::Meta
#include <Asset.h>

An asset is used to render an Object, but is not itself drawable.

Subclassed by Graphics::AssetTemplate< AssetType::Object >, Graphics::AssetTemplate< AssetType::Text >, Graphics::AssetTemplate< AssetType::Font >, Graphics::AssetTemplate< AssetType::Surface >, Graphics::AssetTemplate< AssetType::TextureBrush >, Graphics::AssetTemplate< AssetType::Pen >, Graphics::AssetTemplate< AssetType::Typeface >, Graphics::AssetTemplate< AssetType::SolidBrush >, Graphics::AssetTemplate< AssetType::Blend >, Graphics::AssetTemplate< asset_type >

template<Asset::Type asset_type>
class AssetTemplate : public Graphics::Asset
#include <Asset.h>
class SolidBrush : public Graphics::AssetTemplate<AssetType::SolidBrush>
#include <Asset.h>
class TextureBrush : public Graphics::AssetTemplate<AssetType::TextureBrush>
#include <Asset.h>

Subclassed by Graphics::GradientBrush, Graphics::ImageBrush

class GradientBrush : public Graphics::TextureBrush
#include <Asset.h>
class ImageBrush : public Graphics::TextureBrush
#include <Asset.h>

Brush using pixels from image.

class Brush : public Graphics::Meta
#include <Asset.h>

The source of colour for drawing.

Subclassed by Graphics::Pen

class Pen : public Graphics::Brush
#include <Asset.h>

Subclassed by Graphics::PenAsset

class PenAsset : public Graphics::AssetTemplate<AssetType::Pen>, public Graphics::Pen
#include <Asset.h>
class TextOptions : public Graphics::Meta
#include <Asset.h>
class TypeFace : public Graphics::AssetTemplate<AssetType::Typeface>
#include <Asset.h>

Base class for a loaded typeface, e.g. Sans 16pt bold.

Subclassed by Graphics::LcdTypeFace, Graphics::ResourceTypeface

Public Functions

virtual FontStyles getStyle() const = 0

Style of this typeface (bold, italic, etc.)

virtual uint8_t height() const = 0

Get height of typeface, same for all characters.

virtual uint8_t descent() const = 0

How many pixels from bottom of em-square to baseline

virtual GlyphMetrics getMetrics(char ch) const = 0

Get metrics for a character.

virtual std::unique_ptr<GlyphObject> getGlyph(char ch, const GlyphOptions &options) const = 0

Get the glyph for a character.

Caller is responsible for destroying the glyph when no longer required.

Parameters:

  • ch –

  • options – Options to control how the glyph is drawn (colour, shading, etc)

Return values:

GlyphObject* – The glyph, nullptr if no glyph exists in the typeface for this character

inline uint8_t baseline() const

Get baseline relative to top of mbox.

uint16_t getTextWidth(const char *text, uint16_t length) const

Compute displayed width for a text string.

class Font : public Graphics::AssetTemplate<AssetType::Font>
#include <Asset.h>

Base class for a loaded font.

As there are various formats for defining fonts we need a consistent interface for accessing and rendering them, which this class defines.

Fonts are specified by family and size, and can be registered with various typefaces.

Subclassed by Graphics::LcdFont, Graphics::ResourceFont

class ResourceTypeface : public Graphics::TypeFace
#include <Asset.h>

Public Functions

inline virtual FontStyles getStyle() const override

Style of this typeface (bold, italic, etc.)

inline virtual uint8_t height() const override

Get height of typeface, same for all characters.

inline virtual uint8_t descent() const override

How many pixels from bottom of em-square to baseline

virtual GlyphMetrics getMetrics(char ch) const override

Get metrics for a character.

virtual std::unique_ptr<GlyphObject> getGlyph(char ch, const GlyphOptions &options) const override

Get the glyph for a character.

Caller is responsible for destroying the glyph when no longer required.

Parameters:

  • ch –

  • options – Options to control how the glyph is drawn (colour, shading, etc)

Return values:

GlyphObject* – The glyph, nullptr if no glyph exists in the typeface for this character

class ResourceFont : public Graphics::Font
#include <Asset.h>
class TextAsset : public Graphics::AssetTemplate<AssetType::Text>
#include <Asset.h>
class ObjectAsset : public Graphics::AssetTemplate<AssetType::Object>
#include <Asset.h>
class AssetList : public OwnedLinkedObjectListTemplate<Asset>
#include <Asset.h>
class Blend : public Graphics::AssetTemplate<AssetType::Blend>
#include <Blend.h>

Blend operations.

See MemoryImageSurface::write

Subclassed by Graphics::BlendTemplate< BlendXor, BlendMode::Xor >, Graphics::BlendTemplate< BlendWrite, BlendMode::Write >, Graphics::BlendTemplate< BlendMask, BlendMode::Mask >, Graphics::BlendTemplate< BlendXNor, BlendMode::XNor >, Graphics::BlendTemplate< BlendAlpha, BlendMode::Alpha >, Graphics::BlendTemplate< BlendTransparent, BlendMode::Transparent >, Graphics::BlendTemplate< Class, blendMode >

template<class Class, BlendMode blendMode>
class BlendTemplate : public Graphics::Blend
#include <Blend.h>
class BlendWrite : public Graphics::BlendTemplate<BlendWrite, BlendMode::Write>
#include <Blend.h>
class BlendXor : public Graphics::BlendTemplate<BlendXor, BlendMode::Xor>
#include <Blend.h>
class BlendXNor : public Graphics::BlendTemplate<BlendXNor, BlendMode::XNor>
#include <Blend.h>
class BlendMask : public Graphics::BlendTemplate<BlendMask, BlendMode::Mask>
#include <Blend.h>
class BlendTransparent : public Graphics::BlendTemplate<BlendTransparent, BlendMode::Transparent>
#include <Blend.h>
class BlendAlpha : public Graphics::BlendTemplate<BlendAlpha, BlendMode::Alpha>
#include <Blend.h>
class SharedBuffer
#include <Buffer.h>

Shared heap-allocated data buffer.

Used for write operations with data outside Command List.

class Control
#include <Buffer.h>
struct ReadBuffer
#include <Buffer.h>

Buffer used for reading pixel data from device.

Subclassed by Graphics::ReadStatusBuffer

Public Members

SharedBuffer data

Buffer to read pixel data.

uint16 offset = {0}

Offset from start of buffer to start writing.

PixelFormat format = {}

Input: Requested pixel format, specify ‘None’ to get native format.

struct ReadStatus
#include <Buffer.h>

Stores result of read operation.

Public Members

size_t bytesRead = {0}

On completion, set to actual length of data read.

PixelFormat format = {}

Format of data.

struct ReadStatusBuffer : public Graphics::ReadBuffer
#include <Buffer.h>

Composite ReadBuffer with status.

union PixelFormatStruct
#include <Colors.h>

Public Functions

inline uint8_t byteCount() const
inline uint8_t bitsPerPixel() const
inline ColorOrder colorOrder() const

Public Members

PixelFormat format
uint8_t mByteCount
uint8_t mBitsPerPixel
uint8_t mColorOrder
struct Graphics::PixelFormatStruct::[anonymous] [anonymous]
struct PackedColor
#include <Colors.h>

Colour in device pixel format.

union PixelBuffer
#include <Colors.h>

Structure used to perform pixel format conversions.

Public Members

Color color
PackedColor packed
uint8_t u8[4]
BGRA32 bgra32
RGB24 rgb24
BGR24 bgr24
RGB565 rgb565
struct BGR24
#include <Colors.h>
struct BGRA32
#include <Colors.h>
struct RGB24
#include <Colors.h>
struct RGB565
#include <Colors.h>
class Console : public Print
#include <Console.h>

Public Functions

inline Console(AbstractDisplay &display, RenderQueue &renderQueue)

Console constructor.

Parameters:

  • display – Output device

  • renderQueue – Allows shared access to display

void systemDebugOutput(bool enable)

Use console for debug output.

Parameters:

enable – true to divert m_puts to console, false to disable debug output

void pause(bool state)

Suspend/resume output to display.

While paused, content will be buffered in RAM.

Parameters:

state – true to stop output, false to resume

inline bool isPaused() const

Determine if output is paused.

virtual size_t write(const uint8_t *data, size_t size) override

Writes characters from a buffer to output stream.

Parameters:

  • buffer – Pointer to character buffer

  • size – Quantity of characters to write

Return values:

size_t – Quantity of characters written to stream

inline virtual size_t write(uint8_t c) override

Writes a single character to output stream.

Parameters:

c – Character to write to output stream

Return values:

size_t – Quantity of characters written to output stream

class Button : public Graphics::Control
#include <Button.h>

Basic interactive button on screen.

Responsible for drawing area within designated rectangle

class Control : public Graphics::ObjectTemplate<object_kind>
#include <Control.h>

Basic interactive button on screen.

Responsible for drawing area within designated rectangle

Subclassed by Graphics::Button, Graphics::Label, Graphics::TimeClock

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class List : public LinkedObjectListTemplate<Control>
#include <Control.h>
class Label : public Graphics::Control
#include <Label.h>

Non-interactive text label.

class Screen
#include <Screen.h>

Public Types

using DrawMethod = Delegate<bool(SceneObject &scene)>

Invoked when screen is drawn.

Param scene:

Where to compose screen

Retval bool:

Return true to continue default processing

using ControlMethod = Delegate<bool(ControlEvent event, Control &control)>

Invoked in response to user input.

Param event:

Param control:

Retval bool:

Return true to continue default processing

class TimeClock : public Graphics::Control
#include <TimeClock.h>
struct HMS
#include <TimeClock.h>
class Device
#include <Device.h>

A physical display device.

Subclassed by Graphics::AbstractDisplay

Public Functions

virtual String getName() const = 0

Get name of display.

virtual bool setOrientation(Orientation orientation) = 0

Set display orientation.

virtual Size getNativeSize() const = 0

Get physical size of display.

Return values:

Size – Dimensions for NORMAL orientation

inline Orientation getOrientation()

Get current display orientation.

virtual bool setScrollMargins(uint16_t top, uint16_t bottom) = 0

Set margins for hardware scrolling.

Area between top/bottom can be scrolled using scroll() method.

Parameters:

  • top – Number of fixed pixels at top of screen

  • bottom – Number of fixed pixels at bottom of screen

virtual bool scroll(int16_t y) = 0

Scroll region of display up or down using hardware scrolling.

Parameters:

y – Number of lines to scroll. Positive values scroll content down, negative values scroll up.

struct FillInfo
#include <DisplayList.h>

Supports DisplayList blend operations.

See also

See DisplayList::fill

class DisplayList
#include <DisplayList.h>

Stores list of low-level display commands.

Used by hardware surfaces to efficiently buffer commands which are then executed in interrupt context.

The ILI9341 4-wire SPI mode is awkard to use so to allow more efficient access the command and data information is buffered as various types of ‘chunk’ using this class. A single HSPI request packet is used for all requests and is re-filled in interrupt context from this list.

Count values (data length) are stored as either 1 or 2 bytes. Values less than 0x80 bytes are stored in 1 byte, values from 0x0080 to 0x7fff are stored MSB first with the top bit set, followed by the LSB. For example, 0x1234 would be stored as 0x92 0x34.

Commands are stored in 1 byte. To allow use of this class with other displays may require adjusting this, perhaps converting this into a class template to accommodate these differences more efficiently.

  • Standard chunk. Contains a display-specific command byte followed by optional data.

    • command (1 byte)

    • data length (1 or 2 bytes)

    • data (variable length)

  • Data chunk (no command).

    • COMMAND_DATA (1 byte)

    • data length (1 or 2 bytes)

    • data (variable length)

  • Repeated data chunk (no command). Used to perform colour fills.

    • COMMAND_DATA_REPEAT (1 byte)

    • data length (1 or 2 bytes)

    • repeat count (1 or 2 bytes)

    • data (variable length)

  • Read command. Defines a single read command packet. Reading is particularly awkward on the ILI9341 as it ‘forgets’ the read position after each read packet. Reading a block of display memory therefore requires the address window to be set immediately before the RAMRD instruction. The final block in the sequence is a CALLBACK command.

    • COMMAND_READ (1 byte)

    • data length (1 or 2 bytes)

    • command (1 byte) The display-specific command to issue

    • buffer address (4 bytes)

  • Callback. Invokes a callback function (see Callback type). Note that the single parameter points to a copy of the original data which is stored in the list.

    • COMMAND_CALLBACK (1 byte)

    • parameter data length (1 or 2 bytes)

    • callback function pointer (4 bytes)

    • callback parameters (variable)

Subclassed by Graphics::SpiDisplayList

Public Types

enum CodeArgLengths

Obtain maximum size for command, not including variable data which may be added.

Used to check space before starting a command sequence. Actual space used may be less than this.

Values:

enumerator XX
using Callback = void (*)(void *parameterData)

Queued callback.

The parameter data is copied so the caller does not need to allocate memory dynamically. The data must start on a 32-bit word boundary.

Param parameterData:

A copy of the original parameter data

Public Functions

inline DisplayList(AddressWindow &addrWindow, size_t bufferSize)
Parameters:

  • commands – Codes corresponding to specific display commands

  • addrWindow – Reference to current device address window, synced between lists

  • bufferSize –

inline DisplayList(AddressWindow &addrWindow, const FSTR::ObjectBase &data)

Create pre-defined display list from flash data.

Used for initialisation data

inline DisplayList(AddressWindow &addrWindow, const void *data, size_t length)

Create initialised display list from RAM data.

Used for initialisation data

void reset()

Reset the display list ready for re-use List MUST NOT be in use!

inline bool isEmpty() const

Determine if any commands have been stored for execution.

inline uint16_t freeSpace() const

Get number of bytes remaining in buffer.

inline uint16_t readOffset() const

Get current read position.

inline uint16_t used() const

Get number of bytes stored in buffer.

inline const uint8_t *getContent() const

Get read-only pointer to start of buffer.

uint8_t *getBuffer(uint16_t &available)

Get some space in the list to write pixel data.

Call commit after the data has been written

Parameters:

available – (OUT) How much space is available

Return values:

uint8_t* – Where to write data

inline uint8_t *getBuffer(uint16_t minBytes, uint16_t &available)

Get some space in the list to write pixel data.

Call commit after the data has been written

Parameters:

  • minBytes – Minimum bytes required

  • available – (OUT) How much space is available

Return values:

uint8_t* – Where to write data, nullptr if required space not available

void commit(uint16_t length)

Commit block of data to the list.

Note

MUST NOT call with more data than returned from available in getBuffer call.

Parameters:

length – How many bytes have been written

inline bool writeCommand(uint8_t command, uint32_t data, uint8_t length)

Write command with 1-4 bytes of parameter data.

bool writeCommand(uint8_t command, const void *data, uint16_t length)

Write command with variable amount of parameter data.

bool writeData(const void *data, uint16_t length)

Add WRITE command plus data.

bool writeDataBuffer(SharedBuffer &data, size_t offset, uint16_t length)

Add WRITE command plus external data.

Parameters:

data – Will be locked until display list has been executed

bool blockFill(const void *data, uint16_t length, uint32_t repeat)

Perform a block fill operation with repeat, e.g. multiple pixel fill or repeated pattern.

bool setAddrWindow(const Rect &rect)

Set window for read/write operations.

bool setPixel(PackedColor color, uint8_t bytesPerPixel, Point pt)

Set a single pixel.

bool readMem(void *buffer, uint16_t length)

Read a block of display memory.

bool writeCallback(Callback callback, void *params, uint16_t paramLength)

Request a callback.

The callback will be invoked (in interrupt context) when read from the display list

Parameters:

  • callback – Callback function to invoke

  • params – Parameter data, will be stored in list

  • paramLength – Size of parameter data

bool fill(const Rect &rect, PackedColor color, uint8_t bytesPerPixel, FillInfo::Callback callback)

Perform a block fill operation with blending.

Performs a read/blend/write operation. Use to perform transparent fills or other blend operations on small regions of display memory.

Parameters:

  • rect – Area to fill

  • color –

  • bytesPerPixel –

  • callback – Invoked in interrupt context to perform blend operation

inline bool canLockBuffer()

Enforce maximum number of locked buffers to conserve memory.

Return values:

bool – true if call to lockBuffer() will succeed

bool lockBuffer(SharedBuffer &buffer)

Lock a shared buffer by storing a reference to it. This will be released when reset() is called.

inline bool require(uint16_t length)

Check if list has space for the given number of bytes.

Return values:

bool – true if there’s room

bool readEntry(Entry &info)

Read next command list entry.

Used by virtual display and for debugging. SpiDisplayList uses a different mechanism for reading.

Parameters:

info –

Return values:

bool – false if there are no more commands

inline void prepare(Callback callback, void *param)

Prepare for playback.

Parameters:

  • callback – Invoked when playback has completed, in task context

  • param – Parameter passed to callback

struct Entry
#include <DisplayList.h>

Values returned from readEntry

union Header
#include <DisplayList.h>

Each list entry starts with a header.

This information is interpreted by the display driver but should translate to a single display command.

Each command has fixed content with optional variable data. Length can be packed with command (0-31), or an additional uint8_t or uint16_t.

setPixel(uint8_t x, uint8_t y, void* data, uint8_t len) COL(uint8_t x, uint8_t len) ROW(uint8_t y, 1) DAT data, len

setPixel(uint16_t x, uint8_t y, void* data, uint16_t len) COL(uint16_t x, uint16_t len) ROW(uint8_t y, 1) DAT data, len

fillRect(uint16_t x, uint16_t y, uint16_t w, uint16_t h, data len) COL16 x, w ROW16 y, h

Public Members

Code code
uint8_t len
struct Graphics::DisplayList::Header::[anonymous] [anonymous]
uint8_t u8

Public Static Attributes

static constexpr uint8_t lenMax = {15}
class ImageSurface : public Graphics::Surface
#include <ImageSurface.h>

Virtual class to access an image as a Surface.

Use to create off-screen bitmaps by drawing or copying areas from display memory.

Subclassed by Graphics::FileImageSurface, Graphics::MemoryImageSurface

Public Functions

virtual int readDataBuffer(ReadBuffer &buffer, ReadStatus *status, ReadCallback callback, void *param) override

Read some pixels.

Call setAddrWindow to set up region to be read. Returns true when all pixels have been queued for reading.

Parameters:

  • buffer – Details requested format and buffer to read

  • status – Optional. Stores result of read operation.

  • callback – Optional. Invoked when read has completed

  • param – Parameters passed to callback

Return values:

int – Number of pixels queued for reading (or read); 0 if no further pixels to read, < 0 to try again later

inline virtual void reset() override

Reset surface ready for more commands.

virtual bool present(PresentCallback callback, void *param) override

Present surface to display device.

Hardware devices will queue buffered commands to the display device then return. The surface will be marked as BUSY. Attempting to call present() on a BUSY surface must return true. If surface is EMPTY (no buffered commands), must return false.

Parameters:

  • callback – Invoked when surface is available for more commands

  • param – Passed to callback

Return values:

bool – true If callback has been queued, false if surface is empty

class MemoryImageSurface : public Graphics::ImageSurface
#include <ImageSurface.h>

Image surface using RAM as backing store.

Useful for sprites, etc.

class FileImageSurface : public Graphics::ImageSurface
#include <ImageSurface.h>

Image surface using filing system as backing store.

Slower than RAM but size is unrestricted. Use for constructing complex scenes for faster drawing.

class LcdGlyph : public Graphics::GlyphObject
#include <LcdFont.h>

Public Functions

inline virtual bool init() override

Initialise the object, e.g. parse header content and obtain dimensions.

virtual void readAlpha(void *buffer, Point origin, size_t stride) const override

Obtain glyph information as block of 8-bit alpha values.

This method is called with a positive origin to accommodate negative x/y glyph offsets. Italic and script typefaces do this a lot!

Parameters:

  • buffer –

  • origin – Location of cursor within buffer

  • stride – Number of bytes per row in buffer

class LcdTypeFace : public Graphics::TypeFace
#include <LcdFont.h>

Public Functions

inline virtual FontStyles getStyle() const override

Style of this typeface (bold, italic, etc.)

inline virtual uint8_t height() const override

Get height of typeface, same for all characters.

inline virtual uint8_t descent() const override

How many pixels from bottom of em-square to baseline

inline virtual GlyphObject::Metrics getMetrics(char ch) const override

Get metrics for a character.

virtual std::unique_ptr<GlyphObject> getGlyph(char ch, const GlyphObject::Options &options) const override

Get the glyph for a character.

Caller is responsible for destroying the glyph when no longer required.

Parameters:

  • ch –

  • options – Options to control how the glyph is drawn (colour, shading, etc)

Return values:

GlyphObject* – The glyph, nullptr if no glyph exists in the typeface for this character

class LcdFont : public Graphics::Font
#include <LcdFont.h>
class Meta
#include <Meta.h>

Empty base class to support object enumeration Non-virtual to avoid bloat.

Subclassed by Graphics::Asset, Graphics::Brush, Graphics::Object, Graphics::TextObject::Element, Graphics::TextOptions

class MetaWriter
#include <Meta.h>

Writes object content in readable format for debugging.

class MipiDisplay : public Graphics::SpiDisplay
#include <MipiDisplay.h>

Subclassed by Graphics::Display::ILI9341, Graphics::Display::ST7789V

Public Functions

inline void setNativeSize(Size screenSize)

Sets the screen size. Must be called before calling begin()

inline virtual Size getNativeSize() const override

Get physical size of display.

Return values:

Size – Dimensions for NORMAL orientation

virtual bool setScrollMargins(uint16_t top, uint16_t bottom) override

Set margins for hardware scrolling.

Area between top/bottom can be scrolled using scroll() method.

Parameters:

  • top – Number of fixed pixels at top of screen

  • bottom – Number of fixed pixels at bottom of screen

virtual bool scroll(int16_t y) override

Scroll region of display up or down using hardware scrolling.

Parameters:

y – Number of lines to scroll. Positive values scroll content down, negative values scroll up.

virtual bool setOrientation(Orientation orientation) override

Set display orientation.

inline virtual Size getSize() const override

Get target dimensions.

inline virtual PixelFormat getPixelFormat() const override

All surfaces support the same pixel format.

virtual Surface *createSurface(size_t bufferSize = 0) override

Create a surface for use with this render target.

Caller is responsible for destroying the surface when no longer required.

Parameters:

bufferSize – Size of internal command/data buffer

Return values:

Surface* – The surface to use

class MipiSurface : public Graphics::Surface
#include <MipiDisplay.h>

Public Functions

inline virtual void reset() override

Reset surface ready for more commands.

virtual int readDataBuffer(ReadBuffer &buffer, ReadStatus *status, ReadCallback callback, void *param) override

Read some pixels.

Call setAddrWindow to set up region to be read. Returns true when all pixels have been queued for reading.

Parameters:

  • buffer – Details requested format and buffer to read

  • status – Optional. Stores result of read operation.

  • callback – Optional. Invoked when read has completed

  • param – Parameters passed to callback

Return values:

int – Number of pixels queued for reading (or read); 0 if no further pixels to read, < 0 to try again later

virtual bool render(const Object &object, const Rect &location, std::unique_ptr<Renderer> &renderer) override

Start rendering an object.

Surfaces may override this method to implement alternative rendering using specific hardware features of the display device.

Software renderers should be run by calling surface::execute.

Parameters:

  • object – What to render

  • location – Placement information

  • renderer – If operation cannot be completed in hardware, create a renderer instance to manage the process

Return values:

Return – true on success, false to retry later

virtual bool present(PresentCallback callback, void *param) override

Present surface to display device.

Hardware devices will queue buffered commands to the display device then return. The surface will be marked as BUSY. Attempting to call present() on a BUSY surface must return true. If surface is EMPTY (no buffered commands), must return false.

Parameters:

  • callback – Invoked when surface is available for more commands

  • param – Passed to callback

Return values:

bool – true If callback has been queued, false if surface is empty

class Renderer : public LinkedObjectTemplate<Renderer>
#include <Object.h>

Virtual base class to manage rendering of various types of information to a surface.

Subclassed by Graphics::BlendRenderer, Graphics::CircleRenderer, Graphics::CopyRenderer, Graphics::EllipseRenderer, Graphics::FilledCircleRenderer, Graphics::FilledEllipseRenderer, Graphics::FilledRectRenderer, Graphics::FilledRoundedRectRenderer, Graphics::GfxLineRenderer, Graphics::ImageRenderer, Graphics::LineRenderer, Graphics::MultiRenderer, Graphics::PolylineRenderer, Graphics::RectRenderer, Graphics::RoundedRectRenderer, Graphics::ScrollRenderer, Graphics::SurfaceRenderer, Graphics::TextRenderer

Public Functions

inline Renderer(const Location &location)

Constructor.

Parameters:

location – Location information

virtual bool execute(Surface &surface) = 0

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class Object : public LinkedObjectTemplate<Object>, public Graphics::Meta
#include <Object.h>

A drawable object inherits from this virtual base class.

Subclassed by Graphics::ObjectTemplate< Object::Kind::FilledCircle >, Graphics::ObjectTemplate< Object::Kind::Reference >, Graphics::ObjectTemplate< Object::Kind::Line >, Graphics::ObjectTemplate< Object::Kind::Rect >, Graphics::ObjectTemplate< Object::Kind::FilledEllipse >, Graphics::ObjectTemplate< Object::Kind::Ellipse >, Graphics::ObjectTemplate< Object::Kind::FilledArc >, Graphics::ObjectTemplate< Object::Kind::Arc >, Graphics::ObjectTemplate< Object::Kind::Surface >, Graphics::ObjectTemplate< Object::Kind::FilledRect >, Graphics::ObjectTemplate< Object::Kind::Drawing >, Graphics::ObjectTemplate< Object::Kind::Polyline >, Graphics::ObjectTemplate< Object::Kind::Point >, Graphics::ObjectTemplate< Object::Kind::Copy >, Graphics::ObjectTemplate< Object::Kind::Circle >, Graphics::ObjectTemplate< Object::Kind::Text >, Graphics::ObjectTemplate< Object::Kind::Image >, Graphics::ObjectTemplate< Object::Kind::Scroll >, Graphics::ObjectTemplate< object_kind >, Graphics::SceneObject

Public Functions

virtual Renderer *createRenderer(const Location &location) const = 0

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

template<Object::Kind object_kind>
class ObjectTemplate : public Graphics::Object
#include <Object.h>

Subclassed by Graphics::Control

class ReferenceObject : public Graphics::ObjectTemplate<Object::Kind::Reference>
#include <Object.h>

Reference to another object.

Objects are owned by a Scene, so this allows objects to be re-used in multiple scenes, or to other classes which expose an Object interface.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class PointObject : public Graphics::ObjectTemplate<Object::Kind::Point>
#include <Object.h>

A single pixel == 1x1 rectangle.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class RectObject : public Graphics::ObjectTemplate<Object::Kind::Rect>
#include <Object.h>

A rectangular outline.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class FilledRectObject : public Graphics::ObjectTemplate<Object::Kind::FilledRect>
#include <Object.h>

A filled rectangle.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class LineObject : public Graphics::ObjectTemplate<Object::Kind::Line>
#include <Object.h>

A drawn line.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class PolylineObject : public Graphics::ObjectTemplate<Object::Kind::Polyline>
#include <Object.h>

A sequence of lines.

By default, lines are connected. This is used to draw rectangles, triangles or any other type of polygon. A line is drawn between points 0-1, 1-2, 2-3, etc.

Setting the connected property to false allows the lines to be discontinuous, so a line is drawn between points 0-1, 2-3, 3-4, etc.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class CircleObject : public Graphics::ObjectTemplate<Object::Kind::Circle>
#include <Object.h>

A circle outline.

Public Functions

inline Rect getRect() const

Get bounding retangle for this circle.

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class FilledCircleObject : public Graphics::ObjectTemplate<Object::Kind::FilledCircle>
#include <Object.h>

A filled circle.

Public Functions

inline Rect getRect() const

Get bounding retangle for this circle.

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class EllipseObject : public Graphics::ObjectTemplate<Object::Kind::Ellipse>
#include <Object.h>

An ellipse outline.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class FilledEllipseObject : public Graphics::ObjectTemplate<Object::Kind::FilledEllipse>
#include <Object.h>

A filled ellipse.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class ArcObject : public Graphics::ObjectTemplate<Object::Kind::Arc>
#include <Object.h>

An arc outline.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class FilledArcObject : public Graphics::ObjectTemplate<Object::Kind::FilledArc>
#include <Object.h>

A filled arc.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class ImageObject : public Graphics::ObjectTemplate<Object::Kind::Image>
#include <Object.h>

Virtual base class for an image.

Subclassed by Graphics::GlyphObject, Graphics::StreamImageObject

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

virtual bool init() = 0

Initialise the object, e.g. parse header content and obtain dimensions.

virtual PixelFormat getPixelFormat() const = 0

Get native pixel format.

Return values:

PixelFormat – Return None if ambivalent about format (e.g. calculated pixel data)

virtual size_t readPixels(const Location &loc, PixelFormat format, void *buffer, uint16_t width) const = 0

Read pixels in requested format.

Parameters:

  • loc – Start position

  • format – Required pixel format

  • buffer – Buffer for pixels

  • width – Number of pixels to read

Return values:

size_t – Number of bytes written

class StreamImageObject : public Graphics::ImageObject
#include <Object.h>

Image whose contents are stored in a stream, typically in a file or flash memory.

Subclassed by Graphics::BitmapObject, Graphics::RawImageObject

class BitmapObject : public Graphics::StreamImageObject
#include <Object.h>

A BMP format image.

Code based on https://github.com/adafruit/Adafruit-GFX-Library

Public Functions

virtual bool init() override

Initialise the object, e.g. parse header content and obtain dimensions.

inline virtual PixelFormat getPixelFormat() const override

Get native pixel format.

Return values:

PixelFormat – Return None if ambivalent about format (e.g. calculated pixel data)

virtual size_t readPixels(const Location &loc, PixelFormat format, void *buffer, uint16_t width) const override

Read pixels in requested format.

Parameters:

  • loc – Start position

  • format – Required pixel format

  • buffer – Buffer for pixels

  • width – Number of pixels to read

Return values:

size_t – Number of bytes written

class RawImageObject : public Graphics::StreamImageObject
#include <Object.h>

Image stored as raw pixels in a specific format.

Use images stored in native display format for best performance as no conversion is required.

Subclassed by Graphics::FileImageObject, Graphics::MemoryImageObject

Public Functions

inline virtual bool init() override

Initialise the object, e.g. parse header content and obtain dimensions.

inline virtual PixelFormat getPixelFormat() const override

Get native pixel format.

Return values:

PixelFormat – Return None if ambivalent about format (e.g. calculated pixel data)

virtual size_t readPixels(const Location &loc, PixelFormat format, void *buffer, uint16_t width) const override

Read pixels in requested format.

Parameters:

  • loc – Start position

  • format – Required pixel format

  • buffer – Buffer for pixels

  • width – Number of pixels to read

Return values:

size_t – Number of bytes written

class RenderTarget
#include <Object.h>

Interface for objects which support writing via surfaces.

Subclassed by Graphics::AbstractDisplay, Graphics::FileImageObject, Graphics::MemoryImageObject

Public Functions

virtual Size getSize() const = 0

Get target dimensions.

virtual PixelFormat getPixelFormat() const = 0

All surfaces support the same pixel format.

virtual Surface *createSurface(size_t bufferSize = 0) = 0

Create a surface for use with this render target.

Caller is responsible for destroying the surface when no longer required.

Parameters:

bufferSize – Size of internal command/data buffer

Return values:

Surface* – The surface to use

class MemoryImageObject : public Graphics::RawImageObject, public Graphics::RenderTarget
#include <Object.h>

Public Functions

inline virtual Size getSize() const override

Get target dimensions.

inline virtual PixelFormat getPixelFormat() const override

Get native pixel format.

Return values:

PixelFormat – Return None if ambivalent about format (e.g. calculated pixel data)

inline virtual Surface *createSurface(size_t bufferSize = 0) override

Create a surface for use with this render target.

Caller is responsible for destroying the surface when no longer required.

Parameters:

bufferSize – Size of internal command/data buffer

Return values:

Surface* – The surface to use

class FileImageObject : public Graphics::RawImageObject, public Graphics::RenderTarget
#include <Object.h>

Public Functions

inline virtual Size getSize() const override

Get target dimensions.

inline virtual PixelFormat getPixelFormat() const override

Get native pixel format.

Return values:

PixelFormat – Return None if ambivalent about format (e.g. calculated pixel data)

virtual Surface *createSurface(size_t bufferSize = 0) override

Create a surface for use with this render target.

Caller is responsible for destroying the surface when no longer required.

Parameters:

bufferSize – Size of internal command/data buffer

Return values:

Surface* – The surface to use

class GlyphObject : public Graphics::ImageObject
#include <Object.h>

A character glyph image.

Characters are accessed like regular images but there are some specialisations which may be necessary which this class exposes:

  • To support devices with custom renderers we require access to the raw monochrome bits

  • Images currently don’t support transparency, although this could be enabled using a flag bits in the PackedColor format. The display driver or renderer would then need to interpret this flag and render accordingly. An alternative method is to nominate a transparent colour.

Subclassed by Graphics::LcdGlyph

Public Functions

inline virtual PixelFormat getPixelFormat() const override

Get native pixel format.

Return values:

PixelFormat – Return None if ambivalent about format (e.g. calculated pixel data)

virtual size_t readPixels(const Location &loc, PixelFormat format, void *buffer, uint16_t width) const override

Read pixels in requested format.

Parameters:

  • loc – Start position

  • format – Required pixel format

  • buffer – Buffer for pixels

  • width – Number of pixels to read

Return values:

size_t – Number of bytes written

virtual void readAlpha(void *buffer, Point origin, size_t stride) const = 0

Obtain glyph information as block of 8-bit alpha values.

This method is called with a positive origin to accommodate negative x/y glyph offsets. Italic and script typefaces do this a lot!

Parameters:

  • buffer –

  • origin – Location of cursor within buffer

  • stride – Number of bytes per row in buffer

class TextObject : public Graphics::ObjectTemplate<Object::Kind::Text>
#include <Object.h>

A block of text consisting of zero or more segments.

A segment is a straight run of text using a specific typeface and style.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class ColorElement : public Graphics::TextObject::Element
#include <Object.h>
class Element : public LinkedObjectTemplate<Element>, public Graphics::Meta
#include <Object.h>

Subclassed by Graphics::TextObject::ColorElement, Graphics::TextObject::FontElement, Graphics::TextObject::RunElement, Graphics::TextObject::TextElement

class FontElement : public Graphics::TextObject::Element
#include <Object.h>
class RunElement : public Graphics::TextObject::Element
#include <Object.h>
class TextElement : public Graphics::TextObject::Element
#include <Object.h>
class SurfaceObject : public Graphics::ObjectTemplate<Object::Kind::Surface>
#include <Object.h>

Describes a target surface and corresponding source location.

Used in surface copy operations to read display memory contents.

Public Functions

inline SurfaceObject(Surface &surface, const Rect &dest, Point source)

Constructor.

Parameters:

  • surface –

  • dest – Where on the surface to write

  • source – Start position of source

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class CopyObject : public Graphics::ObjectTemplate<Object::Kind::Copy>
#include <Object.h>

Describes a copy operation within the same surface.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class ScrollObject : public Graphics::ObjectTemplate<Object::Kind::Scroll>
#include <Object.h>

Describes a scrolling operation.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

class DrawingObject : public Graphics::ObjectTemplate<Object::Kind::Drawing>
#include <Object.h>

A collection of line and curve drawing operations.

Stored in a compact format which can be streamed.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

template<typename T>
class ItemList
#include <Renderer.h>

Fixed list of types.

Rendering algorithms create small sets of points, lines or rectangles. Buffering these in a small list simplifies logic considerably.

class PointList : public Graphics::ItemList<Point>
#include <Renderer.h>

Small list of points for drawing.

Algorithms generate multiple points within a loop so buffering them in a list simplifies logic considerably.

Public Functions

bool render(Surface &surface)

Render each point.

Parameters:

surface –

Return values:

bool – true if all points have been rendered, false if surface is full

class RectList : public Graphics::ItemList<Rect>
#include <Renderer.h>

Small list of rectangles, similar to PointList.

Subclassed by Graphics::ArcRectList

class MultiRenderer : public Graphics::Renderer
#include <Renderer.h>

Base class to render multiple objects.

Subclassed by Graphics::Drawing::Renderer, Graphics::RenderQueue, Graphics::SceneRenderer

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

inline Renderer(const Location &location)

Constructor.

Parameters:

location – Location information

class SceneRenderer : public Graphics::MultiRenderer
#include <Renderer.h>

A scene is a list of other objects, so we just iterate through the list and draw each in turn.

Rendering is performed by calling Surface::render(). Surfaces are provided by devices so may be able to provide optimised renderers for their hardware.

class GfxLineRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws 1-pixel lines.

Code based on https://github.com/adafruit/Adafruit-GFX-Library

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class LineRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws lines.

See http://enchantia.com/graphapp/

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class PolylineRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws series of lines defined by a PolylineObject

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class RectRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws a rectangle as a polyline.

Public Functions

inline virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class FilledRectRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws a filled rectangle.

To accommodate transparency, etc.

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class RoundedRectRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws a rectangle outline with rounded corners.

Code based on https://github.com/adafruit/Adafruit-GFX-Library

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class FilledRoundedRectRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws a filled rectangle with rounded corners.

Code based on https://github.com/adafruit/Adafruit-GFX-Library

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class CircleRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws a circle outline.

Code based on https://github.com/adafruit/Adafruit-GFX-Library

Public Functions

inline CircleRenderer(const Location &location, const Pen &pen, Point centre, uint16_t radius, uint8_t corners)

Used to draw corners only.

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class FilledCircleRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws a filled circle.

Code based on https://github.com/adafruit/Adafruit-GFX-Library

Public Functions

inline FilledCircleRenderer(const Location &location, const Brush &brush, Point centre, uint16_t radius, uint16_t delta, uint8_t quadrants)

Used to draw rounded parts of a rounded rectangle These are handled by drawing lines between the left/right corners.

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

struct Ellipse
#include <Renderer.h>

State information for tracing an ellipse outline.

class ArcRectList : public Graphics::RectList
#include <Renderer.h>
class EllipseRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws an ellipse outline.

Uses McIlroy’s Ellipse Algorithm

See http://enchantia.com/graphapp/doc/tech/ellipses.html

Subclassed by Graphics::ArcRenderer

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class FilledEllipseRenderer : public Graphics::Renderer
#include <Renderer.h>

Draws a filled ellipse.

See http://enchantia.com/graphapp/doc/tech/ellipses.html

Subclassed by Graphics::FilledArcRenderer

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class ArcRenderer : public Graphics::EllipseRenderer
#include <Renderer.h>

Render arc outline with adjustable line width.

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class FilledArcRenderer : public Graphics::FilledEllipseRenderer
#include <Renderer.h>

Render arc outline with adjustable line width.

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class ImageRenderer : public Graphics::Renderer
#include <Renderer.h>

Render an image object.

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class SurfaceRenderer : public Graphics::Renderer
#include <Renderer.h>

Copy an area to another surface.

Typically used to copy display memory into RAM

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class CopyRenderer : public Graphics::Renderer
#include <Renderer.h>

Copy an area within the same surface.

Subclassed by Graphics::ImageCopyRenderer

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

inline Renderer(const Location &location)

Constructor.

Parameters:

location – Location information

class ImageCopyRenderer : public Graphics::CopyRenderer
#include <Renderer.h>
class ScrollRenderer : public Graphics::Renderer
#include <Renderer.h>

Scroll an area.

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class BlendRenderer : public Graphics::Renderer
#include <Renderer.h>

Perform blending with draw.

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class TextRenderer : public Graphics::Renderer
#include <Renderer.h>

Draw a line of text.

If foreground and background colours are the same then the text is renderered transparently.

Public Functions

virtual bool execute(Surface &surface) override

Called to do some writing to the surface.

Return values:

bool – true when rendering is complete, false if more work to be done

class RenderQueue : private Graphics::MultiRenderer
#include <RenderQueue.h>

Top-level manager to queue objects for rendering to a specific target.

Use this to render single objects, typically Scenes or Drawings

Public Functions

inline RenderQueue(RenderTarget &target, uint8_t surfaceCount = 2, size_t bufferSize = 0)

Constructor.

Surfaces are created by the target display device.

For minimum RAM usage use a single surface.

For best performance use two, so one can be prepared whilst the other is being written to the screen.

The RenderQueue owns these surfaces.

Parameters:

  • target – Where to render scenes

  • bufferSize – Size of each allocated surface buffer. Specify 0 to use default.

  • surfaceCount – Number of surfaces to allocate

template<typename T>
inline void render(T *object, const Location &location, typename T::Callback callback = nullptr, uint16_t delayMs = 0)

Add object to the render queue and start rendering if it isn’t already.

Parameters:

  • object – Scene, Drawing, etc. to render

  • location – Where to draw the object

  • callback – Optional callback to invoke when render is complete

  • delayMs – Delay between render completion and callback

class SceneObject : public Graphics::Object
#include <Scene.h>

A Scene containing multiple objects.

Public Functions

virtual Renderer *createRenderer(const Location &location) const override

Create a software renderer for this object.

Return nullptr if object cannot/should not be rendered

Parameters:

location –

Return values:

renderer – Returned renderer object

template<typename T>
inline T *addObject(T *obj)

Add a new object to the scene.

Use this method to add custom objects. To draw an object multiple times use drawObject which will add a reference instead.

Parameters:

obj – This will be owned by the scene

inline void reset(Size size)

Reset the scene with a new size.

inline void clear(const Brush &brush = Color::Black)

Clear the scene and fill with a chosen colour.

inline CopyObject *copy(const Rect &source, Point dest)

Copy region of display to another.

Parameters:

  • source – Area to copy

  • dest – Top-left corner to copy to

inline ScrollObject *scroll(const Rect &area, int16_t cx, int16_t cy, bool wrapx = false, bool wrapy = false, Color fill = Color::None)

Scroll display memory.

Parameters:

  • area – Region to scroll

  • cx – Distance to scroll horizontally

  • cy – Distance to scroll vertically

  • wrapx – true to scroll, false to clip in X direction

  • wrapx – Y scroll/clip

  • fill – Optional color to fill in clip mode

class SpiDisplay : protected HSPI::Device, public Graphics::AbstractDisplay
#include <SpiDisplay.h>

Subclassed by Graphics::MipiDisplay

Public Functions

inline virtual HSPI::IoModes getSupportedIoModes() const override

Return set of IO modes supported by a device implementation.

class SpiDisplayList : public Graphics::DisplayList
#include <SpiDisplayList.h>

Display list for hardware SPI devices.

A single HSPI request packet is used for all requests and is re-filled in interrupt context from this list.

Public Functions

bool fillRequest()

Called from interrupt context to re-fill the SPI request packet.

Return values:

bool – true on success, false if there are no further requests

Public Members

HSPI::Request request

The HSPI request packet used by this list.

struct Commands
#include <SpiDisplayList.h>

Commonly-used display-specific command codes.

Short codes are used to represent these commands. Other commands are stored directly in the list.

class WriteStream
#include <Stream.h>
class ReadStream
#include <Stream.h>
class SubStream : public IDataSourceStream
#include <Stream.h>

Public Functions

inline virtual int available() override

Return the total length of the stream.

Return values:

int – -1 is returned when the size cannot be determined

inline virtual uint16_t readMemoryBlock(char *data, int bufSize) override

Read a block of memory.

Todo:

Should IDataSourceStream::readMemoryBlock return same data type as its bufSize param?

Parameters:

  • data – Pointer to the data to be read

  • bufSize – Quantity of chars to read

Return values:

uint16_t – Quantity of chars read

inline virtual int seekFrom(int offset, SeekOrigin origin) override

Change position in stream.

Note

This method is implemented by streams which support random seeking, such as files and memory streams.

Parameters:

  • offset –

  • origin –

Return values:

New – position, < 0 on error

inline virtual bool isFinished() override

Check if all data has been read.

Return values:

bool – True on success.

class Surface : public Graphics::AssetTemplate<AssetType::Surface>
#include <Surface.h>

Interface for a drawing surface.

Represents a rectangular area of pixels which can be read or written.

A display device has at least one of these, representing the primary display area. More complex devices with large amounts of display memory may allow additional surfaces to be used to perform screen updates by ‘flipping’ (switching active surface) or fast copies using display hardware.

Subclassed by Graphics::ImageSurface, Graphics::MipiSurface

Public Types

using ReadCallback = void (*)(ReadBuffer &data, size_t length, void *param)

Callback for readPixel() operations.

Param buffer:

Buffer passed to readPixel() call

Public Functions

virtual int readDataBuffer(ReadBuffer &buffer, ReadStatus *status = nullptr, ReadCallback callback = nullptr, void *param = nullptr) = 0

Read some pixels.

Call setAddrWindow to set up region to be read. Returns true when all pixels have been queued for reading.

Parameters:

  • buffer – Details requested format and buffer to read

  • status – Optional. Stores result of read operation.

  • callback – Optional. Invoked when read has completed

  • param – Parameters passed to callback

Return values:

int – Number of pixels queued for reading (or read); 0 if no further pixels to read, < 0 to try again later

virtual bool render(const Object &object, const Rect &location, std::unique_ptr<Renderer> &renderer)

Start rendering an object.

Surfaces may override this method to implement alternative rendering using specific hardware features of the display device.

Software renderers should be run by calling surface::execute.

Parameters:

  • object – What to render

  • location – Placement information

  • renderer – If operation cannot be completed in hardware, create a renderer instance to manage the process

Return values:

Return – true on success, false to retry later

bool render(const Object &object, const Rect &location)

Render an object in one cycle.

Use this method for simple renders which should complete in one cycle. Typically used for memory surface renders or where an object is expected to render within a single surface.

Parameters:

  • surface – Where to render the object to

  • location –

Return values:

bool – true on success

inline bool execute(std::unique_ptr<Renderer> &renderer)

Execute a renderer.

Parameters:

renderer – Will be released when render has completed

Return values:

bool – true if render is complete

virtual void reset() = 0

Reset surface ready for more commands.

virtual bool present(PresentCallback callback = nullptr, void *param = nullptr) = 0

Present surface to display device.

Hardware devices will queue buffered commands to the display device then return. The surface will be marked as BUSY. Attempting to call present() on a BUSY surface must return true. If surface is EMPTY (no buffered commands), must return false.

Parameters:

  • callback – Invoked when surface is available for more commands

  • param – Passed to callback

Return values:

bool – true If callback has been queued, false if surface is empty

bool fillSmallRect(const Brush &brush, const Rect &location, const Rect &rect)

Fill a small rectangle using a non-transparent brush.

bool drawHLine(PackedColor color, uint16_t x0, uint16_t x1, uint16_t y, uint16_t w)

Draw a simple horizontal line using a filled rectangle.

bool drawVLine(PackedColor color, uint16_t x, uint16_t y0, uint16_t y1, uint16_t w)

Draw a simple vertical line using a filled rectangle.

struct Stat
#include <Surface.h>
class TextParser
#include <TextBuilder.h>

Simplifies construction of TextObject instances.

Subclassed by Graphics::TextBuilder

Public Functions

inline void setCursor(Point pt)

Set location to start new text segment.

class TextBuilder : public Graphics::TextParser, public Print
#include <TextBuilder.h>

Simplifies construction of TextObject instances.

Public Functions

inline virtual size_t write(uint8_t c) override

Writes a single character to output stream.

Parameters:

c – Character to write to output stream

Return values:

size_t – Quantity of characters written to output stream

inline virtual size_t write(const uint8_t *buffer, size_t size) override

Writes characters from a buffer to output stream.

Parameters:

  • buffer – Pointer to character buffer

  • size – Quantity of characters to write

Return values:

size_t – Quantity of characters written to stream

size_t write(uint8_t c) = 0

Writes a single character to output stream.

Parameters:

c – Character to write to output stream

Return values:

size_t – Quantity of characters written to output stream

inline size_t write(const char *str)

Writes a c-string to output stream.

Parameters:

str – Pointer to c-string

Return values:

size_t – Quantity of characters written to stream

size_t write(const uint8_t *buffer, size_t size)

Writes characters from a buffer to output stream.

Parameters:

  • buffer – Pointer to character buffer

  • size – Quantity of characters to write

Return values:

size_t – Quantity of characters written to stream

inline size_t write(const char *buffer, size_t size)

Writes characters from a buffer to output stream.

Parameters:

  • buffer – Pointer to character buffer

  • size – Quantity of characters to write

Return values:

size_t – Quantity of characters written to stream

class XPT2046 : private HSPI::Device, public Graphics::Touch
#include <XPT2046.h>

Public Functions

inline virtual Size getNativeSize() const override

Get physical size of display.

Return values:

Size – Dimensions for NORMAL orientation

inline virtual State getState() const override

Get current state.

class Touch
#include <Touch.h>

Subclassed by Graphics::VirtualTouch, Graphics::XPT2046

Public Types

using Callback = Delegate<void()>

Callback function.

Public Functions

virtual bool setOrientation(Orientation orientation)

Set display orientation.

virtual Size getNativeSize() const = 0

Get physical size of display.

Return values:

Size – Dimensions for NORMAL orientation

virtual State getState() const = 0

Get current state.

inline virtual void setCallback(Callback callback)

Register callback to be invoked when state changes.

inline Size getSize() const

Get native dimensions for current orientation.

inline Orientation getOrientation()

Get current display orientation.

inline Point translate(Point rawPos)

Translate position into screen co-ordinates.

struct Calibration
#include <Touch.h>
struct State
#include <Touch.h>
struct Size
#include <Types.h>

Size of rectangular area (width x height)

template<typename T>
struct TPoint
#include <Types.h>

An (x, y) display coordinate.

Public Functions

template<typename Q>
inline explicit constexpr TPoint(TPoint<Q> pt)

Conversion constructor.

struct Rect
#include <Types.h>

Location and size of rectangular area (x, y, w, h)

Public Functions

inline Rect &clip(const Rect &r)

Obtain intersection with another rectangle.

inline Rect &operator+=(const Rect &r)

Obtain smallest rectangle enclosing this rectangle and another.

class Region
#include <Types.h>

Represents the intersection of two rectangles.

This produces up to 4 separate, non-overlapping rectangles.

Public Functions

inline Region &operator+=(const Rect &r)

Add rectangle to this region.

Produces a single enclosing rectangle.

inline Region &operator-=(const Rect &r)

Remove rectangle from this region.

Operation is currently performed on bounding box ONLY. TODO: Implement region updates using existing information.

struct Location
#include <Types.h>

Identifies position within bounding rectangle.

Public Members

Rect dest

Where to write pixels on surface.

Rect source

Reference source area.

This is generally used by brushes to locate colour information. For example, with an ImageBrush objects can be filled to either re-use the same portion of the reference image, or to reveal a particular part of it.

Point pos

Position relative to dest/source top-left corner.

class ColorRange
#include <Types.h>
class Scale
#include <Types.h>
struct GlyphMetrics
#include <Types.h>

Glyph metrics.

Public Members

uint8_t width

Width of glyph.

uint8_t height

Height of glyph.

int8_t xOffset

Glyph position relative to cursor.

int8_t yOffset

Distance from upper-left corner to baseline.

uint8_t advance

Distance to next character.

namespace Display
class Virtual : public Graphics::AbstractDisplay
#include <Virtual.h>

Virtual display device for Host.

Talks to python virtual screen application via TCP

Public Functions

inline virtual String getName() const override

Get name of display.

inline virtual Size getNativeSize() const override

Get physical size of display.

Return values:

Size – Dimensions for NORMAL orientation

virtual bool setOrientation(Orientation orientation) override

Set display orientation.

inline virtual Size getSize() const override

Get target dimensions.

inline virtual PixelFormat getPixelFormat() const override

All surfaces support the same pixel format.

virtual bool setScrollMargins(uint16_t top, uint16_t bottom) override

Set margins for hardware scrolling.

Area between top/bottom can be scrolled using scroll() method.

Parameters:

  • top – Number of fixed pixels at top of screen

  • bottom – Number of fixed pixels at bottom of screen

virtual bool scroll(int16_t y) override

Scroll region of display up or down using hardware scrolling.

Parameters:

y – Number of lines to scroll. Positive values scroll content down, negative values scroll up.

virtual Surface *createSurface(size_t bufferSize = 0) override

Create a surface for use with this render target.

Caller is responsible for destroying the surface when no longer required.

Parameters:

bufferSize – Size of internal command/data buffer

Return values:

Surface* – The surface to use

class ILI9341 : public Graphics::MipiDisplay
#include <ILI9341.h>

Public Functions

inline virtual String getName() const override

Get name of display.

class NullDevice : public Graphics::AbstractDisplay
#include <Null.h>

Null display device, discards data.

Used for testing performance and algorithms.

Public Functions

inline virtual String getName() const override

Get name of display.

inline virtual Size getNativeSize() const override

Get physical size of display.

Return values:

Size – Dimensions for NORMAL orientation

inline virtual bool setOrientation(Orientation orientation) override

Set display orientation.

inline virtual bool setScrollMargins(uint16_t top, uint16_t bottom) override

Set margins for hardware scrolling.

Area between top/bottom can be scrolled using scroll() method.

Parameters:

  • top – Number of fixed pixels at top of screen

  • bottom – Number of fixed pixels at bottom of screen

inline virtual bool scroll(int16_t y) override

Scroll region of display up or down using hardware scrolling.

Parameters:

y – Number of lines to scroll. Positive values scroll content down, negative values scroll up.

inline virtual Size getSize() const override

Get target dimensions.

inline virtual PixelFormat getPixelFormat() const override

All surfaces support the same pixel format.

virtual Surface *createSurface(size_t bufferSize = 0) override

Create a surface for use with this render target.

Caller is responsible for destroying the surface when no longer required.

Parameters:

bufferSize – Size of internal command/data buffer

Return values:

Surface* – The surface to use

class ST7789V : public Graphics::MipiDisplay
#include <ST7789V.h>

Public Functions

inline virtual String getName() const override

Get name of display.

namespace Drawing

Enums

enum class Command : uint8_t

Values:

enumerator XX
enum class OpCode : uint8_t

Values:

enumerator store
enumerator add
enumerator sub
enumerator execute

Functions

String toString(OpCode opcode)
union Header
#include <Header.h>

Command header structure.

Public Types

enum class Type : uint8_t

Values:

enumerator uint8
enumerator uint16
enumerator uint32
enumerator resource
enum class DataType : uint8_t

Values:

enumerator charArray
enum class ResourceKind : uint8_t

Values:

enumerator text
enumerator image
enum class LengthSize : uint8_t

Values:

enumerator uint8
enumerator uint16

Public Members

uint8_t index

Register index.

Type type
OpCode opcode

Operation to perform.

= OpCode::store

uint32_t param
struct Graphics::Drawing::Header::[anonymous] [anonymous]

Size of resource length field.

ResourceKind kind
LengthSize lengthSize
DataType dataType
struct Graphics::Drawing::Header::[anonymous] resource
Command cmd
class Reader
#include <Reader.h>
struct Registers
#include <Registers.h>
class Renderer : public Graphics::MultiRenderer
#include <Renderer.h>

A drawing contains a compact list of drawing commands, like a virtual plotter.

class Target
#include <Target.h>
class Writer
#include <Writer.h>
namespace Mipi

Enums

enum SerialInterfaceCommand

Values:

enumerator DSI_V_SYNC_START
enumerator DSI_V_SYNC_END
enumerator DSI_H_SYNC_START
enumerator DSI_H_SYNC_END
enumerator DSI_COMPRESSION_MODE
enumerator DSI_END_OF_TRANSMISSION
enumerator DSI_COLOR_MODE_OFF
enumerator DSI_COLOR_MODE_ON
enumerator DSI_SHUTDOWN_PERIPHERAL
enumerator DSI_TURN_ON_PERIPHERAL
enumerator DSI_GENERIC_SHORT_WRITE_0_PARAM
enumerator DSI_GENERIC_SHORT_WRITE_1_PARAM
enumerator DSI_GENERIC_SHORT_WRITE_2_PARAM
enumerator DSI_GENERIC_READ_REQUEST_0_PARAM
enumerator DSI_GENERIC_READ_REQUEST_1_PARAM
enumerator DSI_GENERIC_READ_REQUEST_2_PARAM
enumerator DSI_DCS_SHORT_WRITE
enumerator DSI_DCS_SHORT_WRITE_PARAM
enumerator DSI_DCS_READ
enumerator DSI_EXECUTE_QUEUE
enumerator DSI_SET_MAXIMUM_RETURN_PACKET_SIZE
enumerator DSI_NULL_PACKET
enumerator DSI_BLANKING_PACKET
enumerator DSI_GENERIC_LONG_WRITE
enumerator DSI_DCS_LONG_WRITE
enumerator DSI_PICTURE_PARAMETER_SET
enumerator DSI_COMPRESSED_PIXEL_STREAM
enumerator DSI_LOOSELY_PACKED_PIXEL_STREAM_YCBCR20
enumerator DSI_PACKED_PIXEL_STREAM_YCBCR24
enumerator DSI_PACKED_PIXEL_STREAM_YCBCR16
enumerator DSI_PACKED_PIXEL_STREAM_30
enumerator DSI_PACKED_PIXEL_STREAM_36
enumerator DSI_PACKED_PIXEL_STREAM_YCBCR12
enumerator DSI_PACKED_PIXEL_STREAM_16
enumerator DSI_PACKED_PIXEL_STREAM_18
enumerator DSI_PIXEL_STREAM_3BYTE_18
enumerator DSI_PACKED_PIXEL_STREAM_24
enum SerialTransactionType

Values:

enumerator DSI_RX_ACKNOWLEDGE_AND_ERROR_REPORT
enumerator DSI_RX_END_OF_TRANSMISSION
enumerator DSI_RX_GENERIC_SHORT_READ_RESPONSE_1BYTE
enumerator DSI_RX_GENERIC_SHORT_READ_RESPONSE_2BYTE
enumerator DSI_RX_GENERIC_LONG_READ_RESPONSE
enumerator DSI_RX_DCS_LONG_READ_RESPONSE
enumerator DSI_RX_DCS_SHORT_READ_RESPONSE_1BYTE
enumerator DSI_RX_DCS_SHORT_READ_RESPONSE_2BYTE
enum DisplayCommandSet

Values:

enumerator DCS_NOP
enumerator DCS_SOFT_RESET
enumerator DCS_GET_COMPRESSION_MODE
enumerator DCS_GET_DISPLAY_ID
enumerator DCS_GET_ERROR_COUNT_ON_DSI
enumerator DCS_GET_RED_CHANNEL
enumerator DCS_GET_GREEN_CHANNEL
enumerator DCS_GET_BLUE_CHANNEL
enumerator DCS_GET_DISPLAY_STATUS
enumerator DCS_GET_POWER_MODE
enumerator DCS_GET_ADDRESS_MODE
enumerator DCS_GET_PIXEL_FORMAT
enumerator DCS_GET_DISPLAY_MODE
enumerator DCS_GET_SIGNAL_MODE
enumerator DCS_GET_DIAGNOSTIC_RESULT
enumerator DCS_ENTER_SLEEP_MODE
enumerator DCS_EXIT_SLEEP_MODE
enumerator DCS_ENTER_PARTIAL_MODE
enumerator DCS_ENTER_NORMAL_MODE
enumerator DCS_GET_IMAGE_CHECKSUM_RGB
enumerator DCS_GET_IMAGE_CHECKSUM_CT
enumerator DCS_EXIT_INVERT_MODE
enumerator DCS_ENTER_INVERT_MODE
enumerator DCS_SET_GAMMA_CURVE
enumerator DCS_SET_DISPLAY_OFF
enumerator DCS_SET_DISPLAY_ON
enumerator DCS_SET_COLUMN_ADDRESS
enumerator DCS_SET_PAGE_ADDRESS
enumerator DCS_WRITE_MEMORY_START
enumerator DCS_WRITE_LUT
enumerator DCS_READ_MEMORY_START
enumerator DCS_SET_PARTIAL_ROWS
enumerator DCS_SET_PARTIAL_COLUMNS
enumerator DCS_SET_SCROLL_AREA
enumerator DCS_SET_TEAR_OFF
enumerator DCS_SET_TEAR_ON
enumerator DCS_SET_ADDRESS_MODE
enumerator DCS_SET_SCROLL_START
enumerator DCS_EXIT_IDLE_MODE
enumerator DCS_ENTER_IDLE_MODE
enumerator DCS_SET_PIXEL_FORMAT
enumerator DCS_WRITE_MEMORY_CONTINUE
enumerator DCS_SET_3D_CONTROL
enumerator DCS_READ_MEMORY_CONTINUE
enumerator DCS_GET_3D_CONTROL
enumerator DCS_SET_VSYNC_TIMING
enumerator DCS_SET_TEAR_SCANLINE
enumerator DCS_GET_SCANLINE
enumerator DCS_SET_DISPLAY_BRIGHTNESS
enumerator DCS_GET_DISPLAY_BRIGHTNESS
enumerator DCS_WRITE_CONTROL_DISPLAY
enumerator DCS_GET_CONTROL_DISPLAY
enumerator DCS_WRITE_POWER_SAVE
enumerator DCS_GET_POWER_SAVE
enumerator DCS_SET_CABC_MIN_BRIGHTNESS
enumerator DCS_GET_CABC_MIN_BRIGHTNESS
enumerator DCS_READ_DDB_START
enumerator DCS_READ_PPS_START
enumerator DCS_READ_DDB_CONTINUE
enumerator DCS_READ_PPS_CONTINUE
enum DcsAddressMode

Values:

enumerator DCS_ADDRESS_MODE_MIRROR_Y
enumerator DCS_ADDRESS_MODE_MIRROR_X
enumerator DCS_ADDRESS_MODE_SWAP_XY
enumerator DCS_ADDRESS_MODE_REFRESH_BT
enumerator DCS_ADDRESS_MODE_BGR
enumerator DCS_ADDRESS_MODE_RGB
enumerator DCS_ADDRESS_MODE_LATCH_RL
enumerator DCS_ADDRESS_MODE_FLIP_X
enumerator DCS_ADDRESS_MODE_FLIP_Y
enum DcsPixelFormat

Values:

enumerator DCS_PIXEL_FMT_24BIT
enumerator DCS_PIXEL_FMT_18BIT
enumerator DCS_PIXEL_FMT_16BIT
enumerator DCS_PIXEL_FMT_12BIT
enumerator DCS_PIXEL_FMT_8BIT
enumerator DCS_PIXEL_FMT_3BIT
namespace Resource

Functions

void init(IDataSourceStream *stream)

Application calls this method to set source for graphics resourcess.

Graphics resource data such is compiled into a single binary file which the application must mount in some way (typically as a dedicated partition), then create a stream so the graphics library can access it.

Parameters:

stream – Where to obtain resource data from

IDataSourceStream *createSubStream(uint32_t offset, size_t size)

Graphics objects call this method to obtain access to resource data.

The resource compiler generates a header file containing resource descriptions. The application passes this to the appropriate object constructor, which in turn calls this function to access the related binary data (e.g. font or image bitmaps).

Parameters:

  • offset – Location within resource stream

  • size – Size of data BLOB

struct GlyphResource
#include <resource.h>

Describes glyph bitmap and position.

Public Members

uint16_t bmOffset

Offset relative to TypefaceResource::bmpOffset.

uint8_t width

Bitmap dimensions in pixels.

uint8_t height

Bitmap dimensions in pixels.

int8_t xOffset

X dist from cursor pos to UL corner.

int8_t yOffset

Y dist from cursor pos to UL corner.

uint8_t xAdvance

Distance to advance cursor (x axis)

struct GlyphBlock
#include <resource.h>

Identifies a run of unicode characters.

Public Members

uint16_t codePoint

First character code.

uint16_t length

Number of consecutive characters.

struct TypefaceResource
#include <resource.h>

Public Members

uint32_t bmOffset

Start of bitmap data in resource stream.

struct FontResource
#include <resource.h>
struct ImageResource
#include <resource.h>

References

Used by

Environment Variables

SoC support

  • esp32

  • esp32c2

  • esp32c3

  • esp32s2

  • esp32s3

  • esp8266

  • host

  • rp2040