#include <DeviceDrawable.h>

Public Types
enum	SubDeviceType { NO_SUB_DEVICE , SUB_DEVICE_4BPP , SUB_DEVICE_2BPP }

Public Member Functions
virtual Coord	getDisplayDimensions ()=0

virtual DeviceDrawable *	getSubDeviceFor (const Coord &where, const Coord &size, const color_t *palette, int paletteSize)=0

void	drawText (const Coord &where, const void font, int mag, const char text)

virtual void	internalDrawText (const Coord &where, const void font, int mag, const char text)=0

virtual void	drawBitmap (const Coord &where, const DrawableIcon *icon, bool selected)=0

virtual void	drawXBitmap (const Coord &where, const Coord &size, const uint8_t *data)=0

virtual void	drawBox (const Coord &where, const Coord &size, bool filled)=0

virtual void	drawCircle (const Coord &where, int radius, bool filled)=0

virtual void	drawPolygon (const Coord points[], int numPoints, bool filled)=0

virtual color_t	getUnderlyingColor (color_t col)

virtual void	transaction (bool isStarting, bool redrawNeeded)=0

virtual Coord	internalTextExtents (const void font, int mag, const char text, int *baseline)=0

Coord	textExtents (const void font, int mag, const char text, int *baseline)

virtual void	drawPixel (uint16_t x, uint16_t y)=0

Coord	textExtents (const void font, int mag, const char text)

void	startDraw ()

void	endDraw (bool needsDrawing=true)

void	setColors (color_t fg, color_t bg)

void	setDrawColor (color_t fg)

void	enableTcUnicode ()

bool	isTcUnicodeEnabled ()

UnicodeFontHandler *	getUnicodeHandler (bool enableIfNeeded=true)

void	setFontHandler (UnicodeFontHandler *handler)

SubDeviceType	getSubDeviceType ()

Protected Member Functions
virtual UnicodeFontHandler *	createFontHandler ()

void	setSubDeviceType (SubDeviceType s)

Protected Attributes
UnicodeFontHandler *	fontHandler = nullptr

color_t	backgroundColor = 0

color_t	drawColor = 0

SubDeviceType	subDeviceType = NO_SUB_DEVICE

Detailed Description

This is the interface that all graphical rendering devices extend from when using GraphicsDeviceRenderer. Instances of this map all the graphics primitives for each display type. You can use it yourself in code to present moderately complex displays without committing to a particular device. IE it would be trivial to switch between STM32 BCP LCD, Adafruit library, TFTeSPI and U8G2.

Example usage (assuming you have a drawable object pointer):

drawable->startDraw();
drawable->setDrawColor(RGB(0,0,0));
drawable->drawBox(Coord(0,0), Coord(320, 20), true);
drawable->setColors(RGB(255, 128, 0), RGB(0,0,0));
drawable->drawText(Coord(0,0), nullptr, 0, "hello world");
drawable->setDrawColor(RGB(0,0,255));
drawable->drawCircle(Coord(50, 50), 10, true);
drawable->endDraw();

The virtual methods add a small overhead, but allow us to easily support a very wide range of screens, in future supporting new graphical displays will be far easier, and less maintenance going forwards.

Member Function Documentation

◆ getDisplayDimensions()

virtual Coord tcgfx::DeviceDrawable::getDisplayDimensions ( )

pure virtual

Returns: the dimensions of the screen corrected for the current rotation

◆ getSubDeviceFor()

virtual DeviceDrawable* tcgfx::DeviceDrawable::getSubDeviceFor	(	const Coord &	where,
		const Coord &	size,
		const color_t *	palette,
		int	paletteSize
	)

pure virtual

Gets a sub device that can be rendered to that buffers a part of the screen up to a particular size, it is for sprites or partial buffers when the display is not fully double buffered. This method returns nullptr when such a sub-device is not available or not needed.

Parameters

width	the needed width in pixels
height	the needed height in pixels
bitsPerPx	the number of bits per pixel
palette	the palette that will be used

Returns: the sub display, or null if one is not available.

◆ drawText()

void DeviceDrawable::drawText	(	const Coord &	where,
		const void *	font,
		int	mag,
		const char *	text
	)

Draw text at the location requested using the font and color information provided. If the TcUnicode flag is enabled then all drawing will take place using TcUnicode, otherwise the native font support will be called, as implemented by internalDrawText.

