已知問題

本文列出了所有TouchGFX版本中已知存在的問題以及潛在的權宜措施。 此外，如果您需要執行任何特定的升級步驟才能將TouchGFX升級至特定版本，文中將會提到。 請注意，如果當前版本與最新版本之間隔了幾個版本，您需要執行所有版本的升級步驟，直至升級到最新版本。

CubeMX 6.1.0和CubeProgrammer 2.6的問題

由於“C/C++編譯器” / “語言”選項的錯誤設置（從“自動”更改為“C++”導致編譯錯誤），CubeMX生成的版本CubeMX 6.1.0 EWARM專案不能與X-CUBE-TOUCHGFX一起使用。 此問題將在CubeMX 6.1.1中進行修正。 在此期間，將選項手動改回“自動”將解決編譯問題，但是會在CubeMX生成程式碼時恢復。

CubeProgrammer 2.6中與外部載入器（.stldr）參照方式相關的問題會損壞所有現有應用範本（AT）的Makefile，還會妨礙TouchGFX Designer中“運行目標”特性的正常工作。 此問題還擴展到基於最新AT版本的用戶專案。 應用範本將獲得更新以修復此問題，並將適用於CubeProgrammer 2.5和2.6。 如果您已有了不能與CubeProgrammer 2.6一起使用的基於AT的專案，您可以進行下列修改以添加支援。 在引用外部資料夾時，用戶必須從bin資料夾執行STM32CubeProgrammer_CLI.exe。 一般而言，指：

• cd到STM32CubeProgrammer安裝資料夾的bin資料夾。
• 執行指令，通過對.stldr檔的相對參照對連接的目標硬體進行程式設計。

@cd "$(st_stm32cube_programmer_bin_path)" && ./$(stm_stm32cube_programmer_exe) -c port=SWD -d $(application_path)/$(binary_output_path)/target.hex -el $(stm32cubeLoader_relative_path) -hardRst

TouchGFX 4.18.0

新的.touchgfx格式

從TouchGFX 4.17.0到TouchGFX 4.18.0，.touchfgx檔的內容在兩個主要區域發生了重大改變。 這可能會導致一個全面更新的.touchfgx檔，只需使用TouchGFX Designer打開和保存.TouchGFX專案檔案。 主要變化在以下領域：

預設值不寫入 .touchgfx

具有預設值（例如框體偏移X=0，Y=0或黑色（紅色=0，綠色=0，藍色=0））的小工具參數之前被寫入.touchfgx文件；但在TouchGFX版本4.18.0中，這些值不會寫入。 這可能導致稍小一些的.touchgfx文件。

刪除了TextEntries塊

SingleUseId已經被重命名，以包含亂數字和字母（而不是連續的數字），以便合併一個專案與幾個活躍的開發人員，因為新的一次性使用文字id不會獲得相同的id。 另外，. touchgfx中的“TextEntries”部分已被刪除，這可能會導致. touchgfx檔尺寸大大減少。

LCD16bpp::fillRect與LCD16bpp::drawGlyph

LCD16bpp中的fillRect和drawGlyph函數現在將完整的24位顏色（而不是縮減後的16位（RGB565）顏色）傳遞給DMA。 這可能會導致硬體（而不是模擬器）上出現錯誤的顏色，可以通過從CubeMX重新生成DMA類來修復。

Makefile和xlsx

TouchGFX 4.18.0使用新的.xml格式（而不是以前使用的舊的.xlsx格式）來存儲文字和譯文。 這意味著Makefiles和visual studio專案中所有對"text.xlsx"的引用都應該改為"text.xml"。 TextConvert工具將識別這一點（即使舊的texts.xlsx文件存在而texts.xml不存在），並將texts.xlsx轉換為texts.xml（面向所有未來用途）。

要看到正常工作的新Makefile，只需使用TouchGFX Designer新建一個（空白）專案，並諮詢生成的Makefile（位於資料夾generated/simulator/gcc/Makefile中）。

Linux上的SDL2連結器錯誤

