低レベルのネイティブプラグインのプロファイリング

低レベルのネイティブプラグインプロファイラー 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.h ヘッダーで宣言される IUnityProfiler インターフェースで表されます。Unity はヘッダーを Unity インストールの <UnityInstallPath>\Editor\Data\PluginAPI フォルダーに保存します(macOS の場合は、Unity アプリケーションを右クリックし、Show Package Contents を選択してください。ヘッダーは Contents\PluginAPI 内にあります)。

IUnityProfiler の例

以下の例では、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);

    // Code I want to see in Unity Profiler as "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 はこれを Unity インストールの <UnityInstallPath>\Editor\Data\PluginAPI フォルダーに保存します。(macOS の場合は、Unity アプリケーションを右クリックし、Show Package Contents を選択してください。ヘッダーは Contents\PluginAPI 内にあります)。

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

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

IUnityProfilerCallbacks の例

この例では、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: 割り当てのサイズ。

追加リソース

• Profiler の基本
• コードへのプロファイリング情報の追加
• ネイティブプラグインの基本