Calculate more fine-grained FPS statistics in Android renderer (#10591)

## Summary
- Improves FPS statistics logging in `FpsManager` to distinguish between
different types of frame skips and rendering delays
- Adds tracking for frames missed due to frame pacing vs frames missed
due to slow rendering
- Provides more detailed performance metrics for debugging rendering
issues

## Changes
- Added `choreographerPacingSkips` counter to track VSYNC skips
specifically due to intentional frame pacing
- Added `missedMapRenderFrames` counter to track map render frames
missed due to rendering taking too long (calculated based on the
configured map render frame rate, not just screen refresh rate)
- Enhanced logging to report:
    - Average map core rendering time in milliseconds and FPS
    - Number of map render frames missed
    - VSYNC skips broken down by total and pacing-related
- Added documentation comments explaining the purpose of each counter
- Improved clarity of log messages to differentiate between different
performance metrics

## Context
The previous FPS statistics lumped all frame skips together, making it
difficult to distinguish between:
1. Intentional skips due to frame pacing (when rendering at lower than
screen refresh rate)
2. Missed frames due to rendering taking too long

This change provides clearer visibility into rendering performance for
debugging and optimization.

cc @mapbox/maps-android
cc @mapbox/sdk-platform

---------

Co-authored-by: Peng Liu <[email protected]>
GitOrigin-RevId: 54119ce0ea8f24177d0b3e955c6b00b668ee53cc

Author: 2 people

CHANGELOG.md

@@ -8,6 +8,7 @@ Mapbox welcomes participation and contributions from everyone.
 
 ## Features ✨ and improvements 🏁
 * [compose] Add declarative animation API to experimental `Marker` composable with two animation triggers: `appearAnimation` and `disappearAnimation`. Each trigger accepts a list of `MarkerAnimationEffect` including `wiggle` (pendulum rotation), `scale`, `fadeIn`, and `fadeOut`. Effects can be customized with parameters (e.g., `scale(from = 0.5f, to = 1.5f)`, `fade(from = 0.5f, to = 1.0f)`) and combined for rich animations. See `MarkersActivity` example for usage.
+* Improve FPS statistics logging when `mapView.setOnFpsChangedListener()` is used with separate tracking for frame pacing skips and missed render frames for better performance debugging.
 
 ## Bug fixes 🐞
 * Fix NPE crash in `PointAnnotationClusterActivity` example when the remote GeoJSON endpoint returns a non-successful HTTP response.

maps-sdk/src/main/java/com/mapbox/maps/renderer/FpsManager.kt

@@ -26,8 +26,23 @@ internal class FpsManager(
 
   private var preRenderTimeNs = -1L
   private var choreographerTicks = 0
+
+  /**
+   * VSYNC skipped, either due to taking too long (see [updateFrameStats]) or due to frame pacing
+   * (see [performPacing])
+   */
   private var choreographerSkips = 0
 
+  /**
+   * VSYNC skipped due to frame pacing (see [performPacing])
+   */
+  private var choreographerPacingSkips = 0
+
+  /**
+   * Amount of render frames missed (based on map render frame rate) due to map render taking too long
+   */
+  private var missedMapRenderFrames = 0
+
   internal var fpsChangedListener: OnFpsChangedListener? = null
 
   @Suppress("PrivatePropertyName")
@@ -97,18 +112,19 @@ internal class FpsManager(
   fun postRender() {
     val frameRenderTimeNs = System.nanoTime() - preRenderTimeNs
     frameRenderTimeAccumulatedNs += frameRenderTimeNs
-    // normally we update FPS counter and reset counters once a second
+    // normally we update FPS counter and reset counters once a second (since screenRefreshRate is FPS)
     if (choreographerTicks >= screenRefreshRate) {
       calculateFpsAndReset()
     } else {
       // however to produce correct values we also update FPS after IDLE_TIMEOUT_MS
       // otherwise when updating the map after it was IDLE first update will report
       // huge delta between new frame and last frame (as we're using dirty rendering)
+      val delayMillis = VSYNC_COUNT_TILL_IDLE * (screenRefreshPeriodNs / ONE_MILLISECOND_NS)
       HandlerCompat.postDelayed(
         handler,
         onRenderingPausedRunnable,
         fpsManagerToken,
-        VSYNC_COUNT_TILL_IDLE * (screenRefreshPeriodNs / ONE_MILLISECOND_NS)
+        delayMillis
       )
     }
     preRenderTimeNs = -1L
@@ -123,14 +139,32 @@ internal class FpsManager(
     fpsChangedListener = null
   }
 
+  /**
+   * This is called on every VSYNC (screenRefreshRate)
+   */
   private fun updateFrameStats(frameTimeNs: Long) {
     preRenderTimeNs = System.nanoTime()
     skippedNow = 0
-    // check if we did miss VSYNC deadline meaning too much work was done in previous doFrame
-    if (previousFrameTimeNs != -1L && frameTimeNs - previousFrameTimeNs > screenRefreshPeriodNs + ONE_MILLISECOND_NS) {
-      skippedNow =
-        ((frameTimeNs - previousFrameTimeNs) / (screenRefreshPeriodNs + ONE_MILLISECOND_NS)).toInt()
-      choreographerSkips += skippedNow
+    if (previousFrameTimeNs != -1L) {
+      val frameElapsedTimeNs = frameTimeNs - previousFrameTimeNs
+
+      // check if we did miss VSYNC deadline meaning too much work was done in previous doFrame
+      if (frameElapsedTimeNs > screenRefreshPeriodNs + ONE_MILLISECOND_NS) {
+        // Figure out how many VSYNC (`screenRefreshPeriod`) we missed due to the map rendering taking too long
+        skippedNow =
+          (frameElapsedTimeNs / (screenRefreshPeriodNs + ONE_MILLISECOND_NS)).toInt()
+        choreographerSkips += skippedNow
+      }
+
+      // Check if we did miss map render frames
+      // The map render frame time is based on the userToScreenRefreshRateRatio or the screen refresh rate (1.0)
+      val mapRenderFrameRatio = userToScreenRefreshRateRatio ?: 1.0
+      val mapRenderTimeNs = screenRefreshPeriodNs / mapRenderFrameRatio
+      val missedMapRenderFramesNow =
+        (frameElapsedTimeNs / (mapRenderTimeNs + ONE_MILLISECOND_NS)).toInt()
+      if (missedMapRenderFramesNow > 0) {
+        missedMapRenderFrames += missedMapRenderFramesNow
+      }
     }
     previousFrameTimeNs = frameTimeNs
     // we always increase choreographer tick by one + add number of skipped frames for consistent results
@@ -172,6 +206,8 @@ internal class FpsManager(
    *                 // reset counters
    *        1           |       0.4       |   false
    *        2           |       0.8       |   false
+   *
+   * @return true if we should render this frame, false otherwise
    */
   private fun performPacing(userToScreenRefreshRateRatio: Double): Boolean {
     val drawnFrameIndex = (choreographerTicks * userToScreenRefreshRateRatio).toInt()
@@ -186,6 +222,9 @@ internal class FpsManager(
       previousDrawnFrameIndex = drawnFrameIndex
       return true
     }
+    choreographerPacingSkips++
+    // We also increase choreographerSkips when performing pacing. Note this is not really a
+    // missed map render frame since we're doing pacing.
     choreographerSkips++
     return false
   }
@@ -201,26 +240,32 @@ internal class FpsManager(
       if (choreographerTicks == choreographerSkips) {
         logI(
           TAG,
-          "VSYNC based FPS is $fps, missed $choreographerSkips out of $choreographerTicks VSYNC pulses"
+          "VSYNC based FPS is $fps, " +
+            "skipped $choreographerSkips ($choreographerPacingSkips due to pacing) " +
+            "out of $choreographerTicks VSYNC pulses"
         )
       } else {
+        val actualAmountOfFramesRendered = choreographerTicks - choreographerSkips
         val averageRenderTimeNs =
-          frameRenderTimeAccumulatedNs.toDouble() / (choreographerTicks - choreographerSkips)
-        val fps =
-          String.format("%.2f", screenRefreshPeriodNs / averageRenderTimeNs * screenRefreshRate)
+          frameRenderTimeAccumulatedNs.toDouble() / actualAmountOfFramesRendered
+        val averageFps =
+          String.format("%.2f", (screenRefreshPeriodNs / averageRenderTimeNs) * screenRefreshRate)
         logI(
           TAG,
-          "VSYNC based FPS is $fps," +
-            " average core rendering time is ${averageRenderTimeNs / ONE_MILLISECOND_NS} ms" +
-            " (or $fps FPS)," +
-            " missed $choreographerSkips out of $choreographerTicks VSYNC pulses"
+          "Average map core rendering time is " +
+            "${averageRenderTimeNs / ONE_MILLISECOND_NS} ms (or $averageFps FPS), " +
+            "missed $missedMapRenderFrames map render frames, " +
+            "skipped $choreographerSkips ($choreographerPacingSkips due to render pacing) " +
+            "out of $choreographerTicks VSYNC pulses"
         )
       }
     }
     previousDrawnFrameIndex = 0
     frameRenderTimeAccumulatedNs = 0L
     choreographerTicks = 0
     choreographerSkips = 0
+    choreographerPacingSkips = 0
+    missedMapRenderFrames = 0
   }
 
   internal companion object {