現在只為Windows用戶而包括模擬器使用的SDL2庫。 Linux用戶必須自己安裝SDL2庫。 這是一個只需要執行一次的任務；而對於ubuntu，指令

sudo apt install libsdl2-dev libsdl2-image-dev

可安裝libsdl2和libsdl2-image，包括用於開發的標頭檔

TouchGFX 4.17.0

繪圖工具不再支援setAlpha()

出於性能方面的考慮，Canvas Widget Renderer（CWR）使用的繪圖工具不再支援alpha。 通過在有繪圖工具的畫布小部件上設置alpha，仍然可以達到效果。 一般而言，可以將下面這樣的程式碼：

painter.setColor(Color::getColorFromRGB(0xFF, 0x00, 0x00));
painter.setAlpha(128);
circle.setPainter(painter);

修改成這樣：

painter.setColor(Color::getColorFromRGB(0xFF, 0x00, 0x00));
circle.setPainter(painter);
circle.setAlpha(128);

如果之前將alpha應用於繪圖工具和畫布小部件，可以將這兩個alpha值相乘，然後除以255，如下所示：

painter.setColor(Color::getColorFromRGB(0xFF, 0x00, 0x00));
painter.setAlpha(painterAlpha);
circle.setPainter(painter);
circle.setAlpha(circleAlpha);

變成

painter.setColor(Color::getColorFromRGB(0xFF, 0x00, 0x00));
circle.setPainter(painter);
circle.setAlpha((painterAlpha * circleAlpha) / 255);

或者使用LCD::div255()而不是除以255。

使用HAL類

在版本4.17.0之前，完全不使用HAL的TouchGFX框架中的多個檔案包含標頭檔touchgfx/hal/HAL.hpp。 這些不必要的引用已被清理，這可能導致用戶程式碼由於HAL不為編譯器所知而不進行編譯。 為了修正這個問題，只需包含HAL標頭檔，如下所示：

#include <touchgfx/hal/HAL.hpp>

或者，Screen類有兩個新的函數getScreenWidth()和getScreenHeight()，用於給出螢幕尺寸。 這是獲取螢幕尺寸的推薦方式，可從Screen的任意子類（如Screen1View.cpp）直接呼叫。

TouchGFX Generator中的FMC顯示介面

當使用TouchGFX Generator中新的FMC顯示介面時，在用CubeMX 6.2.1生成時FMC存儲區的記憶體偏移將不正確（零）。 這會在CubeMX 6.3.0中修正，在發佈時，X-CUBE-TouchGFX需要的最低版本將跳至6.3.0而不是目前的6.2.1。 到那時，用戶可以在TouchGFXGeneratedHAL.cpp中輸入正確的FMC BANK存儲位址（將在重新生成時被覆蓋）。 如

#define FMC_BANK1_REG ((uint16_t *) 0x60000000)
#define FMC_BANK1_MEM ((uint16_t *) 0x60000002)

用戶還可以在TouchGFXHAL.cpp中全部重新定義它們。

16-24或32bpp配置的L8映射

在載入L8映射的CLUT時，對OSWrappers::taskYield() 的呼叫被錯誤地引入STM32DMA類。 要解決此問題，用戶可以執行以下操作：

1. 選取到您的Users/<user name>/STM32Cube/Repository/Packs/STMicroelectronics/X-CUBE-TOUCHGFX/4.17.0/CubeMX/templates/Target 資料夾。
2. 根據您的位元深打開相應的dma\u Xbpp\u implementation\u tmp.ftl文件
3. 刪除或注釋while ((READ_REG(DMA2D->FGPFCCR) & DMA2D_FGPFCCR_START) != 0U)迴圈中對 OSWrappers::taskYield()的呼叫，並從STM32CubeMX重新生成程式碼，以使用此修改的範本生成程式碼。

while ((READ_REG(DMA2D->FGPFCCR) & DMA2D_FGPFCCR_START) != 0U)
{
    // OSWrappers::taskYield();
}

TouchGFX 4.15.0

支援MCU

