Generator使用者指南

TouchGFX Generator是X-CUBE-TOUCHGFX的一部分，也是STM32CubeMX附加軟體元件，可幫助開發人員配置TouchGFX讓應用可在開發者的硬體平台上執行。根據現有的STM32CubeMX設定與使用者的輸入，TouchGFX Generator將產生用以配置一個可運作的TouchGFX應用所需的所有檔案，包含了TouchGFX HAL、TouchGFX OSAL和TouchGFX配置檔。

以STM32CubeMX產生程式碼後，可透過用來開發UI的TouchGFX Designer來打開TouchGFX專案。 TouchGFX Designer會自動將所有額外產生的程式碼檔案加入STM32CubeMX所指定的目標IDE當中。

啟用TouchGFX Generator

使用者可透過按「選擇元件（Select Components）」按鈕來存取X-CUBE以新增功能。

在STM32CubeMX中選擇附加軟體（Additional Software）

下圖展示在專案中如何啟用TouchGFX Generator：

啟用TouchGFX Generator

如果為雙核MCU啟用TouchGFX，請確保啟用正確的內容。 TouchGFX只能為單一內文啟用：

啟用適用於雙核心的TouchGFX Generator

產生程式碼的架構

在描述TouchGFX Generator的功能之前，先了解所產生程式碼的架構以及開發人員如何使用該架構來客製化配置和行為至關重要。

要保護由STM32CubeMX所產生的C程式碼中所加入的使用者程式碼，就必需將使用者程式碼置於「使用者程式碼（User Code）」程式碼區段當中。在TouchGFX Generator所產生的C++程式碼中，這樣的靈活性是透過物件繼承的方式來實現。

透過附加軟體（Additional Software）新增並啟用TouchGFX Generator之後，STM32CubeMX會一直為專案建立一個TouchGFX資料夾。無論配置如何，該資料夾總是包含相同的檔案成員，而檔案內容則因STM32CubeMX和使用者配置而異。

由以下的清單可看到啟用TouchGFX Generator之後的STM32CubeMX專案內容，並列出與TouchGFX相關較完整的檔案成員。在清單之後的表格則列出了最重要專案的職責（responsibility）。

TouchGFX 資料夾

│   .mxproject
│   myproject.ioc
├───Core
├───Drivers
├───EWARM
├───Middlewares
└───TouchGFX
    │   ApplicationTemplate.touchgfx.part
    ├───App
    │       app_touchgfx.c
    │       app_touchgfx.h
    └───target
        │   STM32TouchController.cpp
        │   STM32TouchController.hpp
        │   TouchGFXGPIO.cpp
        │   TouchGFXHAL.cpp
        │   TouchGFXHAL.hpp
        │
        └───generated
                OSWrappers.cpp
                TouchGFXConfiguration.cpp
                TouchGFXGeneratedHAL.cpp
                TouchGFXGeneratedHAL.hpp

資料夾	職責（Responsibility）
myproject.ioc	STM32CubeMX專案檔
核心	`main.c`與啟動程式碼（startup code）
驅動程式	CMSIS與MCU系列驅動程式
EWARM	IDE專案資料夾。可以為EWARM，MDK-ARM或STM32CubeIDE
中介軟體	包含TouchGFX函式庫/標頭檔以及FreeRTOS等第三方軟體。
ApplicationTemplate.touchgfx.part	STM32CubeMX使用與TouchGFX Designer專案相關的資訊（如螢幕尺寸和位元深度）來更新.part檔案
應用程式	為X-CUBE和STM32CubeMX的介面。 `app_touchgfx.c`包含了用於初始化TouchGFX並啟動其主迴圈的`MX_TouchGFX_Process (void)`和`MX_TouchGFX_Init (void)` 二個函式的定義。
目標/生成	該子資料夾包含唯讀檔，當配置更改時，這些唯讀檔會被STM32CubeMX所覆蓋。 `TouchGFXGeneratedHAL.cpp`是TouchGFX的`HAL`物件類別的子類別，包含了STM32CubeMX根據目前的設定所產生的程式碼。 `OSWrappers.cpp`（OSAL）包含與TouchGFX引擎同步所需的函式。最後是`TouchGFXConfiguration.cpp`，包含了用來建構和設定TouchGFX（包括HAL）的程式碼。
目標	包含大量的檔案，使用者可修改這些檔案以擴展HAL行為，或者修改檔案以覆蓋由STM32CubeMX產生的配置。 `STM32TouchController.cpp`包含了觸控控制器操作的空介面。 `TouchGFXHAL.cpp`定義了`TouchGFXGeneratedHAL`的物件子類別`TouchGFXHAL`。

