既知の問題

この記事では、すべてのTouchGFXバージョンにおける既知の問題と考えられる対応策を示します。 TouchGFXを特定のバージョンにアップグレードするために実行する必要があるアップグレード･ステップがあれば、その説明も行います。使用している現在のバージョンが複数のリリースよりも古い場合は、最新のリリースに達するまですべてのリリースへのアップグレード･ステップを実行する必要があります。

TouchGFX 4.24.0

F7691では、MJPEGハードウェア･デコーディングを使用する際に、フリーズが発生する可能性があります。回避策は以下のとおりです。

すべてのブロックがデコードされた場合でも、ハードウェア･デコーダは引き続きデコードを実行するため、HAL_JPEG_DecodeCpltCallbackは呼び出されません。

デコーディングの状態は更新されず、HAL_JPEG_STATE_BUSY_DECODINGのままになります。これを回避するには、次の3行のコードを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
このファイルの生成後は、コードを生成するとすべての変更が失われることに注意してください。

もう1つの簡単な方法はハードウェア･デコーディングを無効にすることですが、多くのFPSが失われることになります。

TouchGFX 4.23.0

Microsoft Visual C++ Redistributable

TouchGFX Designerは、Microsoft Visual C++ 2015-2022 Redistributableに依存しているため、これをコンピュータにインストールする必要があります。
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のsetupメソッドは、より多くのユースケースに対応するためにTouchGFX 4.23で変更されました。 VectorRenderer::setupを参照してください。
このクラスをアプリケーションで使用している場合は、この変更を取り入れる必要があります。

たとえば、drawメソッドで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ソフトウェア･パックを併用しています。このパックは、STM32CubeMXのバージョン6.9では利用できません。つまり、TouchGFXとX-Cube-Displayを併用する場合は、STM32CubeMX 6.8を使用する必要があります。
最新のTouchGFX Board Setupは現時点ではSTM32CubeMX 6.8を使用して作成されていますが、最終的にSTM32CubeMX 6.9に更新される予定です。
TouchGFX Designerでは、TouchGFX Board Setupの複数のバージョンを利用可能なため、以前のバージョンを使用できます。

TouchGFX 4.21.0

WideTextAction

Types.hppにあるエニュメレーションWideTextActionの定義が、誤解を招くものだったので変更されました。 TouchGFX 4.20およびそれ以前でWIDE_TEXT_WORDWRAPを使用しており、省略記号（…）を表示したいならば、TouchGFX 4.21ではWIDE_TEXT_WORDWRAP_ELLIPSISを使用する必要があります。「テキストとフォント」も参照してください。

IARによるSTM32U599プロジェクトのコンパイル

TouchGFXプロジェクトをバージョン4.20およびそれ以前のプロジェクトから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/target/generated/TouchGFXConfiguration.cppにあるtouchgfx_components_init()関数内です。

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

注: この解決策を適用すると、わずかにパフォーマンスが低下します。

TouchGFX 4.20.0

Painterインタフェースの変更

パフォーマンス上の理由から、AbstractPainter::render()メソッドはAbstractPainter::paintに変更されました。
独自のPainterクラスを実装している場合は、この新しいインタフェースに対応させる必要があります。詳細については、キャンバス･ウィジェットに関する記事を参照してください。

Painterの実装が生成されたファイルに移動

TouchGFX 4.20では、円、ライン、その他の形状をペイントするソフトウェア･ルーチンが、フレームワーク･コードからCubeMXによって生成されたコードに移動しました。つまり、TouchGFX 4.19.1（またはそれ以前）からTouchGFX 4.20にプロジェクトをアップグレードしたら、CubeMXでコードを再生成する必要があるということです。この変更の理由は、円やラインを描画する際に、グラフィック･アクセラレータ（DMA2D）を使用できるようにするためです。

手順

プロジェクト･ルート･フォルダにある、.iocファイルを探して開きます。

プロジェクトIOCファイル

ソフトウェア･パック･コンポーネント･セレクタで、TouchGFX 4.20を選択します（alt-O）。

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でコードを再生成できない場合は、アプリケーションの.cppファイルに以下のインクルードを挿入することにより、欠落している関数を手動で追加できます。

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

KeilによるSTM32G0のデバッグ

X-NUCLEO-GFX01M1/2ディスプレイ･モジュールを搭載したSTM32G0ボードのTouchGFXプロジェクトでは、外部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拡張タグがありません。そのため、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)

