Generatorユーザ･ガイド

X-CUBE-TOUCHGFXの一部であるTouchGFX Generatorは、STM32CubeMXの追加ソフトウェア･コンポーネントで、開発者が自前のハードウェア･プラットフォーム上でTouchGFXを実行するための設定を行うのを支援するものです。既存のSTM32CubeMXの設定とユーザ入力に基づいて、TouchGFX Generatorは機能するTouchGFXアプリケーションの設定に必要なファイルを生成します。ここには、TouchGFX HAL、TouchGFX OSAL、およびTouchGFXの設定ファイルが含まれています。

STM32CubeMXを介してコードを生成すると、TouchGFX DesignerからTouchGFXプロジェクトを開けるようになり、ここでUIを開発できます。 TouchGFX Designerは、追加生成されたコードのファイルを、STM32CubeMXでプロジェクト用に設定されたターゲットのIDEプロジェクトに自動的に追加します。

TouchGFX Generatorの有効化

ユーザは、X-CUBEから［Select Components］ボタンを押すことで、追加機能にアクセスできます。

STM32CubeMXで［Additional Software］を選択

次の図は、プロジェクトに対してTouchGFX Generatorを有効化する方法を示しています。

TouchGFX Generatorの有効化

デュアル･コアのマイクロコントローラに対してTouchGFXを有効化する場合には、正しいコンテキストで有効化するようにしてください。 TouchGFXは単一コンテキストでのみ有効化できます。

デュアル･コアに対するTouchGFX Generatorの有効化

生成されるコードのアーキテクチャ

TouchGFX Generatorの機能の説明の前に、生成されるコードのアーキテクチャと、開発者がそれを使用して設定や動作をカスタマイズする方法について理解することが重要です。

STM32CubeMXで生成するファイル内のユーザ記述のコードは、STM32CubeMX（Cコード）で生成されるコード全体に明示的に配置されたUser Code･セクションを使用することで保護されます。 TouchGFX Generator（C++コード）で生成されるコードでは、この柔軟性が保持されています。

［Additional Software］でTouchGFX Generatorを追加し、有効化すると、STM32CubeMXは常にそのプロジェクトにTouchGFXフォルダを作成します。このフォルダには設定に関わらず常に同じファイルが含まれますが、ファイルの内容はSTM32CubeMXおよびユーザ設定に応じて変わります。

次のリストは、TouchGFX Generatorが有効化されたSTM32CubeMXプロジェクトの内容の概要を示しており、特にTouchGFX関連ファイルが強調されています。リストの後の表は、最も重要なエントリの役割を概説しています。

TouchGFX フォルダ

│   .mxproject
│   myproject.ioc
├───Core
├───Drivers
├───EWARM
├───Middlewares
└───TouchGFX
    │   ApplicationTemplate.touchgfx.part
    ├───App
    │       app_touchgfx.c
    │       app_touchgfx.h
    └───target
        │   STM32TouchController.cpp
        │   STM32TouchController.hpp
        │   TouchGFXGPIO.cpp
        │   TouchGFXHAL.cpp
        │   TouchGFXHAL.hpp
        │
        └───generated
                OSWrappers.cpp
                TouchGFXConfiguration.cpp
                TouchGFXGeneratedHAL.cpp
                TouchGFXGeneratedHAL.hpp

フォルダ	役割
myproject.ioc	STM32CubeMXプロジェクト･ファイル
Core	`main.c` と起動コード
Drivers	CMSISとマイクロコントローラ･ファミリのドライバ
EWARM	IDEプロジェクト･フォルダ。 EWARM、MDK-ARM、STM32CubeIDEのいずれか
Middlewares	TouchGFXライブラリ / ヘッダファイルと、サードパーティ･ソフトウェア（FreeRTOSなど）が含まれます。
ApplicationTemplate.touchgfx.part	.partファイルはSTM32CubeMXによって、TouchGFX Designerプロジェクトに関連する情報（画面の寸法やビット深度など）で更新されます。
App	X-CUBEのSTM32CubeMXに対するインタフェース。 `app_touchgfx.c` には、関数`MX_TouchGFX_Process(void)`および `MX_TouchGFX_Init(void)` の定義が含まれます。これらの関数はTouchGFXを初期化してメイン･ループを開始するために使用されます。
target/generated	このサブフォルダには、設定変更時にSTM32CubeMXによって上書きされる読出し専用ファイルが含まれます。 `TouchGFXGeneratedHAL.cpp`はTouchGFXクラス`HAL`のサブクラスで、STM32CubeMXが現在の設定に基づいて生成することのできるコードが含まれます。 `OSWrappers.cpp`OSAL）にはTouchGFXエンジンとの同期に必要な関数が含まれます。最後に`TouchGFXConfiguration.cpp` には、TouchGFXの構築および設定のためのコードが含まれます（HALを含む）。
target	HALの動作を拡張したりSTM32CubeMXによって生成された設定をオーバーライドしたりするためにユーザが変更できるファイルの大部分が含まれています。 `STM32TouchController.cpp`には、空のタッチ･コントローラ･インタフェースが含まれます。 `TouchGFXHAL.cpp` は、`TouchGFXGeneratedHAL`のサブクラス`TouchGFXHAL`,を定義します。

