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]ボタンを押すことで、追加機能にアクセスできます。
次の図は、プロジェクトに対してTouchGFX Generatorを有効化する方法を示しています。
デュアル・コアのマイクロコントローラに対してTouchGFXを有効化する場合には、正しいコンテキストで有効化するようにしてください。 TouchGFXは単一コンテキストでのみ有効化できます。
生成されるコードのアーキテクチャ
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 - このグループでは、ハードウェアまたはソフトウェアのビデオ・デコーディングをユーザが有効化できます。 このオプションはビデオ・ウィジェットと併用する必要があります。 なお、すべてのマイクロコントローラがビデオ・デコーディングに対応しているわけではありません。
Display
Displayグループには、ディスプレイに関連する設定(インタフェース、寸法、バッファリング戦略など)が含まれます。
インタフェースと寸法
現在、STM32マイクロコントローラでは、次に示すような複数のディスプレイ・インタフェースを使用できます。
- パラレルRGB(LTDC)
- MIPI DSI
- FMC
- SPI
ディスプレイがLTDCまたはFMCに接続されたマイクロコントローラの場合、TouchGFX Generatorは、接続されたディスプレイにフレームバッファを転送するためのコードを生成できます。 DSIおよびSPIインタフェースのドライバは、開発者自身で実装する必要があります。
Further reading
フレームバッファのピクセル・フォーマット
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
Caution
Further reading
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によってドライバが生成されるので、開発者によるアクションは必要ありません。
TouchGFX Generatorから提供されるChrom-ART(DMA2D)ドライバは、TransferCompleteInterruptの受信方法として次の2つをサポートしています。
- TM32Cube HALドライバを使用して、dma2dハンドラにコールバック関数
hdma2d.XferCpltCallback
を登録する。 DMA2D_IRQHandler()
割込みハンドラを直接使用する。
この2つの方法を切り替えるには、DMA2D IP用のSTM32CubeMXのNVIC設定で、DMA2Dグローバル割込みを有効化 / 無効化します。 グローバル割込みを有効化するとオプション1のコードが生成され、グローバル割込みを無効化するとオプション2のコードが生成されます。
Note
- GPU2D(NeoChrom)はグラフィックス・アクセラレータで、TouchGFXにおいてテクスチャ・マッピングを含む多くの描画操作を加速させます。 これは、RGB565、RGB888、ARGB8888フォーマットのフレームバッファをサポートします。
Caution
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
次の図は、TouchGFX Generatorを通して使用可能なオプションを示しています。
Note
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に設定します。
Caution
- 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を安全に閉じることができます。
- 左側のCategoriesリストからSoftware Packsグループを選択し、STMicroelectonics.X-CUBE-AZRTOS-XXを選択します。
- RTOS ThreadXモードを選択することで、ThreadXを有効にします。
Memory Pool Allocation
をUse Static Allocationに設定します。
TX_TIMER_TICKS_PER_SECOND
を1000に設定して、1ミリ秒ごとにティックを取得します。
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
その他の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]グループが使用可能になります。
開発者は以下の設定を行うことができます。
- 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
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]の両方がグレー表示になります。 マウスをグレー表示されているオプションに合わせ、必要なペリフェラルを確認します。
- Software - STM32CubeMXの[Middleware]セクションでLIBJPEGが有効になっている場合は、[Sotware]オプションを選択すると、ソフトウェア・デコーダが生成されます。 これはつまり、ToughGFX GeneratorによってソフトウェアMJPEGデコーダが生成されるということです。
- Hardware - JPEGが[Multimedia]セクションで有効になっており、CMSIS準拠のRTOSがTouchGFX Generatorで選択されている場合は、[Hardware]オプションを選択できます。
LIBJPEG設定では、効率化のために、[RGB scanline format]セクションでRGB順序を「RGB」ではなく「BGR」に設定する必要があります。 ピクセル当たりのバイト数は3に設定します。
ハードウェア・デコーディングを使用する場合、JPEG設定のRGBフォーマットはディスプレイと同じにする必要があります。
Further reading
Concurrent videos
[Concurrent Videos]オプションは任意の時点でGUIの同じ画面で同時にデコードされるビデオの最大量を指定します。 画面上で1つのビデオをデコードする場合にのみ、[Number of Videos]を1に設定できます。
最大で4つのビデオを同時にデコードできます。
Strategy
ビデオ・デコーディング方式に関して、開発者には次の3つのオプションがあります。
- Direct to Framebuffer - ビデオはUIスレッドでデコードされます。 これは、他の方式よりも時間がかかります。 ハードウェア・ビデオ・デコーディングを使用する場合、[Direct to Framebuffer]オプションは使用できません。
- Single Buffer - ビデオは1つの専用バッファと1つの専用タスクでデコードされます。 このバッファは内部メモリに割り当てられます。
- Double Buffer - ビデオは2つの専用バッファと1つの専用タスクでデコードされます。これは多くのメモリを必要としますが、パフォーマンスは向上します。
シングルまたはダブル・フレームバッファ方式を採用する場合、CMSIS準拠のOSを有効化する必要があります。
Note
Further reading
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のみ)
STM32CubeMXは以下の構造を持つ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をロードするのか、空のテンプレートから開始するのかを選択するオプションが表示されます。
TouchGFX Designerで[Generate Code]を押すと、TouchGFXフォルダの構造は以下のようになります。 下の画像は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
生成された動作の変更
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_
が付いた状態で、元のファイルと同じ場所に配置されます