これを解決するには、DSPタグを.uvprojxプロジェクト･ファイル（/Project/Targets/Target/TargetOption/TargetCommonOption/Cpu XML-element）に追加します。

<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が非常に低速で実行されることがわかっています（たとえば、"Run simulator"が30秒間何もしない）。環境変数LOGONSERVERを空の値に設定すると、この問題の解決に役立つ場合があります。

bashでは、コマンドは以下のようになります。

export LOGONSERVER=

TouchGFX 4.19.0

H7でのMJPEG Video向け、STM32CubeMXによるコードの生成

STM32CubeMX 6.3.0およびそれ以前のバージョンを使用して、たとえばSTM32H750などでMJPEG Videoを使用してコードを生成すると、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に向けて、タイポグラフィの使用方法が変更されました。タイポグラフィにデフォルト設定が設けられ、ゼロ個以上の言語固有の設定が含まれるようになりました。

この内容の詳細については、Designerのガイドを参照してください。

テキスト固有の向きとタイポグラフィはオプションではなくなり、これらのオプションは新しいデフォルトと言語固有の設定に移動しました。この新しい機能により、この機能を使用したプロジェクト内の生成済みコードが影響を受けます。テキスト･コンバータは、デフォルト設定用のフォントIDと、各言語固有の設定ごとにフォントIDを生成します。言語固有の設定から生成されたフォントIDは、下の例に示すように自動的に命名されます。

TouchGFX 4.18における、固有のテキストの向きとタイポグラフィの設定

例: 自動生成されたフォントID

デフォルトのタイポグラフィID: HEADLINE
言語固有の設定: JPN

これによって、generated/fonts/include/fonts/ApplicationFontProvider.hppで2つのフォント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が変更される可能性があるため、エラーのリスクが生じるからです。フォントIDは、常にシンボルによって参照することを推奨します。たとえば、0ではなく、TypographyFontIndex::HEADLINEを使用するということです。

ARMCLANGによるLibJPEGの使用

CubeMXでLibJPEGミドルウェアが選択されている場合、ARMCLANGプロジェクトを実行できません。 LibJPEGはlibcファイル関数（fopenなど）を参照するので、ARMCLANGはセミホスティングを有効にします。
セミホスティングが有効になると、アプリケーションが起動時に、セミホスティングを認識するデバッガへの接続を待機させます。
この問題を解消する1つの方法は、LibJPEG内のfopenへの参照を削除することです。このためには、LibJPEG/source/jdatasrc.cとLibJPEG/source/jdatadst.cという2つのファイルで、JFILEを未定義にします。

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による問題

CubeMX 6.1.0バージョンでは現在、CubeMXによって生成されるEWARMプロジェクトがX-CUBE-TOUCHGFXで動作しません。これは、"C/C++ Compiler" / "Language"オプションで、"Auto"を"C++"に変更するという間違いが設定されており、コンパイル･エラーが発生するからです。この問題はCubeMX 6.1.1で修正される予定です。それまではオプションを手動で"Auto"に戻すとコンパイルの問題は解決します。ただし、CubeMXからのコード生成に戻ることになります。

外部ローダ（.stldr）の参照方法に関連するCubeProgrammer 2.6のバグにより、既存のすべてのアプリケーション･テンプレート（AT）のMakefileが壊れ、TouchGFX Designerの"Run Target"機能も正しく機能しません。この問題は、ATの現在のバージョンをベースにするユーザ･プロジェクトも影響を及ぼします。アプリケーション･テンプレートは、このバグを修正するためのアップデートを適用し、CubeProgrammer 2.5および2.6の両方で機能するようになる予定です。 CubeProgrammer 2.6で機能しないATをベースにしたプロジェクトである場合は、以下の変更を行ってサポートを追加することができます。ユーザは外部ローダへの参照を作成するときに、binフォルダ内のSTM32CubeProgrammer_CLI.exeを実行する必要があります。一般的には以下のとおりです。

STM32CubeProgrammerのインストール･フォルダのbinフォルダへのcdを実行します。
.stldrファイルへのrelative参照を使用して、接続されたターゲットをプログラムするコマンドを実行します。

@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ファイルの内容が2つの主要領域において大幅に変更されました。このため、TouchGFX Designerを使用して.touchgfxプロジェクト･ファイルを開いて保存するだけで、.touchfgxファイルが大きく更新される可能性があります。主要な変更が行われたのは以下の領域です。