TouchGFXConfiguration.cppにはHALを構築する関数とTouchGFXのメイン･ループを開始する関数が含まれることを把握しておくことが重要です。追加設定は、編集可能なユーザクラスTouchGFXHALにて行うことができます。 HALの一般的なアーキテクチャは次のようになります。

生成されるコードの階層

機能の概要

TouchGFX Generatorを有効にすると、ユーザ･インタフェースには次の3つの主なグループが表示されます。 4つ目の［Dependencies］は、現在の設定で問題が検出された場合に表示されます。

Dependencies - このグループには依存関係、警告、または設定内の具体的なエラーに関する開発者への通知が含まれます。エントリが存在しない場合、このグループは非表示になります。
Display - このグループにはディスプレイに関連する設定（インタフェース、フレームバッファのビット深度、幅、高さなど）が含まれます。これらの設定は、TouchGFXプロジェクトのキャンバスのサイズや、アセット用に生成されるコードに直接影響します。
Driver - このグループでは、アプリケーション、グラフィックス･アクセラレーション（DMA2DおよびGPU2D）、RTOSのティック･ソースに関連する多くの既製のドライバに対してユーザがオプトインできます。 STM32CubeMXはFreeRTOS（CMSIS RTOS v1およびv2）の設定をサポートしているため、TouchGFX Generatorはこれらの各オプションに対してドライバを提供します。
Additional Features - このグループはRGB565が選択された場合に表示されるもので、ユーザは非メモリ･マップドFlashから画像またはフォント･データを使用してアプリケーションを作成できます。
Video Decoding - このグループでは、ハードウェアまたはソフトウェアのビデオ･デコーディングをユーザが有効化できます。このオプションはビデオ･ウィジェットと併用する必要があります。なお、すべてのマイクロコントローラがビデオ･デコーディングに対応しているわけではありません。

TouchGFX Generatorには3つのグループ、Display、Driver、Video Decodingがあります。

Display

Displayグループには、ディスプレイに関連する設定（インタフェース、寸法、バッファリング戦略など）が含まれます。

インタフェースと寸法

現在、STM32マイクロコントローラでは、次に示すような複数のディスプレイ･インタフェースを使用できます。

パラレルRGB（LTDC）
MIPI DSI
FMC
SPI

ディスプレイがLTDCまたはFMCに接続されたマイクロコントローラの場合、TouchGFX Generatorは、接続されたディスプレイにフレームバッファを転送するためのコードを生成できます。 DSIおよびSPIインタフェースのドライバは、開発者自身で実装する必要があります。

フレームバッファのピクセル･フォーマット

TouchGFX Generatorによって現在サポートされているフレームバッファのピクセル･フォーマットは、以下です。 Customディスプレイ･インタフェースを使用する場合はすべてのオプションを使用できます。それ以外の場合、オプションはディスプレイ･コントローラの設定に制限されます（たとえば、LTDCフレームバッファの形式を「RGB565」に設定すると、TouchGFX Generatorのオプションは「RGB565」に制限されます）。

BW（1bpp）
Grey2（2bpp）
Grey4（4bpp）
ABRG2222（8bpp）
ARGB2222（8bpp）
BGRA2222（8bpp）
RGBA2222（8bpp）
RGB565（16bpp）
RGB888（24bpp）
ARGB8888（32bpp）
XRGB8888（32bpp）

Note
一部のピクセル･フォーマットでは、ChromART（DMA2D）のサポートがないか、一部のみになります。

Caution
STM32F7/H7の場合、フレームバッファがライトスルーのキャッシュ･メモリ（SRAMなど）に配置されていれば、DMA2D（Generatorで設定されている場合）がアクセスする前に、生成されたコードによってDCacheがクリアされます。 このキャッシュ･メカニズムを機能させるには、STM32CubeMXで［Cortex M7］の［System Core］設定にある［CPU Cache］を必ず有効化してください。

Buffering Strategies

TouchGFX Generatorを介して、次のフレームバッファ戦略を設定できます。

Single Buffer - アプリケーション･フレームバッファを1つだけ使用します。パフォーマンスが制限される可能性がありますが、メモリの使用量は少なくて済みます。［Buffer Location］設定で使用して、内部RAMに配置できます。さらに最適化するには、ディスプレイ･コントローラによって現在処理されているラインを返す関数をユーザが定義できます。この方法はフレームワークによって使用され、このフレームですでにディスプレイに転送済みのメモリへの更新ができるようになります。
Double Buffer - 2つのフレームバッファを使用します。通常、多くのメモリを必要としますが、パフォーマンスが向上します。
Partial Buffer - 1つ以上のユーザ定義のメモリ領域をフレームバッファとして使用します。この戦略は外部RAMに頼らないが、ディスプレイのフレームバッファ全体では使用可能なメモリ量を超える可能性がある場合の低コストのソリューションをターゲットにしています。

シングル・バッファとダブル・バッファの場合、ユーザは［Buffer Location］設定で次のオプションを使用して場所を設定できます。

By Allocation - リンカがリンカ･スクリプトに従ってフレームバッファのメモリを配置できます。デフォルトは内部RAMです。
By Address - ユーザが1つ（シングル）または2つ（ダブル）のフレームバッファ･アドレスを定義できます。

パーシャル・バッファ戦略では、ユーザは以下のパラメータを定義できます。

ブロック数（常に内部RAMに配置される）
ブロック･サイズ（バイト）

