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)”。

相依關係（Dependencies） - 此設定專案群組用來通知開發人員包含配置中的相依關係、警告或具體錯誤的訊息。若沒有條目則該專案群組將隱藏。
顯示（Display） - 此設定專案群組包含與顯示有關的配置如介面、影像緩衝區的位元深度、寬度和高度。這些配置會直接影響TouchGFX專案裡畫布（canvas）的大小以及根據圖源資產（asset）所產生的程式碼。
驅動程式（Driver） - 此設定專案群組允許使用者選擇與應用相關的時標源（tick source）、圖形加速（DMA2D and GPU2D）和RTOS有關的一些現成驅動程式。由於STM32CubeMX支援FreeRTOS（CMSIS RTOS v1與v2）的配置設定，TouchGFX Generator可為每個選項提供驅動程式。
其他功能-如果選擇了RGB565，則會顯示此群組，允許使用者使用非記憶體映射中的圖像和字體資料創建應用程式。
影片解碼 - 該組允許使用者啟用硬體或軟體影片解碼。該選項對於影片控制是必要的。注意！不是所有的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
對於STM32F7/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進行渲染。
DMA2D 加速器（Chrom-ART）- 應用程式在可能的情況下使用Chrom-ART晶片來移動和混合像素，釋放CPU週期。驅動程式由TouchGFX Generator生成，因此開發人員不需要做任何處置。

對於支援DMA2D的MCU，可在CubeMX中的*多媒體(Multimedia)*類別中啟用DMA2D。

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處理函式的呼叫」將導致註冊的回呼函式永遠不會被呼叫。

GPU2D（NeoChrom）是一種圖形加速器，能夠加速TouchGFX中的許多繪圖操作，包括紋理映射。它支援RGB565、RGB888和ARGB8888格式的影像緩衝區。

對於支援DMA2D的MCU，可在CubeMX中的*多媒體(Multimedia)*類別中啟用GPU2D。

Caution
只有當CubeMX中專案的多媒體(Multimedia)部分啟用了GPU2D, GPU2D選項才可見。 它只適用於STM32U599設備，並且只有在中介軟體(Middlewares)部分的ThreadX RTOS也被啟用的情況下，才能與TouchGFX一起使用。

即時作業系統

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

FreeRTOS (CMSIS OS V1和V2) 和ThreadX(本地中介軟體或Azure RTOS套裝軟體) 可直接在STM32CubeMX和TouchGFX 生成器中配置，為使用者提供任務定義和TouchGFX RTOS驅動程式的生成程式碼。 TouchGFX Generator 可生成符合CMSIS V1和CMSIS V2標準的RTOS驅動程式，與任何符合CMSIS標準的RTOS一起運行，一個用於ThreadX的驅動程式，一個用於在沒有作業系統的情況下運行裸機的驅動程式。

ThreadX

可通過選擇AZRTOS套裝軟體或啟用STM32CubeMX中的Native ThreadX 中介軟體（如果適用於選定的MCU設備）來啟用ThreadX。

Note
預設情況下，所有新型STM32 MCU設備支援直接從STM32CubeMX獲得的ThreadX 中介軟體，無需另外下載。 TouchGFX 開發板支援包將緩慢過渡到使用可用的ThreadX中介軟體或X-CUBE-AZRTOS套裝軟體。
提供ThreadX支援的X-CUBE-AZRTOS-XX擴展包已可用於STM32G0xx、STM32G1xx、STM32 L4xx、ST M32F4xx，STM32F7xx和STM32H7xx MCU系列。

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

RTOS驅動程式選項

Note
啟用ThreadX中介軟體時，禁用NoOS選項。
啟用ThreadX中介軟體時，CMSIS_RTOS_V1和CMSIS_RTOS_V2選項被禁用。 意法半導體不提供CMSIS OS封裝，客戶必須選擇客製選項並執行CMSIS封裝。

從STM32CubeMX提供的中介軟體清單啟用和配置ThreadX