デフォルト値が.touchgfxに書き込まれない

これまでは、ボックス･オフセット（X=0, Y=0）や黒色（red=0, green=0, blue=0）などのデフォルト値が設定された状態でウィジェット･パラメータが.touchgfxファイルに書き込まれていましたが、TouchGFXバージョン4.18.0では、これらの値が書き込まれません。これにより、.touchgfxファイルのサイズが少し小さくなる可能性があります。

TextEntriesブロックの削除

SingleUseIdの名前が変更され、連続番号ではなくランダムな番号と文字が含まれるようになり、プロジェクトと複数のアクティブな開発者とのマージが容易になりました。新しいシングル･ユースのテキストIDが同じIDを取得しないからです。さらに、.touchgfx内の"TextEntries"セクションが削除されたため、.touchgfxファイルのサイズが大幅に縮小される可能性があります。

LCD16bpp::fillRectとLCD16bpp::drawGlyph

LCD16bppのfillRectおよびdrawGlyph関数が、軽減された16ビット（RGB565）カラーではなく、完全な24ビット･カラーをDMAに渡すようになりました。このため（シミュレータではなく）ハードウェア上では誤った色になる可能性があります。これは、CubeMXからDMAクラスを再生成することで修正できます。

Makefileとxlsx

TouchGFX 4.18.0では、テキストと翻訳を保存するために、以前使用されていた古い.xlsxフォーマットではなく、新しい.xmlフォーマットを使用します。つまり、MakefileとVisual Studioプロジェクト内の"texts.xlsx"へのすべての参照を"texts.xml"に変更する必要があります。古いtexts.xlsxファイルが存在していてtexts.xmlが存在していない場合でも、TextConvertツールはこれを認識して、将来の使用のためにtexts.xlsxをtexts.xmlに変換します。

新しい動作中のMakefileを確認するには、TouchGFX Designerを使用して、単純に新しい（空の）プロジェクトを作成し、generated/simulator/gcc/Makefileフォルダ内にある生成済みのMakefileを確認します。

texts.xsdのフォント･サイズの制限

Designerでtexts.xmlを有効化するために使用されるtexts.xsdでは、フォント･サイズが255に制限されています。フォント･サイズが255を上回る場合、Designerには次のようなエラー･メッセージが表示されます。

Error message - Font size limit

この回避策は、プロジェクトを閉じ、texts.xsd内でタイポグラフィ･サイズの属性をxs:unsignedByteからxs:unsignedIntに変更してから、再度プロジェクトを開くことです。

LinuxでのSDL2リンカ･エラー

シミュレータが使用するSDL2ライブラリは、Windowsユーザ向けのみに含まれるようになりました。 LinuxユーザはSDL2ライブラリそのものをインストールする必要があります。このタスクの実行は1回限りで、ubuntu用のコマンドは以下のとおりです。

sudo apt install libsdl2-dev libsdl2-image-dev

これにより、開発用にヘッダ･ファイルを含むlibsdl2およびlibsdl2-imageがインストールされます。

TouchGFX 4.17.0

PainterではsetAlpha()がサポートされない

パフォーマンス上の理由で、Canvas Widget Renderer（CWR）によって使用されるPainterでは、アルファがサポートされなくなりました。 Painterの存在するCanvas Widget上でアルファを設定することで、この効果をまだ得ることができます。一般的なコードは以下のように変更できます。変更前:

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);

これまでにPainterとCanvas Widgetの両方にアルファを適用していた場合、これら2つのアルファ値を乗算し、さらに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);

または、255で除算する代わりに、LCD::div255()を使用します。

HALクラスの使用

バージョン4.17.0より前は、HALをまったく使用しないTouchGFXフレームワーク内の複数のファイルに、ヘッダ･ファイルtouchgfx/hal/HAL.hppが含まれていました。これらの不要な参照がクリーンアップされたことで、コンパイラがHALを認知しないために、ユーザ･コードがコンパイルされない可能性が出てきました。これを修正するには、次のようにHALヘッダ･ファイルを単純に加えます。

#include <touchgfx/hal/HAL.hpp>

あるいは、Screenクラスに、スクリーン･サイズを設定するためのgetScreenWidth()とgetScreenHeight()という2つの関数があります。これはスクリーンのサイズを取得するために推奨される方法で、Screenの任意のサブクラスから直接呼び出すことができます（Screen1View.cppなど）。

