既知の問題

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

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

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.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 uVisionのプロジェクト･オプションから手動でコンパイラを選択する必要があります。

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 uVisionにあるv6.x ARM Compilerを使用する方法について説明しています。

Keil uVisionで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フォルダにアンパックし、削除されたファイルを復元する。

CubeMX 6.1.0およびCubeProgrammer 2.6による問題​

TouchGFX 4.17.0​

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

HALクラスの使用​

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

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

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

CubeMX 6.1.0およびCubeProgrammer 2.6による問題

TouchGFX 4.17.0

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

HALクラスの使用

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

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

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