雖然TouchGFX完全支援Cortex-M33，但是在CubeMX中添加支援前，當前CubeMX（v6.0.1）版本中不能啟用“套裝軟體”（包括TouchGFX Generator）。 對基於Cortex-M33的MCU禁用“Trust Zone”，從而將MCU限制在單內容，將允許您啟用TouchGFX Generator。 應在“用戶程式碼”區手動啟用TrustZone。

TouchGFX 4.14.0

ARMCLANG支援

雖然TouchGFX現在為Cortex-M0、Cortex-M4f、Cortex-M7和Cortex-M33提供ARMCLANG（ARM編譯器v6.x）庫，CubeMX卻不能生成啟用ARMCLANG編譯器（ARM編譯器v6.x）的專案。 這要求希望在其專案中使用編譯器的使用者從Keil uVision中的專案選項中手動選擇編譯器。

如果從CubeMX內部配置FreeRTOS中介軟體，生成的任何使用ARMCC（ARM編譯器v5.x）的專案都將有與ARMCLANG不相容的FreeRTOS可移植文件；必須手動替換這些檔。 每當從CubeMX內部運行“生成程式碼”時，任何手動修改都會被覆蓋，最好持續控制專案版本（git等）以撤銷這些特定修改。

總結。 由於CubeMX只能生成ARM Compiler v5.x編譯器專案，因此用戶必須在每次從CubeMX生成程式碼時修改下列內容，除非能夠持續控制專案版本。

1. 在專案選項中選擇ARM Compiler v6.x。
2. 連結ARMCLANG庫而不是ARMCC庫（通過CubeMX配置）。
3. 如果從CubeMX內部配置FreeRTOS，則為了相容ARM Compiler v6.x，應從 portable/GCC資料夾而不是portable/RVDS（ARM Compiler v5.x的默認選擇）獲取FreeRTOS可移植檔。

工作流程

下列工作流程描述了如何從Keil uVision使用v6.x ARM Compiler以及CubeMX生成的專案和TouchGFX ARMCLANG庫。

1. 在Keil uVision中選擇ARMCLANG（v. 6.x）。

ARMCLANG支援

2. 如果您從CubeMX配置FreeRTOS，CubeMX將生成錯誤的可移植檔並將您的專案配置為使用這些檔。 您必須用來自https://github.com/FreeRTOS/FreeRTOS-Kernel/tree/6199b72fbf57a7c5b3d7b195a3bd1446779314cd/portable/GCC的文件（`port.c` 和 portmacro.h）或下載FreeRTOS版本後從其中找到的檔來手動替換這些檔。

   替換port.c：

   

   port.c

   將include路徑設置修改為包含portable/GCC資料夾中的portmacro.h（本例中以Cortex-M7為例）：

   

   可移植檔include路徑

3. “生成程式碼”期間的TouchGFX Designer生成後步驟將基於您選擇的編譯器版本自動插入正確的庫。

TouchGFX 4.13.0

錯誤

字體轉換器

FontConverter工具將為字體中的規則包含的unicode生成字形像素資料，無論該字形是否用在應用中的實際文字中。 這可能導致數百萬位元組的額外字形像素資料。 在這裡可以找到不再為應用不使用的字形生成像素資料的新的FontConverter工具（Windows和Linux）：

• fontconvert_fix.zip

在4.13.0安裝的根目錄提取此檔將更新

touchgfx\framework\tools內部的fontconverter庫

額外編譯器支援

用ARMCLANG編譯器（v6.12）構建的庫可以在這裡找到：

• touchgfx_core_clang.zip

在4.13.0安裝的根目錄提取此檔會將庫touchgfx_core_clang.lib放入內部。

touchgfx\lib\core\cortex_m7\Keil

向後相容

棄用的特性

刪除了下列棄用特性。 如果您在程式碼中引用了它們，您可能需要重新編寫應用的這些部分：

• 棄用的特性TRANSPARENT_COL
• Drawable::getType()
• HAL::blitSetTransparencyKey()
• HAL::registerTextCache()
• HAL::cacheTextString()