パーシャル･バッファ戦略に関する中心的な概念を理解するには、パーシャル･フレームバッファを使用してメモリ要件を軽減する方法に関する専門の記事を参照してください。この記事はパーシャル･フレームバッファを実現する方法を概念的に示したものなので、この記事に示すコードはTouchGFX Generatorによって生成されるコードと少し異なっています。これらの戦略で生成されるコードの具体例については、「フレームバッファ戦略」を参照してください。

Driver

［Driver］セクションでは、TouchGFX ALのさまざまな役割に対応するドライバを開発者が選択できます。

Application Tick Source

アプリケーションのティック･ソースは、アプリケーションを前進させる方法を定義します。開発者は以下のオプションを使用できます。

LTDC - ［Display］グループのインタフェースとして［LTDC］を選択した場合、［Application Tick Source］を［LTDC］にできます。つまり、TouchGFX GeneratorがTouchGFXGeneratedHAL クラスにドライバ関数（LTDC割込みハンドラ）をインストールし、それがOSWrappers::signalVSync().を呼び出してアプリケーションを前進させます。
Custom and FMC - この場合、OSWrappers::signalVSync()を繰り返し呼び出すことでアプリケーションを前進させるハンドラを、開発者が実装する必要があります。

Graphics Accelerator

グラフィック･アクセラレーションに関して、開発者には次の3つのオプションがあります。

None - アプリケーションはCPUのみを使用して描画します。
DMA2D Accelerator (ChromART) - アプリケーションは可能であればChromARTチップを使用してピクセルの移動やブレンドを行い、CPUサイクルを解放します。 TouchGFX Generatorによってドライバが生成されるので、開発者によるアクションは必要ありません。

DMA2Dは、マイクロコントローラがサポートする場合、CubeMXの「Multimedia」カテゴリで有効になります。

TouchGFX Generatorから提供されるChrom-ART（DMA2D）ドライバは、TransferCompleteInterruptの受信方法として次の2つをサポートしています。

TM32Cube HALドライバを使用して、dma2dハンドラにコールバック関数hdma2d.XferCpltCallbackを登録する。
DMA2D_IRQHandler()割込みハンドラを直接使用する。

この2つの方法を切り替えるには、DMA2D IP用のSTM32CubeMXのNVIC設定で、DMA2Dグローバル割込みを有効化 / 無効化します。グローバル割込みを有効化するとオプション1のコードが生成され、グローバル割込みを無効化するとオプション2のコードが生成されます。

Note
DMA2Dのグローバル割込みを使用する場合は、「IRQハンドラ」が「DMA2D HALハンドラ」を呼び出すことを確認します。 これはデフォルトの動作です。
グローバル割込みが有効で「IRQハンドラ」とDMA2Dの「HALハンドラの呼び出し」が無効になっている場合、登録されたコールバックが呼び出されません。

GPU2D（NeoChrom）はグラフィックス･アクセラレータで、TouchGFXにおいてテクスチャ･マッピングを含む多くの描画操作を加速させます。これは、RGB565、RGB888、ARGB8888フォーマットのフレームバッファをサポートします。

GPU2Dは、マイクロコントローラがサポートする場合、CubeMXの「Multimedia」カテゴリで有効になります。

Caution
GPU2Dオプションは、CubeMXで、自分のプロジェクトのMultimediaセクションでGPU2Dが有効になっている場合のみ表示されます。 STM32U599デバイスでのみ使用可能で、MiddlewaresセクションでThreadX RTOSも有効になっている場合のみ、TouchGFXで使用できます。

Real-Time Operating System

開発者はTouchGFXで任意のRTOSを使用できます（OS無しも含む）。「抽象化レイヤ･アーキテクチャ」で説明したように、TouchGFXエンジンはインタフェースを使用して、ユーザが選択したRTOSと、メイン･イベント･ループおよびフレームバッファのアクセスを同期させます。OSWrappers 開発者がTouchGFX Generatorでオペレーティング･システムを選択した場合、選択したOSのプリミティブを介して内部同期するためのコードが生成されます。それでも、特にスタック･サイズを決定するために、STM32CubeMXを介してオペレーティング･システムを設定する必要があります。

FreeRTOS（CMSIS OS V1およびV2）およびThreadX（ネイティブ･ミドルウェアまたはAzure RTOSソフトウェア･パック）は、STM32CubeMXおよびTouchGFX Generator内から直接設定可能で、タスク定義とTouchGFX RTOSドライバの両方のユーザ生成のコードをユーザに提供します。 TouchGFX Generatorは、CMSIS V1およびCMSIS V2準拠のRTOSドライバを生成可能で、これらは任意のCMSIS準拠のRTOS、ThreadXのドライバ、およびオペレーティング･システムなしでベア･メタルで実行するドライバとの組み合わせで機能します。

ThreadX

ThreadXを有効にするには、AZRTOSソフトウェア･パックを選択するか、ネイティブのThreadXミドルウェアをSTM32CubeMXから有効にします（選択したマイクロコントローラ･デバイスで使用可能な場合）。

