クイックスタート - zeux/microprofile

概要と特徴

microprofileは、Jonas Meyer氏によるオリジナル版からフォークした埋め込み可能なCPU/GPUプロファイラであり、インゲームUI、Webブラウザ（内蔵サーバー経由）、またはHTMLファイルとしてプロファイリング結果を可視化できる（README.md:1-22）。主な特徴として、階層的なリージョンによるコードセクションのタイミング計測、文字列形式のラベル機能、D3D11/D3D12/OpenGL/Vulkanに対応したGPUリージョン計測、リアルタイムグラフ表示などが挙げられる。

このフォーク版は、オリジナルのupstream版にはない独自の機能拡張を含んでいる。具体的には、OpenGLまたは他のレンダリングバックエンドを使用したオンスクリーンUIサポート、動的文字列（ラベル）のサポート、スコープ名のハッシュに基づく自動色選択、統一されたCPU/GPUスコープAPIなどが提供されている（README.md:36-51）。また、iOSおよびAndroidプラットフォームにも対応しており、本番環境での使用に適した堅牢性を備えている。

環境要件

対応プラットフォーム

microprofileは、Windows XP以降、Linux、OSX、iOS、Android、Xbox Oneで動作確認されている（README.md:20-24）。他のプラットフォームへの移植も比較的容易であり、プルリクエストが歓迎されている。

依存ライブラリ

デモアプリケーションをビルドするには、SDL2ライブラリが必要である（demo/README:1-6）。各プラットフォームでの要件は以下の通りである：

プラットフォーム	要件
Windows	SDL2（demo/sdl2サブフォルダに配置）、premake4
OSX	SDL2（sdl2-configが利用可能な状態でコンパイル・インストール済み）
Linux	SDL2、OpenGL

コンパイラ要件

LinuxおよびOSX環境では、C++11対応のコンパイラが必要である。Makefileでは-std=c++11フラグが指定されている（demo/ui/Makefile:15-18）。また、Clangコンパイラの使用を前提とした設定が含まれている。

インストール手順

HTMLリソースの埋め込み

microprofileのWeb UI機能を使用するには、まずHTMLリソースをヘッダファイルとして埋め込む必要がある。src/Makefileには、この埋め込み処理を自動化するルールが定義されている（src/Makefile:12-24）。

Linux/OSXの場合：

bash
1cd src
2make ../microprofilehtml.h

このコマンドは、embed.oツールを使用してmicroprofile.htmlを../microprofilehtml.hに変換する。生成されるヘッダファイルには、HTMLコンテンツがC言語の文字列配列として埋め込まれる（src/embed.c:66-80）。

Windowsの場合：

Windows環境では、demo/embed.batスクリプトを使用して埋め込み処理を実行できる（demo/embed.bat:1-4）：

batch
1cd demo
2embed.bat

デモアプリケーションのビルド

推奨パス：UI付きデモ（Linux/OSX）

UI付きデモをビルドする場合、以下のコマンドを実行する：

bash
1cd demo/ui
2make embed_target  # HTMLリソースの埋め込み
3make               # デモのビルド

embed_targetターゲットは、../../srcディレクトリでmakeを実行し、HTML埋め込みヘッダを生成する（demo/ui/Makefile:50-56）。または、make embedを実行すると、埋め込みとビルドを一度に行える。

代替パス：UIなしデモ

UIを無効化した軽量版デモをビルドする場合：

bash
1cd demo/noui
2make

UIなし版では、MICROPROFILE_UI=0およびMICROPROFILE_GPU_TIMERS=0がコンパイルフラグとして設定されている（demo/noui/Makefile:9-14）。これにより、OpenGL依存を排除した構成でビルド可能である。

Windows（Visual Studio）の場合

Visual Studio 2015以降を使用する場合、demo/demo.slnソリューションファイルを開き、noui_d3d11プロジェクトをビルドする（demo/demo.sln:1-28）。Debug/Release、x86/x64の各構成がサポートされている。

ビルド構成の比較

