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

enum	FrameRefreshStrategy { REFRESH_STRATEGY_DEFAULT, REFRESH_STRATEGY_OPTIM_SINGLE_BUFFER_TFT_CTRL, REFRESH_STRATEGY_PARTIAL_FRAMEBUFFER }
	A list of available frame refresh strategies.
enum	RenderingMethod { SOFTWARE, HARDWARE }
	A list of rendering methods.

Public Functions

virtual void	allowDMATransfers()
	Allow the DMA to start transfers.
virtual void	backPorchExited()
	Has to be called from within the LCD IRQ rutine when the Back Porch Exit is reached.
virtual void	blitCopy(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 void	blitCopy(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 void	blitCopy(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 void	blitCopyARGB8888(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 void	blitCopyGlyph(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 void	blitCopyWord(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 void	blitFill(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 void	blitFill(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 void	blitFillWord(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 bool	blockCopy(void RESTRICT dest, const void RESTRICT src, uint32_t numBytes)
	This function performs a platform-specific memcpy, if supported by the hardware.
virtual void	configureInterrupts() =0
	Configures the interrupts relevant for TouchGFX.
virtual uint16_t	configurePartialFrameBuffer(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 void	disableInterrupts() =0
	Disables the DMA and LCD interrupts.
virtual void	drawDrawableInDynamicBitmap(Drawable & drawable, BitmapId bitmapId)
	Render a Drawable and its widgets into a dynamic bitmap.
virtual void	drawDrawableInDynamicBitmap(Drawable & drawable, BitmapId bitmapId, const Rect & rect)
	Render a Drawable and its widgets into a dynamic bitmap.
void	enableDMAAcceleration(const bool enable)
	Sets a flag to allow use of DMA operations to speed up drawing operations.
virtual void	enableInterrupts() =0
	Enables the DMA and LCD interrupts.
virtual void	enableLCDControllerInterrupt() =0
	Configure the LCD controller to fire interrupts at VSYNC.
void	enableMCULoadCalculation(bool enabled)
	This method sets a flag that determines if generic HAL should calculate MCU load based on concrete MCU instrumentation.
virtual void	flushDMA()
	This function blocks until the DMA queue (containing BlitOps) is empty.
virtual void	flushFrameBuffer()
	This function is called whenever the framework has performed a complete draw.
virtual void	flushFrameBuffer(const Rect & rect)
	This function is called whenever the framework has performed a partial draw.
void	frontPorchEntered()
	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 BlitOperations	getBlitCaps()
	Function for obtaining the blit capabilities of the concrete HAL implementation.
ButtonController *	getButtonController() const
	Gets the associated ButtonController.
uint32_t	getCPUCycles()
	Gets the current cycle counter.
uint16_t	getDisplayHeight() const
	Gets display height.
DisplayOrientation	getDisplayOrientation() const
	Gets the current display orientation.
uint16_t	getDisplayWidth() const
	Gets display width.
virtual DMAType	getDMAType()
	Function for obtaining the DMA type of the concrete DMA implementation.
uint8_t	getFingerSize() const
	Gets the finger size in pixels.
virtual FlashDataReader *	getFlashDataReader() const
	Gets the flash data reader.
FrameBufferAllocator *	getFrameBufferAllocator()
	Gets the framebuffer allocator.
FrameRefreshStrategy	getFrameRefreshStrategy() 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_t	getLCDRefreshCount()
	Returns the number of VSync interrupts between the current drawing operation and the last drawing operation, i.e.
uint8_t	getMCULoadPct() const
	Gets the current MCU load.
virtual uint16_t	getTFTCurrentLine()
	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_t	getTouchSampleRate() 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 void	initialize()
	This function initializes the HAL, DMA, TouchController, and interrupts.
void	lockDMAToFrontPorch(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 void	registerEventListener(UIEventListener & listener)
	Registers an event handler implementation with the underlying event system.
void	registerTaskDelayFunction(void(*)(uint16_t) delayF)
	Registers a function capable of delaying GUI task execution.
virtual bool	sampleKey(uint8_t & key)
	Sample external key event.
virtual void	setAnimationStorage(void * animationStorage)
	Sets animation storage address.
void	setAuxiliaryLCD(LCD * auxLCD)
	Set an auxiliary LCD class to be used for offscreen rendering.
void	setButtonController(ButtonController * btnCtrl)
	Stores a pointer to an instance of a specific implementation of a ButtonController.
virtual void	setDisplayOrientation(DisplayOrientation orientation)
	Sets the desired display orientation (landscape or portrait).
void	setDragThreshold(uint8_t value)
	Configure the threshold for reporting drag events.
void	setFingerSize(uint8_t size)
	Sets the finger size in pixels.
void	setFrameBufferAllocator(FrameBufferAllocator * allocator)
	Sets a framebuffer allocator.
virtual void	setFrameBufferSize(uint16_t width, uint16_t height)
	Sets framebuffer size.
virtual void	setFrameBufferStartAddresses(void frameBuffer, void doubleBuffer, void * animationStorage)
	Sets framebuffer start addresses.
void	setFrameRateCompensation(bool enabled)
	Enables or disables compensation for lost frames.
bool	setFrameRefreshStrategy(FrameRefreshStrategy s)
	Set a specific strategy for handling timing and mechanism of framebuffer drawing.
void	setMCUActive(bool active)
	Register if MCU is active by measuring cpu cycles.
void	setMCUInstrumentation(MCUInstrumentation * mcuInstr)
	Stores a pointer to an instance of an MCU specific instrumentation class.
void	setRenderingMethod(RenderingMethod method)
	Set current rendering method for cache maintenance.
void	setTouchSampleRate(int8_t sampleRateInTicks)
	Sets the number of ticks between each touch screen sample.
void	signalDMAInterrupt()
	Notify the framework that a DMA interrupt has occurred.
void	swapFrameBuffers()
	Swaps the two framebuffers.
virtual void	taskDelay(uint16_t ms)
	Delay GUI task execution by number of milliseconds.
virtual void	taskEntry()
	Main event loop.
virtual void	unlockFrameBuffer()
	Unlocks the framebuffer (MUST be called exactly once for each call to lockFrameBuffer()).
void	vSync()
	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 bool	beginFrame()
	Called when beginning to rendering a frame.
virtual void	endFrame()
	Called when a rendering pass is completed.
virtual void	FlushCache()
	Flush D-Cache.
uint16_t *	getClientFrameBuffer()
	Gets client framebuffer.
virtual void	InvalidateCache()
	Invalidate D-Cache.
virtual void	noTouch()
	Called by the touch driver to indicate that no touch is currently detected.
virtual void	performDisplayOrientationChange()
	Perform the actual display orientation change.
virtual void	setTFTFrameBuffer(uint16_t * address) =0
	Sets the framebuffer address used by the TFT controller.
virtual void	tick()
	This function is called at each timer tick, depending on platform implementation.
virtual void	touch(int32_t x, int32_t y)
	Called by the touch driver to indicate a touch.

Public Attributes

uint16_t	DISPLAY_HEIGHT
	The height of the LCD display in pixels.
DisplayRotation	DISPLAY_ROTATION
	The rotation from display to framebuffer.
uint16_t	DISPLAY_WIDTH
	The width of the LCD display in pixels.
uint16_t	FRAME_BUFFER_HEIGHT
	The height of the framebuffer in pixels.
uint16_t	FRAME_BUFFER_WIDTH
	The width of the framebuffer in pixels.
bool	USE_ANIMATION_STORAGE
	Is animation storage enabled?
bool	USE_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_t	fingerSize
	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.
bool	frameBufferUpdatedThisFrame
	True if something was drawn in the current frame.
Gestures	gestures
	Class for low-level interpretation of touch events.
LCD &	lcdRef
	A reference to the LCD.
bool	lockDMAToPorch
	Whether or not to lock DMA transfers with TFT porch signal.
MCUInstrumentation *	mcuInstrumentation
	A reference to an optional MCU instrumentation.
DisplayOrientation	nativeDisplayOrientation
	Contains the native display orientation. If desired orientation is different, apply rotation.
Rect	partialFrameBufferRect
	The region of the screen covered by the partial framebuffer.
FrameRefreshStrategy	refreshStrategy
	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.
bool	isDrawing
	True if currently in the process of rendering a screen.

Public Types Documentation

FrameRefreshStrategy

enum FrameRefreshStrategy

A list of available frame refresh strategies.

REFRESH_STRATEGY_DEFAULT	If not explicitly set, this strategy is used.
REFRESH_STRATEGY_OPTIM_SINGLE_BUFFER_TFT_CTRL	Strategy optimized for single framebuffer on systems with TFT controller.
REFRESH_STRATEGY_PARTIAL_FRAMEBUFFER	Strategy using less than a full framebuffer.

RenderingMethod

enum RenderingMethod

A list of rendering methods.

SOFTWARE	Transition to this method will invalidate the D-Cache, if enabled.
HARDWARE	Transition 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_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.

Parameters:

pSrc	The source-array pointer (points to first value to copy)
pClut	The CLUT pointer (points to CLUT header data which include the type and size of this CLUT followed by colors data)
x	The destination x coordinate on the framebuffer.
y	The destination y coordinate on the framebuffer.
width	The width desired area of the source 2D array.
height	The height of desired area of the source 2D array.
srcWidth	The distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
alpha	The alpha value to use for blending (255 = solid, no blending)
hasTransparentPixels	If true, this data copy contains transparent pixels and require hardware support for that to be enabled.
dstWidth	The distance (in elements) from first value of first line, to first value of second line (the destination 2D array width)
srcFormat	The source buffer color format (default is the framebuffer format)
dstFormat	The destination buffer color format (default is the framebuffer format)
replaceBgAlpha	Replace 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_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.

Parameters:

pSrc	The source-array pointer (points to first value to copy)
x	The destination x coordinate on the framebuffer.
y	The destination y coordinate on the framebuffer.
width	The width desired area of the source 2D array.
height	The height of desired area of the source 2D array.
srcWidth	The distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
alpha	The alpha value to use for blending (255 = solid, no blending)
hasTransparentPixels	If true, this data copy contains transparent pixels and require hardware support for that to be enabled.
replaceBgAlpha	Replace 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_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.

Parameters:

pSrc	The source-array pointer (points to first value to copy)
x	The destination x coordinate on the framebuffer.
y	The destination y coordinate on the framebuffer.
width	The width desired area of the source 2D array.
height	The height of desired area of the source 2D array.
srcWidth	The distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
alpha	The alpha value to use for blending (255 = solid, no blending)
hasTransparentPixels	If true, this data copy contains transparent pixels and require hardware support for that to be enabled.
dstWidth	The distance (in elements) from first value of first line, to first value of second line (the destination 2D array width)
srcFormat	The source buffer color format (default is the framebuffer format)
dstFormat	The destination buffer color format (default is the framebuffer format)
replaceBgAlpha	Replace 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_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.

Parameters:

pSrc	The source-array pointer (points to first value to copy)
x	The destination x coordinate on the framebuffer.
y	The destination y coordinate on the framebuffer.
width	The width desired area of the source 2D array.
height	The height of desired area of the source 2D array.
srcWidth	The distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
alpha	The alpha value to use for blending. This is applied on every pixel, in addition to the per-pixel alpha value (255 = solid, no blending)
replaceBgAlpha	Replace the background buffer per pixel alpha value with 255 = solid.

blitCopyGlyph

virtual void blitCopyGlyph	(	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.

Parameters:

pSrc	The source-array pointer (points to first value to copy)
x	The destination x coordinate on the framebuffer.
y	The destination y coordinate on the framebuffer.
width	The width desired area of the source 2D array.
height	The height of desired area of the source 2D array.
srcWidth	The distance (in elements) from first value of first line, to first value of second line (the source 2D array width)
color	Color of the text.
alpha	The alpha value to use for blending (255 = solid, no blending)
operation	The operation type to use for blit copy.
replaceBgAlpha	Replace the background buffer per pixel alpha value with 255 = solid.

blitCopyWord

virtual void blitCopyWord	(	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.

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:

pSrc	Pointer to the source data (points to first value to copy)
x	The destination x coordinate in the framebuffer with 16-bit pixels.
y	The destination y coordinate in the framebuffer with 16-bit pixels.
width	The width of the area to copy in 16-bit pixels.
height	The height of the area to copy
srcWidth	The width of the source bitmap (stride) in 16-bit pixels.
dstWidth	The width of the framebuffer in 16-bit pixels.

blitFill

virtual void blitFill	(	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.

Parameters:

color	The desired fill-color.
x	The destination x coordinate on the framebuffer.
y	The destination y coordinate on the framebuffer.
width	The width desired area of the source 2D array.
height	The height of desired area of the source 2D array.
alpha	The alpha value to use for blending (255 = solid, no blending)
replaceBgAlpha	Replace 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	(	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.

Parameters:

color	The desired fill-color.
x	The destination x coordinate on the framebuffer.
y	The destination y coordinate on the framebuffer.
width	The width desired area of the source 2D array.
height	The height of desired area of the source 2D array.
alpha	The alpha value to use for blending (255 = solid, no blending)
dstWidth	The distance (in elements) from first value of first line, to first value of second line (the destination 2D array width)
dstFormat	The destination buffer color format (default is the framebuffer format)
replaceBgAlpha	Replace 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_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.

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:

colorValue	The 16-bit value to fill in the framebuffer.
x	The destination x coordinate in the framebuffer with 16-bit pixels.
y	The destination y coordinate in the framebuffer with 16-bit pixels.
width	The width of the area to copy in 16-bit pixels.
height	The height of the area to copy
dstWidth	The width of the framebuffer in 16-bit pixels.

blockCopy

virtual bool blockCopy	(	void *RESTRICT	dest ,
		const void *RESTRICT	src ,
		uint32_t	numBytes
		)

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

Parameters:

dest	Pointer to destination memory.
src	Pointer to source memory.
numBytes	Number 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_t	x ,
		const uint16_t	y ,
		const uint16_t	width ,
		const uint16_t	height
		)

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:

x	The absolute x coordinate of the block on the screen.
y	The absolute y coordinate of the block on the screen.
width	The width of the block.
height	The height of the block requested.

Returns:

The height of the block allocated.

copyFBRegionToMemory

virtual uint16_t * copyFBRegionToMemory	(	Rect	meAbs	)

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:

meAbs	The 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	(	Rect	meAbs ,
		uint16_t *	dst ,
		uint32_t	stride
		)

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:

meAbs	The framebuffer region to copy.
dst	Address of the buffer to store the copy in.
stride	The 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	(	Rect	region	)

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:

region	The 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 ,
		BitmapId	bitmapId
		)

Render a Drawable and its widgets into a dynamic bitmap.

Parameters:

drawable	A reference on the Drawable object to render.
bitmapId	Dynamic bitmap to be used as a rendertarget.

drawDrawableInDynamicBitmap

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

Render a Drawable and its widgets into a dynamic bitmap.

Only the specified Rect region is updated.

Parameters:

drawable	A reference on the Drawable object to render.
bitmapId	Dynamic bitmap to be used as a rendertarget.
rect	Region to update.

enableDMAAcceleration

void enableDMAAcceleration	(	const bool	enable	)

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

Parameters:

enable	True to enable, false to disable.

See also:

getBlitCaps

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	(	bool	enabled	)

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

Parameters:

enabled	If 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:

rect	The area of the screen that has been drawn, expressed in absolute coordinates.

See also:

flushFrameBuffer

Reimplemented by: touchgfx::HALSDL2::flushFrameBuffer

frontPorchEntered

void 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

LCD * 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:

enableDMAAcceleration

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:

the FlashDataReader.

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:

setFrameRefreshStrategy

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_t	width ,
		uint16_t	height
		)

Initializes a new instance of the HAL class.

Parameters:

dmaInterface	Reference to the DMA interface.
display	Reference to the LCD.
touchCtrl	Reference to the touch controller.
width	The width of the LCD display, in pixels.
height	The height of the LCD display, in pixels.

initialize

virtual void initialize	(			)

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

See also:

configureInterrupts

lockDMAToFrontPorch

void lockDMAToFrontPorch	(	bool	enableLock	)

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:

enableLock	True 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

uint16_t * lockFrameBufferForRenderingMethod	(	RenderingMethod	method	)

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

Parameters:

method	The 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:

listener	The 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:

delayF	A 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:

key	Output 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:

animationStorage	If non-null, the animation storage. If null animation storage is disabled.

See also:

setFrameBufferStartAddresses

setAuxiliaryLCD

void setAuxiliaryLCD	(	LCD *	auxLCD	)

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

Parameters:

auxLCD	A pointer on the axiliary LCD class to use for offscreen rendering.

setButtonController

void setButtonController	(	ButtonController *	btnCtrl	)

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

Parameters:

btnCtrl	pointer to button controller.

setDisplayOrientation

virtual void setDisplayOrientation	(	DisplayOrientation	orientation	)

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:

orientation	The desired display orientation.

Note

A screen transition must occur before this takes effect!

setDragThreshold

void setDragThreshold	(	uint8_t	value	)

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:

value	New threshold value.

Note

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

setFingerSize

void setFingerSize	(	uint8_t	size	)

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:

size	the size of the finger.

setFrameBufferAllocator

void setFrameBufferAllocator	(	FrameBufferAllocator *	allocator	)

Sets a framebuffer allocator.

The framebuffer allocator is only used in partial framebuffer mode.

Parameters:

allocator	pointer to a framebuffer allocator object.

setFrameBufferSize

virtual void setFrameBufferSize	(	uint16_t	width ,
		uint16_t	height
		)

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:

width	The width of the framebuffer.
height	The height of the framebuffer.

See also:

touchgfx_generic_init

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:

frameBuffer	Buffer for framebuffer data, must be non-null.
doubleBuffer	If non-null, buffer for double buffer data. If null double buffering is disabled.
animationStorage	If non-null, the animation storage. If null animation storage is disabled.

See also:

setAnimationStorage

setFrameRateCompensation

void setFrameRateCompensation	(	bool	enabled	)

Enables or disables compensation for lost frames.

See knowledge base article.

Parameters:

enabled	true to enable, false to disable.

setFrameRefreshStrategy

bool setFrameRefreshStrategy	(	FrameRefreshStrategy	s	)

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:

s	The desired strategy to use.

Returns:

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

setMCUActive

void setMCUActive	(	bool	active	)

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:

active	If true, MCU is registered as being active, inactive otherwise.

setMCUInstrumentation

void setMCUInstrumentation	(	MCUInstrumentation *	mcuInstr	)

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

Parameters:

mcuInstr	pointer to MCU instrumentation.

setRenderingMethod

void setRenderingMethod	(	RenderingMethod	method	)

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:

method	The rendering method used.

setTouchSampleRate

void setTouchSampleRate	(	int8_t	sampleRateInTicks	)

Sets the number of ticks between each touch screen sample.

Parameters:

sampleRateInTicks	Sample rate. Default is 1 (every tick).

signalDMAInterrupt

void signalDMAInterrupt	(			)

Notify the framework that a DMA interrupt has occurred.

swapFrameBuffers

void swapFrameBuffers	(			)

Swaps the two framebuffers.

taskDelay

virtual void taskDelay	(	uint16_t	ms	)

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:

ms	Number of milliseconds to wait.

See also:

registerTaskDelayFunction

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

virtual void 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:

address	New 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_t	x ,
		int32_t	y
		)

Called by the touch driver to indicate a touch.

Parameters:

x	The x coordinate of the touch.
y	The 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

DMA_Interface & 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.