Note
すべての新しいSTM32マイクロコントローラ･デバイスは、追加のパックをダウンロードしなくてもSTM32CubeMXから直接使用できるThreadXミドルウェアを、デフォルトでサポートしています。 TouchGFX Board Supportパックは、可能な場合はThreadXミドルウェアを使用するか、X-CUBE-AZRTOSソフトウェア･パックを使用する方向に徐々に移行します。
ThreadXサポートを提供するX-CUBE-AZRTOS-XX拡張パックは、STM32G0xx、STM32G4xx、STM32L4xx、STM32F4xx、STM32F7xx、STM32H7xxのマイクロコントローラ･シリーズですでに使用可能です。

次の図は、TouchGFX Generatorを通して使用可能なオプションを示しています。

RTOSドライバのオプション

Note
NoOSオプションは、ThreadXミドルウェアが有効な場合は無効になります。
CMSIS_RTOS_V1およびCMSIS_RTOS_V2オプションは、ThreadXミドルウェアが有効な場合は無効になります。 STはCMSIS OSラッパーを提供していないので、ユーザがCustomオプションを選択してCMSISラッパーを実装する必要があります。

STM32CubeMXが提供するミドルウェア･リストからThreadXを有効にして設定する

ThreadXに適したメモリ設定はMemory Pool Allocationに依存します。推奨される値は、Static Allocationです。 ThreadXミドルウェアの設定で、次の手順を実行します。

下の図に示すように、ModeリストからCoreを選択して、THREADXミドルウェアを有効にします。
TX_TIMER_TICKS_PER_SECONDを1000に設定して、1ミリ秒ごとにティックを取得します。
Memory Pool AllocationをUse Static Allocationに設定します。

ネイティブのThreadXミドルウェアを有効にして設定する

Caution
Native ThreadX Middlewareが有効な場合は、Memory Pool AllocationをUse Dynamic Allocationに設定する必要があります。
Memory Pool AllocationをUse Dynamic Allocationに設定した場合
ユーザは、生成されたapp_azure_rtos.cファイルのUSER CODE BEGIN DYNAMIC_MEM_ALLOCセクションに、不足したコードを追加する必要があります。
さらにユーザは、生成されたapp_azure_rtos.cファイルに記述されている推奨事項に従って、リンカ･ファイルを更新する必要もあります。

AZRTOSソフトウェア･パックからThreadXを有効にして設定する

Software Packs -> Select Componentsを選択するか、Alt-Oを押します。
STMicroelectonics.X-CUBE-AZRTOS-XXを選択します。必要に応じてパックをダウンロードします。
RTOS ThreadXを選択し、CoreチェックボックスをオンにしてThreadXを有効にします。これでSoftware Packs Component Selectorを安全に閉じることができます。

X-CUBE-AZRTOSソフトウェア･パックからThreadXを有効にする

左側のCategoriesリストからSoftware Packsグループを選択し、STMicroelectonics.X-CUBE-AZRTOS-XXを選択します。
RTOS ThreadXモードを選択することで、ThreadXを有効にします。
Memory Pool AllocationをUse Static Allocationに設定します。

ThreadXの設定 - X-CUBE-AZRTOSソフトウェア･パック

TX_TIMER_TICKS_PER_SECONDを1000に設定して、1ミリ秒ごとにティックを取得します。

ThreadXの設定 - X-CUBE-AZRTOSソフトウェア･パック

FreeRTOS

次の関数を呼び出すと、TouchGFXのメイン･ループに入ります。

void MX_TouchGFX_Process(void);

開発者はTouchGFXアプリケーションを実行したいタスクのタスク･ハンドラ内で、この関数を呼び出す必要があります。次の例は、ユーザがSTM32CubeMXからDefaultTaskという名前のFreeRTOSタスクを設定した場合に、 MX_TouchGFX_Process()を呼び出して、このタスク･ハンドラのユーザ･コード･セクションでTouchGFXを開始する方法を示しています。

void StartDefaultTask(void *argument)
{
  /* USER CODE BEGIN 5 */
  MX_TouchGFX_Process();
  /* USER CODE END 5 */ 
}

STM32CubeMXは、スケジューラを起動するosKernelStart();の呼び出しも生成します。

ThreadXミドルウェア

STM32CubeMXは、ミドルウェアおよびユーザ用のスレッドを作成するコードを生成しなくなります。
STM32CubeMXは、MX_TouchGFX_PreOSInit()関数への呼び出しを生成し、この関数がTouchGFXフレームワークを初期化します。
STM32CubeMXは、MX_ThreadX_Init()()関数への呼び出しを生成し、この関数がThreadXカーネルを初期化して起動します。

int main(void)
{
  /* Call PreOsInit function */
    MX_TouchGFX_PreOSInit();
  /* USER CODE BEGIN 2 */

  /* USER CODE END 2 */

  MX_ThreadX_Init();
}

TouchGFX Generatorは、MX_TouchGFX_PreOSInit()関数を生成し、この関数が単純にtouchgfx_init()を呼び出します。

/**
 * PreOS Initialization function
 */
void MX_TouchGFX_PreOSInit(void)
{
  // Calling forward to touchgfx_init in C++ domain
  touchgfx_init();
}

TouchGFX Generatorは、MX_TouchGFX_Init()関数を生成し、この関数がTouchGFXスレッドを作成します。

/**
 * Create TouchGFX Thread
 */
