メイン・コンテンツまでスキップ

HAL

touchgfx/hal/HAL.hpp

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.
enumRenderingMethod { SOFTWARE, HARDWARE }
A list of rendering methods.

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.
virtual 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, bool replaceBgAlpha)
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, bool replaceBgAlpha)
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, bool replaceBgAlpha)
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, bool replaceBgAlpha)
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, bool replaceBgAlpha)
Blits a 4bpp or 8bpp glyph - maybe use the same method and supply additional color mode arg.
virtual voidblitCopyWord(const uint16_t * pSrc, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, uint16_t dstWidth)
Blits a 2D source-array to the framebuffer using 16-bit copy without conversion.
virtual voidblitFill(colortype color, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t alpha, bool replaceBgAlpha)
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, bool replaceBgAlpha)
Blits a color value to the framebuffer performing alpha-blending as specified.
virtual voidblitFillWord(uint16_t colorValue, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t dstWidth)
Fills a part of the framebuffer using 16-bit fill without conversion.
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 uint16_t *copyFromTFTToClientBuffer(Rect region)
Copies a region of the currently displayed framebuffer to memory.
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.
virtual voidinitialize()
This function initializes the HAL, DMA, TouchController, and interrupts.
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.
uint16_t *lockFrameBufferForRenderingMethod(RenderingMethod method)
Locks the framebuffer and sets rendering method for correct cache management.
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.
virtual voidsetAnimationStorage(void * animationStorage)
Sets animation storage address.
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 voidsetFrameBufferSize(uint16_t width, uint16_t height)
Sets framebuffer size.
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.
voidsetRenderingMethod(RenderingMethod method)
Set current rendering method 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.
booluseAuxiliaryLCD
True if using another LCD than the hardware framebuffer.
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.

RenderingMethod

A list of rendering methods.

SOFTWARETransition to this method will invalidate the D-Cache, if enabled.
HARDWARETransition to this method will flush the D-Cache, if enabled.

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

virtual 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 ,
boolreplaceBgAlpha
)

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)
replaceBgAlphaReplace the background buffer per pixel alpha value with 255 = solid.
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 ,
boolreplaceBgAlpha
)

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.
replaceBgAlphaReplace the background buffer per pixel alpha value with 255 = solid.
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 ,
boolreplaceBgAlpha
)

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)
replaceBgAlphaReplace the background buffer per pixel alpha value with 255 = solid.
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 ,
boolreplaceBgAlpha
)

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)
replaceBgAlphaReplace the background buffer per pixel alpha value with 255 = solid.

blitCopyGlyph

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

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.
replaceBgAlphaReplace the background buffer per pixel alpha value with 255 = solid.

blitCopyWord

virtual void blitCopyWord(const uint16_t *pSrc ,
uint16_tx ,
uint16_ty ,
uint16_twidth ,
uint16_theight ,
uint16_tsrcWidth ,
uint16_tdstWidth
)

Blits a 2D source-array to the framebuffer using 16-bit copy without conversion.

This operation can be used to perform hardware accelerated copies to the framebuffer even when the image (and framebuffer) format is not 16-bit.

All parameters (e.g. x) must correspond to their 16-bit values. I.e. the 10th bytes corresponds to x=5.

Parameters:
pSrcPointer to the source data (points to first value to copy)
xThe destination x coordinate in the framebuffer with 16-bit pixels.
yThe destination y coordinate in the framebuffer with 16-bit pixels.
widthThe width of the area to copy in 16-bit pixels.
heightThe height of the area to copy
srcWidthThe width of the source bitmap (stride) in 16-bit pixels.
dstWidthThe width of the framebuffer in 16-bit pixels.

blitFill

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

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)
replaceBgAlphaReplace the background buffer per pixel alpha value with 255 = solid.
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 ,
boolreplaceBgAlpha
)

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)
replaceBgAlphaReplace the background buffer per pixel alpha value with 255 = solid.
Note

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

blitFillWord

virtual void blitFillWord(uint16_tcolorValue ,
uint16_tx ,
uint16_ty ,
uint16_twidth ,
uint16_theight ,
uint16_tdstWidth
)

Fills a part of the framebuffer using 16-bit fill without conversion.

This operation can be used to perform hardware accelerated fills in the framebuffer even when the framebuffer format is not 16-bit.

All parameters (e.g. x) must correspond to their 16-bit values. I.e. the 10th bytes corresponds to x=5.

Parameters:
colorValueThe 16-bit value to fill in the framebuffer.
xThe destination x coordinate in the framebuffer with 16-bit pixels.
yThe destination y coordinate in the framebuffer with 16-bit pixels.
widthThe width of the area to copy in 16-bit pixels.
heightThe height of the area to copy
dstWidthThe width of the framebuffer in 16-bit pixels.

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.

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.

copyFromTFTToClientBuffer

virtual uint16_t * copyFromTFTToClientBuffer(Rectregion)

Copies a region of the currently displayed framebuffer to memory.

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

Parameters:
regionThe displayed framebuffer region to copy.
Returns:

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

Note

Requires double framebuffer to be enabled.

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

virtual void initialize()

This function initializes the HAL, DMA, TouchController, and interrupts.

See also:

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). Calls the InvalidateCache virtual if previous operation was hardware based.

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.

lockFrameBufferForRenderingMethod

Locks the framebuffer and sets rendering method for correct cache management.

Parameters:
methodThe rendering method to be used.
Returns:

A pointer to the beginning of the currently used framebuffer.

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

setAnimationStorage

virtual void setAnimationStorage(void *animationStorage)

Sets animation storage address.

Parameters:
animationStorageIf non-null, the animation storage. If null animation storage is disabled.
See also:

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.

setFrameBufferSize

virtual void setFrameBufferSize(uint16_twidth ,
uint16_theight
)

Sets framebuffer size.

By default the display size and the framebuffer size are the same, but in some hardware configurations, the hardware may have a width of e.g. 832 pixels even though the display is only 800 pixels wide. First set the display width and height using touchgfx_generic_init() and the update the framebuffer size using setFrameBufferSize().

Parameters:
widthThe width of the framebuffer.
heightThe height of the framebuffer.
See also:

Reimplemented by: touchgfx::HALSDL2::setFrameBufferSize

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.
See also:

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.

setRenderingMethod

Set current rendering method for cache maintenance.

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

Parameters:
methodThe rendering method 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 setRenderingMethod when changing rendering method 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 setRenderingMethod when changing rendering method 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.

useAuxiliaryLCD

bool useAuxiliaryLCD

True if using another LCD than the hardware framebuffer.

isDrawing

bool isDrawing

True if currently in the process of rendering a screen.