Parameters

where	the position on the screen
font	the font to use
mag	the magnification of the font - if supported
text	the string to print

◆ drawBitmap()

virtual void tcgfx::DeviceDrawable::drawBitmap	(	const Coord &	where,
		const DrawableIcon *	icon,
		bool	selected
	)

pure virtual

Draw an icon bitmap at the specified location using the provided color, you can choose either the regular or selected icon. Note that not all icon formats are available on every display.

Parameters

where	the position of the screen
icon	the icon to draw
bg	the background color to draw behind the bitmap
selected	if the regular or selected icon should be used.

◆ drawXBitmap()

virtual void tcgfx::DeviceDrawable::drawXBitmap	(	const Coord &	where,
		const Coord &	size,
		const uint8_t *	data
	)

pure virtual

Draws an XBM at the provided location, of the given size, in the colours provided.

Parameters

where	the position on the screen
size	the size of the image in pixels
data	the raw bitmap data that should be presented
fgColor	the color for the bitmap to use
bgColor	the background color to fill first.

◆ drawBox()

virtual void tcgfx::DeviceDrawable::drawBox	(	const Coord &	where,
		const Coord &	size,
		bool	filled
	)

pure virtual

Draw either a hollow or filled both with the provided dimensions, in the color provided.

Parameters

where	the position of the box
size	the size of the box
color	the color of the box
filled	if true, the box is filled, otherwise it is an outline only.

◆ drawCircle()

virtual void tcgfx::DeviceDrawable::drawCircle	(	const Coord &	where,
		int	radius,
		bool	filled
	)

pure virtual

Draw a circle that is either filled or not filled on the screen

Parameters

where	the position of the circle centre
radius	the radius of the circle to draw
filled	true if it is to be filled, otherwise false

◆ drawPolygon()

virtual void tcgfx::DeviceDrawable::drawPolygon	(	const Coord	points[],
		int	numPoints,
		bool	filled
	)

pure virtual

Draw a triangle or polygon onto the screen as a series of points, if the driver supports it. All drivers support lines and triangles, but nothing above that is guaranteed.

It may be that a triangle can be filled but a polygon cant. If points is two it will try and use draw line and if points is 3 it will try to use draw triangle. There is no guarantee that the underlying driver will support anything above draw triangle, so check your driver before using more than 3 points. TcMenu graphics libraries never use this for anything higher than triangle, as it may not be supported.

◆ getUnderlyingColor()

virtual color_t tcgfx::DeviceDrawable::getUnderlyingColor ( color_t col )

inlinevirtual

the device must be able to map colors for situations where a palette is used. The default implementation just returns the original color.

Parameters

col	the color to find the underlying color for

Returns: the actual color mapping for the display.

◆ transaction()

virtual void tcgfx::DeviceDrawable::transaction	(	bool	isStarting,
		bool	redrawNeeded
	)

pure virtual

Indicates the start or end of a transaction, for core devices, it indicates the end of a rendering loop, for sub devices it means that we have finished with the

Parameters

isStarting
redrawNeeded

◆ internalTextExtents()

virtual Coord tcgfx::DeviceDrawable::internalTextExtents	(	const void *	font,
		int	mag,
		const char *	text,
		int *	baseline
	)

pure virtual

This is the internal implementation of textExtents for when TcUnicode is not in use, always prefer the use of textExtents unless you actually need to directly access the library functions.

Parameters

font	the font to get sizing for
mag	the magnification of the font if supported
text	the text to get the size of
baseline	optionally, the base line will be populated if this is provided.

Returns: the X and Y dimensions

◆ textExtents() [1/2]

Coord DeviceDrawable::textExtents	(	const void *	font,
		int	mag,
		const char *	text,
		int *	baseline
	)

gets the extents of the text, and optionally the baseline for the given font and text. The X axis of the returned Coord is the text width, the Y axis has the height, finally the base line is the descent.

Parameters

font	the font to get sizing for
mag	the magnification of the font if supported
text	the text to get the size of
baseline	optionally, the base line will be populated if this is provided.

Returns: the X and Y dimensions

◆ drawPixel()

virtual void tcgfx::DeviceDrawable::drawPixel	(	uint16_t	x,
		uint16_t	y
	)

pure virtual