UINT MX_TouchGFX_Init(VOID *memory_ptr)
{
  UINT ret = TX_SUCCESS;
  CHAR *pointer = 0;

  /* Allocate the stack for TouchGFX Thread.  */
  if (tx_byte_allocate((TX_BYTE_POOL*)memory_ptr, (VOID **) &pointer,
                       TOUCHGFX_STACK_SIZE, TX_NO_WAIT) != TX_SUCCESS)
  {
    ret = TX_POOL_ERROR;
  }

  /* Create TouchGFX Thread */
  else if (tx_thread_create(&TouchGFXThread, (CHAR *)"TouchGFX", TouchGFX_Task, 0,
                       pointer, TOUCHGFX_STACK_SIZE,
                       5, 5,
                       TX_NO_TIME_SLICE, TX_AUTO_START) != TX_SUCCESS)
  {
    ret = TX_THREAD_ERROR;
  }

  return ret;
}

TouchGFX Generatorが必要なコードを生成し、そのコードがSTM32CubeMXによってapp_azure_rtos.cファイルに挿入されます。

  /**
  * @brief  Define the initial system.
  * @param  first_unused_memory : Pointer to the first unused memory
  * @retval None
  */
VOID tx_application_define(VOID *first_unused_memory)
{
  ...

  if (tx_byte_pool_create(&touchgfx_app_byte_pool, "TouchGFX App memory pool", touchgfx_byte_pool_buffer, TOUCHGFX_APP_MEM_POOL_SIZE) != TX_SUCCESS)
  {
    /* USER CODE BEGIN TouchGFX_Byte_Pool_Error */

    /* USER CODE END TouchGFX_Byte_Pool_Error */
  }
  else
  {
    /* USER CODE BEGIN TouchGFX_Byte_Pool_Success */

    /* USER CODE END TouchGFX_Byte_Pool_Success */

    memory_ptr = (VOID *)&touchgfx_app_byte_pool;
    if (MX_TouchGFX_Init(memory_ptr) != TX_SUCCESS)
    {
      /* USER CODE BEGIN  MX_X-CUBE-TOUCHGFX_Init_Error */
      while(1);
      /* USER CODE END  MX_X-CUBE-TOUCHGFX_Init_Error */
    }
    /* USER CODE BEGIN  MX_X-CUBE-TOUCHGFX_Init_Success */

    /* USER CODE END  MX_X-CUBE-TOUCHGFX_Init_Success */
  }

  ...
}

tx_application_define()関数は初期化時にThreadXカーネルによって呼び出されます。
MX_TouchGFX_Init()関数はtx_application_define()によって呼び出されます。
TouchGFXスレッドは後で、ThreadXカーネルの起動時に起動されます。

Note
STM32CubeMXは、ThreadXミドルウェアのStatic Memory Pool Allocation設定の完全なコードのみを生成します。
ThreadXをDynamic Memory Allocationで設定したい場合には、X-CUBE-TOUCHGFX拡張パック内で提供されるSTM32H7B3I-DK/Applications/AnimatedImagesの例を参照してください。

その他のCMSIS準拠OS

STM32CubeMXが提供可能なOS（FreeRTOSおよびThreadX）以外のCMSIS準拠OSを必要とする開発者は、RTOSの設定とタスク定義を手動で行う必要があります。一般的には、以下の手動ステップを行う必要があります。

RTOSを設定する。
TouchGFXを実行するためのタスクを定義する（MX_TouchGFX_Process）。
スケジューラを起動する。

MX_TouchGFX_Process を呼び出して、タスク･ハンドラ内で TouchGFXエンジンのメイン･ループを開始します。

void MX_TouchGFX_Process(void);

Additional features

External Data Reader

RGB565フレームバッファ･ピクセル･フォーマットでは、touchgfxは、いわゆるデータ･リーダのインタフェースをサポートしています。これにより開発者は、メモリ内で追加バッファが必要となるキャッシュを行うのではなく、メモリマップされないシリアルFlashから直接データを読み出せます。データ･リーダを実装して、メモリマップされないFlashチップからアプリケーション･アセットを取得する方法の例については、シリアルFlashの記事を参照してください。

通常、データ･リーダのオプションは、追加バッファ用に十分なメモリを備えていない低コストのソリューション（STM32G0など）で使用されます。 DMA2Dが有効である場合、これは有効化できません。

フレームバッファのピクセル･フォーマットとしてRGB565を選択すると、［Additional Features］グループが使用可能になります。

［Additional Features］のデータ･リーダ

開発者は以下の設定を行うことができます。

External Data Reader: この機能を有効化または無効化します。有効化すると、TouchGFXは生成済みのインタフェースを介してアセットのデータを直接取得します。無効化した場合は、開発者がメモリ内のバッファに画像をキャッシュする必要があります。
External Data Reader: Line Buffer Size: 画像またはテキストをフレームバッファにブレンドするための2つのバッファを作成します。 ARGB8888ピクセル･フォーマットでフル･サイズの画像をサポートするためのデフォルト値は、一画面の幅 x 4バイトです。
External Data Reader: Minimum DMA transfer size: DMA転送を開始するための最小限必要なバイト数を設定します。これより少ないバイト数が要求された場合、DMAは使用されません。

［External Data Reader］を有効にしてコードを生成すると、メモリマップされないFlashからアセットを直接取得できるように以下の追加ファイルが作成されます。

TouchGFX/target/generated/TouchGFXGeneratedDataReader.cpp
TouchGFX/target/generated/TouchGFXGeneratedDataReader.hpp
TouchGFX/target/TouchGFXDataReader.cpp
TouchGFX/target/TouchGFXDataReader.hpp

