低级原生插件 Profiler API

Unity 性能分析器是一种可用于分析和改进应用程序性能的工具。性能分析器对应用程序的原生 Unity 代码和托管代码中的函数调用执行帧时间分析。可以使用 ProfilerMarker API 将计时标记插入自己的代码中，以便更好地了解应用程序特定区域的性能。

可以使用低级原生插件性能分析器 API 扩展性能分析器并分析原生插件代码的性能，或是准备性能分析数据以发送到第三方性能分析工具，例如 Razor (PS4)、PIX（Xbox、Windows）、Chrome Tracing、ETW、ITT、Vtune 或 Telemetry。低级原生插件性能分析器 API 提供以下接口来用于 Unity 性能分析器与外部工具之间的通信：

• IUnityProfiler：使用此接口可从 C/C++ 原生插件代码向 Unity 性能分析器添加检测事件。
• IUnityProfilerCallbacks：使用此接口可拦截 Unity 性能分析器事件并将它们存储或重定向到其他工具。

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 性能分析器中显示为"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 回调

原生性能分析器插件 API 在 Unity 子系统与第三方性能分析 API 之间提供了接口，以便可以使用外部性能分析工具对 Unity 应用程序进行性能分析。IUnityProfilerCallbacks 头文件公开了该 API，Unity 将它存储在 Unity 安装的 <UnityInstallPath>\Editor\Data\PluginAPI 文件夹中。（在 macOS 上，右键单击 Unity 应用程序，然后选择 Show Package Contents。该头文件处于 Contents\PluginAPI 中）。

以下 Unity 性能分析器功能有助于捕获检测数据，以便可以分析应用程序的性能。

要在外部分析器中使用 Unity 性能分析器生成的检测数据，可以在集成第三方性能分析器的 C/C++ 插件代码中使用最少量的回调：

用法示例

此示例演示如何将 Unity 性能分析器事件传递给另一个具有压入/弹出语义的性能分析器。它提供两种函数：

• void MyProfilerPushMarker(const char* name) - 压入命名标记。
• void MyProfilerPopMarker() - 弹出检测标记。

以下示例提供将开始和结束检测事件从 Unity 性能分析器传递到外部性能分析器所需的最小实现：

# 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 示例

您可以每帧动态注册和取消注册标记回调。以下示例根据第三方性能分析状态通过启用和禁用回调来最大限度降低性能分析开销。

| 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 数组：传递给 Profiler.BeginSample 的 UTF16 字符串。此大小以字节为单位。
• UInt32：类别索引。

GC.Alloc

GC.Alloc 是与垃圾收集分配相对应的标记。该标记提供以下数据：

• Int64：分配大小。