默認禁用TextureMapper

為了減少TouchGFX使用的程式碼空間，默認禁用TextureMapper。 TouchGFX designer將插入程式碼，以便在所有新專案中啟用紋理映射器。

如果將舊專案遷移至TouchGFX 4.13並更新至TouchGFX 4.13，將由TouchGFX Designer處理此問題。

如果是手動更新，則需要插入程式碼來啟用TextureMapper。 否則，將不會在螢幕上繪製任何TextureMapper。

從這裡閱讀更多內容：配置TouchGFX特性。

不相容HAL SDL1

將兩個函數從TouchGFX庫程式碼移動到了HALSDL2.cpp。 這對於將HALSDL2.cpp用作Windows模擬器的HAL的應用而言並沒有分別。

如果您有舊應用（早於TouchGFX 4.8.0），則您的模擬器可能在使用HALSDL（非2）。 此模擬器HAL不再包含在TouchGFX中。 HALSDL缺失之前包含在TouchGFX庫中的兩個函數。 您需要將它們手動添加到HALSDL.cpp：

HALSDL.cpp

void simulator_enable_stdio();
void simulator_enable_stdio()
{
    HWND consoleHwnd = GetConsoleWindow(); // Get handle of console window
    if (!consoleHwnd)                      // No console window yet?
    {
        HWND activeHwnd = GetActiveWindow(); // Remember which window is active

        AllocConsole();                   // Allocate a new console
        consoleHwnd = GetConsoleWindow(); // Get handle of console window

        FILE* dummy;
        freopen_s(&dummy, "CONIN$", "r", stdin); // Redirect stdin/stdout/stderr to the new console
        freopen_s(&dummy, "CONOUT$", "w", stdout);
        freopen_s(&dummy, "CONOUT$", "w", stderr);

        SwitchToThisWindow(activeHwnd, true); // Switch back to the originally active window
    }
    if (consoleHwnd)
    {
        ShowWindow(consoleHwnd, SW_SHOW); // Show/hide it!
    }
}
void simulator_printf(const char* format, va_list pArg);
void simulator_printf(const char* format, va_list pArg)
{
    // Create a console window, if window is visible.
    simulator_enable_stdio();
    if (GetConsoleWindow()) // Only print if we have a console window
    {
        vprintf(format, pArg);
    }
}

TouchGFX 4.12.3

向後相容

螢幕轉換

更早的版本在完成螢幕轉換後重繪整個螢幕。 此額外重繪在一些運行緩慢的平臺上導致了性能問題。 如果您出於某些原因需要此類重繪，則需要使螢幕的相關部分無效，如通過呼叫轉換到的螢幕的Screen::afterTransition()虛擬函數中的container.invalidate()的方式。

二進位字體

由於字距調整資料現已包含在二進位字體中，因此修改了二進位字體的格式。 需重新生成二進位字體檔，原來的檔將無效。 根據Makefiles的設置方式，通常通過重新生成所有資產來完成（如“make -f simulator/gcc/Makefile clean assets”）。

TouchGFX 4.11.0

向後相容

在touchgfx/framework/include/touchgfx/lcd/LCD.hpp中，我們刪除了檔touchgfx/hal/HAL.hpp中一個在早期版本中誤插入的include函數。 這可能導致包含LCD.hpp並使用HAL.hpp內容的檔中發生編譯器錯誤。 解決方案是在檔中另外包含touchgfx/framework/include/touchgfx/hal/HAL.hpp。

TouchGFX 4.10.0

從4.9.x升級

從版本4.10.0開始，TouchGFX只在STM32 MCU上運行。

如需更新舊專案，您需要執行下列操作。

在應用啟動時添加下列突出顯示的程式碼，以便將正在STM32硬體上運行的情況通知TouchGFX。 合適位置是BoardConfiguration.cpp中hw_init()函數的結尾

BoardConfiguration.cpp

void hw_init() {
    ...
    //Enable CRC engine for STM32 Lock check
    __HAL_RCC_CRC_CLK_ENABLE();
}