需要注意的是TouchGFXConfiguration.cpp包含了一個用來建構HAL的函式，以及一個用於啟動TouchGFX主迴圈的函式。在可編輯的使用者類別TouchGFXHAL當中可以新增附加的配置。 HAL的一般架構如下所示：

產生的程式碼之階層結構

特性概述

啟用TouchGFX Generator之後在使用者介面可看到四個設定群組：

相依關係（Dependencies） - 此設定專案群組用來通知開發人員包含配置中的相依關係、警告或具體錯誤的訊息。若沒有條目則該專案群組將隱藏。
顯示（Display） - 此設定專案群組包含與顯示有關的配置如介面、影像緩衝區的位元深度、寬度和高度。這些配置會直接影響TouchGFX專案裡畫布（canvas）的大小以及根據圖源資產（asset）所產生的程式碼。
驅動程式（Driver） - 此設定專案群組允許使用者選擇與應用相關的時標源（tick source）、圖形加速和RTOS有關的一些現成驅動程式。由於STM32CubeMX支援FreeRTOS（CMSIS RTOS v1與v2）的配置設定，TouchGFX Generator可為每個選項提供驅動程式。
影片解碼 - 該組允許使用者啟用硬體或軟體影片解碼。該選項對於影片控制是必要的。注意！不是所有的MCU都支援影片解碼。

TouchGFX Generator有四個設定專案群組：相依關係、顯示、驅動程式以及影片解碼

顯示（Display）

顯示（Display）設定專案群組群組包含與顯示有關的配置，如介面、尺寸和緩衝區使用策略。

介面與尺寸

目前STM32微控制器可使用多種顯示介面，如：

平行RGB（LTDC）
MIPI DSI
FMC
SPI

如果MCU帶有連接到LTDC或FMC的顯示器，TouchGFX Generator可生成程式碼，以將影像緩衝器傳輸到連接的顯示器。而對於DSI和SPI介面來說，驅動程式必須由開發人員自行實作。

影像緩衝區像素格式

TouchGFX Generator目前支援以下影像緩衝像素格式。當使用“自訂”顯示介面時，所有選項均可用，否則選項被限制為顯示控制器設置（例如，在TouchGFX Generator中配置LTDC Framebuffer格式為“RGB565”將選項限制為“RGB565”）。

BW (1bpp)
Grey2 (2bpp)
Grey4 (4bpp)
ABRG2222 (8bpp)
ARGB2222 (8bpp)
BGRA2222 (8bpp)
RGBA2222 (8bpp)
RGB565 (16bpp)
RGB888 (24bpp)
ARGB8888 (32bpp)
XRGB8888 (32bpp)

Note
一些像素格式沒有或僅有部分ChromART（DMA2D）支援。

Caution
對於Cortex F7/H7：如果影像緩衝器放置在Write Through快閃記憶體（例如SRAM）中，那麼DCache會在DMA2D（如果已在Generator中進行配置）存取它之前被生成的程式碼清空。 記住要在STM32CubeMX中的Cortex M7的系統核心設置中啟用CPU快取，這樣快閃機制才能正常工作。

緩衝區策略

可透過TouchGFX Generator設定以下影像緩衝區策略：