ThreadX成功的記憶體配置取決於記憶體池分配。推薦數值為靜態配置(Static Allocation)。在ThreadX中介軟體配置中執行以下步驟：

從模式清單中選擇Core來啟用THREADX中介軟體，如下圖所示。
將TX_TIMER_TICKS_PER_SECOND設定為1000，以獲取每毫秒的計時
將記憶體池分配設定為使用靜態配置(Use Static Allocation)

啟用並配置本機ThreadX中介軟體

Caution
啟用本機ThreadX中介軟體(Native ThreadX Middleware)時，記憶體池分配(Memory Pool Allocation)應設定為使用動態分配(Use Dynamic Allocation)
當記憶體池分配設定為使用動態分配時
用戶必須在生成的app_azure_rtos.c檔的User code BEGIN DYNAMIC_MEM_ALLOC部分中添加缺失的程式碼。
用戶還需要根據生成的app_azure_rtos.c檔中描述的建議更新連結器檔。

從AZRTOS套裝軟體啟用並配置ThreadX

選擇套裝軟體(Software Packs)->選擇組件(Components)或按Alt-O鍵。
選擇STMicroelectonics.X-CUBE-AZRTOS-XX。如果需要，請下載此套裝軟體。
選擇RTOS ThreadX並勾選Core核取方塊以啟用ThreadX。現在您可以安全地關閉套裝軟體元件選擇器。

從X-CUBE-AZRTOS套裝軟體啟用ThreadX

從左側的類別列表中選擇套裝軟體組，並選擇STMicroelectronics.X-CUBE-AZRTOS-XX
通過選擇RTOS ThreadX模式來啟用ThreadX
將記憶體池分配設定為使用靜態配置(Use Static Allocation)

ThreadX配置 - X-CUBE-AZRTOS套裝軟體

將TX_TIMER_TICKS_PER_SECOND設定為1000，以獲取每毫秒的計時。

ThreadX配置 - X-CUBE-AZRTOS套裝軟體

FreeRTOS

呼叫以下函式即進入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 */ 
}

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

ThreadX中介軟體

STM32CubeMX不再負責為中介軟體和用戶生成創建執行緒的程式碼。
STM32CubeMX將生成對MX_TouchGFX_PreOSInit()函數的呼叫，該函數將初始化TouchGFX框架
STM32CubeMX將生成對MX_ThreadX_Init()()函數的呼叫，該函數將初始化並啟動ThreadX內核

int main(void)
{
  /* Call PreOsInit function */
    MX_TouchGFX_PreOSInit();
  /* USER CODE BEGIN 2 */

  /* USER CODE END 2 */

  MX_ThreadX_Init();
}

TouchGFX生成器將生成MX_TouchGFX_PreOSInit()函數，該函數將簡單呼叫touchgfx_init()

/**
 * PreOS Initialization function
 */
void MX_TouchGFX_PreOSInit(void)
{
  // Calling forward to touchgfx_init in C++ domain
  touchgfx_init();
}

TouchGFX Generator將生成MX_TouchGFX_Init()函數，該函數將創建TouchGFX執行緒

/**
 * Create TouchGFX Thread
 */
UINT MX_TouchGFX_Init(VOID *memory_ptr)
{
  UINT ret = TX_SUCCESS;
  CHAR *pointer = 0;

  /* Allocate the stack for TouchGFX Thread.  */
  if (tx_byte_allocate((TX_BYTE_POOL*)memory_ptr, (VOID **) &pointer,
                       TOUCHGFX_STACK_SIZE, TX_NO_WAIT) != TX_SUCCESS)
  {
    ret = TX_POOL_ERROR;
  }

  /* Create TouchGFX Thread */
  else if (tx_thread_create(&TouchGFXThread, (CHAR *)"TouchGFX", TouchGFX_Task, 0,
                       pointer, TOUCHGFX_STACK_SIZE,
                       5, 5,
                       TX_NO_TIME_SLICE, TX_AUTO_START) != TX_SUCCESS)
  {
    ret = TX_THREAD_ERROR;
  }

  return ret;
}

