tcMenu
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
tcgfx::DeviceDrawable Class Referenceabstract

#include <DeviceDrawable.h>

Public Types

enum  SubDeviceType { NO_SUB_DEVICE , SUB_DEVICE_4BPP , SUB_DEVICE_2BPP }
 

Public Member Functions

virtual Coord getDisplayDimensions ()=0
 
virtual DeviceDrawablegetSubDeviceFor (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
widththe needed width in pixels
heightthe needed height in pixels
bitsPerPxthe number of bits per pixel
palettethe 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
wherethe position on the screen
fontthe font to use
magthe magnification of the font - if supported
textthe 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
wherethe position of the screen
iconthe icon to draw
bgthe background color to draw behind the bitmap
selectedif 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
wherethe position on the screen
sizethe size of the image in pixels
datathe raw bitmap data that should be presented
fgColorthe color for the bitmap to use
bgColorthe 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
wherethe position of the box
sizethe size of the box
colorthe color of the box
filledif 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
wherethe position of the circle centre
radiusthe radius of the circle to draw
filledtrue 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
colthe 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
fontthe font to get sizing for
magthe magnification of the font if supported
textthe text to get the size of
baselineoptionally, 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
fontthe font to get sizing for
magthe magnification of the font if supported
textthe text to get the size of
baselineoptionally, 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
xthe x location
ythe 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
fontthe font to measure
magthe magnification if supported
textthe 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
needsDrawingtrue 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
fgthe foreground / draw color
bgthe background color

◆ setDrawColor()

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

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

Parameters
fgforeground / 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
enabledtrue 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
enableIfNeededif 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
handlerpointer 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
sthe type of sub-device supported.

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