Skip to main content
Version: 4.16

HALSDL2

HAL implementation for the TouchGFX simulator. This particular simulator HAL implementation uses SDL2 to show the content of the framebuffer in a window.

See: HAL

Inherits from: HAL

Public Functions#

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 voidcopyScreenshotToClipboard()
Copies the screenshot to clipboard.
booldoSampleTouch(int32_t & x, int32_t & y) const
Samples the position of the mouse cursor.
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.
boolgetConsoleVisible() const
Is console window visible?
boolgetWindowVisible() const
Is the window visible?
HALSDL2(DMA_Interface & dma, LCD & lcd, TouchController & touchCtrl, uint16_t width, uint16_t height)
Initializes a new instance of the HALSDL2 class.
voidloadSkin(DisplayOrientation orientation, int x, int y)
Loads a skin for a given display orientation that will be rendered in the simulator window with the the TouchGFX framebuffer placed inside the bitmap at the given coordinates.
virtual boolsampleKey(uint8_t & key)
Sample key event from keyboard.
virtual voidsaveNextScreenshots(int n)
Copy the next N screenshots to disk.
voidsaveScreenshot()
Saves a screenshot to the default folder and default filename.
virtual voidsaveScreenshot(char folder, char filename)
Saves a screenshot.
virtual boolsdl_init(int argcount, char ** args)
Initializes SDL.
voidsetConsoleVisible(bool visible, bool redrawWindow =true)
Change visibility of console window (hidden vs.
voidsetVsyncInterval(float ms)
Sets vsync interval for simulating same tick speed as the real hardware.
voidsetWindowVisible(bool visible, bool redrawWindow =true)
Change visibility of window (hidden vs.
virtual voidtaskEntry()
Main event loop.
uint8_t *doRotate(uint8_t dst, uint8_t src)
Rotates a framebuffer if the display is rotated.
char **getArgv(int * argc)
Gets the argc and argv for a Windows program.
const char *getWindowTitle()
Gets window title.
boolisSingleStepping()
Is single stepping.
uint8_t *scaleTo24bpp(uint8_t dst, uint16_t src, Bitmap::BitmapFormat format)
Scale framebuffer to 24bpp.
voidsetSingleStepping(bool singleStepping =true)
Single stepping enable/disable.
voidsetWindowTitle(const char * title)
Sets window title.
voidsingleStep(uint16_t steps =1)
Single step a number of steps.

Protected Functions#

virtual voidconfigureInterrupts()
Configures the interrupts relevant for TouchGFX.
virtual voidconfigureLCDInterrupt()
Configures LCD interrupt.
virtual voiddisableInterrupts()
Disables the DMA and LCD interrupts.
virtual voidenableInterrupts()
Enables the DMA and LCD interrupts.
virtual voidenableLCDControllerInterrupt()
Enables the LCD interrupt.
virtual uint16_t *getTFTFrameBuffer() const
Gets TFT framebuffer.
virtual voidperformDisplayOrientationChange()
Perform the actual display orientation change.
virtual voidrenderLCD_FrameBufferToMemory(const Rect & _rectToUpdate, uint8_t * frameBuffer)
Update framebuffer using an SDL Surface.
virtual voidsetTFTFrameBuffer(uint16_t * addr)
Sets TFT framebuffer.

Additional inherited members#

Public Types inherited from HAL#

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

Public Functions inherited from HAL#

virtual voidallowDMATransfers()
Allow the DMA to start transfers.
virtual voidbackPorchExited()
Has to be called from within the LCD IRQ rutine when the Back Porch Exit is reached.
voidblitCopy(const uint16_t pSrc, const uint8_t pClut, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, uint8_t alpha, bool hasTransparentPixels, uint16_t dstWidth, Bitmap::BitmapFormat srcFormat, Bitmap::BitmapFormat dstFormat)
Blits a 2D source-array to the framebuffer performing alpha-blending as specified.
virtual voidblitCopy(const uint16_t * pSrc, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, uint8_t alpha, bool hasTransparentPixels)
Blits a 2D source-array to the framebuffer performing alpha-blending as specified using the default lcd format.
virtual voidblitCopy(const uint16_t * pSrc, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, uint8_t alpha, bool hasTransparentPixels, uint16_t dstWidth, Bitmap::BitmapFormat srcFormat, Bitmap::BitmapFormat dstFormat)
Blits a 2D source-array to the framebuffer performing alpha-blending as specified.
virtual voidblitCopyARGB8888(const uint16_t * pSrc, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, uint8_t alpha)
Blits a 2D source-array to the framebuffer performing per-pixel alpha blending.
virtual voidblitCopyGlyph(const uint8_t * pSrc, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t srcWidth, colortype color, uint8_t alpha, BlitOperations operation)
Blits a 4bpp or 8bpp glyph - maybe use the same method and supply additional color mode arg.
virtual voidblitFill(colortype color, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t alpha)
Blits a color value to the framebuffer performing alpha-blending as specified.
virtual voidblitFill(colortype color, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t alpha, uint16_t dstWidth, Bitmap::BitmapFormat dstFormat)
Blits a color value to the framebuffer performing alpha-blending as specified.
virtual 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 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.
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.
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.
int8_tgetTouchSampleRate() const
Gets the number of ticks between each touch screen sample.
HAL(DMA_Interface & dmaInterface, LCD & display, TouchController & touchCtrl, uint16_t width, uint16_t height)
Initializes a new instance of the HAL class.
voidinitialize()
This function is responsible for initializing the entire framework.
voidlockDMAToFrontPorch(bool enableLock)
Function to set whether the DMA transfers are locked to the TFT update cycle.
virtual uint16_t *lockFrameBuffer()
Waits for the framebuffer to become available for use (i.e.
virtual voidregisterEventListener(UIEventListener & listener)
Registers an event handler implementation with the underlying event system.
voidregisterTaskDelayFunction(void(*)(uint16_t) delayF)
Registers a function capable of delaying GUI task execution.
voidsetAuxiliaryLCD(LCD * auxLCD)
Set an auxiliary LCD class to be used for offscreen rendering.
voidsetButtonController(ButtonController * btnCtrl)
Stores a pointer to an instance of a specific implementation of a ButtonController.
virtual voidsetDisplayOrientation(DisplayOrientation orientation)
Sets the desired display orientation (landscape or portrait).
voidsetDragThreshold(uint8_t value)
Configure the threshold for reporting drag events.
voidsetFingerSize(uint8_t size)
Sets the finger size in pixels.
voidsetFrameBufferAllocator(FrameBufferAllocator * allocator)
Sets a framebuffer allocator.
virtual voidsetFrameBufferStartAddresses(void frameBuffer, void doubleBuffer, void * animationStorage)
Sets framebuffer start addresses.
voidsetFrameRateCompensation(bool enabled)
Enables or disables compensation for lost frames.
boolsetFrameRefreshStrategy(FrameRefreshStrategy s)
Set a specific strategy for handling timing and mechanism of framebuffer drawing.
voidsetMCUActive(bool active)
Register if MCU is active by measuring cpu cycles.
voidsetMCUInstrumentation(MCUInstrumentation * mcuInstr)
Stores a pointer to an instance of an MCU specific instrumentation class.
voidsetRenderingVariant(RenderingVariant variant)
Set current rendering variant for cache maintenance.
voidsetTouchSampleRate(int8_t sampleRateInTicks)
Sets the number of ticks between each touch screen sample.
voidsignalDMAInterrupt()
Notify the framework that a DMA interrupt has occurred.
voidswapFrameBuffers()
Swaps the two framebuffers.
virtual voidtaskDelay(uint16_t ms)
Delay GUI task execution by number of milliseconds.
virtual 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 inherited from HAL#

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 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 inherited from HAL#

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 inherited from HAL#

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

Public Functions Documentation#

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.

Reimplements: touchgfx::HAL::blockCopy

copyScreenshotToClipboard#

virtual void copyScreenshotToClipboard()

Copies the screenshot to clipboard.

doSampleTouch#

bool doSampleTouch(int32_t &x ,const
int32_t &yconst
)const

Samples the position of the mouse cursor.

Parameters:
xThe x coordinate.
yThe y coordinate.
Returns:

True if touch detected, false otherwise.

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.

Reimplements: touchgfx::HAL::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.

Reimplements: touchgfx::HAL::flushFrameBuffer

getConsoleVisible#

bool getConsoleVisible()const

Is console window visible?

Returns:

True if it is visible, false if it is hidden.

See also:

getWindowVisible#

bool getWindowVisible()const

Is the window visible?

Returns:

True if it is visible, false if it is hidden.

See also:

HALSDL2#

HALSDL2(DMA_Interface &dma ,
LCD &lcd ,
TouchController &touchCtrl ,
uint16_twidth ,
uint16_theight
)

Initializes a new instance of the HALSDL2 class.

Parameters:
dmaReference to DMA interface.
lcdReference to the LCD.
touchCtrlReference to Touch Controller driver.
widthWidth of the display.
heightHeight of the display.

loadSkin#

void loadSkin(DisplayOrientationorientation ,
intx ,
inty
)

Loads a skin for a given display orientation that will be rendered in the simulator window with the the TouchGFX framebuffer placed inside the bitmap at the given coordinates.

Different bitmaps can be loaded in landscape and portrait mode. If the provided bitmap cannot be loaded, the TouchGFX framebuffer will be displayed as normal. If the png files contain areas with alpha < 255, this will be used to create a shaped window.

Parameters:
orientationThe orientation.
xThe x coordinate.
yThe y coordinate.
Note

The skins must be named "portrait.png" and "landscape.png" and placed inside the "simulator/" folder. The build process of the simulator will automatically copy the skins to the folder where the executable simulator is generated. When as skin is set, the entire framebuffer is rendered through SDL whenever there is a change. Without a skin, only the areas with changes is rendered through SDL.

sampleKey#

virtual bool sampleKey(uint8_t &key)

Sample key event from keyboard.

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

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

Reimplements: touchgfx::HAL::sampleKey

saveNextScreenshots#

virtual void saveNextScreenshots(intn)

Copy the next N screenshots to disk.

On each screen update, the new screen is saved to disk.

Parameters:
nNumber of screenshots to save. These are added to any ongoing amount of screenshots in queue.

saveScreenshot#

Saves a screenshot to the default folder and default filename.

saveScreenshot#

virtual void saveScreenshot(char *folder ,
char *filename
)

Saves a screenshot.

Parameters:
folderFolder name to place the screenshot in.
filenameFilename to save the screenshot to.

sdl_init#

virtual bool sdl_init(intargcount ,
char **args
)

Initializes SDL.

Parameters:
argcountNumber of arguments.
argsArguments.
Returns:

True if init went well, false otherwise.

setConsoleVisible#

void setConsoleVisible(boolvisible ,
boolredrawWindow =true
)

Change visibility of console window (hidden vs.

shown).

Parameters:
visibleShould the window be visible?
redrawWindow(Optional) Should the window be redrawn? Default is true.
See also:

setVsyncInterval#

void setVsyncInterval(floatms)

Sets vsync interval for simulating same tick speed as the real hardware.

Due to limitations in the granularity of SDL, the generated ticks in the simulator might not occur at the exact time, but accumulated over several ticks, the precision is very good.

Parameters:
msThe milliseconds between ticks.
Note

That you can also use HAL::setFrameRateCompensation() in the simulator. The effect of this can easily be demonstrated by dragging the console output window of the simulator (when running from Visual Studio) as this will pause the SDL and generate a lot of ticks when the console window is released. Beware that since the missed vsyncs are accumulated in an 8 bit counter, only up to 255 ticks may be missed, so at VsyncInterval = 16.6667, dragging the windows for more than 255 * 16.6667ms = 4250ms = 4.25s will not generate all the ticks that were actually missed. This situation is, however, not very realistic, as normally just a couple of vsyncs are skipped.

setWindowVisible#

void setWindowVisible(boolvisible ,
boolredrawWindow =true
)

Change visibility of window (hidden vs.

shown) as well as (due to backward compatibility) the visibility of the console window.

Parameters:
visibleShould the window be visible?
redrawWindow(Optional) Should the window be redrawn? Default is true.
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!

Reimplements: touchgfx::HAL::taskEntry

doRotate#

static uint8_t * doRotate(uint8_t *dst ,
uint8_t *src
)

Rotates a framebuffer if the display is rotated.

Parameters:
dstDestination for the rotated framebuffer. must be non-null if the screen is rotated.
srcThe framebuffer.
Returns:

Null if it fails, else a pointer to an uint8_t.

getArgv#

static char ** getArgv(int *argc)

Gets the argc and argv for a Windows program.

Parameters:
argcPointer to where to store number of arguments.
Returns:

The argv list of arguments.

getWindowTitle#

static const char * getWindowTitle()

Gets window title.

Returns:

null "TouchGFX simulator" unless set to something else using setWindowTitle().

See also:

isSingleStepping#

static bool isSingleStepping()

Is single stepping.

Returns:

True if single stepping, false if not.

See also:

scaleTo24bpp#

static uint8_t * scaleTo24bpp(uint8_t *dst ,
uint16_t *src ,
Bitmap::BitmapFormatformat
)

Scale framebuffer to 24bpp.

The format of the framebuffer (src) is given in parameter format. The result is placed in the pre-allocated memory pointed to by parameter dst. If the frambebuffer is in format Bitmap::RGB888, parameter dst is not used and the parameter src is simply returned.

Parameters:
dstDestination for the framebuffer. must be non-null unless format is Bitmap::RGB888.
srcThe framebuffer.
formatDescribes the format of the framebuffer (lcd().framebufferFormat()).
Returns:

Null if it fails, else a pointer to an uint8_t.

setSingleStepping#

static void setSingleStepping(boolsingleStepping =true)

Single stepping enable/disable.

When single stepping is enabled, F10 will execute one tick and F9 will disable single stepping.

Parameters:
singleStepping(Optional) True to pause the simulation and start single stepping.
See also:

setWindowTitle#

static void setWindowTitle(const char *title)

Sets window title.

Sets window title of the TouchGFX simulator.

Parameters:
titleThe title, if null the original "TouchGFX simulator" will be used.
See also:

singleStep#

static void singleStep(uint16_tsteps =1)

Single step a number of steps.

Only works if single stepping is already enabled.

Parameters:
steps(Optional) The steps Default is 1 step.
See also:

Protected Functions Documentation#

configureInterrupts#

virtual void configureInterrupts()

Configures the interrupts relevant for TouchGFX.

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

Reimplements: touchgfx::HAL::configureInterrupts

configureLCDInterrupt#

virtual void configureLCDInterrupt()

Configures LCD interrupt.

disableInterrupts#

virtual void disableInterrupts()

Disables the DMA and LCD interrupts.

Reimplements: touchgfx::HAL::disableInterrupts

enableInterrupts#

virtual void enableInterrupts()

Enables the DMA and LCD interrupts.

Reimplements: touchgfx::HAL::enableInterrupts

enableLCDControllerInterrupt#

Enables the LCD interrupt.

Reimplements: touchgfx::HAL::enableLCDControllerInterrupt

getTFTFrameBuffer#

virtual uint16_t * getTFTFrameBuffer()const

Gets TFT framebuffer.

Returns:

null if it fails, else the TFT framebuffer.

Reimplements: touchgfx::HAL::getTFTFrameBuffer

performDisplayOrientationChange#

Perform the actual display orientation change.

Reimplements: touchgfx::HAL::performDisplayOrientationChange

renderLCD_FrameBufferToMemory#

virtual void renderLCD_FrameBufferToMemory(const Rect &_rectToUpdate ,
uint8_t *frameBuffer
)

Update framebuffer using an SDL Surface.

Parameters:
_rectToUpdateArea to update.
frameBufferTarget framebuffer.

setTFTFrameBuffer#

virtual void setTFTFrameBuffer(uint16_t *addr)

Sets TFT framebuffer.

Parameters:
addrThe address of the TFT framebuffer.

Reimplements: touchgfx::HAL::setTFTFrameBuffer