單一影像緩衝區 - 僅使用一個應用影像緩衝區。性能可能會受限，但記憶體用量較少。可與「緩衝區位置（Buffer Location）」的配置一起使用以將其放置在內部RAM當中。若需更進一步的最佳化，使用者可以定義一個函式來回傳顯示控制器當前正在處理的「行（current line）」。框架可使用該方法在該圖框當中對內容已被傳輸到顯示器的記憶體作更新。
雙影像緩衝區 - 使用兩個影像緩衝區。通常是指以更大的記憶體用量為代價來換取更好的性能。
局部緩衝區 - 將一個或多個由使用者定義的記憶體區塊作為影像緩衝區。此策略適用於不依賴外部RAM但所使用連接的顯示器其全部完整的影像緩衝區卻超過內部可用記憶體這類型低成本的方案。

對單一緩衝區與雙緩衝區來說，使用者可透過「緩衝器位置（Buffer Location）」來設定其記憶體位置，此設定提供以下選項：

依配置（By Allocation） - 允許連結器根據連結器設定檔來放置影像緩衝記憶體。預設選項為置於內部RAM（internal RAM）中。
依位址（By Address） - 允許使用者定義一個（單）或兩個（雙）影像緩衝區位址。

局部緩衝區策略允許使用者定義以下參數：

區塊數量（始終放置在內部RAM中）
區塊大小（位元組數）

要了解有關局部緩衝策略的一些核心概念，請閱讀關於「使用局部影像緩衝區以降低記憶體用量」的專文此專文從概念上說明了如何實現局部緩衝區，而要稍微留意的是在專文中所展示的程式碼會與TouchGFX Generator所產生的程式碼略有不同。有關為這些策略而產生的具體程式碼範例，請參見影像緩衝策略。

驅動程式

這個驅動程式的設定專案群組讓開發人員可以為TouchGFX AL的各種功能選擇驅動程式。

應用時標源（Application Tick Source）

應用時標源定義了應用程式的運作進行方式。開發人員有以下的選項：

LTDC - 如果在「顯示（Display）」的設定專案群組當中將介面（Interface）設為「LTDC」，則應用時標源即可設定為「LTDC」。這表示TouchGFX Generator將在TouchGFXGeneratedHAL物件類別當中置入驅動函式（LTDC中斷處理程式）並在此驅動函式當中透過呼叫OSWrappers::signalVSync()來驅使應用程式的運作。
客製化和FMC > - 在這種情況下，開發人員需要自行實作一個處理函式（handler）以便透過重複呼叫OSWrappers::signalVSync()來驅使應用程式的運作。

圖形加速器

關於圖形加速開發人員有三個選項：

無 - 應用程式僅使用CPU來繪製圖框（frames）。
Chrom-ART (DMA2D) - 應用程式在可以使用Chrom-ART的情況下使用Chrom-ART來移動和混合像以釋放CPU資源。驅動程式由TouchGFX Generator安裝因此開發人員不需要做任何處置。

TouchGFX Generator提供的Chrom-ART （DMA2D）驅動程式支援兩種TransferCompleteInterrupt的處理方式：

使用STM32Cube HAL驅動程式，其中回呼函式（callback function）註冊到dma2d的控制程式碼（handle）hdma2d. XferCpltCallback。
直接使用中斷處理程式DMA2D_IRQHandler ()。

在STM32CubeMX藉由開啟或關閉DMA2D IP配置NVIC Setting分頁裡的DMA2D全域中斷，便可以在這兩種方式之間作切換。開啟全域中斷可以產生選項1的程式碼，關閉全域中斷可以產生選項2的程式碼。

Note
開啟使用DMA2D的全域中斷時請確保「IRQ處理函式」會呼叫DMA2D HAL處理函式，這是預設的行為。
如果在啟用全域中斷的同時閉閉DMA2D的「IRQ處理函式」和「HAL處理函式的呼叫」將導致註冊的回呼函式永遠不會被呼叫。

即時作業系統

開發人員可在TouchGFX使用任何的RTOS（甚至不使用作業系統）。如「抽象層架構（Abstration Layer Architecture）」中所述，依據使用者所選的RTOS，TouchGFX引擎使用OSWrappers介面來同步TouchGFX引擎的主要事件迴圈和影像緩衝區之間的存取。當開發者通過TouchGFX Generator選擇作業系統時，將生成程式碼並通過所選作業系統的基元實現內部同步。作業系統仍然必須通過STM32CubeMX進行配置，以確定堆疊大小等。

