Xiamocon アプリケーションの基本構造
################################################################################

Xiamocon アプリケーションは 4 つの関数から構成されます。

.. csv-table:: Xiamocon アプリケーションの関数
   :header: "関数", "説明"

   "xmcAppGetConfig", "アプリケーションのコンフィグレーション情報を返す関数"
   "xmcAppSetup", "アプリケーションのセットアップを行う関数。"
   "xmcAppLoop", "アプリケーションのメインループ関数。"
   "xmcAppTerminate", "アプリケーションの終了処理を行う関数。"

xmcAppGetConfig
================================================================================

プロトタイプ宣言:

.. code-block:: c++

    xmc::AppConfig xmcAppGetConfig(void)

xmcAppGetConfig 関数は、アプリケーションのコンフィグレーション情報を返す関数です。
xmc::AppConfig 構造体には、システムを初期化するための基本的なコンフィグレーション情報が含まれます。

通常は getDefaultAppConfig() 関数を使用してデフォルトのコンフィグレーションを取得し、必要に応じて値を変更してから返します。

.. csv-table:: xmc::AppConfig のメンバー
   :header: "型","メンバー", "説明"

   "xmc::PixelFormat","displayPixelFormat", "ディスプレイのピクセルフォーマットを指定する列挙型。"
   "bool","speakerEnabled", "スピーカーの有効/無効を指定するブール値。"
   "xmc::audio::SampleFormat","speakerSampleFormat", "スピーカーのサンプルフォーマットを指定する列挙型。"
   "uint32_t","speakerSampleRateHz", "スピーカーのサンプルレートを指定する整数。"
   "uint32_t","speakerLatencySamples", "スピーカーのレイテンシをサンプル単位で指定する整数。"

全てのコンフィグレーションをデフォルト値のまま使用する場合は、xmcAppGetConfig 関数の定義は省略することができます。

displayPixelFormat
--------------------------------------------------------------------------------

ディスプレイのピクセルフォーマットを xmc::PixelFormat 列挙型で指定します。Xiamocon SDK では、現在のところ次のピクセルフォーマットがサポートされます。

.. csv-table:: xmc::PixelFormat 列挙型の値
   :header: "値", "説明"

   "xmc::PixelFormat::RGB444", "12 ビット RGB フォーマット。赤、緑、青がそれぞれ 4 ビットで表されます。"
   "xmc::PixelFormat::RGB565 (デフォルト)", "16 ビット RGB フォーマット。赤が 5 ビット、緑が 6 ビット、青が 5 ビットで表されます。"   

RGB444 フォーマットはメモリの使用量抑制とディスプレイ更新速度の向上に貢献しますが、
ピクセル処理が複雑になるため、レンダリングのパフォーマンスが低下する可能性があります。

speakerEnabled
--------------------------------------------------------------------------------

スピーカーの有効/無効を指定するブール値です。
true の場合、プラットフォーム側のオーディオ出力機能が有効になります。

プラットフォーム側の機能を使用せず独自にオーディオ出力を実装する場合は false を指定します。

speakerSampleFormat
--------------------------------------------------------------------------------

スピーカーのサンプルフォーマットを xmc::audio::SampleFormat 列挙型で指定します。
Xiamocon SDK では、現在のところ次のサンプルフォーマットがサポートされます。

.. csv-table:: xmc::audio::SampleFormat 列挙型の値
   :header: "値", "説明"

   "xmc::audio::SampleFormat::LINEAR_PCM_U8_MONO", "8 ビット符号なし整数フォーマット。"
   "xmc::audio::SampleFormat::LINEAR_PCM_S16_MONO (デフォルト)", "16 ビット符号付き整数フォーマット。"

LINEAR_PCM_U8_MONO フォーマットは使用するメモリは少なくなりますが、
プラットフォーム側で 16 ビット符号付きへ変換されるため、若干のパフォーマンス上のオーバーヘッドがあります。

speakerSampleRateHz
--------------------------------------------------------------------------------

スピーカーのサンプリングレートを指定します。単位はヘルツ (Hz) です。

基本的にこの値は変更しないで下さい。
サンプリングレートはプラットフォーム側の PDM 変換処理と密接に関係するため、
この値を変更するとオーディオ出力が正常に行えなくなったり、ノイズが発生する可能性があります。

RP2350 では 20.833 kHz、ESP32S3 では 24 kHz がデフォルトで使用されます。

speakerLatencySamples
--------------------------------------------------------------------------------

スピーカーのレイテンシをサンプル数で指定します。

この値を小さくするとレイテンシが小さくなりますが、
グラフィックス処理等でシステムに負荷がかかると音が途切れやすくなります。

デフォルトでは 1024 サンプルが使用されます。

xmcAppSetup
================================================================================

プロトタイプ宣言:

.. code-block:: c++

   void xmcAppSetup(void)

xmcAppSetup 関数は、アプリケーションのセットアップを行う関数です。
この関数内で各種リソースの確保や外部デバイスの初期化などを行います。

戻り値はありません。

この関数内で行う処理が何も無い場合は、関数の定義を省略することができます。

xmcAppLoop
================================================================================

プロトタイプ宣言:

.. code-block:: c++

   void xmcAppLoop(void)

xmcAppLoop 関数は、アプリケーションのメインループ関数です。
この関数は、アプリケーションが実行されている間、繰り返し呼び出されます。

キーパッドの入力処理、オーディオ出力の維持、バッテリー監視などは
プラットフォーム側で行われるため、この関数内で行う必要はありません。

この関数内では、アプリケーションのロジックやグラフィックス処理などを実装します。

戻り値はありません。

xmcAppTerminate
================================================================================

プロトタイプ宣言:

.. code-block:: c++

   XmcStatus xmcAppTerminate(xmc::system::ShutdownReason reason)

xmcAppTerminate 関数は、アプリケーションの終了処理を行う関数です。

`reason` には終了要求の理由が渡されます。
理由の種類は `xmc::system::ShutdownReason` 列挙型で表されます。

.. csv-table:: xmc::system::ShutdownReason の値
   :header: "値", "説明"

   "xmc::system::ShutdownReason::POWER_SWITCH", "電源ボタン操作による終了要求"
   "xmc::system::ShutdownReason::LOW_BATTERY", "低電圧検知による終了要求"
   "xmc::system::ShutdownReason::REQUESTED_BY_APPLICATION", "アプリケーションからの終了要求"

システムが電源ボタンが押されたことを検知するとこの関数が呼び出されます。
この関数内で、確保したリソースの解放や外部デバイスの終了処理などを行います。

この関数が XMC_OK を返すとシステムの電源が切れます。

XMC_OK 以外を返すことでシャットダウンをキャンセルすることができますが、
I/O 処理など、どうしても中断できない処理を行っている場合に限るべきです。

この関数内で行うことが何も無く、単に XMC_OK を返すだけの場合は、関数の定義を省略することができます。