低レベルのネイティブプラグイン Profiler API

Unity Profiler は、アプリケーションのパフォーマンスを分析し、改善するためのツールです。Profiler は、アプリケーションの Unity ネイティブコードやマネージコードの関数呼び出しの フレーム時間分析 を実行します。ProfilerMarker API を使用して独自のコードにタイミングマーカーを挿入することで、アプリケーションの特定エリアのパフォーマンスをより深く理解することができます。

低レベルのネイティブプラグイン プロファイラー API を使用して、プロファイラを拡張し、ネイティブプラグインコードのパフォーマンスをプロファイルしたり、Razor(PS4)、PIX(Xbox、Windows)、Chrome Tracing、ETW、ITT、Vtune、Telemetry などのサードパーティのプロファイリングツールに送信するプロファイリングデータを準備することができます。低レベルのネイティブプラグイン Profiler API は、Unity Profiler と外部ツール間の通信のために以下のインターフェースを提供します。

• IUnityProfiler: C/C++ ネイティブプラグインコードから Unity Profiler にインストルメンテーションイベントを追加するには、このインターフェースを使用します。
• IUnityProfilerCallbacks: このインターフェースを使用して、Unity Profiler のイベントのインターセプト、保存、他のツールへのリダイレクトを行います。

IUnityProfiler API

IUnityProfiler プラグイン API を使用して、ネイティブプラグインの C/C++ コードにインストルメンテーションを追加します。

プラグインAPI は IUnityProfiler インターフェースで表現されており、IUnityProfiler.h ヘッダーで宣言されています。Unity はこのヘッダーを、Unity インストールの<UnityInstallPath>\Editor\Data\PluginAPI フォルダーに格納します。(macOS では、Unity アプリケーションを右クリックして、Show Package Contents を選択してください。ヘッダーは Contents\PluginAPI にあります。)

使用例

この例では、プロファイラーイベントを生成し、Profiler ウィンドウに表示します。

# include <IUnityInterface.h>
# include <IUnityProfiler.h>

static IUnityProfiler* s_UnityProfiler = NULL;
static const UnityProfilerMarkerDesc* s_MyPluginMarker = NULL;
static bool s_IsDevelopmentBuild = false;

static void MyPluginWorkMethod()
{
    if (s_IsDevelopmentBuild)
        s_UnityProfiler->BeginSample(s_MyPluginMarker);

    // Unity Profiler で "MyPluginMethod" として表示したいコード
    // ...

    if (s_IsDevelopmentBuild)
        s_UnityProfiler->EndSample(s_MyPluginMarker);
}

extern "C" void UNITY_INTERFACE_EXPORT UNITY_INTERFACE_API UnityPluginLoad(IUnityInterfaces* unityInterfaces)
{
    s_UnityProfiler = unityInterfaces->Get<IUnityProfiler>();
    if (s_UnityProfiler == NULL)
        return;
    s_IsDevelopmentBuild = s_UnityProfiler->IsAvailable() != 0;
    s_UnityProfiler->CreateMarker(&s_MyPluginMarker, "MyPluginMethod", kUnityProfilerCategoryOther, kUnityProfilerMarkerFlagDefault, 0);
}

extern "C" void UNITY_INTERFACE_EXPORT UNITY_INTERFACE_API UnityPluginUnload()
{
    s_UnityProfiler  = NULL;
}

IUnityProfilerCallbacks API コールバック

ネイティブの Profiler プラグイン API は、Unity のサブシステムとサードパーティのプロファイリング API との間のインターフェースを提供します。そのため、外部のプロファイリング ツールを使用して Unity アプリケーションのプロファイリングを行うことができます。IUnityProfilerCallbacks ヘッダーが API を公開しており、Unity はこの API を、Unity インストールの <UnityInstallPath>\Editor\Data\PluginAPI フォルダーに格納します。(macOS では、Unity アプリケーションを右クリックして、Show Package Contents を選択します。ヘッダーは Contents\PluginAPI にあります)。

以下の Unity Profiler の機能は、インストルメンテーションデータの取得に役立ち、アプリケーションのパフォーマンスを分析することができます。

Unity Profiler が生成するインストルメンテーションデータを外部のプロファイラーで使用するために、以下の最小限のコールバックを、サードパーティのプロファイラーを統合する C/C++ プラグインコードで使用できます。

使用例

この例では、Unity Profiler のイベントを、Push/Pop セマンティクスを持つ別のプロファイラーに渡す方法を示しています。以下の 2 つの関数を用意しています。