通常通り、TouchGFX Generatorによって生成されたコードに対して、TouchGFXGeneratedDataReader は読出し専用であり、ユーザの変更は TouchGFXDataReaderクラス内で行う必要があります。 TouchGFXGeneratedDataReaderのタイプはtouchgfx::FlashDataReader.です。

以下のファイルが変更され、DataReaderを使用するようにTouchGFX HALが設定されます。

TouchGFX/target/generated/TouchGFXConfiguration.cpp
TouchGFX/target/generated/TouchGFXGeneratedHAL.cpp
TouchGFX/target/generated/TouchGFXGeneratedHAL.hpp

Note
データ･リーダの［Additional Feature］は、DMA2DとLTDCが無効になっている場合にのみ使用できます。

8bitLTDCカラー･ルックアップ･テーブル

フレームバッファをL8フォーマットで読み出すようにLTDCが設定されており、TouchGFXが ABRG2222、ARGB222、BGRA2222、RGBA2222のいずれかでレンダリングする場合、TouchGFX Generatorは、TouchGFXHAL::initialize()の実行時にLTDCにロードされるCLUTを提供します。 LTDCおよびCLUTの使用方法の詳細については、STM32マイクロコントローラのリファレンス･マニュアルを参照してください。

Video Decoding

［Video Decoding］セクションを使用すると、開発者は、ハードウェアまたはソフトウェアのいずれかのビデオ･デコーディング機能を使用してTouchGFX HALを強化できます。

［Video Decoding］はRGB565（16bpp）およびRGB888（24bpp）フレームバッファ･ピクセル･フォーマットでのみ利用可能です。これらのフォーマットのどちらも選択されていない場合は、［Video Decoding］セクションは使用できません。

Note
すべてのマイクロコントローラがハードウェア･ビデオ･デコーディングに対応しているわけではありません。

Type

デフォルトでは、［Video Decoding］の［Type］は無効になっています。必要なペリフェラルがSTM32CubeMXで有効化されていない場合は、［Software］と［Hardware］の両方がグレー表示になります。マウスをグレー表示されているオプションに合わせ、必要なペリフェラルを確認します。

［Hardware］のビデオ･タイプの依存関係を示す情報ボックス

Software - STM32CubeMXの［Middleware］セクションでLIBJPEGが有効になっている場合は、［Sotware］オプションを選択すると、ソフトウェア･デコーダが生成されます。これはつまり、ToughGFX GeneratorによってソフトウェアMJPEGデコーダが生成されるということです。
Hardware - JPEGが［Multimedia］セクションで有効になっており、CMSIS準拠のRTOSがTouchGFX Generatorで選択されている場合は、［Hardware］オプションを選択できます。

Video Decodingタイプのオプション

LIBJPEG設定では、効率化のために、［RGB scanline format］セクションでRGB順序を「RGB」ではなく「BGR」に設定する必要があります。ピクセル当たりのバイト数は3に設定します。

LIBJPEGの必要な［RGB scanline format］の設定

ハードウェア･デコーディングを使用する場合、JPEG設定のRGBフォーマットはディスプレイと同じにする必要があります。

Concurrent videos

［Concurrent Videos］オプションは任意の時点でGUIの同じ画面で同時にデコードされるビデオの最大量を指定します。画面上で1つのビデオをデコードする場合にのみ、［Number of Videos］を1に設定できます。

最大で4つのビデオを同時にデコードできます。

Strategy

ビデオ･デコーディング方式に関して、開発者には次の3つのオプションがあります。

Direct to Framebuffer - ビデオはUIスレッドでデコードされます。これは、他の方式よりも時間がかかります。ハードウェア･ビデオ･デコーディングを使用する場合、［Direct to Framebuffer］オプションは使用できません。
Single Buffer - ビデオは1つの専用バッファと１つの専用タスクでデコードされます。このバッファは内部メモリに割り当てられます。
Double Buffer - ビデオは2つの専用バッファと１つの専用タスクでデコードされます。これは多くのメモリを必要としますが、パフォーマンスは向上します。

シングルまたはダブル･フレームバッファ方式を採用する場合、CMSIS準拠のOSを有効化する必要があります。

CMSIS RTOS要件に関する情報ボックス

Note
ダブル･バッファ方式を採用する場合には、メモリ消費に注意してください。

Decode Format

ソフトウェア･デコーディングの場合、開発者は、フレームバッファのピクセル･フォーマットに関係なく、RGBバッファのピクセル･フォーマットを選択できます。 TouchGFX Generatorは、これらのフォーマットが異なっている場合に、ChromARTでピクセル･フォーマットの変換を実行できるコードを生成します。ビデオ･デコーディング･バッファをRGB565にすると、開発者はメモリ･フットプリントを小さくすることができます。

デコード形式

Buffer size

バッファの幅と高さの設定は、アプリケーションの最大ビデオ寸法に一致する必要があります。幅は32で割り切れる必要があります。

次のコードは、480x272、RGB888ビデオ･ディスプレイと「シングル･バッファ」ビデオ･デコーディング方式を使用するアプリケーション向けにTouchGFXGeneratedHAL.cppに生成されたコードです。

TouchGFXGeneratedHAL.cpp

#include <DedicatedBufferVideoController.hpp>
#include <SoftwareMJPEGDecoder.hpp>

