Kanzi Engine のパフォーマンスを測定する¶

Profiling build を使用して、Kanzi Engine のさまざまな部分のパフォーマンスを測定します。このビルドには、プロファイルされた Kanzi ライブラリが含まれています。

Profiling build のパフォーマンスプロファイリングカテゴリ¶

Profiling build には、Kanzi Engine のさまざまな部分のパフォーマンスを測定するために使用できるパフォーマンスプロファイリングカテゴリとプロファイラが付属しています。

スタートアップ のパフォーマンスプロファイラーは、アプリケーションのスタートアップ中に Kanzi が使用する時間を測定します。

例えば、スタートアップパフォーマンスプロファイラを使用して、アプリケーションの初期化、スタートアップkzbファイルのオープン、プラグインのロードにかかる時間を測定します。

起動パフォーマンスプロファイリングカテゴリを参照してください。
メインループ プロファイラは、Kanzi がメインループで実行するタスクに使用される時間を測定します。これを使用して、アプリケーションのフレームレートに影響を与える要因を特定できます。

例えば、メインループプロファイラを使用して、入力イベントの処理、レイアウトの計算、アニメーションの実行、アプリケーションステートの更新、ノードのレンダリングにかかる時間を測定します。

メインループプロファイラーを参照してください。

起動パフォーマンスプロファイリングカテゴリ¶

起動パフォーマンスプロファイラーは、アプリケーションの起動中に Kanzi Engine が異なるタスクに費やす時間を測定します。起動パフォーマンスプロファイラーは StartupProfilerRegistry に登録されています。デフォルトで、すべての起動パフォーマンスプロファイリングカテゴリが有効になっています。アプリケーション設定でカテゴリの状態を設定するには、Configuration name を使用します。ProfilingCategoryFilter を参照してください。

この表は、Profiling build に含まれる Kanzi のスタートアップパフォーマンスプロファイリングカテゴリとプロファイラを一覧にしています。

カテゴリ (Category)	設定名	プロファイラ
アプリケーション初期化	`StartupInitialization`	`StartupProfilerRegistry::m_initializationProfiler`
デフォルトのリソース登録	`StartupRegisterDefaultResources`	`StartupProfilerRegistry::m_registerDefaultResourcesProfiler`
グラフィックスの初期化	`StartupInitializeGraphics`	`StartupProfilerRegistry::m_initializeGraphicsProfiler`
GL サブシステム初期化	`StartupInitializeGL`	`StartupProfilerRegistry::m_initializeGLProfiler`
スタートアップ kzb ファイルオープン	`StartupOpenKzb`	`StartupProfilerRegistry::m_openKzbProfiler`
ロードスレッド初期化	`StartupInitializeLoadingThreads`	`StartupProfilerRegistry::m_initializeLoadingThreadsProfiler`
メタデータ登録	`StartupRegisterMetadata`	`StartupProfilerRegistry::m_registerMetadataProfiler`
プラグインロード	`StartupLoadPlugins`	`StartupProfilerRegistry::m_loadPluginsProfiler`
プレハブロード	`StartupLoadPrefab`	`StartupProfilerRegistry::m_loadPrefabProfiler`
プレハブインスタンス化	`StartupInstantiatePrefab`	`StartupProfilerRegistry::m_instantiatePrefabProfiler`
プレハブ添付	`StartupAttachPrefab`	`StartupProfilerRegistry::m_attachPrefabProfiler`
レンダラーリセット	`StartupResetRenderer`	`StartupProfilerRegistry::m_resetRendererProfiler`
ランタイムアセット登録	`StartupRegisterRuntimeAssets`	`StartupProfilerRegistry::m_registerRuntimeAssetsProfiler`
ドメイン初期化	`StartupInitializeDomain`	`StartupProfilerRegistry::m_initializeDomainProfiler`
`Application::onProjectLoaded`	`StartupOnProjectLoaded`	`StartupProfilerRegistry::m_onProjectLoadedProfiler`
`Application::resumeGL`	`StartupResumeGL`	`StartupProfilerRegistry::m_resumeGLProfiler`

メインループプロファイラー¶