• void MyProfilerPushMarker(const char* name) - 名前付きのマーカーをプッシュします。 void MyProfilerPopMarker() - インストルメンテーションマーカーを表示します。

次の例では、Unity Profiler から外部のプロファイラーにインストルメンテーションの開始と終了のイベントを渡すために、必要最小限の実装を行っています。

# include <IUnityInterface.h>
# include <IUnityProfilerCallbacks.h>

static IUnityProfilerCallbacks* s_UnityProfilerCallbacks = NULL;

static void UNITY_INTERFACE_API MyProfilerEventCallback(const UnityProfilerMarkerDesc* markerDesc, UnityProfilerMarkerEventType eventType, unsigned short eventDataCount, const UnityProfilerMarkerData* eventData, void* userData)
{
    switch (eventType)
    {
        case kUnityProfilerMarkerEventTypeBegin:
        {
            MyProfilerPushMarker(markerDesc->name);
            break;
        }
        case kUnityProfilerMarkerEventTypeEnd:
        {
            MyProfilerPopMarker();
            break;
        }
    }
}

static void UNITY_INTERFACE_API MyProfilerCreateMarkerCallback(const UnityProfilerMarkerDesc* markerDesc, void* userData)
{
    s_UnityProfilerCallbacks->RegisterMarkerEventCallback(markerDesc, MyProfilerEventCallback, NULL);
}

extern "C" void UNITY_INTERFACE_EXPORT UNITY_INTERFACE_API UnityPluginLoad(IUnityInterfaces* unityInterfaces)
{
    s_UnityProfilerCallbacks = unityInterfaces->Get<IUnityProfilerCallbacks>();
    s_UnityProfilerCallbacks->RegisterCreateMarkerCallback(&MyProfilerCreateMarkerCallback, NULL);
}

extern "C" void UNITY_INTERFACE_EXPORT UNITY_INTERFACE_API UnityPluginUnload()
{
    s_UnityProfilerCallbacks->UnregisterCreateMarkerCallback(&MyProfilerCreateMarkerCallback, NULL);
    s_UnityProfilerCallbacks->UnregisterMarkerEventCallback(NULL, &MyProfilerEventCallback, NULL);
}

ノート: すべてのマーカーから指定するコールバックを登録解除するには、最初のパラメーターを null に設定して UnregisterEventCallback を実行します。

UnitySystracePlugin の例

フレームごとに 1 回づつ、マーカコールバックを動的に登録および登録解除できます。次の例は、サードパーティのプロファイルの状況に応じて、コールバックを有効または無効にすることによって、プロファイリングのオーバーヘッドを最小化する方法を示しています。

| static void UNITY_INTERFACE_API SystraceFrameCallback(void* userData)
{
    bool isCapturing = ATrace_isEnabled();
    if (isCapturing != s_isCapturing)
    {
        s_isCapturing = isCapturing;
        if (isCapturing)
        {
            s_UnityProfilerCallbacks->
              RegisterCreateMarkerCallback(SystraceCreateEventCallback, NULL);
        }
        else
        {
            s_UnityProfilerCallbacks->
              UnregisterCreateMarkerCallback(SystraceCreateEventCallback, NULL);
            s_UnityProfilerCallbacks->
              UnregisterMarkerEventCallback(NULL, SystraceEventCallback, NULL);
        }
    }
}

ノート: すべてのマーカーから指定するコールバックを登録解除するには、最初のパラメーターを null に設定して UnregisterEventCallback を実行します。

特別なマーカー

Unity には有用なメタデータを含む以下の特別なマーカーがあります。

• Profiler.DefaultMarker
• GC.Alloc

Profiler.DefaultMarker

Profiler.DefaultMarker は、Unity が Profiler.BeginSample とProfiler.EndSample のイベントのために予約しているマーカーです。

上の例では、kUnityProfilerMarkerEventTypeBegin eventType は、Profiler.BeginSample イベントに対応しており、以下のデータを持っています。

• Int32: UnityEngine.Object インスタンス ID。オブジェクトが指定されていない場合は 0 です。
• UInt16 array: Profiler.BeginSample に渡されるUTF16 文字列。サイズはバイト数です。
• UInt32: カテゴリインデックス。

GC.Alloc

GC.Alloc は、ガベージコレクションの割り当てに対応するマーカーです。以下のデータが含まれます。

• Int64: 割り当てのサイズ。