構成	UI	Webサーバー	GPUタイマー	用途
`demo/ui`	有効	有効	有効	フル機能確認・開発
`demo/noui`	無効	有効	無効	サーバー専用・軽量環境
`noui_d3d11`	無効	（要確認）	D3D11	Windowsネイティブ

最短実行パス

最も迅速にmicroprofileの動作を確認するには、以下の手順を実行する：

bash
1# 1. リポジトリをクローン
2git clone https://github.com/zeux/microprofile.git
3cd microprofile
4
5# 2. UIなしデモをビルド（SDL2不要、最も依存が少ない）
6cd demo/noui
7make
8
9# 3. デモを実行
10./demo_noui

この構成では、UI機能とGPUタイマーが無効化されているため、SDL2やOpenGLの依存なしでビルド・実行可能である（demo/noui/Makefile:9-14）。Webサーバー機能は有効なため、ブラウザ経由でプロファイリング結果を確認できる。

実行検証

デモアプリケーションの動作確認

デモアプリケーションが正常にビルド・実行された場合、以下の要素が機能していることを確認できる：

スレッド初期化: MicroProfileOnThreadCreate("Main")により、メインスレッドがプロファイラに登録される（src/test_gl.cpp:24-28）
スコープ計測: MICROPROFILE_SCOPEIマクロにより、CPUスコープの計測が開始される（src/test_gl.cpp:30-36）
フレームフリップ: MicroProfileFlip()により、フレームデータが処理される（src/test_gl.cpp:38）

Webサーバーへのアクセス

MICROPROFILE_WEBSERVER=1が設定されている場合、内蔵Webサーバーが起動する（demo/ui/Makefile:11-12）。ブラウザで所定のポートにアクセスすることで、プロファイリング結果をリアルタイムで確認できる。

注意: デフォルトのポート番号は、提供されたソースファイルからは確認できない。microprofile.hヘッダファイル内のMICROPROFILE_WEBSERVER_PORT定義を確認する必要がある（要確認）。

基本的なAPIの使用例

microprofileの基本的な使用パターンは、src/test_gl.cppに示されている（src/test_gl.cpp:24-43）。以下に、典型的な初期化から終了までの流れを示す：

初期化とスレッド登録

cpp
1#define MICROPROFILE_IMPL
2#define MICROPROFILEUI_IMPL
3#define MICROPROFILEDRAW_IMPL
4#include "microprofile.h"
5#include "microprofileui.h"
6#include "microprofiledraw.h"
7
8int main()
9{
10    MicroProfileSetForceEnable(true);
11    MicroProfileOnThreadCreate("Main");

MICROPROFILE_IMPLなどの定義は、ヘッダオンリーライブラリの実体を生成するために必要である（src/test_gl.cpp:14-22）。

スコープ計測

cpp
1    {
2        MICROPROFILE_SCOPEI("Group", "Name", -1);
3        MICROPROFILE_SCOPEGPUI("NameGpu", -1);
4        
5        MICROPROFILE_LABEL("Group", "Label");
6        MICROPROFILE_LABELF("Group", "Label %d", 5);
7    }

MICROPROFILE_SCOPEI: CPUスコープの計測を開始する。第1引数はグループ名、第2引数はスコープ名、第3引数は色（-1で自動選択）
MICROPROFILE_SCOPEGPUI: GPUスコープの計測を開始する
MICROPROFILE_LABEL: 文字列ラベルを追加する
MICROPROFILE_LABELF: printf形式のラベルを追加する

フレーム処理と終了

cpp
1    MicroProfileFlip();
2    MicroProfileDraw(128, 64);
3    MicroProfileOnThreadExit();
4}

MicroProfileFlip()は各フレームの終了時に呼び出し、プロファイリングデータを処理する（src/test_gl.cpp:38）。MicroProfileDraw()はオンスクリーンUIを描画する（UI有効時のみ）。

設定オプション

microprofileの機能は、コンパイル時のマクロ定義によって制御できる。主な設定オプションを以下に示す：