FreeRTOS（相容CMSIS OS）和AzureRTOS（僅適用於H7）可以直接從STM32CubeMX和TouchGFX Generator中進行配置，為使用者提供生成的程式碼，用於任務定義和TouchGFX RTOS驅動程式。 TouchGFX Generator可以生成符合CMSIS V1和CMSIS V2規範的RTOS驅動程式，該驅動程式適合任何符合CMSIS規範的RTOS，可以在沒有作業系統的裸機上運行，是面向ThreadX的原生驅動程式（通過AzureRTOS X-Cube）。在沒有作業系統的情況下，開發人員無法依賴CubeMX生成任務定義程式碼，必須在用戶程式碼中完成。

Note
所有TouchGFX開發版設置可從運行FreeRTOS的designer獲得。

下圖顯示了透過TouchGFX Generator可用的選項。

RTOS驅動程式選項

具體來說，在該圖中，AzureRTOS X-CUBE已經啟用，允許選擇ThreadX和CMSIS RTOS V2（ThreadX符合CMSIS規範)。如果FreeRTOS已啟用，“ThreadX”選項則禁用。可以通過X-CUBE-AZRTOS-H7（僅限H7）套裝軟體啟用ThreadX。

X-CUBE-AZRTOS配置

呼叫以下函式即進入TouchGFX主迴圈。

void MX_TouchGFX_Process(void);

開發者需要在執行TouchGFX任務的處理函式（task handler）當中呼叫此函式。如果使用者從STM32CubeMX配置了名為 DefaultTask 的FeeRTOS任務，則以下範例顯示了如何呼叫 MX_TouchGFX_Process() ，以啟動其任務處理函式的使用者程式碼部分中的TouchGFX。

void StartDefaultTask(void *argument)
{
  /* USER CODE BEGIN 5 */
  MX_TouchGFX_Process();
  /* USER CODE END 5 */ 
}

啟動FreeRTOS時，STM32CubeMX還將呼叫osKernelStart()，這將啟動調度器。

其他CMSIS相容的OS

當開發人員不使用STM32CubeMX 所提供的FreeRTOS和ThreadX而要採用其他CMSIS相容的即時作業系統時就必須自行手動完成RTOS配置和任務定義。通常需要以下步驟：

設定RTOS
定義用來執行TouchGFX的任務（以便在其中呼叫MX_TouchGFX_Process）
啟動排程器（scheduler）

以下是如何對ThreadX手動執行步驟2和3的範例。由於STM32CubeMX不能説明作業系統的任何配置，它不支援所有必須在提供的用戶程式碼片段中完成的的操作，以避免程式碼被覆寫。以下為GUI任務函式定義實作的虛擬程式碼（pseudo code）。任何不是由STM32CubeMX產生的程式碼通常都要分散置於main.c程式檔當中的使用者程式碼區段（User Code Sections）。

/* BEGIN USER CODE SECTION */
#include "tx_api.h"

#define GUI_THREAD_STACK_SIZE         1024
TX_THREAD gui_thread;
void    gui_thread_entry(ULONG thread_input); //Thread prototype
/* END USER CODE SECTION */