uint32_t lineBuffer[480];

SoftwareMJPEGDecoder mjpegdecoder1((uint8_t*)lineBuffer);

uint32_t videoRGBBuffer[97920];
DedicatedBufferController<1, 480, 272, 480*3U, Bitmap::RGB888> videoController;

//Singleton Factory
VideoController& VideoController::getInstance()
{
    return videoController;
}

void TouchGFXGeneratedHAL::initialize()
{
    HAL::initialize();
    registerEventListener(*(Application::getInstance()));
    setFrameBufferStartAddresses((void*)frameBuf, (void*)(frameBuf + sizeof(frameBuf) / (sizeof(uint32_t) * 2)), (void*)0);

    /*
     * Add software decoder to video controller
     */
    videoController.addDecoder(mjpegdecoder1, 0);

    videoController.setRGBBuffer((uint8_t*)videoRGBBuffer, sizeof(videoRGBBuffer));
}

生成されるプロジェクト

STM32CubeMXでGenerate Codeボタンを使用してコードを生成する場合、TouchGFXは（少なくとも）以下のIDEで動作します。

EWARM
MDK-ARM
STM32CubeIDE

最適なプロジェクト構造を得るために、プロジェクト生成では以下のオプションを選択します。

［Application structure］:［Advanced］
［Generate under root］無効化(STM32CubeIDEのみ)

［Advanced］のアプリケーション構造を選択し、［Generate under root］をオフにする

STM32CubeMXは以下の構造を持つTouchGFXフォルダも生成します。

TouchGFXフォルダの構造

