文档

Unity 引擎

Unity 引擎

分析低关卡原生插件

扩展性性能分析器并从原生插件收集性性能数据。
阅读时间10 分钟最后更新于 3 小时前

您可以使用低关卡原生插件性能分析器 API 来扩展性能分析器并收集原生插件代码的性能数据,或准备性能分析数据以发送到第三方分析工具,例如 Razor (PS4)、Pix (Xbox、Windows)、Chrome Tracing、ETW、ITT、VTune 或 Telemetry。
关卡原生插件性能分析性能分析器 API 提供以下接口,用于在 Unity Profiler 与External工具之间进行通信:
  • IUnityProfiler:使用此接口可以从 C/C++ 原生插件代码向 Unity Profiler 添加检测事件。
  • IUnityProfilerCallbacks:使用此接口可以拦截 Unity Profiler 事件并将它们存储或重定向到 Other 工具。

IUnityProfiler API 参考

使用
IUnityProfiler
插件 API 向原生插件的 C/C++ 代码添加检测。
插件 API 由
IUnityProfiler
接口表示,该接口在
IUnityProfiler.h
标头中声明。Unity 将标头存储在 Unity 安装的
<UnityInstallPath>\Editor\Data\PluginAPI
文件夹中。(在 macOS 上,右键单击 Unity 应用程序,然后选择 Show Package Contents)。标头位于
Contents\PluginAPI
)。

方法

描述

CreateMarker
创建表示指定检测作用域的性能分析器标记,然后可以使用该标记来 Generate 检测样本。
SetMarkerMetadataName
指定可性能分析器标记的检测样本一起传递的自定义定义参数名称。
BeginSample
开始以性性能分析器分析器标记命名的代码的检测部分。
EndSample
结束检测部分。
EmitEvent
使用元数据发出 Generic 事件。
IsEnabled
如果性能性能分析器正在捕获数据,则返回 1。
IsAvailable
返回 1 表示 Editor 或 Development 玩家(其中 性能分析器 可用),返回 0 表示 发布 玩家。
RegisterThread
使用指定 Name 注册当前线程。
UnregisterThread
从性性能分析器中取消注册当前线程。\

IUnityProfiler 示例

以下示例生成 性能分析器 窗口可以显示的 性能分析器 事件:
#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_导出 Unity_INTERFACE_API UnityPluginLoad(IUnityInterfaces* unityInterfaces){ s_UnityProfiler = unityInterfaces->Get<IUnityProfiler>(); if (s_UnityProfiler == NULL) 返回; s_IsDevelopmentBuild = s_UnityProfiler->IsAvailable() != 0; s_UnityProfiler->CreateMarker(&s_MyPluginMarker, "MyPluginMethod", kUnityProfilerCategoryOther, kUnityProfilerMarkerFlagDefault, 0);}extern "C" void Unity_INTERFACE_导出 Unity_INTERFACE_API UnityPluginUnload(){ s_UnityProfiler = NULL;}

IUnityProfilerCallbacks API 回调

原生性能性能分析器插件 API 在 Unity 子系统和第三方性能分析 API 之间提供了一个接口,因此您可以使用External性能分析工具对 Unity 应用程序程序进行性能配置文件。
IUnityProfilerCallbacks
标头公开了 API,Unity 将其存储在 Unity 安装的
<UnityInstallPath>\Editor\Data\PluginAPI
Folder 中。(在 macOS 上,右键单击 Unity 应用程序,然后选择 Show Package Contents)。标头位于
Contents\PluginAPI
)。
以下 Unity Profiler Features有助于捕获检测数据,以便分析应用程序程序的性能:

性能分析器功能

描述

类别:Unity 将性能配置文件数据组到多个类别(例如渲染、脚本和动画),并为每个Category分配颜色。颜色编码类别有助于在性能分析器窗口中直观区分数据类型。性能分析器原生插件 API 会检索这些颜色,以便您可以在 External 性能分析工具中使用它们。
使用标志使用标志用作过滤器器,可减少 Unity 发送到External性能分析工具的数据amount。您可以使用使用标志在 Unity 将性能分析数据发送到 External 工具之前移除这些数据中的不必要信息。性能分析器将以下使用标志应用于事件Markers,以便可以过滤器数据:

可用性标志 标志 Unity Editor、Development Player 或释放 Player 中是否有可用的标记。