メインループプロファイラーは、Kanzi メインループの各イテレーションで Kanzi Engine が異なるタスクに費やす時間を測定します。アプリケーション設定に MainLoop カテゴリを追加することで、メインループプロファイラーを有効にできます。ProfilingCategoryFilter を参照してください。

メインループプロファイラには、メインループスケジューラインターフェース MainLoopScheduler::getProfiler を通じてアクセスできます。Application から Application::getMainLoopScheduler を使用してメインループスケジューラにアクセスできます。

Performance HUD では、メインループタスクのパフォーマンス測定グラフを表示できます。Performance HUD でパフォーマンス測定グラフを表示するを参照してください。

アプリケーション設定では、メインループのパフォーマンスプロファイラーでサンプルバッファサイズを設定できます。MainLoopProfilingSampleBufferCount を参照してください。

Performance HUD でパフォーマンス測定グラフを表示する¶

Profiling build の任意のメインループタスクに対して、アプリケーションコードに追加したカスタムタスクを含むパフォーマンスプロファイリンググラフを表示できます。

Performance HUD でパフォーマンス測定グラフを表示するには、

アプリケーション設定で、完全な Performance HUD の表示を有効にします。
- application.cfg で:
```
PerformanceInfoLevel = 2
```
- Application::onConfigure 関数内で：
```
configuration.performanceInfoLevel = ApplicationProperties::PerformanceInfoLevelFull;
```
アプリケーション開発と PerformanceInfoLevel を参照してください。
（オプション） Performance HUD のフォントサイズを設定できます。
- application.cfg で:
```
PerformanceInfoFontSize = 14
```
- Application::onConfigure 関数内で：
```
configuration.performanceInfoProperties.fontSize = 14;
```
PerformanceInfoFontSize を参照してください。
アプリケーション構成でメインループプロファイリングカテゴリを有効にします。
- application.cfg で:
```
ProfilingCategoryFilter="MainLoop=on"
```
- Application::onConfigure 関数内で：
```
configuration.profilingCategoryFilter = "MainLoop=on";
```
ProfilingCategoryFilter を参照してください。
アプリケーション構成で、表示したいタスクのグラフを有効にします。デフォルトのメインループタスクの名前については、Application::initializeMainLoopTasks の定義を参照してください。

例えば、タスク TickAnimations と Render のグラフを表示するには、次のように設定します:
- application.cfg で:
```
PerformanceInfoGraphFilter="TickAnimations;Render"
```
- Application::onConfigure 関数内で：
```
configuration.performanceInfoProperties.graphFilter = "TickAnimations;Render";
```
PerformanceInfoGraphFilter を参照してください。
（オプション） Set the colors that Kanzi uses to draw the Performance HUD:
1. 色を設定したいファイルで、Visual Studio で performance_info.hpp ヘッダーファイルをインクルードします。
  
  たとえば、Kanzi がスクロールビューの例の Performance HUD の描画に使用する色を設定するには、scroll_view.cpp ファイルに以下を追加します。
```
#include <kanzi/core.ui/application/performance_info.hpp>
```
2. Kanzi が Performance HUD のグラフフレーム、グラフデータ、テキストを表示するために使用する色を設定します。
  
  例えば、scroll_view.cpp ファイルの Application::onProjectLoaded 関数に以下を追加します。
```
// Get the performanceInfo object. If the object does not exist, create it.
PerformanceInfo& performanceInfo = acquirePerformanceInfo();
// Set the color of graph frames to gray.
performanceInfo.setBorderColor(ColorRGBA(0.5f, 0.5f, 0.5f));
// Set the color of graph data to yellow.
performanceInfo.setLineColor(ColorRGBA(1.0f, 1.0f, 0.0f));
// Set the color of text to black.
performanceInfo.setFontColor(ColorRGBA(0.0f, 0.0f, 0.0f));
```
アプリケーションをビルドして実行します。Kanzi アプリケーションのデプロイを参照してください。

パフォーマンスグラフを表示するには、Kanzi の Profiling build を使用する必要があります。

例えば、Windowsでは、Profiling ビルド構成を使用して Visual Studio でアプリケーションをビルドします。

アプリケーションを実行すると、Performance HUD がパフォーマンス測定グラフを表示します。