TouchGFX Generator將生成所需的程式碼，這些程式碼將被STM32CubeMX插入到app_azure_rtos.c文件中

  /**
  * @brief  Define the initial system.
  * @param  first_unused_memory : Pointer to the first unused memory
  * @retval None
  */
VOID tx_application_define(VOID *first_unused_memory)
{
  ...

  if (tx_byte_pool_create(&touchgfx_app_byte_pool, "TouchGFX App memory pool", touchgfx_byte_pool_buffer, TOUCHGFX_APP_MEM_POOL_SIZE) != TX_SUCCESS)
  {
    /* USER CODE BEGIN TouchGFX_Byte_Pool_Error */

    /* USER CODE END TouchGFX_Byte_Pool_Error */
  }
  else
  {
    /* USER CODE BEGIN TouchGFX_Byte_Pool_Success */

    /* USER CODE END TouchGFX_Byte_Pool_Success */

    memory_ptr = (VOID *)&touchgfx_app_byte_pool;
    if (MX_TouchGFX_Init(memory_ptr) != TX_SUCCESS)
    {
      /* USER CODE BEGIN  MX_X-CUBE-TOUCHGFX_Init_Error */
      while(1);
      /* USER CODE END  MX_X-CUBE-TOUCHGFX_Init_Error */
    }
    /* USER CODE BEGIN  MX_X-CUBE-TOUCHGFX_Init_Success */

    /* USER CODE END  MX_X-CUBE-TOUCHGFX_Init_Success */
  }

  ...
}

tx_application_define()函數在初始化時由ThreadX內核呼叫。
The MX_TouchGFX_Init()函數由tx_application_define()呼叫。
TouchGFX執行緒將在稍後啟動ThreadX內核時啟動。

Note
STM32CubeMX僅為ThreadX中介軟體生成靜態記憶體池分配配置的完整程式碼。
如果您想用動態記憶體分配來配置ThreadX，請參考X-CUBE-TOUCHGFX擴展包中的STM32H7B3I-DK/Applications/AnimatedImages範例

其他CMSIS相容的OS

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

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

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

void MX_TouchGFX_Process(void);

額外功能

外部資料讀取器

對於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專案

以下json結構是基於STM32U599的專案“生成程式碼體系結構”部分中提到的.part檔內容範例。以下範例中的後期生成指令將使用TouchGFX和可選元件所需的庫以及TouchGFX Designer創建的新檔（如：新螢幕和資產）更新使用者在STM32CubeMX專案管理器選項卡（如：EWARM）中選擇的專案。

{
  "Application": {
    "Name": "STM32U599J-DK",
    "TouchGfxPath": "../Middlewares/ST/touchgfx",
    "AvailableColorDepths": [ 24 ],
    "AvailableLCDs":
    {
      "24": "LCDGPU2D"
    },
    "AvailableResolutions": [
      {
        "Width": 480,
        "Height": 480
      }
    ],
    "PostGenerateTargetCommand": "touchgfx update_project",
    "Family": "STM32U5",
    "SubFamily": "STM32U599/5A9",
    "Platform": "m33",
    "ProjectFile": "../STM32U599J-DK.ioc",
    "OptionalComponentsRoot": "../Middlewares/ST/touchgfx_components",
    "OptionalComponents": [
      "GPU2D"
    ]
  },
  "Version": "4.19.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

Caution

即時作業系統​

ThreadX​

Note

Note

從STM32CubeMX提供的中介軟體清單啟用和配置ThreadX​

Caution

從AZRTOS套裝軟體啟用並配置ThreadX​

FreeRTOS​

ThreadX中介軟體​

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）

圖形加速器

即時作業系統

ThreadX

從STM32CubeMX提供的中介軟體清單啟用和配置ThreadX

從AZRTOS套裝軟體啟用並配置ThreadX

FreeRTOS

ThreadX中介軟體

其他CMSIS相容的OS

額外功能

外部資料讀取器

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

影片解碼

類型

併發影片

策略

解碼格式

緩衝區大小：

產生的專案

TouchGFX Designer專案

修改所產生的行為

升級專案