Low-level native plug-in Profiler API

The Unity Profiler is a tool that you can use to analyze and improve the performance of your application. The ProfilerA window that helps you to optimize your game. It shows how much time is spent in the various areas of your game. For example, it can report the percentage of time spent rendering, animating, or in your game logic. More info
See in Glossary carries out frame time analysis of function calls in native Unity code and managed code in your application. You can use the ProfilerMarker API to insert timing markers into your own code to get a better understanding of the performance of specific areas of your application.

You can use the low-level native plug-inA platform-specific native code library that is created outside of Unity for use in Unity. Allows you can access features like OS calls and third-party code libraries that would otherwise not be available to Unity. More info
See in Glossary profiler API to extend the Profiler and profile the performance of native plug-inA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
See in Glossary code, or to prepare profiling data to send to third-party profiling tools such as Razor (PS4), PIX (Xbox, Windows), Chrome Tracing, ETW, ITT, Vtune, or Telemetry. The low-level native plug-in Profiler APIs provide the following interfaces for communication between the Unity Profiler and external tooling:

• IUnityProfiler: Use this interface to add instrumentation events to the Unity Profiler from C/C++ native plug-in code.
• IUnityProfilerCallbacks: Use this interface to intercept Unity Profiler events and store or redirect them to other tools.

IUnityProfiler API

Use the IUnityProfiler plug-in API to add instrumentation to the C/C++ code of your native plug-ins.

The plug-in API is represented by IUnityProfiler interface, which is declared in the IUnityProfiler.h header. Unity stores the header in the <UnityInstallPath>\Editor\Data\PluginAPI folder of your Unity installation. (On macOS, right-click on the Unity application, and select Show Package Contents. The header is in Contents\PluginAPI).

Usage example

This example generates Profiler events that are then shown in the Profiler Window.

#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 callbacks

The native Profiler plug-in API provides an interface between Unity’s subsystems and third-party profiling APIs so you can use an external profiling tool to profile your Unity application. The IUnityProfilerCallbacks header exposes the API, which Unity stores in the <UnityInstallPath>\Editor\Data\PluginAPI folder of your Unity installation. (On macOS, right-click on the Unity application, and select Show Package Contents. The header is in Contents\PluginAPI).

The following Unity Profiler features help capture instrumentation data so you can analyze the performance of your application.

To use the instrumentation data that the Unity Profiler generates in an external profiler, you can use these minimal set of callbacks in your C/C++ plug-in code that integrates the third-party profiler:

Usage example

This example shows you how to pass Unity Profiler events to another profiler which has push/pop semantics. It provides two functions:

• void MyProfilerPushMarker(const char* name) - pushes a named marker.
• void MyProfilerPopMarker() - pops instrumentation marker.

The following example provides the minimal implementation required to pass begin and end instrumentation events from the Unity Profiler to the external 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);
}

Note: To unregister the given callback from all markers, run UnregisterEventCallback with the first parameter set to null.

UnitySystracePlugin example

You can register and unregister marker callbacks dynamically, once every frame. The following example minimizes profiling overhead by enabling and disabling callbacks, depending on a third party profile state.

| 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);
        }
    }
}

Note: To unregister the given callback from all markers, run UnregisterEventCallback with the first parameter set to null.

Special markers

Unity has the following special markers that contain useful metadata:

• Profiler.DefaultMarker
• GC.Alloc

Profiler.DefaultMarker

The Profiler.DefaultMarker is a marker that Unity reserves for Profiler.BeginSample and Profiler.EndSample events.

In the example above, kUnityProfilerMarkerEventTypeBegin eventType corresponds to the Profiler.BeginSample event and has the following data:

• Int32: The UnityEngine.Object instance ID. This is 0 if the object is not specified.
• UInt16 array: The UTF16 string that is passed to Profiler.BeginSample. The size is in bytes.
• UInt32: The category index.

GC.Alloc

GC.Alloc is a marker that corresponds to garbage collection allocation. It has the following data:

• Int64: The size of the allocation.