Verbosity levels 与在 Editor 中执行的任务类型以及任务所需的信息关卡(例如,内部、调试或用户关卡)相关。
帧事件您可以使用性能分析性能分析器原生插件 API 在External性能分析工具中执行帧时间分析。
线程性能分析Unity ON线程(例如,主要线程、渲染线程和任务System工作线程)上执行amount工作。您可以使用性能分析性能分析器原生插件 API ONAny线程上Enable性能分析。
要使用 Unity Profiler 在External性能性能分析器中生成的检测数据,可以在集成第三方性能性能分析器的 C/C++ 插件代码中使用以下最小回设置:

callback

函数

RegisterCreateCategoryCallback
注册
IUnityProfilerCreateCategoryCallback
回调以在 Unity 创建 Category 时获取性能分析器的 Category Name 和颜色。
RegisterCreateMarkerCallback
注册每当 Unity 创建标记时调用的
IUnityProfilerCreateMarkerCallback
回调。使用于获取标记的Name、性能性能分析器Category和使用标志。回调函数的 const
UnityProfilerMarkerDesc* markerDesc
参数表示指向标记描述的持久指针,您可以使用该指针在
RegisterMarkerEventCallback
中过滤 Markers。
RegisterMarkerEventCallback
注册 Unity 在发生单一、作用域、内存分配或垃圾Collection事件When调用的 IUnityProfilerMarkerEventCallback 回调。然后,您可以使用此回调在 External 性能分析工具中调用相关函数。**注意:**Unity 表示带有
GC.Alloc
Markers 的内存分配事件以及带有
GC.Collect
Markers 的垃圾收集事件。
RegisterFrameCallback
将样本封装到逻辑帧中,以便不使帧External性能分析工具可以使用这些样本。还注册 Unity Profiler 在 Unity 启动Next一个逻辑 CPU 帧行的回调。
RegisterCreateThreadCallback
注册回调,以便在 Unity 注册线程进行性能分析时获取内部线程 Name。

IUnityProfilerCallbacks example

此示例演示如何将 Unity Profiler 事件通道到另一个具有推送/弹出语义的性能分析器。它提供两个函数:
  • void MyProfilerPushMarker(const char* name)
    :推送指定的标记。
  • void MyProfilerPopMarker()
    :弹出检测标记。
以下示例提供了将开始和结束检测事件从 Unity Profiler 通道到External性能性能分析器所需的最小实现:
#include <IUnityInterface.h>#include <IUnityProfilerCallbacks.h>static IUnityProfilerCallbacks* s_UnityProfilerCallbacks = NULL;Static void Unity_INTERFACE_API MyProfilerEventCallback(const UnityProfilerMarkerDesc* markDesc, 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* markDesc, void* userData){ s_UnityProfilerCallbacks->RegisterMarkerEventCallback(markerDesc, MyProfilerEventCallback, NULL);}extern "C" void Unity_INTERFACE_导出 Unity_INTERFACE_API UnityPluginLoad(IUnityInterfaces* unityInterfaces){ s_UnityProfilerCallbacks = unityInterfaces->Get<IUnityProfilerCallbacks>(); s_UnityProfilerCallbacks->RegisterCreateMarkerCallback(&MyProfilerCreateMarkerCallback, NULL);}extern "C" void Unity_INTERFACE_导出 Unity_INTERFACE_API UnityPluginUnload(){ s_UnityProfilerCallbacks->UnregisterCreateMarkerCallback(&MyProfilerCreateMarkerCallback, NULL); s_UnityProfilerCallbacks > UnregisterMarkerEventCallback( null, &MyProfilerEventCallback, null);}
注意
要从 All Markers 中取消注册给定回调,请运行第一个参数设置为
null
的
UnregisterEventCallback
。

UnitySystracePlugin example

您可以动态注册和取消注册标记回调,帧一次。以下示例根据第三方配置文件状态启用和禁用回调,从而最大限度减少性能分析开销。
| 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); } }}
注意
要从 All Markers 中取消注册给定回调,请运行第一个参数设置为
null
的
UnregisterEventCallback
。

特殊 Markers

Unity 具有以下包含有用元数据的特殊 Markers:
  • Profiler.DefaultMarker
  • GC.Alloc

Profiler.DefaultMarker

Profiler.DefaultMarker
是 Unity 为性能分析器 BeginSample 和性能分析器 EndSample 事件保留的标记。
在上一个示例中,
kUnityProfilerMarkerEventTypeBegin eventType
对应于
Profiler.BeginSample
事件,并具有以下数据:
  • Int32:
    UnityEngine.Object
    实例 ID。如果未指定 Object,则为 0。
  • UInt16 Array:传递给
    Profiler.BeginSample
    的 UTF16 字符串。大小以字节为单位。
  • uint32Category 索引。

GC.Alloc

GC.Alloc
是与垃圾收集分配对应的标记。它有以下数据:
  • int64分配的大小。

其他资源