Track energy usage

Read energy consumption for each hardware component on supported devices using the Adaptive Performance Energy Usage API.

The Energy Usage API reports the energy that hardware components such as the CPU and GPU consume over a measurement interval. Use it to monitor how much energy a scene, feature, or play session draws on supported devices, and to compare the energy cost of different settings.

Energy usage is a provider capability, so it’s only available when the active provider and device support it. When it isn’t supported, IEnergyUsageControl.EnergyUsageTrackingSupported is false and the API reports no readings. For more information, refer to Check for feature support, and to your provider’s documentation for platform support details.

To work on energy usage without a supported device, simulate readings for each hardware component in the Device Simulator. For more information, refer to Adaptive Performance Device Simulator plug-in reference.

Start and stop tracking

Energy tracking is off by default. Access energy-usage control through the EnergyUsageControl extension method on IAdaptivePerformance, then call StartEnergyUsageTracking to begin collecting readings and StopEnergyUsageTracking to stop.

using UnityEngine;
using UnityEngine.AdaptivePerformance;

public class EnergyUsageExample : MonoBehaviour
{
    IAdaptivePerformance ap;

    void Start()
    {
        ap = Holder.Instance;
        if (ap == null || !ap.Active)
            return;

        var control = ap.EnergyUsageControl();
        if (control == null || !control.EnergyUsageTrackingSupported)
        {
            Debug.Log("Energy usage tracking is not supported on this device.");
            return;
        }

        control.StartEnergyUsageTracking();
    }

    void OnDisable()
    {
        ap?.EnergyUsageControl()?.StopEnergyUsageTracking();
    }
}

Call StartEnergyUsageTracking again at any time to reset the baseline, so that subsequent readings are measured from that point. StartEnergyUsageTracking returns false when tracking can’t start, for example when Adaptive Performance isn’t active or the device doesn’t support the feature.

Read energy usage

While tracking is active, read the latest values from PerformanceMetrics.EnergyUsage. Call EnergyUsage.Get with an EnergyUsageSubsystem value to get the reading for a specific hardware component.

var energyUsage = Holder.Instance.PerformanceStatus.PerformanceMetrics.EnergyUsage;
var cpu = energyUsage.Get(EnergyUsageSubsystem.Cpu);
if (cpu.Available)
{
    // Energy is in microwatt-seconds; interval is in milliseconds.
    double milliwatts = (double)cpu.Energy / cpu.Interval;
    Debug.Log($"CPU used {milliwatts:F1} mW. That's {cpu.Energy} microwatt-seconds over {cpu.Interval} ms");
}

Each EnergyUsageReading reports the following values:

A hardware component can be unavailable independently of the others, so always check Available before you use a reading.

Update cadence and limitations

Energy readings update at the platform’s native cadence, which can be considerably slower than once per frame. Both Energy and Interval are measured from the tracking baseline to the most recent hardware update. Refer to your provider’s documentation for the update cadence on a specific platform.

Because of this cadence, energy usage suits long running monitoring rather than fine grained measurement. It isn’t precise enough to measure the energy of a short operation such as a single code block, and the reported energy covers the whole hardware component rather than a specific workload.

For a practical example, refer to the Energy Reading sample.

Additional resources

• Track timing and thermal data
• Check for feature support
• Adaptive Performance Device Simulator plug-in reference
• Scripting with Adaptive Performance