向後相容

刪除了未使用的檔\touchgfx\framework\include\touchgfx\canvas_widget_renderer\RGBA8.hpp。

專案更新器的問題

從TouchGFX Designer呼叫的IAR和Keil專案更新器不遵循在相應IDE中設置的自訂文件級別優化。

TextArea和ChromART（DMA2D）

用ChromART渲染TextAreas（當TextArea是最頂端的元素/最後進行繪製時）導致影像緩衝的提前解鎖，繼而導致當前幀提前完成/傳輸到顯示器。 在TouchGFX呼叫endFrame()後，所有繪製操作（包括DMA操作）應已完成。 由於TextArea在如何適當地保護影像緩衝方面違反合約，即使從endFrame()返回後，仍然允許DMA操作繼續。

小部件的合約為：

1. 鎖定影像緩衝（返回指向影像緩衝的指標）。
2. 在影像緩衝中繪製一些內容。 
3. 解鎖框架緩衝區。

或者，使用DMA操作，這種情況下將自動處理影像緩衝的同步。

在版本4.10.0中，如果是當前螢幕最頂端的元素（最後進行繪製），TextArea將兩個流程混合可能導致短時脈衝波干擾。 此問題可通過用下列endFrame()重寫手動保護endFrame()來修正（基於F4 HAL）。 此舉確保在仍在處理ChromART操作時endFrame()不返回。  

void STM32F4HAL::endFrame()
{
    if (dma.isDMARunning())
    {
        OSWrappers::tryTakeFrameBufferSemaphore();
    }
    HAL::endFrame();
}

TouchGFX 4.9.0

從4.8.0升級

隨著應用範本（從實質上將開發板支援包與核心框架分離開來）的引入，我們從版本4.9.0的touchgfx資料夾中刪除了許多底層驅動和其他檔。 這些檔案現在由應用範本提供。 但是，這意味著您不能通過只替換touchgfx資料夾升級到4.9.0，那樣做可能導致一些BSP檔案缺失。 相反地，TouchGFX Designer能夠自動執行升級。 可通過兩種不同的方式升級，您需要選擇一種最適合您的方式。

Caution

請確保升級前進行了專案備份。

方法1：保留原始檔結構

要執行此方法，只需在新的TouchGFX Designer 4.9.0中打開專案。 TouchGFX Designer將詢問您是否要升級，在點擊“確定”後，TouchGFX Designer將應用必要修改。 TouchGFX Designer將執行下列操作：

1. 將新的壓縮過的touchgfx資料夾解壓到應用中，並修改TouchGFX路徑以與之匹配。
2. 下載並解壓所有已從touchgfx資料夾中刪除的檔案，因此專案仍然可以編譯。

此方法幾乎會讓一切保持原樣，如果原有檔案結構適合您的專案，則這是最輕鬆的選擇。 此方法的主要缺點是不會有圖像轉換器加速（通過操作影像檔案夾而不是單個檔案）。 但是，您可以手動修改makefile，以便使用此方法。

方法2：導入到新的範本

您可以使用此方法將專案轉換到基於新範本的檔案結構中。 為此，您必須首先讓Designer使用上面的方法1升級專案。 然後，使用合適的應用範本（模擬器或與您的評估板匹配的應用範本）新建專案。 在Designer中打開此新專案後，轉至頂部功能表並點擊“編輯->導入GUI”。 在對話方塊中指定專案的.touchgfx文件。 Designer會自動將所有UI檔（包括資產）導入新建的專案。 如果在gui資料夾之外增加了額外的程式碼，您需要將這些檔案手動複製到新專案。

方法3：手動升級（無TouchGFX Designer）

如果不使用TouchGFX Designer，您可以用以下方式執行升級：

1. 用版本4.9.0的安裝資料夾中的資料夾替換touchgfx資料夾。
2. 用版本4.9.0的安裝資料夾中的資料夾替換touchgfx資料夾。下載此zip檔並將其解壓到touchgfx資料夾，恢復刪除的檔案。