Appフォルダには、TouchGFXを初期化し、起動するコードが含まれています。
targetフォルダには、読出し専用の生成済みコード（generated/内）と、変更可能なユーザ･クラス(STM32TouchController.cpp、TouchGFXGPIO.cpp およびTouchGFXHAL.cppが含まれています。
.partファイルは、TouchGFXヘッダ･ファイルとライブラリを完備した完全なTouchGFXプロジェクトを作成するために、TouchGFX Designerを使用して開かれます。partファイルにはピクセル･フォーマットやDesignerがTouchGFXアプリケーション･コードを生成するときに使用するキャンバスの寸法などの関連するアプリケーション情報が含まれています。

TouchGFX Designerプロジェクト

以下のjson構造は、STM32U599に基づくプロジェクトの「生成されるコードのアーキテクチャ」セクションで説明した.partファイルの内容例を示しています。下の例の生成後コマンドは、［STM32CubeMX Project Manager］タブでユーザが選択したプロジェクト（EWARMなど）を、TouchGFXで必要なライブラリとオプションのコンポーネント、ならびにTouchGFX Designerによって作成された新しいファイル（新しいスクリーンやアセットなど）で更新します。

{
  "Application": {
    "Name": "STM32U599J-DK",
    "TouchGfxPath": "../Middlewares/ST/touchgfx",
    "AvailableColorDepths": [ 24 ],
    "AvailableLCDs":
    {
      "24": "LCDGPU2D"
    },
    "AvailableResolutions": [
      {
        "Width": 480,
        "Height": 480
      }
    ],
    "PostGenerateTargetCommand": "touchgfx update_project",
    "Family": "STM32U5",
    "SubFamily": "STM32U599/5A9",
    "Platform": "m33",
    "ProjectFile": "../STM32U599J-DK.ioc",
    "OptionalComponentsRoot": "../Middlewares/ST/touchgfx_components",
    "OptionalComponents": [
      "GPU2D"
    ]
  },
  "Version": "4.19.0"
}

TouchGFX Designerで.partファイルを開くと、開発者には、具体的なUIをロードするのか、空のテンプレートから開始するのかを選択するオプションが表示されます。

UIの選択

TouchGFX Designerで［Generate Code］を押すと、TouchGFXフォルダの構造は以下のようになります。下の画像はTouchGFXフォルダ構造の具体例を示しており、生成後の新しいファイルやフォルダをハイライト表示しています。

［Generate Code］

TouchGFXフォルダの構造

TouchGFXは、STM32CubeMXの.iocファイルから選択されたIDEを検出し（STM32CubeIDE、EWARM、MDK-ARMの場合）、画面の定義や画像およびフォント･アセットなどの新しく生成されたファイルでプロジェクト･ファイルを更新します。

この時点で開発者は、STM32CubeMX、TouchGFX Designer、およびツールチェーン / IDEで以下のように交互に作業できるようになります。

STM32CubeMXでIDEプロジェクトのドライバを更新する。
STM32CubeMXはDesignerで即座に選択したUI関連の変更で、TouchGFXの.partファイルを更新する。
STM32CubeMXはTouchGFXが特定のプラットフォーム上で動作するために必要なTouchGFX Generatorの設定に基づいて、HALコード（TouchGFX/target/generated/）を生成する。
TouchGFX Designerは生成されたコードでプロジェクトを更新する。

Note
デュアルコア･プロジェクトでは、TouchGFXが特定のコンテキストに対して有効になっていると、通常、TouchGFXプロジェクトはそのコンテキスト専用のフォルダに配置されます（「CM4/TouchGFX」または「CM7/TouchGFX」など）。

生成された動作の変更

HALはクラス階層を持つので、STM32CubeMXによって生成されたHALの設定や動作をユーザがオーバーライドできることに留意してください。以下の例では、開発者が initialize 関数を変更することで、TouchGFXの追加設定や、TouchGFXGeneratedHAL の既存の設定の変更が可能です。

TouchGFXHAL.cpp

void TouchGFXHAL::initialize()
{
    // Calling parent implementation of initialize().
    //
    // To overwrite the generated implementation, omit call to parent function
    // and implemented needed functionality here.
    // Please note, HAL::initialize() must be called to initialize the framework.

    TouchGFXGeneratedHAL::initialize();

    //Overriding configurations
    hal.lockDMAToFrontPorch(true);
    hal.setFingerSize(4);
    hal....
}

プロジェクトのアップグレード

TouchGFX Generatorのパラメータは.iocファイル（STM32CubeMXプロジェクト）に格納されます。 TouchGFX Generatorの新バージョンがリリースされると、旧バージョンのパラメータが新バージョンと互換性を持たないために移行が必要になる可能性があります。

STM32CubeMXはX-CUBEバージョン間のアップグレードをサポートしていないため、［Generate Code］が押されると、.touchgfxファイルのPostGenerateTargetCommandセクション内の以下のコマンドによってTouchGFX Designerで自動的にアップグレードが実行されます。

.touchgfx

"PostGenerateTargetCommand" : "touchgfx update_project --project-file=../upgrade.ioc --platform=m7"

コマンドによって.ioc ファイルが読み出され、現在のバージョンのX-CUBE-TOUCHGFXに合うようにパラメータが更新されます。次の例は、X-CUBE-TOUCHGFX 4.13.0で作成された.iocファイルで、スクリプト（X-CUBE-TOUCHGFX 4.14.0）を手動で実行する方法を示しています。

STM32F746 DISCOアプリケーション･テンプレートを使用した4.13.0から4.14.0へのアップグレード例

$ touchgfx update_project --project-file=../STM32F746G_DISCO.ioc
  TouchGFX Generator 4.13.0 found
  Creating backup of ../STM32F746G_DISCO.ioc as ../backup_STM32F746G_DISCO.ioc
  Performing upgrade 4.13.0 -> 4.14.0 ... OK

更新されたプロジェクトをSTM32CubeMXで開くと、.iocファイルで示されたバージョンのX-CUBE-TOUCHGFXをインストールするように求められます（まだインストールしていない場合）。［Download now］をクリックすると、X-Cube-TouchGFX-4.14.0のダウンロードとインストールが行われます。

追加ソフトウェア･コンポーネントが見つからない場合:

アップグレード･プロセスの実行時、TouchGFX Generatorの設定はすべて保持され、.iocファイルのバックアップは先頭にbackup_が付いた状態で、元のファイルと同じ場所に配置されます

Note
TouchGFX Generatorによって提供される新機能を使用するには、STM32CubeMXで［Generate Code］を実行する必要があります。

Caution
既存のTouchGFXプロジェクト用にSTM32CubeMXを介してX-CUBE-TOUCHGFXをアップグレードするときに、そのアップグレード･プロセスがTouchGFX Designerによって実行されない場合、TouchGFX Generatorのパラメータは別のバージョンに適用されるパラメータであるため、デフォルトにリセットされます。

TouchGFX Generatorの有効化​

生成されるコードのアーキテクチャ​

TouchGFX フォルダ

機能の概要​

Display​

インタフェースと寸法​

Further reading

フレームバッファのピクセル･フォーマット​

Note

Caution

Further reading

Buffering Strategies​

Driver​

Application Tick Source​

Graphics Accelerator​

Note

Caution

Real-Time Operating System​

ThreadX​

Note

Note

STM32CubeMXが提供するミドルウェア･リストからThreadXを有効にして設定する​

Caution

AZRTOSソフトウェア･パックからThreadXを有効にして設定する​

FreeRTOS​

ThreadXミドルウェア​

Note

その他のCMSIS準拠OS​

Additional features​

External Data Reader​

Note

8bitLTDCカラー･ルックアップ･テーブル​

Video Decoding​

Note

Type​

Further reading

Concurrent videos​

Strategy​

Note

Further reading

Decode Format​

Buffer size​

TouchGFXGeneratedHAL.cpp

生成されるプロジェクト​

TouchGFX Designerプロジェクト​

Note

生成された動作の変更​

TouchGFXHAL.cpp

プロジェクトのアップグレード​

.touchgfx

STM32F746 DISCOアプリケーション･テンプレートを使用した4.13.0から4.14.0へのアップグレード例

Note

Caution

TouchGFX Generatorの有効化

生成されるコードのアーキテクチャ

機能の概要

Display

インタフェースと寸法

フレームバッファのピクセル･フォーマット

Buffering Strategies

Driver

Application Tick Source

Graphics Accelerator

Real-Time Operating System

ThreadX

STM32CubeMXが提供するミドルウェア･リストからThreadXを有効にして設定する

AZRTOSソフトウェア･パックからThreadXを有効にして設定する

FreeRTOS

ThreadXミドルウェア

その他のCMSIS準拠OS

Additional features

External Data Reader

8bitLTDCカラー･ルックアップ･テーブル

Video Decoding

Type

Concurrent videos

Strategy

Decode Format

Buffer size

生成されるプロジェクト

TouchGFX Designerプロジェクト

生成された動作の変更

プロジェクトのアップグレード