Draw a pixel in the current draw color at the location provided. This should be implemented in the most optimal way possible for the platform

Parameters

x	the x location
y	the y location

◆ textExtents() [2/2]

Coord tcgfx::DeviceDrawable::textExtents	(	const void *	font,
		int	mag,
		const char *	text
	)

inline

Gets the width and height of the text in the font provided, returned in a Coord.

Parameters

font	the font to measure
mag	the magnification if supported
text	the text to measure

Returns: the X and Y dimensions

◆ startDraw()

void tcgfx::DeviceDrawable::startDraw ( )

inline

Should be called before starting any rendering onto a device, in case there's anything that needs to be done before drawing. This is a helper method that calls transaction()..

◆ endDraw()

void tcgfx::DeviceDrawable::endDraw ( bool needsDrawing = true )

inline

Should be called after you've finished drawing, to ensure that everything is completed and drawn. This is a helper method that calls transaction()..

Parameters

needsDrawing true if there were changes, (default is true)

◆ setColors()

void tcgfx::DeviceDrawable::setColors	(	color_t	fg,
		color_t	bg
	)

inline

set the draw color and background color to be used in subsequent operations

Parameters

fg	the foreground / draw color
bg	the background color

◆ setDrawColor()

void tcgfx::DeviceDrawable::setDrawColor ( color_t fg )

inline

Sets only the drawing color, leaving the background as it was before.

Parameters

fg	foreground / drawing color.

◆ enableTcUnicode()

void tcgfx::DeviceDrawable::enableTcUnicode ( )

inline

Enables the use of tcUnicode characters, and at this point the drawable assumes all fonts are tcUnicode or Adafruit GFX. This only prevents creation of the handler if called before getting the font handler.

Parameters

enabled true if TcUnicode support is to be enabled, otherwise false.

◆ isTcUnicodeEnabled()

bool tcgfx::DeviceDrawable::isTcUnicodeEnabled ( )

inline

Check if TcUnicode is enabled. Useful before calling getFontHandler to ensure the support is on.

Returns: true if on, otherwise false

◆ getUnicodeHandler()

UnicodeFontHandler * DeviceDrawable::getUnicodeHandler ( bool enableIfNeeded = true )

Gets hold of the TcUnicode font handler that can render text onto the display. It has features similar to print and Adafruit GFX that make rendering unicode character with UTF-8 easier.

Parameters

enableIfNeeded if true, the TcUnicode enable flag will be enabled if needed.

Returns: the font handler if unicode is enabled, otherwise nullptr.

◆ setFontHandler()

void tcgfx::DeviceDrawable::setFontHandler ( UnicodeFontHandler * handler )

inline

If a native font handler has already been created, avoid creating a second instance and give the drawable the same instance to save memory.

Parameters

handler pointer to the existing handler

◆ getSubDeviceType()

SubDeviceType tcgfx::DeviceDrawable::getSubDeviceType ( )

inline

Returns: the type of sub-device that is supported by this display drawable.

◆ createFontHandler()

UnicodeFontHandler * DeviceDrawable::createFontHandler ( )

protectedvirtual

It is best that all device drawables override this with an optimal implementation rather than rely on the default one which indirects through draw pixel here adding a layer of latency

Returns: a font handler

◆ setSubDeviceType()

void tcgfx::DeviceDrawable::setSubDeviceType ( SubDeviceType s )

inlineprotected

Normally used internally by extension classes to set the type of subdevice they can support. Defaults to none.

Parameters

s	the type of sub-device supported.

The documentation for this class was generated from the following files:

src/graphics/DeviceDrawable.h
src/graphics/DeviceDrawable.cpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ getDisplayDimensions()

◆ getSubDeviceFor()

◆ drawText()

◆ drawBitmap()

◆ drawXBitmap()

◆ drawBox()

◆ drawCircle()

◆ drawPolygon()

◆ getUnderlyingColor()

◆ transaction()

◆ internalTextExtents()

◆ textExtents() [1/2]

◆ drawPixel()

◆ textExtents() [2/2]

◆ startDraw()

◆ endDraw()

◆ setColors()

◆ setDrawColor()

◆ enableTcUnicode()

◆ isTcUnicodeEnabled()

◆ getUnicodeHandler()

◆ setFontHandler()

◆ getSubDeviceType()

◆ createFontHandler()

◆ setSubDeviceType()