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以新增功能。
下圖展示在專案中如何啟用TouchGFX Generator:
如果為雙核MCU啟用TouchGFX,請確保啟用正確的內容。 TouchGFX只能為單一內文啟用:
產生程式碼的架構
在描述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都支援影片解碼。
顯示(Display)
顯示(Display)設定專案群組群組包含與顯示有關的配置,如介面、尺寸和緩衝區使用策略。
介面與尺寸
目前STM32微控制器可使用多種顯示介面,如:
- 平行RGB(LTDC)
- MIPI DSI
- FMC
- SPI
如果MCU帶有連接到LTDC或FMC的顯示器,TouchGFX Generator可生成程式碼,以將影像緩衝器傳輸到連接的顯示器。 而對於DSI和SPI介面來說,驅動程式必須由開發人員自行實作。
Further reading
影像緩衝區像素格式
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
Caution
Further reading
緩衝區策略
可透過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生成,因此開發人員不需要做任何處置。
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
- GPU2D(NeoChrom)是一種圖形加速器,能夠加速TouchGFX中的許多繪圖操作,包括紋理映射。 它支援RGB565、RGB888和ARGB8888格式的影像緩衝區。
Caution
即時作業系統
開發人員可在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
下圖顯示了透過TouchGFX Generator可用的選項。
Note
從STM32CubeMX提供的中介軟體清單啟用和配置ThreadX
ThreadX成功的記憶體配置取決於記憶體池分配。 推薦數值為靜態配置(Static Allocation)。 在ThreadX中介軟體配置中執行以下步驟:
- 從模式清單中選擇
Core
來啟用THREADX
中介軟體,如下圖所示。 - 將
TX_TIMER_TICKS_PER_SECOND
設定為1000,以獲取每毫秒的計時 - 將
記憶體池分配
設定為使用靜態配置(Use Static Allocation)
Caution
- 當記憶體池分配設定為使用動態分配時
- 用戶必須在生成的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。 現在您可以安全地關閉套裝軟體元件選擇器。
- 從左側的類別列表中選擇套裝軟體組,並選擇STMicroelectronics.X-CUBE-AZRTOS-XX
- 通過選擇RTOS ThreadX模式來啟用ThreadX
- 將
記憶體池分配
設定為使用靜態配置(Use Static Allocation)
- 將
TX_TIMER_TICKS_PER_SECOND
設定為1000,以獲取每毫秒的計時。
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
其他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)設定項群組。
開發人員可進行以下設定:
- 外部資料讀取器:以來啟用或關閉功能。 如果啟用,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
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
類型
預設情況下,影片解碼的”類型”是禁用的。 如果STM32CubeMX中沒有啟用所需的外設,“軟體”和“硬體”都將顯示為灰色。 將滑鼠懸停在灰色的選項上,看看需要哪些外設。
- 軟體 - 如果在STM32CubeMX的中介軟體部分啟用了LIBJPEG,則可以選擇“軟體”選項,並生成軟體解碼器。 這意味著TouchGFX Generator將生成一個軟體MJPEG解碼器。
- 硬體 - 如果在多媒體部分啟用了JPEG,並且在TouchGFX Generator中選擇了符合CMSIS要求的RTOS,則可以選擇“硬體”選項。
在LIBJPEG設置中,為了提高效率,“RGB掃描線格式”中的RGB排序必須設置為“BGR”而不是“RGB”。 每個像素的位元組數必須設置為3。
使用硬體解碼時,JPEG設置中的RGB格式必須與顯示器相同。
Further reading
併發影片
“併發影片”選項可設置GUI中任意給定時間在同一螢幕上同時被解碼的最大數量影片。 如果希望一塊螢幕上只解碼一個影片,則可以將“影片數量”設置為1。
最多可以同時解碼4個影片。
策略
關於影片解碼策略,開發人員有三種選擇。
- “直接到影像緩衝區(Direct to Framebuffer)” - 影片在UI執行緒中被解碼。 解碼速度慢於其他策略。 使用硬體影片解碼時,“直接到影像緩衝區(Direct to Framebuffer)選項不可被使用。
- 單緩衝區 - 在專用的緩衝區中,以單獨的任務進行影片解碼。 該緩衝區位於內部記憶體中。
- 雙緩衝區 - 在兩個專用緩衝區中,以單獨的任務進行影片解碼,以犧牲記憶體為代價獲得更好的性能。
採用單或雙影像緩衝區策略時,必須啟用符合CMSIS要求的作業系統。
Note
Further reading
解碼格式
對於軟體解碼,開發人員可以選擇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)
STM32CubeMX還會產生具有以下目錄結構的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或從空白範本開始。
按下TouchGFX Designer當中的產生程式碼(Generate Code)之後可得到如下的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
修改所產生的行為
需要注意的是,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中的所有設定,.ioc檔的備份檔會以前置檔名backup_
的方式放成原始檔旁。