TouchGFX GeneratorのFMCディスプレイ･インタフェース

TouchGFX Generatorで新しいFMCディスプレイ･インタフェースを使用する場合、CubeMX 6.2.1で生成するときに、FMCバンクのメモリ･オフセットが正しく（ゼロに）設定されません。これはCubeMX 6.3.0で修正予定で、リリース時点でX-CUBE-TouchGFXの最低限必要なバージョンが現在の6.2.1から6.3.0に引き上げられる予定です。それまでは、ユーザがTouchGFXGeneratedHAL.cpp内に正しいFMC BANKメモリのアドレスを入力します（再生成時に上書きされます）。たとえば、次のようになります。

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

ユーザは、TouchGFXHAL.cppでこれら全体を再定義することもできます。

16bpp、24bpp、32bpp構成のL8画像

L8画像のCLUTを読み込むときに、OSWrappers::taskYield()がSTM32DMAクラスに誤って導入されます。これを修正するために、ユーザは以下を実行します。

Users/<user name>/STM32Cube/Repository/Packs/STMicroelectronics/X-CUBE-TOUCHGFX/4.17.0/CubeMX/templates/Targetフォルダに移動。
ビット深度に基づいて、適切なdma_Xbpp_implementation_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 Setup

TouchGFX 4.17.0よりも古いバージョンでは、TouchGFX Board Setups（TBS）をTouchGFX Designerから取得することはできません。新しい設計には、最新バージョンのTouchGFXを使用することを強く推奨します。

TouchGFX 4.15.0

マイクロコントローラのサポート

Cortex-M33はTouchGFXによって完全サポートされていますが、CubeMXにサポートを追加しない限り、現在のバージョンのCubeMX（v6.0.1）では、マルチ・コンテキストのマイクロコントローラに対して"Software Packs"（特にTouchGFX Generator）を有効にできません。 Cortex-M33ベースのマイクロコントローラの"Trust Zone"を無効化することで、マイクロコントローラを単一コンテキストに制限すれば、TouchGFX Generatorを有効にできます。 TrustZoneは、User Codeセクションで手動で有効化する必要があります。

TouchGFX 4.14.0

ARMCLANGのサポート

TouchGFXでは、Cortex-M0、Cortex-M4f、Cortex-M7、Cortex-M33に対して、ARMCLANG（ARM Compiler v6.x）ライブラリを提供するようになりました。しかし、CubeMXでは、ARMCLANGコンパイラ（ARM Compiler v6.x）を有効化するプロジェクトを生成できません。このため、プロジェクト内でこのコンパイラを使用したいユーザは、Keil μVisionのプロジェクト･オプションから手動でコンパイラを選択する必要があります。

CubeMXからFreeRTOSミドルウェアを設定する場合、ARMCC（ARM Compiler v5.x）を使用する生成済みのプロジェクトは、ARMCLANGと互換性を持たないFreeRTOS portableファイルを持つことになるため、これらを手動で置き換える必要があります。 CubeMXから"Generate code"を実行すると常にすべての手動変更が上書きされるので、これらの特定の変更を元に戻せるよう、バージョン管理下（gitなど）にプロジェクトを保持しておくことをお勧めします。

要約すると、 CubeMXで生成できるのはARM Compiler v5.xコンパイラ･プロジェクトのみなので、ユーザはバージョン管理下にプロジェクトを保持していない限り、CubeMXからコードを生成するたびに以下の変更を行う必要があるということです。

プロジェクト･オプションでARM Compiler v6.xを選択。
ARMCCライブラリ（CubeMXで設定されたもの）ではなく、ARMCLANGライブラリにリンク。
CubeMXからFreeRTOSを設定する場合、ARM Compiler v6.xと互換性を持たせるために、FreeRTOS portableファイルをportable/RVDSフォルダ（ARM Compiler v5.xのデフォルト）ではなく、portable/GCCフォルダから取得する。

ワーク・フロー

以下のワークフローは、CubeMXで生成されたプロジェクトとTouchGFX ARMCLANGライブラリを使い、Keil μVisionにあるv6.x ARM Compilerを使用する方法について説明しています。

Keil μVisionでARMCLANG（v. 6.x）を選択します。

ARMCLANGのサポート

