アーキテクチャ概要（全体像） - zeux/microprofile

システムアーキテクチャ概要

microprofile は、計測対象アプリケーションに直接組み込んで使用するインプロセス型プロファイラである。外部サーバーや専用エージェントを必要とせず、計測、データ収集、可視化の全機能が単一ライブラリ内で完結する設計となっている。

正在加载图表渲染器...

アーキテクチャ構成要素の説明

インストルメンテーション層: MICROPROFILE_SCOPE 等のマクロを通じて、ユーザーコード内の計測ポイントを定義する。これらのマクロは、スコープの開始・終了時に自動的にタイミングデータを記録する（microprofile.h:39-74）。
タイマー管理: CPU と GPU のタイミング計測を統一的に管理する。MicroProfileEnter/MicroProfileLeave 等の API は、対象が CPU か GPU かを自動判別する（README.md:42-43）。
GPU バックエンド: 複数のグラフィックス API（OpenGL、D3D11、D3D12、Vulkan）に対応し、コンパイル時に任意の組み合わせを選択可能。実行時に単一のバックエンドを動的に初期化できる柔軟な設計となっている（README.md:45-47）。
可視化層: 収集したプロファイリングデータを、インゲーム UI または Web ブラウザ経由で表示する。両者は統一された命名規則と情報表示を共有する（README.md:38-40）。

対応プラットフォームと GPU バックエンドの柔軟性

microprofile は、Windows XP 以降、Linux、OSX、iOS、Android、Xbox One といった幅広いプラットフォームで動作実績がある。他プラットフォームへの移植も容易な設計となっており、プラットフォーム固有の依存部分が最小限に抑えられている（README.md:20-25）。

GPU タイミング計測に関しては、D3D11、D3D12、OpenGL、Vulkan の主要グラフィックス API をサポートする。これらのバックエンドは、コンパイル時に任意の組み合わせを有効化でき、実行時に初期化するバックエンドを動的に選択可能である。これにより、単一のバイナリで複数のレンダリングパスに対応できる（README.md:45-47）。

GPU バックエンド初期化フロー

各 GPU バックエンドの初期化は、対応する MicroProfileGpuInit* 関数を呼び出すことで行う。D3D12 および Vulkan では、マルチスレッド環境でのコマンドリスト使用に対応しており、MicroProfileGpuBegin、MicroProfileGpuEnd、MicroProfileGpuSubmit という明示的なライフサイクル管理が提供されている（microprofile.h:96-110）。

コア API とインストルメンテーション構造

計測マクロの分類

計測用マクロは、宣言・定義用とスコープベースの計測用に分類される。

マクロ名	用途	使用場所
`MICROPROFILE_DECLARE`	タイマーの外部宣言	ヘッダファイル
`MICROPROFILE_DEFINE`	タイマーの定義	ソースファイル（グローバルスコープ）
`MICROPROFILE_DECLARE_GPU`	GPU タイマーの外部宣言	ヘッダファイル
`MICROPROFILE_DEFINE_GPU`	GPU タイマーの定義	ソースファイル（グローバルスコープ）
`MICROPROFILE_SCOPE`	定義済みタイマーでのスコープ計測	関数内
`MICROPROFILE_SCOPEI`	インライン定義でのスコープ計測	関数内
`MICROPROFILE_SCOPEGPU`	定義済み GPU タイマーでのスコープ計測	関数内
`MICROPROFILE_SCOPEGPUI`	インライン定義での GPU スコープ計測	関数内
`MICROPROFILE_META`	メタデータの追加	スコープ内
`MICROPROFILE_LABEL`	文字列ラベルの追加	スコープ内
`MICROPROFILE_LABELF`	printf 形式のフォーマット付きラベル	スコープ内

（microprofile.h:39-52）

スコープベース計測の実行フロー

正在加载图表渲染器...

スコープ計測の詳細動作

MICROPROFILE_SCOPEI マクロは、グループ名、タイマー名、色（RGB 値または -1 で自動選択）を引数に取り、スコープの開始時に MicroProfileEnter を、終了時に MicroProfileLeave を自動的に呼び出す。これにより、RAII パターンによる例外安全な計測が実現されている（microprofile.h:55-70）。

色に -1 を指定した場合、スコープ名のハッシュ値に基づいて自動的に色が選択される。これにより、手動での色管理を省略しつつ、一貫した視覚的識別が可能となる（README.md:41-42）。

必須実装インターフェース

microprofile を動作させるためには、いくつかの外部関数をホストアプリケーション側で実装する必要がある。これらは、デバッグ描画、GPU タイムスタンプ取得、スレッド情報の提供に関するインターフェースである（microprofile.h:75-86）。

デバッグ描画関数

インゲーム UI を表示するために、以下の描画関数の実装が必須となる：

関数名	責務	パラメータ
`MicroProfileDrawText`	テキスト描画	座標、色、テキスト、文字数
`MicroProfileDrawBox`	矩形描画	座標、色、ボックスタイプ
`MicroProfileDrawLine2D`	2D 線分描画	頂点数、頂点配列、色

