已知問題

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

TouchGFX 4.24.0

On F769I when using MJPEG hardware decoding, you can encounter freezing. The workaround is below:

HAL_JPEG_DecodeCpltCallback isn't called because the hardware decoder is continuing to decode, even though all blocks have been decoded.

The state of the decoding is not updated, but stuck in HAL_JPEG_STATE_BUSY_DECODING, the workaround is to add these three lines of code in HardwareMJPEGDecoder::decodeMJPEGFrame, see code below:

if(HAL_JPEG_GetState(&hjpeg) != HAL_JPEG_STATE_READY){
   HAL_JPEG_Abort(&hjpeg);
}

in <YOUR_PROJECT_PATH>\TouchGFX\target\generated\HardwareMJPEGDecoder.cpp :

void HardwareMJPEGDecoder::decodeMJPEGFrame(const uint8_t* const mjpgdata, const uint32_t length, uint8_t* outputBuffer, uint16_t bufferWidth, uint16_t bufferHeight, uint32_t bufferStride)
{
   ... 
   do{
    ...
        } while (JpegProcessing_End != 1);
        /// part to add ///
        if(HAL_JPEG_GetState(&hjpeg) != HAL_JPEG_STATE_READY){
            HAL_JPEG_Abort(&hjpeg);
        }
        /// part to add ///
        /* reset flag */
        Jpeg_HWDecodingEnd = 0;
    }
}

Caution
Beware, since this file is generated, you will lost all modifications if you regenerate code.

Another simpler way is to disable hardware decoding, but you will lose a lot of FPS.

TouchGFX 4.23.0

Microsoft Visual C++可轉散發套件

TouchGFX Designer仰賴Microsoft Visual C++ 2015-2022可轉散發套件，因此必須在電腦上安裝此套件。
可從以下網址下載：https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022

使用者應選擇X64版本。

touchgfx::VectorRenderer類別的介面變更

touchgfx::VectorRenderer類別的設定方法已在TouchGFX 4.23中變更，以提供更多使用案例。請參閱VectorRenderer::setup。
如果您已在任何應用程式使用此類別，就必須調整配合此項變更。

例如SVGImage類別在方法繪製中使用VectorRenderer類別：