CubeMXからFreeRTOSを設定する場合、CubeMXは誤ったportable ファイルを生成し、それらを使用するようにプロジェクトが設定されまる。ユーザはこれらを（https://github.com/FreeRTOS/FreeRTOS-Kernel/tree/6199b72fbf57a7c5b3d7b195a3bd1446779314cd/portable/GCC (port.cおよびportmacro.h））にあるものに置き換えるか、FreeRTOSリリースをダウンロードしてその中からファイルを見つける必要があります。
port.cを置き換えます。
port.c
インクルード･パスの設定を変更して、portable/GCCフォルダ（この場合はCortex-M7）のportmacro.hを含むようにします。
Portable のインクルード･パス
"Generate Code"実行時のTouchGFX Designer生成後ステップで、ユーザが選択したコンパイラ･バージョンに基づいて正しいライブラリが自動的に挿入される。

TouchGFX 4.13.0

バグ

フォント･コンバータ

FontConverterツールでは、アプリケーションの実際のテキストでそのグリフが使用されているかどうかに関わらず、フォントのルールの一部であるUnicode用のグリフのピクセル･データが生成されることがあります。これにより数メガバイトのグリフのピクセル･データが、追加で発生する可能性があります。新しいFontConverterツール（WindowsおよびLinux）では、アプリケーションで使用されていないグリフのピクセル･データは生成されなくなっています。新しいツールには次のリンクからアクセスできます。

fontconvert_fix.zip

お使いの4.13.0インストールのルートにこのファイルを展開すると、フォント･コンバータのバイナリが以下の内部に更新されます。

touchgfx\framework\tools

追加のコンパイラ･サポート

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との非互換

2つの関数が、TouchGFXライブラリ･コードからHALSDL2.cppに移動しました。これにより、WindowsシミュレータのHALとしてHALSDL2.cppを使用するアプリケーションには何の影響もありません。

ただし、古いアプリケーション（TouchGFX 4.8.0より前）の場合、シミュレータはおそらくHALSDL（HALSDL2ではない）を使用してます。このシミュレータのHALは、TouchGFXには含まれなくなりました。 HALSDLには、以前TouchGFXライブラリに含まれていた2つの関数が欠落しています。ユーザはこれらを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()を呼び出します。

バイナリ･フォント

カーニング･データもバイナリ･フォントに含まれるようになったため、バイナリ･フォントのフォーマットが変更されました。バイナリ･フォント･ファイルを再生成する必要があります。古いファイルは正しく機能しないためです。 Makefileの設定方法によっては、これは通常すべてのアセットを再生成することで実行されます（make -f simulator/gcc/Makefile clean assetsなど）。

TouchGFX 4.11.0

後方互換性

touchgfx/framework/include/touchgfx/lcd/LCD.hppでは、以前のバージョンで誤って挿入されたファイルtouchgfx/hal/HAL.hppのインクルードが削除されました。このため、LCD.hppを含んでいてHAL.hppのコンテンツも使用しているファイルで、コンパイル･エラーが発生する可能性があります。解決策として、ファイルにtouchgfx/framework/include/touchgfx/hal/HAL.hppも含めてください。

TouchGFX 4.10.0

4.9.xからのアップグレード

バージョン4.10.0から、TouchGFXはSTM32マイクロコントローラのみで実行されます。

古いプロジェクトを更新する場合には、以下を実行する必要があります。

アプリケーションのスタートアップで、以下のハイライトされたコードを追加して、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ではこの2つの手順が混ざっているので、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が自動的にアップグレードを実行できます。アップグレードは2つの異なる方法で実行可能なので、ユーザは自分に最適な方法を決定する必要があります。

Caution
アップグレードの前には、必ずプロジェクトのバックアップを取るようにしてください。

方法1: 元のファイル構造を維持

この方法は、単純に新しい4.9.0 Designerでプロジェクトを開くことで実行できます。 TouchGFX Designerからアップグレードを行うかどうか尋ねられるので、OKをクリックすると、TouchGFX Designerが必要な変更を適用します。 TouchGFX Designerは以下の操作を実行します。

圧縮された新しいtouchgfxフォルダをアプリケーションにアンパックし、これと一致するようにTouchGFXのパスを変更。
touchgfxフォルダから削除したすべてのファイルをダウンロードしてアンパックし、プロジェクトが引き続きコンパイルできるようにする。

