已知問題

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

TouchGFX 4.26.0

Changed AbstractPainters constructor

The setup method in the abstract classes touchgfx::AbstractPainter and touchgfx::AbstractPainterBitmap, and all inherited classes has been changed in TouchGFX 4.26 to avoid undefined behaviour. The constructor doesn't take arguments anymore, and the color/bitmap can only be set with setColor()/setBitmap().

Updated GCC compilers

The GCC compiler provided with TouchGFX has been updated in version 4.26. The Windows GCC (for the simulator) is now 13.2.0. The ARM GCC (for Run Target in the TouchGFX Designer) is now 13.3.1.

The new compilers have been used to compile the TouchGFX libraries that are used by TouchGFX Designer and STM32CubeIDE.

The new compilers generate different code compared to the old compilers. The performance of a TouchGFX program can therefore be different compared to version 4.25. In general the performance is better in 4.26.

The new compilers has C++17 as default dialect, but support many C++20 and 23 features.

TouchGFX 4.25.0

Possible clash between TouchGFX / CMISIS-DSP

If you have CMISIS-DSP in your project, a clash can occur with PI.

This is because PI is defined in CMISIS-DSP (as a define variable) and TouchGFX (as a const float)

#include <dsp/fast_math_functions.h>
...
touchgfx::PI; // Compile error since PI is redefined
...
PI; // OK, but its only and always the DSP's PI
...

Slow assets generation

If admin rights are not given, assets generation can be very slow. The root of this issue can be the UAC, when it's set to "Never notify". With that configuration TouchGFX will never have the rights for some operations.

There's more information in the two links below.

https://support.microsoft.com/en-us/windows/user-account-control-settings-d5b2046b-dcb8-54eb-f732-059f321afe18

https://learn.microsoft.com/en-us/windows/security/application-security/application-control/user-account-control/how-it-works

TouchGFX 4.24.2

STM32N6 的限制

TouchGFX 僅支援在 STM32CubeMX 中建立的「僅限安全域」的 STM32N6 專案。

TouchGFX 4.24.0

在F769I上使用MJPEG硬體解碼時，您可能會遇到凍結。因應措施如下：

由於硬體解碼器正在持續解碼(即使所有區塊皆已解碼)，因此不會呼叫HAL_JPEG_DecodeCpltCallback。

解碼狀態尚未更新，但卡在HAL_JPEG_STATE_BUSY_DECODING，因應措施為將這三行程式新增至HardwareMJPEGDecoder::decodeMJPEGFrame，請看下方程式碼：

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

位於 <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
請注意，由於此檔案是由系統產生的，若您重新產生程式碼，您將會遺失所有修改。

另一個較簡單的方法是停用硬體解碼，但您會損失許多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。這項錯誤是在檔案名稱中包含作業系統。 STM32CubeMX creates a file with the new name while leaving the old file in place. 兩個檔案都是由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小工具一文瞭解更多詳細資訊。

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