int main()
{
  /* BEGIN USER CODE SECTION - Choose an appropriate one from main.c */
  /* Allocate the stack for gui thread  */
  tx_byte_allocate(...);

  /* Create the gui thread.  */
  tx_thread_create(&gui_thread, "GUI Thread", gui_thread_entry, 0,
              pointer, GUI_TASK_STACK_SIZE,
              1, 1, TX_NO_TIME_SLICE, TX_AUTO_START);

  /* END USER CODE SECTION*/

於任務處理函式當中呼叫MX_TouchGFX_Process以啟動TouchGFX引擎主迴圈。

/* BEGIN USER CODE SECTION */
void gui_thread_entry(ULONG thread_input)
{
  MX_TouchGFX_Process();
}
/* END USER CODE SECTION*/

啟動排程器以啟動GUI任務及TouchGFX應用。

/* BEGIN USER CODE SECTION */
tx_kernel_enter();
/* END USER CODE SECTION*/

額外功能

外部資料讀取器

對於RGB565影像緩衝像素格式，TouchGFX支援所謂的資料讀取器（Data Reader）介面，讓開發者能夠直接從非記憶體映射（non-memory-mapped）的序列式快閃記憶體（serial flash）讀取資料，而無需進行暫存（caching），當然這需要增加額外的緩衝儲存區。有關如何實作DataReader以便由非記憶體映射（non-memory-mapped）的快閃記憶體當中獲取應用程式圖資（asset）的範例請參見Serial Flash文章。

資料讀取器（Data Reader）選項通常適用在如STM32G0這一類沒有足夠的記憶體用於額外緩衝區的低成本解決方案。在啟用DMA2D之後便無法啟用這個選項。

將影像緩衝像素格式（Framebuffer Pixel Format）設為RGB565之後便可看到新增了附加功能（Additional Features）設定項群組。

額外功能: 資料讀取器（Data Reader）

開發人員可進行以下設定：

外部資料讀取器：以來啟用或關閉功能。如果啟用，TouchGFX會直接透過所產生的介面獲取圖資（assets）。如果功能關閉，則開發者需要將影像暫存（cache）到記憶體緩衝區中。
外部資料讀取器：建立兩個緩衝區以便將影像或文字混合到影像緩衝區當中。預設值為一個螢幕寬度乘上4位元組以支援ARGB8888像素格式的全尺寸影像。
最小DMA傳輸量：設定啟動DMA傳輸所需的最小位元組。如果請求的傳輸量少於最小位元組便不會用到DMA。

在啟用外部資料讀取器（External Data Reader）的情況下產生程式碼會建立如下的附加檔案以利直接從非記憶體映射（non-memory-mapped）的快閃記憶體中獲取圖資（asset）。

TouchGFX/target/generated/TouchGFXGeneratedDataReader.cpp
TouchGFX/target/generated/TouchGFXGeneratedDataReader.hpp
TouchGFX/target/TouchGFXDataReader.cpp
TouchGFX/target/TouchGFXDataReader.hpp

像往常一樣，TouchGFX Generator產生的程式碼TouchGFXGeneratedDataReader為唯讀，使用者的修改應該要在TouchGFXDataReader物件類別中進行。而TouchGFXGeneratedDataReader繼承自touchgfx::FlashDataReader 物件類別。

TouchGFX Generator會修改以下檔案來配置TouchGFX HAL以使用DataReader。

TouchGFX/target/generated/TouchGFXConfiguration.cpp
TouchGFX/target/generated/TouchGFXGeneratedHAL.cpp
TouchGFX/target/generated/TouchGFXGeneratedHAL.hpp

Note
只有在同時關閉DMA2D與LTDC的情況之下才可使用DataReader附加功能。

8位元 LTDC顏色查找表（Look-up Table）

當LTDC設定為以L8的格式讀取影像緩衝區，並且TouchGFX以[ABRG2222](.. /.. /api/classes/classtouchgfx_1_1_l_c_d8bppa_b_g_r2222), [ARGB222](.. /.. /api/classes/classtouchgfx_1_1_l_c_d8bppa_r_g_b2222), [BGRA2222](.. /.. /api/classes/classtouchgfx_1_1_l_c_d8bppb_g_r_a2222)，或[RGBA2222](.. /.. /api/classes/classtouchgfx_1_1_l_c_d8bppr_g_b_a2222)的方式作渲染算圖時，TouchGFX Generator將提供CLUT，並在TouchGFXHAL::initialize()期間將該CLUT載入到LTDC中。有關LTDC和CLUT的用法，詳見STM32 MCU參考手冊。

影片解碼

‘影片解碼’部分允許開發人員通過硬體或軟體影片解碼能力增強TouchGFX HAL。

影片解碼僅支援RGB565（16bpp）和RGB888（24bpp）影像緩衝像素格式。如果沒有選擇這兩種格式，則影片解碼部分將不可用。

Note
不是所有MCU都支援硬體影片解碼。

類型

預設情況下，影片解碼的”類型”是禁用的。如果STM32CubeMX中沒有啟用所需的外設，“軟體”和“硬體”都將顯示為灰色。將滑鼠懸停在灰色的選項上，看看需要哪些外設。

資訊框顯示“硬體”的影片類型依賴項

軟體 - 如果在STM32CubeMX的中介軟體部分啟用了LIBJPEG，則可以選擇“軟體”選項，並生成軟體解碼器。這意味著TouchGFX Generator將生成一個軟體MJPEG解碼器。
硬體 - 如果在多媒體部分啟用了JPEG，並且在TouchGFX Generator中選擇了符合CMSIS要求的RTOS，則可以選擇“硬體”選項。

影片解碼類型選項

在LIBJPEG設置中，為了提高效率，“RGB掃描線格式”中的RGB排序必須設置為“BGR”而不是“RGB”。每個像素的位元組數必須設置為3。

需要的LIBJPEG RGB掃描線格式設置

使用硬體解碼時，JPEG設置中的RGB格式必須與顯示器相同。

併發影片

“併發影片”選項可設置GUI中任意給定時間在同一螢幕上同時被解碼的最大數量影片。如果希望一塊螢幕上只解碼一個影片，則可以將“影片數量”設置為1。

最多可以同時解碼4個影片。

策略

關於影片解碼策略，開發人員有三種選擇。

“直接到影像緩衝區（Direct to Framebuffer）” - 影片在UI執行緒中被解碼。解碼速度慢於其他策略。使用硬體影片解碼時，“直接到影像緩衝區（Direct to Framebuffer）選項不可被使用。
單緩衝區 - 在專用的緩衝區中，以單獨的任務進行影片解碼。該緩衝區位於內部記憶體中。
雙緩衝區 - 在兩個專用緩衝區中，以單獨的任務進行影片解碼，以犧牲記憶體為代價獲得更好的性能。

採用單或雙影像緩衝區策略時，必須啟用符合CMSIS要求的作業系統。

關於CMSIS RTOS要求的資訊框

Note
使用雙緩衝區策略時，要注意記憶體消耗。

解碼格式

對於軟體解碼，開發人員可以選擇RGB緩衝區的像素格式，不管影像緩衝區的像素格式是什麼。 TouchGFX Generator生成的程式碼允許ChromART在不同的格式之間進行像素格式轉換。在RGB565中擁有影片解碼緩衝區允許開發人員佔用更小的記憶體。

解碼格式

緩衝區大小：

緩衝區的寬度和高度設置必須對應應用程式中的最大影片尺寸。寬度值必須能被32整除。

以下程式碼是在TouchGFXGeneratedHAL.cpp中生成的程式碼，其面向的應用程式使用RGB888顯示器 - 採用480*272影片和“單緩衝區”影片解碼策略。

TouchGFXGeneratedHAL.cpp

#include <DedicatedBufferVideoController.hpp>
#include <SoftwareMJPEGDecoder.hpp>

uint32_t lineBuffer[480];

SoftwareMJPEGDecoder mjpegdecoder1((uint8_t*)lineBuffer);

uint32_t videoRGBBuffer[97920];
DedicatedBufferController<1, 480, 272, 480*3U, Bitmap::RGB888> videoController;

//Singleton Factory
VideoController& VideoController::getInstance()
{
    return videoController;
}

void TouchGFXGeneratedHAL::initialize()
{
    HAL::initialize();
    registerEventListener(*(Application::getInstance()));
    setFrameBufferStartAddresses((void*)frameBuf, (void*)(frameBuf + sizeof(frameBuf) / (sizeof(uint32_t) * 2)), (void*)0);

    /*
     * Add software decoder to video controller
     */
    videoController.addDecoder(mjpegdecoder1, 0);

    videoController.setRGBBuffer((uint8_t*)videoRGBBuffer, sizeof(videoRGBBuffer));
}

產生的專案

使用STM32CubeMX中的產生程式碼（Generate Code）按鈕產生程式碼時可產生以下IDE的TouchGFX專案檔：

EWARM
MDK-ARM
STM32CubeIDE

藉由選取以下與專案產生相關的選項可以得到較佳的專案目錄結構：

應用結構：進階
關閉 Generate under root（僅適用於STM32CubeIDE）

選取「進階的應用程式結構（Advanced application structure）」並取消選取「Generate under root」

STM32CubeMX還會產生具有以下目錄結構的TouchGFX資料夾：

TouchGFX資料夾結構

應用資料夾包含用於初始化和啟動TouchGFX的程式碼。
target資料夾包含產生的唯讀程式檔（置於generated/目錄中）和可修改的使用者物件類別檔（STM32TouchController.cpp ，TouchGFXGPIO.cpp和TouchGFXHAL.cpp）
.part檔案，使用TouchGFX Designer來開啟以建立完整的TouchGFX專案（包括TouchFX的標頭檔和函式庫）。part檔案包含為了產生TouchGFX應用程式碼設計人員需使用的相關程式資訊（如像素格式與畫布尺寸）。

TouchGFX Designer專案

以下程式碼是在產生程式碼的架構（Generated Code Architecture）章節當中提及的.part檔案內容的範例。當TouchGFX Designer建立新檔案（如新螢幕與圖資）時，後置產生指令（post-generate command，如下所示）會更新STM32CubeMX中選擇的專案（如EWARM ）。

{
 "Application": {
 "Name": "my_project",
 "TouchGfxPath": "../Middlewares/ST/touchgfx",
 "AvailableColorDepths": [ 16 ],
 "AvailableLCDs":
  {
    "16": "LCD16bpp"
 },
 "AvailableResolutions" :
 [
  {
    "Width": 320,
    "Height": 240
  }
 ],
 "PostGenerateTargetCommand" : "touchgfx update_project --project-file=../my_project.ioc --platform=m7"
 },
 "Version": "4.13.0"
}

使用TouchGFX Designer開啟.part檔案時，開發人員可以選擇載入具體實際的UI或從空白範本開始。

選擇UI

按下TouchGFX Designer當中的產生程式碼（Generate Code）之後可得到如下的TouchGFX資料夾結構。由下圖可看到TouchGFX資料夾結構的具體範例，當中以高亮度強調了產生後的新檔案及資料夾。

產生程式碼

TouchGFX資料夾結構

TouchGFX將從STM32CubeMX的.ioc檔當中偵測所選取的IDE（STM32CubeIDE，EWARM，MDK-ARM），並使用新生成的檔案（如用於螢幕定義、圖像和字型的圖資）來更新專案檔。

此時，開發人員可以交互使用STM32CubeMX，TouchGFX Designer和工具鏈/IDE，其中：

STM32CubeMX可以更新IDE專案中的驅動程式
STM32CubeMX根據UI相關變更來更新TouchGFX .part檔案，而設計工具（designer）可同時立即取得這些變更
STM32CubeMX根據TouchGFX與平台相關的TouchGFX Generator配置來產生HAL程式碼（TouchGFX/target/generated/）。
TouchGFX Designer使用產生的程式碼來更新專案。

Note
對於雙核專案（為特定內文啟用TouchGFX），TouchGFX專案通常會位於該內文的專用資料夾中，例如:“CM4 / TouchGFX”或“CM7 / TouchGFX”。

修改所產生的行為

需要注意的是，HAL的物件類別階層結構讓使用者可以覆寫（override）STM32CubeMX所產生的HAL配置或行為（behavior）。在以下範例中，開發人員可以修改initialize函式對TouchGFX作額外的配置，或修改TouchGFXGeneratedHAL當中現有的配置集組。

TouchGFXHAL.cpp

void TouchGFXHAL::initialize()
{
    // Calling parent implementation of initialize().
    //
    // 若要覆寫生成的實現，請忽略對父函數的呼叫
    // 並在此處實現所需的功能。
    // 請注意：必須呼叫HAL::initialize()以初始化框架。

    TouchGFXGeneratedHAL::initialize();

    //覆蓋配置
    hal.lockDMAToFrontPorch(true);
    hal.setFingerSize(4);
    hal....
}

升級專案

TouchGFX Generator的相關參數儲存在STM32CubeMX專案檔.ioc當中。當發佈新版TouchGFX Generator時，舊版的參數可能與新版的參數不相容，此時便需要進行轉移（migration）。

STM32CubeMX不支援X-CUBE版本之間的升級。而由於.touchgfx檔案內PostGenerateTargetCommand當中的指令（如下所示），因此在按下Generate Code時TouchGFX Designer會自動執行升級。

.touchgfx

"PostGenerateTargetCommand" : "touchgfx update_project --project-file=../upgrade.ioc --platform=m7"

這道指令將讀取.ioc檔並更新參數以適應X-CUBE-TOUCHGFX目前的版本。由以下範例可以看到如何透過手動執行X-CUBE-TOUCHGFX 4.14.0的腳本（script）指令對X-CUBE-TOUCHGFX 4.13.0所建立的.ioc檔案進行升級。

使用STM32F746 DISCO應用範本從4.13.0升級到4.14.0的範例

$ touchgfx update_project --project-file=../STM32F746G_DISCO.ioc
  TouchGFX Generator 4.13.0 found
  Creating backup of ../STM32F746G_DISCO.ioc as ../backup_STM32F746G_DISCO.ioc
  Performing upgrade 4.13.0 -> 4.14.0 ... OK

以STM32CubeMX開啟升級過的專案時CubeMX會提示使用者要安裝.ioc檔所指定的X-CUBE-TOUCHGFX版本（若指定版本尚未安裝的情況下）。點選立即下載（Download now）後將下載並安裝X-Cube-TouchGFX-4.14.0。

遺漏附加軟體：TouchGFX Generator 4.14.0

升級期間會保留TouchGFX Generator中的所有設定，.ioc檔的備份檔會以前置檔名backup_的方式放成原始檔旁。

Note
要使用TouchGFX Generator所提供的新功能必須在STM32CubeMX中再執行產生程式碼（Generate Code）。

Caution
如果透過STM32CubeMX（而不是透過TouchGFX Designer）來執行為現有的TouchGFX專案升級X-CUBE-TOUCHGFX，TouchGFX Generator參數將被重置為預設值。

啟用TouchGFX Generator​

產生程式碼的架構​

TouchGFX 資料夾

特性概述​

顯示（Display）​

介面與尺寸​

Further reading

影像緩衝區像素格式​

Note

Caution

Further reading

緩衝區策略​

驅動程式​

應用時標源（Application Tick Source）​

圖形加速器​

Note

即時作業系統​

Note

其他CMSIS相容的OS​

額外功能​

外部資料讀取器​

Note

8位元 LTDC顏色查找表（Look-up Table）​

影片解碼​

Note

類型​

Further reading

併發影片​

策略​

Note

Further reading

解碼格式​

緩衝區大小：​

TouchGFXGeneratedHAL.cpp

產生的專案​

TouchGFX Designer專案​

Note

修改所產生的行為​

TouchGFXHAL.cpp

升級專案​

.touchgfx

使用STM32F746 DISCO應用範本從4.13.0升級到4.14.0的範例

Note

Caution

啟用TouchGFX Generator

產生程式碼的架構

特性概述

顯示（Display）

介面與尺寸

影像緩衝區像素格式

緩衝區策略

驅動程式

應用時標源（Application Tick Source）

圖形加速器

即時作業系統

其他CMSIS相容的OS

額外功能

外部資料讀取器

8位元 LTDC顏色查找表（Look-up Table）

影片解碼

類型

併發影片

策略

解碼格式

緩衝區大小：

產生的專案

TouchGFX Designer專案

修改所產生的行為

升級專案