このアプローチでは、ほぼすべてが以前と同じ状態になるので、以前のファイル構造が自分のプロジェクトに適している場合には、最も簡単な選択になります。主な欠点は、画像コンバータの速度アップの恩恵を受けられないことです。これは、個々のファイルではなく、画像フォルダに対して作業するためです。ただし、makefileを手動で変更してこのアプローチを使用することができます。

方法2: 新しいテンプレートへのインポート

この方法を使用すると、プロジェクトを新しいテンプレート･ベースのファイル編成に移行できます。このためには、まず上記の方法1を使用して、Designerでプロジェクトをアップグレードします。次に、適切なアプリケーション･テンプレート（シミュレータ、または使用する評価ボードと合致するもの）を使用して、新しいプロジェクトを作成します。 Designerでこの新しいプロジェクトを開いて、トップ･メニューに移動し、"Edit -> Import GUI"をクリックします。ダイアログ･ボックスで、自分のプロジェクトの.touchgfxファイルを指定します。これで、DesignerがすべてのUIファイル（アセットを含む）を、新しく作成したプロジェクトに自動的にインポートします。 GUIフォルダ以外に追加したコードがある場合は、それらのファイルを新しいプロジェクトに手動でコピーする必要があります。

方法3: Designerを使用せずに手動でアップグレード

Designerを使用しない場合、以下のようにアップグレードを実行できます。

プロジェクトで使用するtouchgfxフォルダを、4.9.0インストールにあるものと置き換える。
このzipファイルをダウンロードして、touchgfxフォルダにアンパックし、削除されたファイルを復元する。

TouchGFX 4.24.0​

Caution

TouchGFX 4.23.0​

Microsoft Visual C++ Redistributable​

touchgfx::VectorRendererクラスで変更されたインタフェース​

TouchGFX 4.22.0​

X-Cube-Display​

TouchGFX 4.21.0​

WideTextAction​

IARによるSTM32U599プロジェクトのコンパイル​

NeoChromでのSTM32上のSVG描画​

TouchGFX 4.20.0​

Painterインタフェースの変更​

Painterの実装が生成されたファイルに移動​

手順​

リンカ･エラー​

KeilによるSTM32G0のデバッグ​

KeilによるSTM32U5とSTM32L5プロジェクトのコンパイル​

LOGONSERVERの環境変数​

TouchGFX 4.19.0​

H7でのMJPEG Video向け、STM32CubeMXによるコードの生成​

Core\Src\stm32h7xx_hal_msp.c

タイポグラフィの新しい操作方法​

例: 自動生成されたフォントID​

4.19.0へのアップグレード時に自動生成されるタイポグラフィ​

ユーザ･コードでのフォントIDの参照​

ARMCLANGによるLibJPEGの使用​

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​

PainterではsetAlpha()がサポートされない​

HALクラスの使用​

TouchGFX GeneratorのFMCディスプレイ･インタフェース​

16bpp、24bpp、32bpp構成のL8画像​

TouchGFX 4.16.0​

TouchGFX Board Setup​

TouchGFX 4.15.0​

マイクロコントローラのサポート​

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: Designerを使用せずに手動でアップグレード​

TouchGFX 4.24.0

TouchGFX 4.23.0

Microsoft Visual C++ Redistributable

touchgfx::VectorRendererクラスで変更されたインタフェース

TouchGFX 4.22.0

X-Cube-Display

TouchGFX 4.21.0

WideTextAction

IARによるSTM32U599プロジェクトのコンパイル

NeoChromでのSTM32上のSVG描画

TouchGFX 4.20.0

Painterインタフェースの変更

Painterの実装が生成されたファイルに移動

手順

リンカ･エラー

KeilによるSTM32G0のデバッグ

KeilによるSTM32U5とSTM32L5プロジェクトのコンパイル

LOGONSERVERの環境変数

TouchGFX 4.19.0

H7でのMJPEG Video向け、STM32CubeMXによるコードの生成

タイポグラフィの新しい操作方法

例: 自動生成されたフォントID

4.19.0へのアップグレード時に自動生成されるタイポグラフィ

ユーザ･コードでのフォントIDの参照

ARMCLANGによるLibJPEGの使用

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

PainterではsetAlpha()がサポートされない

HALクラスの使用

TouchGFX GeneratorのFMCディスプレイ･インタフェース

16bpp、24bpp、32bpp構成のL8画像

TouchGFX 4.16.0

TouchGFX Board Setup

TouchGFX 4.15.0

マイクロコントローラのサポート

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: Designerを使用せずに手動でアップグレード