In TouchGFX 4.20 the software routines that paint circles, lines, and other shapes have been moved from the framework code to the code generated by STM32CubeMX. 這代表您將專案由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」(產生程式碼)。 Now go to TouchGFX Designer and regenerate code (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

The missing functions are generated into TouchGFX/target/generated/STM32DMA.cpp, when you regenerate code in STM32CubeMX.

If your controller does not have DMA2D (or it is not enabled), STM32CubeMX will include the software routines that was used in TouchGFX 4.19.1 and previous versions.

If you for some reason cannot regenerate code in STM32CubeMX, you can manually add the missing functions by inserting the following includes in a .cpp file in your application:

#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專案

Keil projects created with STM32CubeMX are missing the DSP extension tag in the project file. 由於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產生程式碼

When generating code with MJPEG Video on e.g. an STM32H750 with STM32CubeMX 6.3.0 or earlier, unfortunately, the code to configure the MDMA to the MDMA handlers, as shown in Video Decoding, is missing and developers must add the highlighted user code manually:

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結合使用

ARMCLANG projects where the LibJPEG middlewares is selected in STM32CubeMX cannot run. 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

Issues with STM32CubeMX 6.1.0 and CubeProgrammer 2.6

As of version STM32CubeMX 6.1.0 EWARM projects generated by STM32CubeMX do not work with X-CUBE-TOUCHGFX because of a wrong setting for "C/C++ Compiler" / "Language" option which was changed from "Auto" to "C++" causing compilation errors. This issue will be fixed in STM32CubeMX 6.1.1. In the mean time, changing the option back to "Auto", manually, will solve compilation issues but will be reverted upon code generation from STM32CubeMX.

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檔的內容在兩個主要區域發生了重大改變。 This may result in a vastly updated .touchfgx file, simply by opening and saving a .touchgfx project file using TouchGFX Designer. 主要變化在以下領域：

預設值不寫入 .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。 This may result in wrong colors on the hardware (not the simulator) and can be fixed by regenerating the DMA classes from STM32CubeMX.

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中的字體大小限制

The texts.xsd which is used by TouchGFX Designer to validate the texts.xml has a limit on the font size of 255. If you have font sizes greater than 255, you will see an error message in TouchGFX Designer like this:

錯誤消息-字體大小限制

解決方法是關閉專案，將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顯示介面

When using the new FMC Display Interface in TouchGFX Generator the memory offset for FMC banks will not be correct (zero) when generating with STM32CubeMX 6.2.1. This will be corrected in STM32CubeMX 6.3.0 and upon release the minimum required version for X-CUBE-TouchGFX will be bumped to 6.3.0 rather than the current 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開發板設定

TouchGFX 開發板設定(TBS')無法從版本低於TouchGFX 4.17.0的TouchGFX Designer中擷取。強烈建議使用最新版的TouchGFX，以進行任何新的設計。

TouchGFX 4.15.0

支援MCU

While Cortex-M33 is fully supported by TouchGFX, "Software Packs" (TouchGFX Generator, among others) cannot be enabled in the current verison of STM32CubeMX (v6.0.1) for multi-context MCUs until support is added in STM32CubeMX. 對基於Cortex-M33的MCU禁用“Trust Zone”，從而將MCU限制在單內容，將允許您啟用TouchGFX Generator。應在“用戶程式碼”區手動啟用TrustZone。

TouchGFX 4.14.0

ARMCLANG支援

While TouchGFX now provides an ARMCLANG (ARM compiler v6.x) library for Cortex-M0, Cortex-M4f, Cortex-M7 and Cortex-M33, STM32CubeMX is not able to generate projects that enable the ARMCLANG compiler (ARM Compiler v6.x). 因此對於希望在專案中使用編譯器的使用者，就必須從Keil μVision的專案選項中手動選擇編譯器。

If configuring the FreeRTOS middleware from within STM32CubeMX, any generated project using ARMCC (ARM compiler v5.x) will have FreeRTOS portable files that are not compatible with ARMCLANG; And these have to be replaced manually. Whenever "Generate code" is run from within STM32CubeMX any manual changes will be overwritten and it would be wise to keep the project under version control (git, etc.) to undo these particular changes.

總結。 Since STM32CubeMX can only generate ARM Compiler v5.x compiler projects, users have to modify the following every time code is generated from STM32CubeMX unless they keep their project under version control.

在專案選項中選擇ARM Compiler v6.x。
Link with the ARMCLANG library instead of the ARMCC library (configured by STM32CubeMX).
If configuring FreeRTOS from within STM32CubeMX, then the FreeRTOS portable files should be taken from the portable/GCC folder rather than portable/RVDS (default for ARM Compiler v5.x) in order to be compatible with ARM Compiler v6.x.

工作流程

The following workflow describes how to use v6.x ARM Compiler from Keil μVision with STM32CubeMX generated projects and a TouchGFX ARMCLANG library.

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

ARMCLANG支援

If you're configuring FreeRTOS from STM32CubeMX, STM32CubeMX will generate the wrong portable files and configure your project to use those. 您必須用來自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 and Chrom-ART (DMA2D)

Rendering of TextAreas with Chrom-ART (when TextArea is the top most element / last to be drawn) cause a premature unlocking of the framebuffer and subsequently a premature completion/transfer of the current frame to the display. 在TouchGFX呼叫endFrame()後，所有繪製操作（包括DMA操作）應已完成。由於TextArea在如何適當地保護影像緩衝方面違反合約，即使從endFrame()返回後，仍然允許DMA操作繼續。

小部件的合約為：

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

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

在版本4.10.0中，如果是當前螢幕最頂端的元素（最後進行繪製），TextArea將兩個流程混合可能導致短時脈衝波干擾。此問題可通過用下列endFrame()重寫手動保護endFrame()來修正（基於F4 HAL）。 It ensures that endFrame() does not return if Chrom-ART operations are still being processed.

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檔案缺失。 Instead, TouchGFX Designer is able to perform the upgrade automatically. 可通過兩種不同的方式升級，您需要選擇一種最適合您的方式。

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

方法1：保留原始檔結構

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

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

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

方法2：導入到新的範本

您可以使用此方法將專案轉換到基於新範本的檔案結構中。 To achieve this, you must first let TouchGFX Designer upgrade your project using Method 1 above. 然後，使用合適的應用範本（模擬器或與您的評估板匹配的應用範本）新建專案。 With this new project opened in TouchGFX Designer, go to the top menu and click "Edit -> Import GUI". 在對話方塊中指定專案的.touchgfx文件。 TouchGFX Designer will then automatically import all the UI files, including assets, into the newly created project. 如果在gui資料夾之外增加了額外的程式碼，您需要將這些檔案手動複製到新專案。

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

If you are not using TouchGFX Designer, you can perform the upgrade by:

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

TouchGFX 4.26.0​

Changed AbstractPainters constructor​

Updated GCC compilers​

TouchGFX 4.25.0​

Possible clash between TouchGFX / CMISIS-DSP​

Slow assets generation​

TouchGFX 4.24.2​

STM32N6 的限制​

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​

Issues with STM32CubeMX 6.1.0 and 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開發板設定​

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

向後相容​

TouchGFX 4.26.0

Changed AbstractPainters constructor

Updated GCC compilers

TouchGFX 4.25.0

Possible clash between TouchGFX / CMISIS-DSP

Slow assets generation

TouchGFX 4.24.2

STM32N6 的限制

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

Issues with STM32CubeMX 6.1.0 and 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開發板設定

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 and Chrom-ART (DMA2D)

TouchGFX 4.9.0

從4.8.0升級

方法1：保留原始檔結構

方法2：導入到新的範本

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