Skip to main content
Version: 4.16

HAL

Hardware Abstraction Layer. Contains functions that are specific to the hardware platform the code is running on.

Inherited by: HALSDL2

Public Types#

enumFrameRefreshStrategy { REFRESH_STRATEGY_DEFAULT, REFRESH_STRATEGY_OPTIM_SINGLE_BUFFER_TFT_CTRL, REFRESH_STRATEGY_PARTIAL_FRAMEBUFFER }
A list of available frame refresh strategies.
enumRenderingVariant { SOFTWARE, HARDWARE }
A list of rendering variants.

Public Functions#

virtual voidallowDMATransfers()
Allow the DMA to start transfers.
virtual voidbackPorchExited()
Has to be called from within the LCD IRQ rutine when the Back Porch Exit is reached.
voidblitCopy(const uint16_t pSrc, const uint8_t pClut, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, uint8_t alpha, bool hasTransparentPixels, uint16_t dstWidth, Bitmap::BitmapFormat srcFormat, Bitmap::BitmapFormat dstFormat)
Blits a 2D source-array to the framebuffer performing alpha-blending as specified.
virtual voidblitCopy(const uint16_t * pSrc, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, uint8_t alpha, bool hasTransparentPixels)
Blits a 2D source-array to the framebuffer performing alpha-blending as specified using the default lcd format.
virtual voidblitCopy(const uint16_t * pSrc, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, uint8_t alpha, bool hasTransparentPixels, uint16_t dstWidth, Bitmap::BitmapFormat srcFormat, Bitmap::BitmapFormat dstFormat)
Blits a 2D source-array to the framebuffer performing alpha-blending as specified.
virtual voidblitCopyARGB8888(const uint16_t * pSrc, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, uint8_t alpha)
Blits a 2D source-array to the framebuffer performing per-pixel alpha blending.
virtual voidblitCopyGlyph(const uint8_t * pSrc, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, colortype color, uint8_t alpha, BlitOperations operation)
Blits a 4bpp or 8bpp glyph - maybe use the same method and supply additional color mode arg.
virtual voidblitFill(colortype color, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t alpha)
Blits a color value to the framebuffer performing alpha-blending as specified.
virtual voidblitFill(colortype color, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t alpha, uint16_t dstWidth, Bitmap::BitmapFormat dstFormat)
Blits a color value to the framebuffer performing alpha-blending as specified.
virtual boolblockCopy(void RESTRICT dest, const void RESTRICT src, uint32_t numBytes)
This function performs a platform-specific memcpy, if supported by the hardware.
virtual voidconfigureInterrupts() =0
Configures the interrupts relevant for TouchGFX.
virtual uint16_tconfigurePartialFrameBuffer(const uint16_t x, const uint16_t y, const uint16_t width, const uint16_t height)
Configures a partial framebuffer as current framebuffer.
virtual uint16_t *copyFBRegionToMemory(Rect meAbs)
Copies a region of the currently displayed framebuffer to memory.
virtual uint16_t *copyFBRegionToMemory(Rect meAbs, uint16_t * dst, uint32_t stride)
Copies a region of the currently displayed framebuffer to a buffer.
virtual voiddisableInterrupts() =0
Disables the DMA and LCD interrupts.
virtual voiddrawDrawableInDynamicBitmap(Drawable & drawable, BitmapId bitmapId)
Render a Drawable and its widgets into a dynamic bitmap.
virtual voiddrawDrawableInDynamicBitmap(Drawable & drawable, BitmapId bitmapId, const Rect & rect)
Render a Drawable and its widgets into a dynamic bitmap.
voidenableDMAAcceleration(const bool enable)
Sets a flag to allow use of DMA operations to speed up drawing operations.
virtual voidenableInterrupts() =0
Enables the DMA and LCD interrupts.
virtual voidenableLCDControllerInterrupt() =0
Configure the LCD controller to fire interrupts at VSYNC.
voidenableMCULoadCalculation(bool enabled)
This method sets a flag that determines if generic HAL should calculate MCU load based on concrete MCU instrumentation.
virtual voidflushDMA()
This function blocks until the DMA queue (containing BlitOps) is empty.
virtual voidflushFrameBuffer()
This function is called whenever the framework has performed a complete draw.
virtual voidflushFrameBuffer(const Rect & rect)
This function is called whenever the framework has performed a partial draw.
voidfrontPorchEntered()
Has to be called from within the LCD IRQ routine when the Front Porch Entry is reached.
uint16_t *getAnimationStorage() const
Gets the optional framebuffer used for animation storage.
LCD *getAuxiliaryLCD()
Get the auxiliary LCD class attached to the HAL instance if any.
virtual BlitOperationsgetBlitCaps()
Function for obtaining the blit capabilities of the concrete HAL implementation.
ButtonController *getButtonController() const
Gets the associated ButtonController.
uint32_tgetCPUCycles()
Gets the current cycle counter.
uint16_tgetDisplayHeight() const
Gets display height.
DisplayOrientationgetDisplayOrientation() const
Gets the current display orientation.
uint16_tgetDisplayWidth() const
Gets display width.
virtual DMATypegetDMAType()
Function for obtaining the DMA type of the concrete DMA implementation.
uint8_tgetFingerSize() const
Gets the finger size in pixels.
virtual FlashDataReader *getFlashDataReader() const
Gets the flash data reader.
FrameBufferAllocator *getFrameBufferAllocator()
Gets the framebuffer allocator.
FrameRefreshStrategygetFrameRefreshStrategy() const
Used internally by TouchGFX core to manage the timing and process of drawing into the framebuffer.
Gestures *getGestures()
Get the Gesture class attached to the HAL instance.
uint32_tgetLCDRefreshCount()
Returns the number of VSync interrupts between the current drawing operation and the last drawing operation, i.e.
uint8_tgetMCULoadPct() const
Gets the current MCU load.
virtual uint16_tgetTFTCurrentLine()
Get the current line (Y) of the TFT controller.
virtual uint16_t *getTFTFrameBuffer() const =0
Gets the framebuffer address used by the TFT controller.
int8_tgetTouchSampleRate() const
Gets the number of ticks between each touch screen sample.
HAL(DMA_Interface & dmaInterface, LCD & display, TouchController & touchCtrl, uint16_t width, uint16_t height)
Initializes a new instance of the HAL class.
voidinitialize()
This function is responsible for initializing the entire framework.
voidlockDMAToFrontPorch(bool enableLock)
Function to set whether the DMA transfers are locked to the TFT update cycle.
virtual uint16_t *lockFrameBuffer()
Waits for the framebuffer to become available for use (i.e.
virtual voidregisterEventListener(UIEventListener & listener)
Registers an event handler implementation with the underlying event system.
voidregisterTaskDelayFunction(void(*)(uint16_t) delayF)
Registers a function capable of delaying GUI task execution.
virtual boolsampleKey(uint8_t & key)
Sample external key event.
voidsetAuxiliaryLCD(LCD * auxLCD)
Set an auxiliary LCD class to be used for offscreen rendering.
voidsetButtonController(ButtonController * btnCtrl)
Stores a pointer to an instance of a specific implementation of a ButtonController.
virtual voidsetDisplayOrientation(DisplayOrientation orientation)
Sets the desired display orientation (landscape or portrait).
voidsetDragThreshold(uint8_t value)
Configure the threshold for reporting drag events.
voidsetFingerSize(uint8_t size)
Sets the finger size in pixels.
voidsetFrameBufferAllocator(FrameBufferAllocator * allocator)
Sets a framebuffer allocator.
virtual voidsetFrameBufferStartAddresses(void frameBuffer, void doubleBuffer, void * animationStorage)
Sets framebuffer start addresses.
voidsetFrameRateCompensation(bool enabled)
Enables or disables compensation for lost frames.
boolsetFrameRefreshStrategy(FrameRefreshStrategy s)
Set a specific strategy for handling timing and mechanism of framebuffer drawing.
voidsetMCUActive(bool active)
Register if MCU is active by measuring cpu cycles.
voidsetMCUInstrumentation(MCUInstrumentation * mcuInstr)
Stores a pointer to an instance of an MCU specific instrumentation class.
voidsetRenderingVariant(RenderingVariant variant)
Set current rendering variant for cache maintenance.
voidsetTouchSampleRate(int8_t sampleRateInTicks)
Sets the number of ticks between each touch screen sample.
voidsignalDMAInterrupt()
Notify the framework that a DMA interrupt has occurred.
voidswapFrameBuffers()
Swaps the two framebuffers.
virtual voidtaskDelay(uint16_t ms)
Delay GUI task execution by number of milliseconds.
virtual voidtaskEntry()
Main event loop.
virtual voidunlockFrameBuffer()
Unlocks the framebuffer (MUST be called exactly once for each call to lockFrameBuffer()).
voidvSync()
Called by the VSync interrupt.
virtual ~HAL()
Finalizes an instance of the HAL class.
HAL *getInstance()
Gets the HAL instance.
LCD &lcd()
Gets a reference to the LCD.

Protected Functions#

virtual boolbeginFrame()
Called when beginning to rendering a frame.
virtual voidendFrame()
Called when a rendering pass is completed.
virtual voidFlushCache()
Flush D-Cache.
uint16_t *getClientFrameBuffer()
Gets client framebuffer.
virtual voidInvalidateCache()
Invalidate D-Cache.
virtual voidnoTouch()
Called by the touch driver to indicate that no touch is currently detected.
virtual voidperformDisplayOrientationChange()
Perform the actual display orientation change.
virtual voidsetTFTFrameBuffer(uint16_t * address) =0
Sets the framebuffer address used by the TFT controller.
virtual voidtick()
This function is called at each timer tick, depending on platform implementation.
virtual voidtouch(int32_t x, int32_t y)
Called by the touch driver to indicate a touch.

Public Attributes#

uint16_tDISPLAY_HEIGHT
The height of the LCD display in pixels.
DisplayRotationDISPLAY_ROTATION
The rotation from display to framebuffer.
uint16_tDISPLAY_WIDTH
The width of the LCD display in pixels.
uint16_tFRAME_BUFFER_HEIGHT
The height of the framebuffer in pixels.
uint16_tFRAME_BUFFER_WIDTH
The width of the framebuffer in pixels.
boolUSE_ANIMATION_STORAGE
Is animation storage enabled?
boolUSE_DOUBLE_BUFFERING
Is double buffering enabled?

Protected Attributes#

LCD *auxiliaryLCD
Auxiliary LCD class used to render Drawables into dynamic bitmaps.
ButtonController *buttonController
A reference to an optional ButtonController.
DMA_Interface &dma
A reference to the DMA interface.
uint8_tfingerSize
The radius of the finger in pixels.
uint16_t *frameBuffer0
Pointer to the first framebuffer.
uint16_t *frameBuffer1
Pointer to the second framebuffer.
uint16_t *frameBuffer2
Pointer to the optional third framebuffer used for animation storage.
FrameBufferAllocator *frameBufferAllocator
A reference to an optional FrameBufferAllocator.
boolframeBufferUpdatedThisFrame
True if something was drawn in the current frame.
Gesturesgestures
Class for low-level interpretation of touch events.
LCD &lcdRef
A reference to the LCD.
boollockDMAToPorch
Whether or not to lock DMA transfers with TFT porch signal.
MCUInstrumentation *mcuInstrumentation
A reference to an optional MCU instrumentation.
DisplayOrientationnativeDisplayOrientation
Contains the native display orientation. If desired orientation is different, apply rotation.
RectpartialFrameBufferRect
The region of the screen covered by the partial framebuffer.
FrameRefreshStrategyrefreshStrategy
The selected display refresh strategy.
void(*taskDelayFunc
Pointer to a function that can delay GUI task for a number of milliseconds.
TouchController &touchController
A reference to the touch controller.
boolisDrawing
True if currently in the process of rendering a screen.

Public Types Documentation#

FrameRefreshStrategy#

A list of available frame refresh strategies.

REFRESH_STRATEGY_DEFAULTIf not explicitly set, this strategy is used.
REFRESH_STRATEGY_OPTIM_SINGLE_BUFFER_TFT_CTRLStrategy optimized for single framebuffer on systems with TFT controller.
REFRESH_STRATEGY_PARTIAL_FRAMEBUFFERStrategy using less than a full framebuffer.

RenderingVariant#

A list of rendering variants.

SOFTWARE
HARDWARE

Public Functions Documentation#

allowDMATransfers#

virtual void allowDMATransfers()

Allow the DMA to start transfers.

Front Porch Entry is a good place to call this.

backPorchExited#

virtual void backPorchExited()

Has to be called from within the LCD IRQ rutine when the Back Porch Exit is reached.

Has to be called from within the LCD IRQ rutine when the Back Porch Exit is reached.

blitCopy#

void blitCopy(const uint16_t *pSrc ,
const uint8_t *pClut ,
uint16_tx ,
uint16_ty ,
uint16_twidth ,
uint16_theight ,
uint16_tsrcWidth ,
uint8_talpha ,
boolhasTransparentPixels ,
uint16_tdstWidth ,
Bitmap::BitmapFormatsrcFormat ,
Bitmap::BitmapFormatdstFormat
)

Blits a 2D source-array to the framebuffer performing alpha-blending as specified.

Parameters:
pSrcThe source-array pointer (points to first value to copy)
pClutThe CLUT pointer (points to CLUT header data which include the type and size of this CLUT followed by colors data)
xThe destination x coordinate on the framebuffer.
yThe destination y coordinate on the framebuffer.
widthThe width desired area of the source 2D array.
heightThe height of desired area of the source 2D array.
srcWidthThe distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
alphaThe alpha value to use for blending (255 = solid, no blending)
hasTransparentPixelsIf true, this data copy contains transparent pixels and require hardware support for that to be enabled.
dstWidthThe distance (in elements) from first value of first line, to first value of second line (the destination 2D array width)
srcFormatThe source buffer color format (default is the framebuffer format)
dstFormatThe destination buffer color format (default is the framebuffer format)
Note

Alpha=255 is assumed "solid" and shall be used if HAL does not support BLIT_OP_COPY_WITH_ALPHA.

blitCopy#

virtual void blitCopy(const uint16_t *pSrc ,
uint16_tx ,
uint16_ty ,
uint16_twidth ,
uint16_theight ,
uint16_tsrcWidth ,
uint8_talpha ,
boolhasTransparentPixels
)

Blits a 2D source-array to the framebuffer performing alpha-blending as specified using the default lcd format.

Parameters:
pSrcThe source-array pointer (points to first value to copy)
xThe destination x coordinate on the framebuffer.
yThe destination y coordinate on the framebuffer.
widthThe width desired area of the source 2D array.
heightThe height of desired area of the source 2D array.
srcWidthThe distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
alphaThe alpha value to use for blending (255 = solid, no blending)
hasTransparentPixelsIf true, this data copy contains transparent pixels and require hardware support for that to be enabled.
Note

Alpha=255 is assumed "solid" and shall be used if HAL does not support BLIT_OP_COPY_WITH_ALPHA.

blitCopy#

virtual void blitCopy(const uint16_t *pSrc ,
uint16_tx ,
uint16_ty ,
uint16_twidth ,
uint16_theight ,
uint16_tsrcWidth ,
uint8_talpha ,
boolhasTransparentPixels ,
uint16_tdstWidth ,
Bitmap::BitmapFormatsrcFormat ,
Bitmap::BitmapFormatdstFormat
)

Blits a 2D source-array to the framebuffer performing alpha-blending as specified.

Parameters:
pSrcThe source-array pointer (points to first value to copy)
xThe destination x coordinate on the framebuffer.
yThe destination y coordinate on the framebuffer.
widthThe width desired area of the source 2D array.
heightThe height of desired area of the source 2D array.
srcWidthThe distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
alphaThe alpha value to use for blending (255 = solid, no blending)
hasTransparentPixelsIf true, this data copy contains transparent pixels and require hardware support for that to be enabled.
dstWidthThe distance (in elements) from first value of first line, to first value of second line (the destination 2D array width)
srcFormatThe source buffer color format (default is the framebuffer format)
dstFormatThe destination buffer color format (default is the framebuffer format)
Note

Alpha=255 is assumed "solid" and shall be used if HAL does not support BLIT_OP_COPY_WITH_ALPHA.

blitCopyARGB8888#

virtual void blitCopyARGB8888(const uint16_t *pSrc ,
uint16_tx ,
uint16_ty ,
uint16_twidth ,
uint16_theight ,
uint16_tsrcWidth ,
uint8_talpha
)

Blits a 2D source-array to the framebuffer performing per-pixel alpha blending.

Parameters:
pSrcThe source-array pointer (points to first value to copy)
xThe destination x coordinate on the framebuffer.
yThe destination y coordinate on the framebuffer.
widthThe width desired area of the source 2D array.
heightThe height of desired area of the source 2D array.
srcWidthThe distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
alphaThe alpha value to use for blending. This is applied on every pixel, in addition to the per-pixel alpha value (255 = solid, no blending)

blitCopyGlyph#

virtual void blitCopyGlyph(const uint8_t *pSrc ,
uint16_tx ,
uint16_ty ,
uint16_twidth ,
uint16_theight ,
uint16_tsrcWidth ,
colortypecolor ,
uint8_talpha ,
BlitOperationsoperation
)

Blits a 4bpp or 8bpp glyph - maybe use the same method and supply additional color mode arg.

Parameters:
pSrcThe source-array pointer (points to first value to copy)
xThe destination x coordinate on the framebuffer.
yThe destination y coordinate on the framebuffer.
widthThe width desired area of the source 2D array.
heightThe height of desired area of the source 2D array.
srcWidthThe distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
colorColor of the text.
alphaThe alpha value to use for blending (255 = solid, no blending)
operationThe operation type to use for blit copy.

blitFill#

virtual void blitFill(colortypecolor ,
uint16_tx ,
uint16_ty ,
uint16_twidth ,
uint16_theight ,
uint8_talpha
)

Blits a color value to the framebuffer performing alpha-blending as specified.

Parameters:
colorThe desired fill-color.
xThe destination x coordinate on the framebuffer.
yThe destination y coordinate on the framebuffer.
widthThe width desired area of the source 2D array.
heightThe height of desired area of the source 2D array.
alphaThe alpha value to use for blending (255 = solid, no blending)
Note

Alpha=255 is assumed "solid" and shall be used if HAL does not support BLIT_OP_FILL_WITH_ALPHA.

blitFill#

virtual void blitFill(colortypecolor ,
uint16_tx ,
uint16_ty ,
uint16_twidth ,
uint16_theight ,
uint8_talpha ,
uint16_tdstWidth ,
Bitmap::BitmapFormatdstFormat
)

Blits a color value to the framebuffer performing alpha-blending as specified.

Parameters:
colorThe desired fill-color.
xThe destination x coordinate on the framebuffer.
yThe destination y coordinate on the framebuffer.
widthThe width desired area of the source 2D array.
heightThe height of desired area of the source 2D array.
alphaThe alpha value to use for blending (255 = solid, no blending)
dstWidthThe distance (in elements) from first value of first line, to first value of second line (the destination 2D array width)
dstFormatThe destination buffer color format (default is the framebuffer format)
Note

Alpha=255 is assumed "solid" and shall be used if HAL does not support BLIT_OP_FILL_WITH_ALPHA.

blockCopy#

virtual bool blockCopy(void *RESTRICTdest ,
const void *RESTRICTsrc ,
uint32_tnumBytes
)

This function performs a platform-specific memcpy, if supported by the hardware.

Parameters:
destPointer to destination memory.
srcPointer to source memory.
numBytesNumber of bytes to copy.
Returns:

true if the copy succeeded, false if copy was not performed.

Reimplemented by: touchgfx::HALSDL2::blockCopy

configureInterrupts#

virtual void configureInterrupts()=0

Configures the interrupts relevant for TouchGFX.

This primarily entails setting the interrupt priorities for the DMA and LCD interrupts.

Reimplemented by: touchgfx::HALSDL2::configureInterrupts

configurePartialFrameBuffer#

virtual uint16_t configurePartialFrameBuffer(const uint16_tx ,
const uint16_ty ,
const uint16_twidth ,
const uint16_theight
)

Configures a partial framebuffer as current framebuffer.

This method uses the assigned FrameBufferAllocator to allocate block of compatible dimensions. The height of the allocated block is returned.

Parameters:
xThe absolute x coordinate of the block on the screen.
yThe absolute y coordinate of the block on the screen.
widthThe width of the block.
heightThe height of the block requested.
Returns:

The height of the block allocated.

copyFBRegionToMemory#

virtual uint16_t * copyFBRegionToMemory(RectmeAbs)

Copies a region of the currently displayed framebuffer to memory.

Used for e.g. SlideTransition and for displaying pre-rendered drawables e.g. in animations where redrawing the drawable is not necessary.

Parameters:
meAbsThe framebuffer region to copy.
Returns:

A pointer to the memory address containing the copy of the framebuffer.

Note

Requires animation storage to be present.

copyFBRegionToMemory#

virtual uint16_t * copyFBRegionToMemory(RectmeAbs ,
uint16_t *dst ,
uint32_tstride
)

Copies a region of the currently displayed framebuffer to a buffer.

Used for e.g. SlideTransition and for displaying pre-rendered drawables e.g. in animations where redrawing the drawable is not necessary. The buffer can e.g. be a dynamic bitmap.

Parameters:
meAbsThe framebuffer region to copy.
dstAddress of the buffer to store the copy in.
strideThe width of the target buffer (row length).
Returns:

A pointer to the memory address containing the copy of the framebuffer.

Note

Requires animation storage to be present.

disableInterrupts#

virtual void disableInterrupts()=0

Disables the DMA and LCD interrupts.

Reimplemented by: touchgfx::HALSDL2::disableInterrupts

drawDrawableInDynamicBitmap#

virtual void drawDrawableInDynamicBitmap(Drawable &drawable ,
BitmapIdbitmapId
)

Render a Drawable and its widgets into a dynamic bitmap.

Parameters:
drawableA reference on the Drawable object to render.
bitmapIdDynamic bitmap to be used as a rendertarget.

drawDrawableInDynamicBitmap#

virtual void drawDrawableInDynamicBitmap(Drawable &drawable ,
BitmapIdbitmapId ,
const Rect &rect
)

Render a Drawable and its widgets into a dynamic bitmap.

Only the specified Rect region is updated.

Parameters:
drawableA reference on the Drawable object to render.
bitmapIdDynamic bitmap to be used as a rendertarget.
rectRegion to update.

enableDMAAcceleration#

void enableDMAAcceleration(const boolenable)

Sets a flag to allow use of DMA operations to speed up drawing operations.

Parameters:
enableTrue to enable, false to disable.
See also:

enableInterrupts#

virtual void enableInterrupts()=0

Enables the DMA and LCD interrupts.

Reimplemented by: touchgfx::HALSDL2::enableInterrupts

enableLCDControllerInterrupt#

virtual void enableLCDControllerInterrupt()=0

Configure the LCD controller to fire interrupts at VSYNC.

Called automatically once TouchGFX initialization has completed.

Reimplemented by: touchgfx::HALSDL2::enableLCDControllerInterrupt

enableMCULoadCalculation#

void enableMCULoadCalculation(boolenabled)

This method sets a flag that determines if generic HAL should calculate MCU load based on concrete MCU instrumentation.

Parameters:
enabledIf true, set flag to update MCU load.

flushDMA#

virtual void flushDMA()

This function blocks until the DMA queue (containing BlitOps) is empty.

flushFrameBuffer#

virtual void flushFrameBuffer()

This function is called whenever the framework has performed a complete draw.

On some platforms, a local framebuffer needs to be pushed to the display through a SPI channel or similar. Implement that functionality here. This function is called whenever the framework has performed a complete draw.

Reimplemented by: touchgfx::HALSDL2::flushFrameBuffer

flushFrameBuffer#

virtual void flushFrameBuffer(const Rect &rect)

This function is called whenever the framework has performed a partial draw.

Parameters:
rectThe area of the screen that has been drawn, expressed in absolute coordinates.
See also:

Reimplemented by: touchgfx::HALSDL2::flushFrameBuffer

frontPorchEntered#

Has to be called from within the LCD IRQ routine when the Front Porch Entry is reached.

getAnimationStorage#

uint16_t * getAnimationStorage()const

Gets the optional framebuffer used for animation storage.

Returns:

The address or 0 if unused.

getAuxiliaryLCD#

Get the auxiliary LCD class attached to the HAL instance if any.

Returns:

A pointer on the axiliary LCD class attached to the HAL instance.

getBlitCaps#

virtual BlitOperations getBlitCaps()

Function for obtaining the blit capabilities of the concrete HAL implementation.

As default, will return whatever blitcaps are reported by the associated DMA object.

DMA operations can be disabled by calling enableDMAAcceleration(bool).

Returns:

a bitmask of the supported blitcaps.

See also:

getButtonController#

ButtonController * getButtonController()const

Gets the associated ButtonController.

Returns:

A pointer to the ButtonController, or zero if no ButtonController has been set.

getCPUCycles#

uint32_t getCPUCycles()

Gets the current cycle counter.

Returns:

the cycle counter.

getDisplayHeight#

uint16_t getDisplayHeight()const

Gets display height.

Returns:

The display height.

getDisplayOrientation#

DisplayOrientation getDisplayOrientation()const

Gets the current display orientation.

Will be equal to the native orientation of the display unless setDisplayOrientation has been explicitly called earlier.

Returns:

The current display orientation.

getDisplayWidth#

uint16_t getDisplayWidth()const

Gets display width.

Returns:

The display width.

getDMAType#

virtual DMAType getDMAType()

Function for obtaining the DMA type of the concrete DMA implementation.

As default, will return DMA_TYPE_GENERIC type value.

Returns:

a DMAType value of the concrete DMA implementation.

getFingerSize#

uint8_t getFingerSize()const

Gets the finger size in pixels.

Returns:

The size of the finger in pixels, 1 is the default value.

getFlashDataReader#

virtual FlashDataReader * getFlashDataReader()const

Gets the flash data reader.

This method must be implemented in subclasses that uses a FlashDataReader object.

Returns:

getFrameBufferAllocator#

FrameBufferAllocator * getFrameBufferAllocator()

Gets the framebuffer allocator.

Returns:

The framebuffer allocator.

getFrameRefreshStrategy#

FrameRefreshStrategy getFrameRefreshStrategy()const

Used internally by TouchGFX core to manage the timing and process of drawing into the framebuffer.

Returns:

Current frame refresh strategy.

See also:

getGestures#

Gestures * getGestures()

Get the Gesture class attached to the HAL instance.

Returns:

A pointer to the Gestures object.

getLCDRefreshCount#

uint32_t getLCDRefreshCount()

Returns the number of VSync interrupts between the current drawing operation and the last drawing operation, i.e.

the number of lost frames.

Returns:

Number of VSync since previous draw.

getMCULoadPct#

uint8_t getMCULoadPct()const

Gets the current MCU load.

Returns:

mcuLoadPct the MCU Load in %.

getTFTCurrentLine#

virtual uint16_t getTFTCurrentLine()

Get the current line (Y) of the TFT controller.

This function is used to obtain the progress of the TFT controller. More specifically, the line (or Y-value) currently being transferred.

Note: The value must be adjusted to account for vertical back porch before returning, such that the value is always within the range of [0; actual display height in pixels[

It is used for the REFRESH_STRATEGY_OPTIM_SINGLE_BUFFER_TFT_CTRL frame refresh strategy in order to synchronize framebuffer drawing with TFT controller progress. If this strategy is used, the concrete HAL subclass must provide an override of this function that returns correct line value. If this strategy is not used, then the getTFTCurrentLine function is never called and can be disregarded.

Returns:

In this default implementation, 0xFFFF is returned to signify "not implemented".

getTFTFrameBuffer#

virtual uint16_t * getTFTFrameBuffer()const =0

Gets the framebuffer address used by the TFT controller.

Returns:

The address of the framebuffer currently being displayed on the TFT.

Reimplemented by: touchgfx::HALSDL2::getTFTFrameBuffer

getTouchSampleRate#

int8_t getTouchSampleRate()const

Gets the number of ticks between each touch screen sample.

Returns:

Number of ticks between each touch screen sample.

HAL#

HAL(DMA_Interface &dmaInterface ,
LCD &display ,
TouchController &touchCtrl ,
uint16_twidth ,
uint16_theight
)

Initializes a new instance of the HAL class.

Parameters:
dmaInterfaceReference to the DMA interface.
displayReference to the LCD.
touchCtrlReference to the touch controller.
widthThe width of the LCD display, in pixels.
heightThe height of the LCD display, in pixels.

initialize#

void initialize()

This function is responsible for initializing the entire framework.

lockDMAToFrontPorch#

void lockDMAToFrontPorch(boolenableLock)

Function to set whether the DMA transfers are locked to the TFT update cycle.

If locked, DMA transfer will not begin until the TFT controller has finished updating the display. If not locked, DMA transfers will begin as soon as possible. Default is true (DMA is locked with TFT).

Disabling the lock will in most cases significantly increase rendering performance. It is therefore strongly recommended to disable it. Depending on platform this may in rare cases cause rendering problems (visible tearing on display). Please see the chapter "Optimizing DMA During TFT Controller Access" for details on this setting.

Parameters:
enableLockTrue to lock DMA transfers to the front porch signal. Conservative, default setting. False to disable, which will normally yield substantial performance improvement.
Note

This setting only has effect when using double buffering.

lockFrameBuffer#

virtual uint16_t * lockFrameBuffer()

Waits for the framebuffer to become available for use (i.e.

not used by DMA transfers).

Returns:

A pointer to the beginning of the currently used framebuffer.

Note

Function blocks until framebuffer is available. Client code MUST call unlockFrameBuffer() when framebuffer operation has completed.

registerEventListener#

virtual void registerEventListener(UIEventListener &listener)

Registers an event handler implementation with the underlying event system.

The actual HAL implementation decides whether or not multiple UIEventListener instances are allowed (including execution order).

Parameters:
listenerThe listener to register.

registerTaskDelayFunction#

void registerTaskDelayFunction(void(*)(uint16_t)delayF)

Registers a function capable of delaying GUI task execution.

In order to make use of the HAL::taskDelay function, a delay function must be registered by calling this function. Usually the delay function would be OSWrappers::taskDelay.

Parameters:
delayFA pointer to a function returning void with an uint16_t parameter specifying number of milliseconds to delay.
Note

The task delay capability is only used when the frame refresh strategy REFRESH_STRATEGY_OPTIM_SINGLE_BUFFER_TFT_CTRL is selected. Otherwise it is not necessary to register a delay function.

sampleKey#

virtual bool sampleKey(uint8_t &key)

Sample external key event.

Parameters:
keyOutput parameter that will be set to the key value if a keypress was detected.
Returns:

True if a keypress was detected and the "key" parameter is set to a value.

Reimplemented by: touchgfx::HALSDL2::sampleKey

setAuxiliaryLCD#

void setAuxiliaryLCD(LCD *auxLCD)

Set an auxiliary LCD class to be used for offscreen rendering.

Parameters:
auxLCDA pointer on the axiliary LCD class to use for offscreen rendering.

setButtonController#

Stores a pointer to an instance of a specific implementation of a ButtonController.

Parameters:
btnCtrlpointer to button controller.

setDisplayOrientation#

virtual void setDisplayOrientation(DisplayOrientationorientation)

Sets the desired display orientation (landscape or portrait).

If desired orientation is different from the native orientation of the display, a rotation is automatically applied. The rotation does not incur any performance cost.

Parameters:
orientationThe desired display orientation.
Note

A screen transition must occur before this takes effect!

setDragThreshold#

void setDragThreshold(uint8_tvalue)

Configure the threshold for reporting drag events.

A touch input movement must exceed this value in either axis in order to report a drag. Default value is 0.

Parameters:
valueNew threshold value.
Note

Use if touch controller is not completely accurate to avoid "false" drags.

setFingerSize#

void setFingerSize(uint8_tsize)

Sets the finger size in pixels.

Setting the finger size to a size of more than 1 pixel will emulate a finger of width and height of 2*(fingersize-1)+1. This can be especially useful when trying to interact with small elements on a high ppi display. The finger size will influence which element is chosen as the point of interaction, when clicking, dragging, ... the display. A number of samples will be drawn from within the finger area and a best matching drawable will be chosen. The best matching algorithm will consider the size of the drawable and the distance from the touch point.

Parameters:
sizethe size of the finger.

setFrameBufferAllocator#

Sets a framebuffer allocator.

The framebuffer allocator is only used in partial framebuffer mode.

Parameters:
allocatorpointer to a framebuffer allocator object.

setFrameBufferStartAddresses#

virtual void setFrameBufferStartAddresses(void *frameBuffer ,
void *doubleBuffer ,
void *animationStorage
)

Sets framebuffer start addresses.

Sets individual framebuffer start addresses.

Parameters:
frameBufferBuffer for framebuffer data, must be non-null.
doubleBufferIf non-null, buffer for double buffer data. If null double buffering is disabled.
animationStorageIf non-null, the animation storage. If null animation storage is disabled.

setFrameRateCompensation#

void setFrameRateCompensation(boolenabled)

Enables or disables compensation for lost frames.

See knowledge base article.

Parameters:
enabledtrue to enable, false to disable.

setFrameRefreshStrategy#

Set a specific strategy for handling timing and mechanism of framebuffer drawing.

By setting a different frame refresh strategy, the internals of how TouchGFX interacts with the framebuffer can be modified.

Currently there are two strategies available. This will increase over time.

  • REFRESH_STRATEGY_OPTIM_SINGLE_BUFFER_TFT_CTRL: this strategy is available on targets that use single buffering on a TFT controller based system. It requires an implementation of the getTFTCurrentLine() function as well as a task delay function being registered. The implementation of this strategy is that TouchGFX will carefully track the progress of the TFT controller, and draw parts of the framebuffer whenever possible. The effect is that the risk of tearing is much reduced compared to the default single buffer strategy of only drawing in porch areas. It does have a drawback of slightly increased MCU load. But in many cases employing this strategy will make it possible to avoid external RAM, by using just a single framebuffer in internal RAM and still avoid tearing.
  • REFRESH_STRATEGY_DEFAULT: This is a general strategy that works for all target configurations. Recommendation: Try using REFRESH_STRATEGY_OPTIM_SINGLE_BUFFER_TFT_CTRL if you're on a TFT controller based system (ie. non-8080) and you have a desire to avoid external RAM. Otherwise stick to REFRESH_STRATEGY_DEFAULT.
Parameters:
sThe desired strategy to use.
Returns:

true if the desired strategy will be used, false otherwise.

setMCUActive#

void setMCUActive(boolactive)

Register if MCU is active by measuring cpu cycles.

If user wishes to track MCU load, this method should be called whenever the OS Idle task is scheduled in or out. This method makes calls to a concrete implementation of GPIO functionality and a concrete implementation of cpu cycles.

Parameters:
activeIf true, MCU is registered as being active, inactive otherwise.

setMCUInstrumentation#

Stores a pointer to an instance of an MCU specific instrumentation class.

Parameters:
mcuInstrpointer to MCU instrumentation.

setRenderingVariant#

Set current rendering variant for cache maintenance.

This function is used to keep track of previous rendering variant and will determine if cache should be flush or invalidated depending on transition state.

Parameters:
variantThe rendering variant used.

setTouchSampleRate#

void setTouchSampleRate(int8_tsampleRateInTicks)

Sets the number of ticks between each touch screen sample.

Parameters:
sampleRateInTicksSample rate. Default is 1 (every tick).

signalDMAInterrupt#

Notify the framework that a DMA interrupt has occurred.

swapFrameBuffers#

Swaps the two framebuffers.

taskDelay#

virtual void taskDelay(uint16_tms)

Delay GUI task execution by number of milliseconds.

This function requires the presence of a task delay function. If a task delay function has not been registered, it returns immediately. Otherwise it returns when number of milliseconds has passed.

Parameters:
msNumber of milliseconds to wait.
See also:

taskEntry#

virtual void taskEntry()

Main event loop.

Will wait for VSYNC signal, and then process next frame. Call this function from your GUI task.

Note

This function never returns!

Reimplemented by: touchgfx::HALSDL2::taskEntry

unlockFrameBuffer#

virtual void unlockFrameBuffer()

Unlocks the framebuffer (MUST be called exactly once for each call to lockFrameBuffer()).

vSync#

void vSync()

Called by the VSync interrupt.

Called by the VSync interrupt for counting of LCD refreshes.

~HAL#

virtual ~HAL()

Finalizes an instance of the HAL class.

getInstance#

static HAL * getInstance()

Gets the HAL instance.

Returns:

The HAL instance.

lcd#

static LCD & lcd()

Gets a reference to the LCD.

Returns:

A reference to the LCD.

Protected Functions Documentation#

beginFrame#

virtual bool beginFrame()

Called when beginning to rendering a frame.

Returns:

true if rendering can begin, false otherwise.

endFrame#

virtual void endFrame()

Called when a rendering pass is completed.

FlushCache#

virtual void FlushCache()

Flush D-Cache.

Called by setRenderingVariant when chaning rendering variant from Software to Hardware indicating the cache should be invalidated.

getClientFrameBuffer#

uint16_t * getClientFrameBuffer()

Gets client framebuffer.

Returns:

The address of the framebuffer currently used by the framework to draw in.

InvalidateCache#

virtual void InvalidateCache()

Invalidate D-Cache.

Called by setRenderingVariant when chaning rendering variant from Hardware to Software indicating the cache should be invalidated.

noTouch#

virtual void noTouch()

Called by the touch driver to indicate that no touch is currently detected.

performDisplayOrientationChange#

Perform the actual display orientation change.

Reimplemented by: touchgfx::HALSDL2::performDisplayOrientationChange

setTFTFrameBuffer#

virtual void setTFTFrameBuffer(uint16_t *address)

Sets the framebuffer address used by the TFT controller.

Parameters:
addressNew framebuffer address.

Reimplemented by: touchgfx::HALSDL2::setTFTFrameBuffer

tick#

virtual void tick()

This function is called at each timer tick, depending on platform implementation.

touch#

virtual void touch(int32_tx ,
int32_ty
)

Called by the touch driver to indicate a touch.

Parameters:
xThe x coordinate of the touch.
yThe y coordinate of the touch.

Public Attributes Documentation#

DISPLAY_HEIGHT#

uint16_t DISPLAY_HEIGHT

The height of the LCD display in pixels.

DISPLAY_ROTATION#

DisplayRotation DISPLAY_ROTATION

The rotation from display to framebuffer.

DISPLAY_WIDTH#

uint16_t DISPLAY_WIDTH

The width of the LCD display in pixels.

FRAME_BUFFER_HEIGHT#

uint16_t FRAME_BUFFER_HEIGHT

The height of the framebuffer in pixels.

FRAME_BUFFER_WIDTH#

uint16_t FRAME_BUFFER_WIDTH

The width of the framebuffer in pixels.

USE_ANIMATION_STORAGE#

bool USE_ANIMATION_STORAGE

Is animation storage enabled?

USE_DOUBLE_BUFFERING#

bool USE_DOUBLE_BUFFERING

Is double buffering enabled?

Protected Attributes Documentation#

auxiliaryLCD#

LCD * auxiliaryLCD

Auxiliary LCD class used to render Drawables into dynamic bitmaps.

buttonController#

ButtonController * buttonController

A reference to an optional ButtonController.

dma#

A reference to the DMA interface.

fingerSize#

uint8_t fingerSize

The radius of the finger in pixels.

frameBuffer0#

uint16_t * frameBuffer0

Pointer to the first framebuffer.

frameBuffer1#

uint16_t * frameBuffer1

Pointer to the second framebuffer.

frameBuffer2#

uint16_t * frameBuffer2

Pointer to the optional third framebuffer used for animation storage.

frameBufferAllocator#

FrameBufferAllocator * frameBufferAllocator

A reference to an optional FrameBufferAllocator.

frameBufferUpdatedThisFrame#

bool frameBufferUpdatedThisFrame

True if something was drawn in the current frame.

gestures#

Gestures gestures

Class for low-level interpretation of touch events.

lcdRef#

LCD & lcdRef

A reference to the LCD.

lockDMAToPorch#

bool lockDMAToPorch

Whether or not to lock DMA transfers with TFT porch signal.

mcuInstrumentation#

MCUInstrumentation * mcuInstrumentation

A reference to an optional MCU instrumentation.

nativeDisplayOrientation#

DisplayOrientation nativeDisplayOrientation

Contains the native display orientation. If desired orientation is different, apply rotation.

partialFrameBufferRect#

Rect partialFrameBufferRect

The region of the screen covered by the partial framebuffer.

refreshStrategy#

FrameRefreshStrategy refreshStrategy

The selected display refresh strategy.

taskDelayFunc#

void(* taskDelayFunc

Pointer to a function that can delay GUI task for a number of milliseconds.

touchController#

TouchController & touchController

A reference to the touch controller.

isDrawing#

bool isDrawing

True if currently in the process of rendering a screen.