マクロ	説明	デフォルト
`MICROPROFILE_UI`	オンスクリーンUIの有効/無効	1（有効）
`MICROPROFILE_WEBSERVER`	Webサーバーの有効/無効	1（有効）
`MICROPROFILE_GPU_TIMERS`	GPUタイマーの有効/無効	1（有効）
`MICROPROFILE_GPU_TIMERS_GL`	OpenGL GPUタイマーの有効/無効	0（無効）
`MICROPROFILE_ENABLED`	プロファイラ全体の有効/無効	1（有効）

UI有効時の設定例

demo/ui/Makefileでは、以下のコンパイルフラグが設定されている（demo/ui/Makefile:9-15）：

makefile
1CFLAGS+=-Wall -DMICROPROFILE_UI=1 
2CFLAGS+=-DMICROPROFILE_WEBSERVER=1
3CFLAGS+=-g -O0 -Wno-invalid-offsetof

UI無効時の設定例

demo/noui/Makefileでは、UIとGPUタイマーを無効化し、Webサーバーのみを有効にしている（demo/noui/Makefile:9-14）：

makefile
1CFLAGS+=-Wall -DMICROPROFILE_UI=0 -DMICROPROFILE_WEBSERVER=1 -DMICROPROFILE_GPU_TIMERS=0
2CFLAGS+=-g -O0 -Wno-invalid-offsetof -Wall -Werror

この構成は、ヘッドレスサーバー環境や、OpenGLコンテキストが利用できない環境での使用に適している。

よくある問題とトラブルシューティング

1. SDL2が見つからない

症状: sdl2-config: command not foundまたは同様のエラーが発生する。

原因: SDL2ライブラリがインストールされていない、またはパスが通っていない。

解決策:

OSX: brew install sdl2でインストール
Linux: パッケージマネージャーでlibsdl2-devをインストール
Windows: demo/sdl2サブフォルダにSDL2を配置（demo/README:1-6）

2. HTML埋め込みヘッダが生成されない

症状: microprofilehtml.h: No such file or directoryエラーが発生する。

原因: HTMLリソースの埋め込み処理が実行されていない。

解決策: デモをビルドする前に、make embed_targetまたはmake embedを実行する（demo/ui/Makefile:50-56）。または、srcディレクトリで直接make ../microprofilehtml.hを実行する（src/Makefile:12-24）。

3. OpenGLリンクエラー

症状: undefined reference to glQueryCounterなどのリンクエラーが発生する。

原因: OpenGLライブラリがリンクされていない、またはGPUタイマー機能が無効な環境でGL関数を参照している。

解決策:

Linux: Makefileに-lGLが含まれていることを確認（src/Makefile:6-10）
OSX: -framework OpenGLが設定されていることを確認
代替案: MICROPROFILE_GPU_TIMERS=0を設定してGPUタイマーを無効化（demo/noui/Makefile:9-14）

4. Visual Studioでのビルドエラー

症状: premake4関連のエラー、またはSDL2が見つからないエラーが発生する。

原因: premake4がインストールされていない、またはSDL2のパス設定が不正。

解決策:

premake4をインストールし、PATHを通す
SDL2をdemo/sdl2に配置する（demo/README:1-6）
既存のdemo/demo.slnを直接使用する場合はpremake4不要（demo/demo.sln:1-28）

次のステップ

クイックスタートガイドで基本的な環境構築と実行が完了したら、以下のトピックについて詳細を確認することを推奨する：

APIリファレンス: MicroProfileEnter/MicroProfileLeaveなどの低レベルAPIや、カウンター機能の使用方法
GPU プロファイリング: D3D11/D3D12/OpenGL/Vulkanバックエンドの設定と使用
Web UIの活用: ブラウザベースの可視化機能とHTMLエクスポート
本番環境での運用: オーバーヘッドの最小化と安全な有効化/無効化

これらの詳細については、microprofile.hヘッダファイルのコメントおよびREADMEの機能説明（README.md:10-18）を参照すること。