（microprofile.h:77-79）

GPU タイムスタンプ関数

GPU プロファイリングを行うには、以下の 3 関数の実装が必要である：

MicroProfileGpuInsertTimer: GPU コマンドストリームにタイムスタンプクエリを挿入
MicroProfileGpuGetTimeStamp: クエリ結果からタイムスタンプ値を取得
MicroProfileTicksPerSecondGpu: GPU タイマーの周波数を返す

（microprofile.h:81-83）

デフォルト GPU バックエンド実装

主要グラフィックス API については、デフォルト実装が提供されている。これらを有効にするには、MICROPROFILE_IMPL を定義するソースファイル内で対応するマクロ（MICROPROFILE_GPU_TIMERS_GL、MICROPROFILE_GPU_TIMERS_D3D11 等）を 1 に定義し、適切な初期化関数を呼び出す（microprofile.h:87-110）。

モジュール依存関係

正在加载图表渲染器...

依存関係のポイント

プラットフォーム抽象化: 時刻取得やスレッド管理などのプラットフォーム固有機能は、抽象化されたインターフェースを通じて利用される。これにより、新規プラットフォームへの移植が容易になっている。
描画バックエンドの分離: インゲーム UI の描画は、ホストアプリケーションが提供するプリミティブな描画関数上に構築される。これにより、任意のレンダリングエンジンとの統合が可能である（microprofile.h:77-79）。
GPU バックエンドの選択的リンク: GPU タイミング機能は、使用するグラフィックス API に応じたバックエンド実装とリンクされる。複数バックエンドをコンパイルしておき、実行時に一つを選択する構成が可能である（README.md:45-47）。

主要設計上の決定事項

CPU/GPU 統合スコープ API

本フォーク版の特徴として、MicroProfileEnter/MicroProfileLeave 等の API が、対象グループが CPU か GPU かを自動判別する点が挙げられる。これにより、開発者は計測対象の種類を意識せずに統一された API を使用できる（README.md:42-43）。

動的 GPU バックエンド選択

GPU バックエンドをコンパイル時に複数組み込んでおき、実行時に初期化するバックエンドを動的に決定できる。この設計により、単一のバイナリで異なるグラフィックス API を使用する複数のレンダリングパスに対応できる（README.md:45-47）。

遅延バッファ割り当て

プロファイラのメモリオーバーヘッドを削減するため、計測グループがアクティブでない場合、大部分のバッファが遅延割り当てされる。これにより、プロファイラが有効でもデータ収集を行っていない状態でのメモリ消費が抑制される（README.md:48-49）。

統一された UI 命名規則

インゲーム UI と Web UI で、同じ情報を同じ名称で一貫して表示する。これにより、どちらの可視化手段を使用しても、学習コストなしに同じ情報にアクセスできる（README.md:38-40）。

本番環境での有効化に対応した堅牢性

エッジケース、オーバーフロー条件、GPU タイミングの問題などに対する堅牢性向上の修正が含まれており、本番ビルドでの有効化も安全に行えるよう設計されている（README.md:48）。

技術選択の根拠

技術・設計	用途	選択理由	代替案との比較
ヘッダオンリライブラリ	統合の簡素化	ソースファイル 1 つで実装完了、ビルドシステムへの影響最小	静的ライブラリ：リンク設定が必要
マクロベース計測	計測ポイント定義	最小限の記述でスコープ計測、RAII による例外安全	関数呼び出し：開始/終了の対応管理が必要
統合 CPU/GPU API	API の簡素化	種別を意識しない統一インターフェース	分離 API：種別ごとの関数呼び分けが必要
動的バックエンド選択	マルチ API 対応	実行時までバックエンド決定を遅延可能	静的リンク：API ごとにビルドが必要
インゲーム UI	リアルタイム確認	コンテキスト切り替えなしでプロファイリング可能	外部ツールのみ：アプリ切り替えが必要
Web サーバー	詳細分析	ブラウザの機能を活用したリッチな可視化	ファイル出力のみ：リアルタイム性が低下
遅延割り当て	メモリ効率	非アクティブ時のオーバーヘッド削減	事前割り当て：常に最大メモリを消費
プラットフォーム抽象化	移植性	新規プラットフォーム対応が容易	直接 API 呼び出し：移植時に広範囲の修正が必要

既知の制限事項

GPU タイムスタンプのスレッド制約

GPU タイムスタンプの挿入は、単一スレッドからのみ行うことができる。これは、多くのグラフィックス API におけるコマンドバッファのスレッド安全性制約に由来する（microprofile.h:112-114）。

カテゴリ数の上限

本フォーク版では、最大 48 カテゴリまでのサポートに制限されている。アップストリーム版と比較した際の機能差の一つである（README.md:33-34）。

アップストリームとの機能差異

本フォーク版には、アップストリーム版に存在する WebSocket ベースのライブ接続機能や、長時間実行コード（レベル読み込み等）のプロファイリングに有用なタイムライン機能が含まれていない。一方で、インゲーム UI サポートや動的文字列ラベル等の独自機能拡張が行われている（README.md:30-50）。