overview

Documentation

Overview

Performance Hint API overview.

Documents the Android Performance Hint API using the ndk hint package. The Performance Hint API allows applications to communicate their performance requirements to the system so that it can adjust CPU frequency and scheduling in real time. This is the primary mechanism for achieving consistent frame timing without over- or under-clocking the CPU.

Core concept:

The application creates a hint session with a set of thread IDs (the
threads doing frame work) and a target work duration. Each frame, the
application reports how long the work actually took. The system uses
the ratio of actual-to-target duration to adjust CPU frequency:

  actual < target  ->  system may lower CPU frequency to save power
  actual ~ target  ->  CPU frequency is well-matched
  actual > target  ->  system may raise CPU frequency to meet deadlines

Typical game loop integration:

1. Obtain a Manager via APerformanceHintManager_fromContext (JNI).
2. Gather thread IDs for your render and game-logic threads.
3. Create a Session with those thread IDs and a target duration (e.g., 16_666_666 ns for 60 fps).
4. Each frame, measure the wall-clock work time and call ReportActualWorkDuration.
5. If the frame rate target changes (e.g., 60 fps -> 90 fps), call UpdateTargetWorkDuration with the new target.
6. Close the Session when the render loop exits.

The Manager handle is obtained from the Android system through JNI:

APerformanceHintManager *mgr = APerformanceHintManager_fromContext(env, context);

There is no Go-side constructor for Manager because the handle must come from the Android runtime. In a real application you would pass the pointer across the JNI boundary and wrap it in a hint.Manager.

Prerequisites:

• Android device with API level 33+ (ADPF performance hint support).
• A valid APerformanceHintManager handle obtained via JNI.