void SVGImage::draw(const Rect& invalidatedArea) const
{
  ...
  VectorRenderer* renderer = VectorRenderer::getInstance();
  renderer->setup(*this, invalidatedArea);
  ...

在TouchGFX 4.23中已將此程式碼更新為：

void SVGImage::draw(const Rect& invalidatedArea) const
{
  ...
  VectorRenderer* renderer = VectorRenderer::getInstance();
  renderer->setup(getAbsoluteRect(), invalidatedArea);
  ...
}

目前的作法不是傳送小工具指標，而是傳送小工具覆蓋的矩形(以絕對座標表示)。這項變更可讓VectorRenderer在小工具之外更為實用。

Canvas (畫布)類別也進行類似變更。

TouchGFX 4.22.0

X-Cube-Display

部分客戶同時使用TouchGFX及STM32CubeMX的X-Cube-Display套裝軟體。不過版本6.9的STM32CubeMX並未提供此套裝軟體。因此如果您使用TouchGFX搭配X-Cube-Display，就必須使用STM32CubeMX 6.8。
最新的TouchGFX開發板設定目前是以STM32CubeMX 6.8製作，但最終將會更新為STM32CubeMX 6.9。
TouchGFX Designer提供多種版本的TouchGFX開發板設定，因此可使用先前版本。

TouchGFX 4.21.0

WideTextAction

列舉WideTextAction在Types.hpp之中的定義已變更，以免造成誤導。如果您在TouchGFX 4.20或之前版本使用WIDE_TEXT_WORDWRAP，並預期看到省略符號(…)，就必須在TouchGFX 4.21之中使用WIDE_TEXT_WORDWRAP_ELLIPSIS。請另行參閱文字與字型。

以IAR編譯STM32U599專案

由4.20或更舊版本的TouchGFX專案升級為TouchGFX 4.21時，就會在IAR出現連結錯誤。

Error[Li006]: duplicate definitions for "HAL_CPU2D_CommandListCpltCallback"; in "...\Obj\nema_hal.o", and "...\Obj\nema_hal_threadx.o"
Error[Li006]: duplicate definitions for "nema_buffer_create"; in "...\Obj\nema_hal.o", and "...\Obj\nema_hal_threadx.o"
...

此項錯誤的原因是檔案TouchGFX/Target/generated/nema_hal_threadx.c已重新命名為TouchGFX/Target/generated/nema_hal.c。這項錯誤是在檔案名稱中包含作業系統。 CubeMX會以新名稱建立檔案，並將舊檔案留在原地。兩個檔案都是由IAR編譯。解決問題的方法就是移除TouchGFX/Target/generated/nema_hal_threadx.c這個檔案。

以NeoChrom在STM32進行SVG繪製

具有大型座標的SVG形狀，在具有NeoChrom的目標渲染時可能會不正確。這是由NeoChrom程式庫的限制所造成。發生問題的原因可能是放大，或是SVG本身的大型座標。

解決問題的方法是將呼叫插入nema_vg_handle_large_coords()。 touchgfx_components_init()函數是理想的位置，位在TouchGFX/target/generated/TouchGFXConfiguration.cpp之中：

void touchgfx_components_init()
{
    nema_init();
    nema_vg_init(480, 480);
    nema_vg_handle_large_coords(1, 1);
}

附註：此項解決方案會略微降低效能。

TouchGFX 4.20.0

繪圖器介面變更

基於效能考量，AbstractPainter::render()方法已由AbstractPainter::paint取代。
如果您實作自己的繪圖器類別，就需要改為此項新介面。請參閱Canvas小工具一文瞭解更多詳細資訊。

繪圖器實作移往產生的檔案

在TouchGFX 4.20之中，用於繪製圓形、線條及其他形狀的軟體常式，已由架構程式碼移往CubeMX產生的程式碼。這代表您將專案由TouchGFX 4.19.1 (或之前版本)升級為TouchGFX 4.20之後，就必須在CubeMX重新產生程式碼。這項變動的原因，是為了在繪製圓形和線條時能夠使用圖形加速器DMA2D。

指示說明

請在專案根資料夾尋找並開啟.ioc檔案：

專案IOC檔案

請在Software Packs Component Selector (套裝軟體元件選擇器)(alt-O)之中選擇TouchGFX 4.20：

選擇TouchGFX 4.20

關閉此對話方塊，並按下右上角的「Generate Code」(產生程式碼)。現在前往TouchGFX Designer並重新產生程式碼(F4)。

連結器錯誤

如果您的專案使用Circle小工具這類項目，且沒有重新產生程式碼，就會出現連結器錯誤。錯誤會像是以下這樣(此為16bpp)：

Linking TouchGFX/build/bin/target.elf
Middlewares/ST/touchgfx/lib/core/cortex_m7/gcc\libtouchgfx.a(PainterRGB565.o): In function `touchgfx::PainterRGB565::paint(unsigned char*, short, short, short, short, unsigned char) const':
(.text._ZNK8touchgfx13PainterRGB5655paintEPhssssh+0x1a): undefined reference to `touchgfx::paint::rgb565::lineFromColor(unsigned short*, unsigned int, unsigned long, unsigned char, unsigned long)'
Middlewares/ST/touchgfx/lib/core/cortex_m7/gcc\libtouchgfx.a(PainterRGB565.o): In function `touchgfx::PainterRGB565::tearDown() const':
(.text._ZNK8touchgfx13PainterRGB5658tearDownEv+0x0): undefined reference to `touchgfx::paint::rgb565::tearDown()'
collect2.exe: error: ld returned 1 exit status

若為24bpp則是：

Linking TouchGFX/build/bin/target.elf
        Middlewares/ST/touchgfx/lib/core/cortex_m7/gcc\libtouchgfx.a(PainterRGB888.o): In function `touchgfx::PainterRGB888::paint(unsigned char*, short, short, short, short, unsigned char) const':
        (.text._ZNK8touchgfx13PainterRGB8885paintEPhssssh+0x18): undefined reference to `touchgfx::paint::rgb888::lineFromColor(unsigned char*, unsigned int, unsigned long, unsigned char)'
        Middlewares/ST/touchgfx/lib/core/cortex_m7/gcc\libtouchgfx.a(PainterRGB888.o): In function `touchgfx::PainterRGB888::tearDown() const':
        (.text._ZNK8touchgfx13PainterRGB8888tearDownEv+0x0): undefined reference to `touchgfx::paint::rgb888::tearDown()'
        collect2.exe: error: ld returned 1 exit status

您在CubeMX重新產生程式碼時，遺漏的函數會產生並進入TouchGFX/target/generated/STM32DMA.cpp。

如果您的控制器沒有DMA2D (或是並未啟用)，CubeMX會將TouchGFX 4.19.1及之前版本使用的軟體常式納入其中。

如果您因故無法在CubeMX重新產生程式碼，可以將下列include插入應用程式的.cpp檔案中，以手動方式新增遺漏的函數：

#include <touchgfx/hal/Paint.hpp>
#include <touchgfx/hal/PaintRGB565Impl.hpp> // 16bpp painting routines
#include <touchgfx/hal/PaintRGB888Impl.hpp> // 24bpp painting routines

使用Keil除錯STM32G0

適用於STM32G0開發板的TouchGFX專案與X-NUCLEO-GFX01M1/2顯示模組，針對外部SPI Flash資料使用0x90000000的位址範圍。這樣會中斷Keil除錯器，因為該除錯器啟動除錯工作階段時，會存取前述位址。 Keil會提供以下錯誤訊息：「Cannot access target. Shutting down debug session」(無法存取目標。關閉除錯工作階段)。

在Keil開始除錯工作階段

解決以上問題的方法，就是利用以下文字為除錯器建立init指令碼：

load STM32G071_NUCLEO\STM32G071_NUCLEO.axf NOCODE
g,main

NOCODE選項會告知Keil不要載入程式碼；這樣就可去除存取問題。

適用於Keil的除錯初始化指令碼

在除錯設定對話方塊中選擇檔案：

適用於Keil的除錯設定

使用Keil編譯STM32U5及STM32L5專案

使用CubeMx建立的Keil專案，其專案檔案中沒有DSP延伸標記。由於TouchGFX程式庫具有DSP延伸標記集，因此與TouchGFX程式庫連結時會產生連結器錯誤。連結器錯誤範例如下：

STM32U575ZI_NUCLEO\STM32U575ZI_NUCLEO.axf: Error: L6366E: abstractpartition.o attributes are not compatible with the provided attributes.
Object abstractpartition.o contains Build Attributes that are incompatible with the provided attributes.
Tag_DSP_extension = This code was permitted to use Thumb DSP functions as an optional architecture extension above the base architecture as indicated by Tag_CPU_arch (=1)

解決這項問題的方法，就是在.uvprojx專案檔案(位於/Project/Targets/Target/TargetOption/TargetCommonOption/Cpu XML-element)中新增DSP標記：

<Targets>
    <Target>
      <TargetName>STM32U575ZI_NUCLEO</TargetName>
      <ToolsetNumber>0x4</ToolsetNumber>
      <ToolsetName>ARM-ADS</ToolsetName>
      <pCCUsed>6120000::V6.12::.\ARMCLANG</pCCUsed>
      <uAC6>1</uAC6>
      <TargetOption>
        <TargetCommonOption>
          <Device>STM32U575ZITx</Device>
          <Vendor>STMicroelectronics</Vendor>
          <PackID>Keil.STM32U5xx_DFP.2.0.0</PackID>
          <PackURL>https://www.keil.com/pack/</PackURL>
          <Cpu>IRAM(0x20000000-0x200BFFFF) IROM(0x08000000-0x81FFFFF) CLOCK(8000000) FPU3(SFPU) CPUTYPE("Cortex-M33") ELITTLE TZ DSP</Cpu>
          <FlashUtilSpec></FlashUtilSpec>

LOGONSERVER環境變數

我們發現TouchGFX在部分電腦的執行速度非常慢(例如「執行模擬器」沒有動作持續30秒)。將環境變數LOGONSERVER設定為空白值可能有助於改善這項問題。

在Bash中的指令如下：

export LOGONSERVER=

TouchGFX 4.19.0

以H7上的MJPEG影片在STM32CubeMX產生程式碼

可惜的是，如果以MJPEG影片在使用STM32CubeMX 6.3.0或之前版本的STM32H750產生程式碼，用於設定MDMA至MDMA處理常式的程式碼(如影片解碼所示)會消失不見，開發人員必須手動新增以下反白顯示的使用者程式碼：

Core\Src\stm32h7xx_hal_msp.c

void HAL_JPEG_MspInit(JPEG_HandleTypeDef* hjpeg)
{
  if(hjpeg->Instance==JPEG)
  {
  /* USER CODE BEGIN JPEG_MspInit 0 */
     hmdma_jpeg_infifo_th.Init.Request = MDMA_REQUEST_JPEG_INFIFO_TH;
     hmdma_jpeg_outfifo_th.Init.Request = MDMA_REQUEST_JPEG_OUTFIFO_TH;
  /* USER CODE END JPEG_MspInit 0 */
   ...

使用字體排印的新方法

從TouchGFX 4.18.1到TouchGFX 4.19.0，字體排印的使用發生了變化。現在，字體排印有一個預設設置和零個或多個特定語言設置。

在設計器指南中瞭解更多相關資訊

文字特定的方向和字體排印不再是一個選項，這些選項已轉移至新的預設設置和特定語言設置中。這項新功能會對使用該功能的專案生成的程式碼產生影響。文字轉換器將為預設設置生成一個字體id，並為每種特定語言設置生成一個id。根據特定語言設置生成的字體id將被自動命名，參見以下範例。

在TouchGFX 4.18中設置特定的文字方向和字體排印

範例：

自動生成的字體id：HEADLINE
預設字體排印id：JPN

在generated/fonts/include/fonts/ApplicationFontProvider.hpp中生成兩個字體ID：

struct TypographyFontIndex
{
    static const touchgfx::FontId HEADLINE = 0;
    static const touchgfx::FontId HEADLINE_AUTO_GENERATED_FOR_JPN = 1;
};

升級到4.19.0時自動生成的字體排印

如前所述，文字特定的方向和字體排印不再是一個選項。由於功能上的這一變化，在升級舊版本時，可能會生成具有預設和特定語言設置的新字體排印。您可以通過id來識別這些自動生成的字體排印。文字方向作為尾碼或A-Z範圍內的字母：

Headline_LTR
PosterText_RTL
Title_A
ButtonText_B

在使用者程式碼中引用字體id

如果在使用者程式碼中引用字體id，則可能需要對其進行更新。當字體id不是通過符號而是通過值引用的情況下，會有出錯的風險，因為在升級期間字體id可能會更改。建議始終通過符號引用字體id，即：用TypographyFontIndex::HEADLINE而非0。

將LibJPEG與ARMCLANG結合使用

在CubeMX中選擇了LibJPEG中介軟體的ARMCLANG專案無法運行。 ARMCLANG啟用半託管，因為LibJPEG引用libc檔函數（如：fopen）。
半託管使應用程式在啟動期間等待與半託管感知調試器連接。
解決此問題的一種方法是取消兩個檔中對JFILE的定義來刪除對LibJPEG中fopen的引用：LibJPEG/source/jdatasrc.c 和 LibJPEG/source/jdatadst.c:

LibJPEG/source/jdatasrc.c

#include "jerror.h"

#undef JFILE

/* Expanded data source object for stdio input */
#ifdef JFILE 

LibJPEG/source/jdatadst.c

#include "jerror.h"

#undef JFILE

#ifndef HAVE_STDLIB_H       /* <stdlib.h> should declare malloc(),free() */

H750B Discovery上的MJPEG影片

H750B Discovery板使用YCbCr影片資料的硬體解碼。 TouchGFX為該板提供的程式碼中的一個錯誤導致某些影片出現可見瑕疵。
解決方案是改為軟體解碼。在某些情況下，也可以通過將影片的寬度更改幾個像素來解決問題。

ThreadX組合語言程式文件

Keil IDE的ThreadX組合語言程式檔使用新的ARMCLANG V6組合語言程式語法。某些固件包中提供的startup.s檔使用的是舊的ARMCC組合語言程式語法。這意味著您必須將專案設置為使用ARMCLANG V6組合語言程式，然後針對startup_stm32xxx.s進行重寫:

取消選擇用於startup.s的ARMCLANG V6組合語言程式

TouchGFX 4.18.0

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

Note
CubeProgrammer錯誤在2.10版中得到解決。

新的.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中）。

texts.xsd中的字體大小限制

設計器用於驗證texts.xml的texts.xsd的字體大小限制為255。如果字體大於255，您將在設計器中看到如下錯誤消息:

錯誤消息-字體大小限制

解決方法是關閉專案，將texts.xsd中的“字體大小”屬性從xs:unsignedByte更改為xs:unsignedInt，然後重新打開專案。

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類。要解決此問題，用戶可以執行以下操作：

選取到您的Users/<user name>/STM32Cube/Repository/Packs/STMicroelectronics/X-CUBE-TOUCHGFX/4.17.0/CubeMX/templates/Target 資料夾。
根據您的位元深打開相應的dma\u Xbpp\u implementation\u tmp.ftl文件
刪除或注釋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.16.0

TouchGFX Board Setups

TouchGFX Board Setups (TBS') cannot be retrieved from TouchGFX Designer in versions older than TouchGFX 4.17.0. It is strongly recommended to use the latest version of TouchGFX for any new designs.

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 μVision的專案選項中手動選擇編譯器。

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

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

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

工作流程

下列工作流程說明如何以CubeMX產生的專案及TouchGFX ARMCLANG函式庫，從Keil μVision使用v6.x ARM Compiler。

在Keil μVision選擇ARMCLANG (v. 6.x)。

ARMCLANG支援

如果您從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路徑
“生成程式碼”期間的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操作繼續。

小部件的合約為：

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

或者，使用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將執行下列操作：

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

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

方法2：導入到新的範本

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

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

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

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

TouchGFX 4.24.0​

Caution

TouchGFX 4.23.0​

Microsoft Visual C++可轉散發套件​

touchgfx::VectorRenderer類別的介面變更​

TouchGFX 4.22.0​

X-Cube-Display​

TouchGFX 4.21.0​

WideTextAction​

以IAR編譯STM32U599專案​

以NeoChrom在STM32進行SVG繪製​

TouchGFX 4.20.0​

繪圖器介面變更​

繪圖器實作移往產生的檔案​

指示說明​

連結器錯誤​

使用Keil除錯STM32G0​

使用Keil編譯STM32U5及STM32L5專案​

LOGONSERVER環境變數​

TouchGFX 4.19.0​

以H7上的MJPEG影片在STM32CubeMX產生程式碼​

Core\Src\stm32h7xx_hal_msp.c

使用字體排印的新方法​

範例：​

升級到4.19.0時自動生成的字體排印​

在使用者程式碼中引用字體id​

將LibJPEG與ARMCLANG結合使用​

LibJPEG/source/jdatasrc.c

LibJPEG/source/jdatadst.c

H750B Discovery上的MJPEG影片​

ThreadX組合語言程式文件​

TouchGFX 4.18.0​

CubeMX 6.1.0和CubeProgrammer 2.6的問題​

Note

新的.touchgfx格式​

預設值不寫入 .touchgfx​

刪除了TextEntries塊​

LCD16bpp::fillRect與LCD16bpp::drawGlyph​

Makefile和xlsx​

texts.xsd中的字體大小限制​

Linux上的SDL2連結器錯誤​

TouchGFX 4.17.0​

繪圖工具不再支援setAlpha()​

使用HAL類​

TouchGFX Generator中的FMC顯示介面​

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

TouchGFX 4.16.0​

TouchGFX Board Setups​

TouchGFX 4.15.0​

支援MCU​

TouchGFX 4.14.0​

ARMCLANG支援​

工作流程​

TouchGFX 4.13.0​

錯誤​

字體轉換器​

額外編譯器支援​

向後相容​

棄用的特性​

默認禁用TextureMapper​

不相容HAL SDL1​

HALSDL.cpp

TouchGFX 4.12.3​

向後相容​

螢幕轉換​

二進位字體​

TouchGFX 4.11.0​

向後相容​

TouchGFX 4.10.0​

從4.9.x升級​

BoardConfiguration.cpp

向後相容​

專案更新器的問題​

TextArea和ChromART（DMA2D）​

TouchGFX 4.9.0​

從4.8.0升級​

Caution

方法1：保留原始檔結構​

方法2：導入到新的範本​

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

TouchGFX 4.24.0

TouchGFX 4.23.0

Microsoft Visual C++可轉散發套件

touchgfx::VectorRenderer類別的介面變更

TouchGFX 4.22.0

X-Cube-Display

TouchGFX 4.21.0

WideTextAction

以IAR編譯STM32U599專案

以NeoChrom在STM32進行SVG繪製

TouchGFX 4.20.0

繪圖器介面變更

繪圖器實作移往產生的檔案

指示說明

連結器錯誤

使用Keil除錯STM32G0

使用Keil編譯STM32U5及STM32L5專案

LOGONSERVER環境變數

TouchGFX 4.19.0

以H7上的MJPEG影片在STM32CubeMX產生程式碼

使用字體排印的新方法

範例：

升級到4.19.0時自動生成的字體排印

在使用者程式碼中引用字體id

將LibJPEG與ARMCLANG結合使用

H750B Discovery上的MJPEG影片

ThreadX組合語言程式文件

TouchGFX 4.18.0

CubeMX 6.1.0和CubeProgrammer 2.6的問題

新的.touchgfx格式

預設值不寫入 .touchgfx

刪除了TextEntries塊

LCD16bpp::fillRect與LCD16bpp::drawGlyph

Makefile和xlsx

texts.xsd中的字體大小限制

Linux上的SDL2連結器錯誤

TouchGFX 4.17.0

繪圖工具不再支援setAlpha()

使用HAL類

TouchGFX Generator中的FMC顯示介面

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

TouchGFX 4.16.0

TouchGFX Board Setups

TouchGFX 4.15.0

支援MCU

TouchGFX 4.14.0

ARMCLANG支援

工作流程

TouchGFX 4.13.0

錯誤

字體轉換器

額外編譯器支援

向後相容

棄用的特性

默認禁用TextureMapper

不相容HAL SDL1

TouchGFX 4.12.3

向後相容

螢幕轉換

二進位字體

TouchGFX 4.11.0

向後相容

TouchGFX 4.10.0

從4.9.x升級

向後相容

專案更新器的問題

TextArea和ChromART（DMA2D）

TouchGFX 4.9.0

從4.8.0升級

方法1：保留原始檔結構

方法2：導入到新的範本

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