グラフが表示されない場合は、アプリケーションウィンドウを大きくしてください。

../../_images/main-loop-rendering-and-layout-in-hud.png

Kanzi Engine のパフォーマンスプロファイリングデータをログに記録する¶

Kanzi Engine のパフォーマンスを分析するために、パフォーマンスプロファイリングデータをログに記録します。

起動パフォーマンス情報のログ記録¶

Profiling build の Kanzi スタートアップパフォーマンスプロファイラを使用して、アプリケーションのスタートアップ中に Kanzi Engine が異なるタスクに費やす時間を測定できます。起動パフォーマンスプロファイリングカテゴリを参照してください。

起動パフォーマンス情報を記録するには、Profiling build 構成を使用してアプリケーションをビルドしてください。

たとえば、Windows でアプリケーションをビルドして実行するには:

Visual Studioで、Profiling ビルド構成を使用してアプリケーションをビルドします。
コンピュータでコマンドラインを開き、アプリケーションを実行して、パフォーマンス測定データを保存したいファイルにアプリケーションの出力を送るようにします。
```
<MyProject>\Application\bin> ..\build_vs<Version>\runtime\Profiling\MyApplication.exe > MyApplicationProfiling.log
```

Kanzi は、起動パフォーマンス測定情報をログに書き込みます。

...
info:profiling> Startup profiling:
info:profiling> StartupInitialization                        335 981 800 ns
info:profiling> |-- StartupInitializeGraphics                304 665 900 ns
info:profiling> |-- StartupCreateDomain                        1 450 500 ns
info:profiling> |-- StartupInitializeLoadingThreads           26 921 700 ns
info:profiling> |-- StartupRegisterRuntimeAssets                 122 800 ns
info:profiling> |-- StartupLoadPlugins                               200 ns
info:profiling> |-- StartupRegisterMetadata                      776 100 ns
info:profiling> |-- StartupOpenKzb                             1 106 000 ns
info:profiling> StartupInitializeGL                                  100 ns
info:profiling> StartupResumeGL                                1 316 800 ns
info:profiling> StartupLoadPrefab                            808 960 000 ns
info:profiling> StartupInstantiatePrefab                       1 351 700 ns
info:profiling> StartupRegisterDefaultResources                   17 400 ns
info:profiling> StartupAttachPrefab                           16 614 700 ns
info:profiling> StartupResetRenderer                              59 700 ns
info:profiling> StartupOnProjectLoaded                            38 600 ns
info:profiling> Startup profiling data logging took   1 712 800 ns
...

プロファイラからのデータをログに記録する¶

特定のプロファイラからデータをログに記録できます。

プロファイラからすべてのデータサンプルをログに記録するには、AbstractProfiler::logAllData 関数を使用します。

例えば、メインループプロファイラからすべてのデータをログに記録するには、次のように使用します。
```
getMainLoopScheduler().getProfiler()->logAllData();
```
プロファイラからデータのサマリーを記録するには、AbstractProfiler::logAggregateData 関数を使用します。すべてのプロファイラが集計ログを実装しているわけではないことに注意してください。

例えば、StartupProfilerRegistry の StartupProfilerRegistry::m_initializationProfiler からデータの概要を記録するには、次を使用します。
```
getStartupProfilerRegistry().m_initializationProfiler->logAggregateData();
```

プロファイラーレジストリからデータをログに記録する¶

特定のプロファイラーレジストリに登録されているすべてのプロファイラーからデータを記録するには、プロファイラーを反復処理し、AbstractProfiler::logAggregateData または AbstractProfiler::logAllData 関数を呼び出します。

例えば、アプリケーションを終了する際にカスタムプロファイラからパフォーマンスプロファイリングデータのサマリーをログに記録するには、次のようにします。

// Kanzi calls this function when the application exits.
void onShutdown() override
{
    // Get the default profiler registry.
    const auto& registry = kzProfilingGetDefaultRegistry();

    // Go through all profilers in the registry and log their aggregate data.
    for (auto profilerIter = registry.beginProfilers(),
        profilerIterEnd = registry.endProfilers();
        profilerIter != profilerIterEnd; ++profilerIter)
    {
        (*profilerIter)->logAggregateData();
    }
}