TouchGFX  v4.8.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Pages
TouchGFX Manual


Welcome to the TouchGFX Manual! The sections contained within embody the complete documentation of the TouchGFX graphics framework and the toolchain that supports it. If you are new to TouchGFX we recommended that you, as a start, read the following topics to get a solid understanding of the framework and how to get from source code to running application.

  1. What is TouchGFX and the philospohy behind it? (Further down this section).
  2. The TouchGFX Distribution discusses the contents, structure and licensing model of the TouchGFX distribution.
  3. Development Environment shows you how to setup a TouchGFX development environment.
  4. PC Simulator teaches you to build and execute applications for the PC simulator, including a Quickstart for the impatient.
  5. Examples contains a list of ready to build examples to try out either on the PC simulator or on target hardware.
  6. Creating a New Application shows you how to create a new application from scratch using gcc or Microsoft Visual Studio.
  7. Application Development enlightens you in the ways of TouchGFX application development now that you have read the above topics. Keep the API documentation handy.
  8. Target Hardware now that your finished application is ready to be deployed.

Several advanced topics go beyond standard application development and deployment.

  1. Target Configurations contains details on how board- and OS-packages are used in conjunction to construct build configurations for hardware platforms.
  2. RT Operating System (touchgfx/os/) is important for those interested in running a different OS than what TouchGFX provides (FreeRTOS).
  3. Performance Measurement Add on Cortex-M MCU instrumentation to your project in an effort to read out cpu cycles, elapsed time, and MCU load.
  4. Text Format shows you how to enable Hardware-accelerated text rendering on ST devices. This setting is used by TouchGFX applications where applicable.
  5. Advanced contains topics on the fundamental workings of TouchGFX such as TFT Controller timings and how to do performance measurements by reading out CPU cycles from Cortex-M CPUs.
  6. Porting Guide reveals the innards of the TouchGFX HAL and provides you with a complete guide to porting TouchGFX to platforms other than the ones immediately supported.

The remaining parts of this manual go into detail about the contents of a TouchGFX distribution and how to develop, build, execute and download TouchGFX applications. Advanced topics are available for those who require a different configuration than what is immediately provided by the standard TouchGFX distribution.

What is TouchGFX?

TouchGFX is a framework written in C++ that enables you to create modern graphical user interfaces on embedded systems with limited resources. That means a smartphone-like look and feel on hardware an order of magnitude less powerful than smartphones. TouchGFX is unique in its ability to provide the same user interface experience people have come to expect today, in applications that for reasons of unit cost, power consumption or otherwise cannot use the hardware platforms normally associated with that type of UI. TouchGFX achieves its smart-phone-like look and feel by making use of cutting-edge graphics invalidation routines (Occlusion Culling) and by applying clever rendering algorithms and drawing mechanisms.

To give you an easy-to-understand picture of the structure of the framework, here is a teaser diagram depicting the different layers of TouchGFX: Core, Application, OS- and Hardware Abstraction Layers and how these fit together. We will revisit the diagram later in this manual and leave you with an initial impression for now.


TouchGFX was designed to make application development as flexible and effortless as possible for application programmers by offering, amongst other things, the following:

  1. An Object-Oriented and extendable API
  2. A tool chain for generating application assets (bitmaps and fonts) and building PC Simulator applications
  3. Said PC simulator for prototyping and easy debugging
  4. A Built-in (but optional) scheme for efficient memory allocation
  5. An architecture that cleanly separates the responsibilities of the GUI from the business logic of the application

TouchGFX is able to run on a multitude of hardware platforms. A natural fit is any Cortex-M based platform, with the exact parameters, of course, depending on display resolution, memory latency and bandwidth, etc. Example platforms are:

MCUClock speedDisplay
Cortex-M0 24-48MHz 320x240 QVGA
Cortex-M3 48-64MHz 320x240 QVGA
Cortex-M3/M4 96-120MHz 480x272 WQVGA
Cortex-M3/M4 120-204MHz 800x480 WVGA
Cortex-M3/M4 180-204MHz 1024x768 XGA
Cortex-M7 200MHz 1024x768 XGA

TouchGFX can run on systems where the TFT controller is integrated in the MCU with frame buffers in external memory, or on systems that use an LCD with integrated frame buffer and controller. In some cases a Cortex-M0 based solution could also be sufficient. The framework comes with built-in support for a number of evaluation boards and MCUs. For a complete list see Supported Hardware.

The resource requirements of TouchGFX depends, of course, on the size and complexity of the specific application. Below are figures for the usage of the framework itself as well as typical requirements for UI implementations. The lower bound represent user interfaces like the simple examples included in the framework distribution. The higher bound represent very complex applications with ~200 different screens.

Int. RAM
10-20 KB (framework+stack)
1-15 KB (widgets)
Int. ROM
20 KB (framework)
1-40 KB (screen definitions, UI logic)
Ext. RAM
1-3 frame buffers in external RAM / integrated on display
Ext. Flash
1-8 MB for graphics data, fonts, text and translations.
Operating System
OS independent. Can run with (one task, two semaphores) or without (not recommended).

Background and Philosophy

The development of TouchGFX started in 2009 where existing solutions were found to be either unsuitable for the types of hardware we were concerned with, or took an approach to user interface design and implementation we felt were not quite up to date. While other solutions are certainly capable of delivering great-looking UIs, they simply cannot run on cost-efficient, low-power hardware. Other alternatives are comparable to TouchGFX in resource requirements but with concepts like resizable and minimizable windows, focus, cursors and standard look and feel widgets seem more targeted towards creating interfaces reminiscent of desktop PCs rather than smartphones.

A key design decision of TouchGFX is to prefer prerasterized (bitmap) graphics as opposed to arithmetical (vector) graphics. Apart from text rendering, almost everything is done with bitmaps. This means that the DMA can be used extensively when rendering, thereby significantly reducing the MCU load. We can also heavily optimize occlusion culling by using offline-generated data from the bitmap conversion tool. In essence, this is what enables TouchGFX to run well on the target platform range described in "What is TouchGFX?".

Another important design decision was to not include standard look and feel widgets. That means there is no built-in definition of what e.g. a button should look like. The graphics associated with the button must be supplied as part of the application thus giving it a customized look and feel, tailored to the specific application and the client's brand and style guides. By taking this approach, leaving out standard graphics, the memory footprint is reduced and better tailors the framework to be customizable to a very high degree.

Last, but not least, the framework was designed with extreme focus on memory usage and MCU load. Very rarely does an application consist of just a user interface, so there must be plenty of resources available for the system to do "real work" as well. The footprint of TouchGFX is very low and it is capable of rendering even very complex full-screen transition effects with an MCU load typically less than 15%.