[maps-sdk] Deprecate RenderThreadStats.totalDroppedFrames; add accurate frame breakdown (#15422)

GitOrigin-RevId: 09c954adb4f234341a862708c539d91a97899cd4

Author: pengdev

CHANGELOG.md

@@ -7,6 +7,7 @@ Mapbox welcomes participation and contributions from everyone.
 # main
 
 ## Features ✨ and improvements 🏁
+* Deprecated `RenderThreadStats.totalDroppedFrames`. Added `totalSkippedVsync`, `pacedSkippedVsync`, and `missedMapRenderFrames` for an accurate breakdown of frame performance when `setMaximumFps()` is used.
 * Report render-thread frame timing to the Android Dynamic Performance Framework (ADPF) on API 31+ devices, allowing the OS to scale CPU frequency based on actual rendering load.
 
 # 11.29.0-rc.1 August 10, 2026

app/src/main/java/com/mapbox/maps/testapp/examples/SimulateNavigationRouteActivity.kt

@@ -90,7 +90,7 @@ class SimulateNavigationRouteActivity : AppCompatActivity() {
     logI(TAG, "\ttotal time: $totalTime ms")
     logI(TAG, "\ttotal frames (rendered + skipped): $totalFrames")
     logI(TAG, "\taverage FPS: ${(totalFrames / (totalTime / 1000F)).format()}")
-    logI(TAG, "\tskipped frames: $totalDroppedFrames")
+    logI(TAG, "\tskipped frames: $totalSkippedVsync (pacing: $pacedSkippedVsync, missed render: $missedMapRenderFrames)")
     logI(TAG, "\t50 percentile: ${percentile50.format()} ms")
     logI(TAG, "\t90 percentile: ${percentile90.format()} ms")
     logI(TAG, "\t95 percentile: ${percentile95.format()} ms")

compose-app/src/main/java/com/mapbox/maps/compose/testapp/utils/FrameStatsRecorder.kt

@@ -45,11 +45,11 @@ public class FrameStatsRecorder {
     }
     jsonObject.addProperty(KEY_TOTAL_FRAMES, stats.totalFrames)
     jsonObject.addProperty(KEY_TOTAL_TIME, stats.totalTime)
-    jsonObject.addProperty(KEY_DROPPED, stats.totalDroppedFrames)
+    jsonObject.addProperty(KEY_DROPPED, stats.totalSkippedVsync)
     jsonObject.addProperty(
       KEY_DROPPED_PERCENT,
       BigDecimal
-        .valueOf((stats.totalDroppedFrames.toDouble() / stats.totalFrames) * 100.0)
+        .valueOf((stats.totalSkippedVsync.toDouble() / stats.totalFrames) * 100.0)
         .setScale(2, RoundingMode.HALF_UP)
         .toDouble()
     )

maps-sdk/api/Release/metalava.txt

@@ -697,20 +697,26 @@ package com.mapbox.maps.renderer {
 
   @com.mapbox.maps.MapboxExperimental public final class RenderThreadStats {
     method public java.util.List<java.lang.Double> getFrameTimeList();
+    method public long getMissedMapRenderFrames();
+    method public long getPacedSkippedVsync();
     method public Double? getPercentile50();
     method public Double? getPercentile90();
     method public Double? getPercentile95();
     method public Double? getPercentile99();
-    method public long getTotalDroppedFrames();
+    method @Deprecated public long getTotalDroppedFrames();
     method public long getTotalFrames();
+    method public long getTotalSkippedVsync();
     method public long getTotalTime();
     property public final java.util.List<java.lang.Double> frameTimeList;
+    property public final long missedMapRenderFrames;
+    property public final long pacedSkippedVsync;
     property public final Double? percentile50;
     property public final Double? percentile90;
     property public final Double? percentile95;
     property public final Double? percentile99;
-    property public final long totalDroppedFrames;
+    property @Deprecated public final long totalDroppedFrames;
     property public final long totalFrames;
+    property public final long totalSkippedVsync;
     property public final long totalTime;
   }
 

maps-sdk/api/maps-sdk.api

@@ -751,15 +751,18 @@ public abstract interface annotation class com/mapbox/maps/renderer/RenderThread
 }
 
 public final class com/mapbox/maps/renderer/RenderThreadStats {
-	public synthetic fun <init> (JJJLjava/util/List;Ljava/lang/Double;Ljava/lang/Double;Ljava/lang/Double;Ljava/lang/Double;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public synthetic fun <init> (JJJJJJLjava/util/List;Ljava/lang/Double;Ljava/lang/Double;Ljava/lang/Double;Ljava/lang/Double;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getFrameTimeList ()Ljava/util/List;
+	public final fun getMissedMapRenderFrames ()J
+	public final fun getPacedSkippedVsync ()J
 	public final fun getPercentile50 ()Ljava/lang/Double;
 	public final fun getPercentile90 ()Ljava/lang/Double;
 	public final fun getPercentile95 ()Ljava/lang/Double;
 	public final fun getPercentile99 ()Ljava/lang/Double;
 	public final fun getTotalDroppedFrames ()J
 	public final fun getTotalFrames ()J
+	public final fun getTotalSkippedVsync ()J
 	public final fun getTotalTime ()J
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;

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

@@ -24,6 +24,10 @@ internal class FpsManager(
   private var frameRenderTimeAccumulatedNs = 0L
   var skippedNow = 0
     private set
+  var pacingSkipsNow: Int = 0
+    private set
+  var missedMapRenderFramesNow: Int = 0
+    private set
 
   private var preRenderTimeNs = -1L
   private var choreographerTicks = 0
@@ -152,6 +156,8 @@ internal class FpsManager(
    */
   private fun updateFrameStats(frameTimeNs: Long) {
     skippedNow = 0
+    pacingSkipsNow = 0
+    missedMapRenderFramesNow = 0
     if (previousFrameTimeNs != -1L) {
       val frameElapsedTimeNs = frameTimeNs - previousFrameTimeNs
 
@@ -167,10 +173,11 @@ internal class FpsManager(
       // 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 =
+      val missedMapRenderFramesDelta =
         (frameElapsedTimeNs / (mapRenderTimeNs + ONE_MILLISECOND_NS)).toInt()
-      if (missedMapRenderFramesNow > 0) {
-        missedMapRenderFrames += missedMapRenderFramesNow
+      if (missedMapRenderFramesDelta > 0) {
+        missedMapRenderFrames += missedMapRenderFramesDelta
+        missedMapRenderFramesNow = missedMapRenderFramesDelta
       }
     }
     previousFrameTimeNs = frameTimeNs
@@ -230,6 +237,7 @@ internal class FpsManager(
       return true
     }
     choreographerPacingSkips++
+    pacingSkipsNow = 1
     // We also increase choreographerSkips when performing pacing. Note this is not really a
     // missed map render frame since we're doing pacing.
     choreographerSkips++

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

@@ -656,7 +656,9 @@ internal abstract class MapboxRenderThread : Choreographer.FrameCallback {
       if (startTime != 0L && endTime != 0L) {
         renderThreadStatsRecorder?.addFrameStats(
           (endTime - startTime) / 1e6,
-          fpsManager.skippedNow
+          fpsManager.skippedNow,
+          fpsManager.pacingSkipsNow,
+          fpsManager.missedMapRenderFramesNow
         )
       }
     }

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

@@ -15,7 +15,9 @@ import kotlin.math.ceil
 class RenderThreadStatsRecorder {
 
   private var startTime = 0L
-  private var totalDroppedFrames = 0L
+  private var totalSkippedVsync = 0L
+  private var pacedSkippedVsync = 0L
+  private var missedMapRenderFrames = 0L
   private val frameTimeList = mutableListOf<Double>()
 
   /**
@@ -36,8 +38,10 @@ class RenderThreadStatsRecorder {
     startTime = SystemClock.elapsedRealtime()
   }
 
-  internal fun addFrameStats(frameTime: Double, droppedFrames: Int) {
-    totalDroppedFrames += droppedFrames
+  internal fun addFrameStats(frameTime: Double, droppedFrames: Int, pacingSkips: Int, missedMapFrames: Int) {
+    totalSkippedVsync += droppedFrames
+    pacedSkippedVsync += pacingSkips
+    missedMapRenderFrames += missedMapFrames
     frameTimeList.add(frameTime)
   }
 
@@ -62,8 +66,11 @@ class RenderThreadStatsRecorder {
 
     return RenderThreadStats.Builder()
       .setTotalTime(SystemClock.elapsedRealtime() - startTime)
-      .setTotalFrames(frameTimeList.size + totalDroppedFrames)
-      .setTotalDroppedFrames(totalDroppedFrames)
+      .setTotalFrames(frameTimeList.size + totalSkippedVsync)
+      .setTotalDroppedFrames(totalSkippedVsync)
+      .setTotalSkippedVsync(totalSkippedVsync)
+      .setPacedSkippedVsync(pacedSkippedVsync)
+      .setMissedMapRenderFrames(missedMapRenderFrames)
       .setFrameTimeList(frameTimeListCopy)
       .setPercentile50(percentileOfSortedList(sortedFrameTimeList, 50.0))
       .setPercentile90(percentileOfSortedList(sortedFrameTimeList, 90.0))
@@ -72,7 +79,9 @@ class RenderThreadStatsRecorder {
       .build()
       .also {
         startTime = 0L
-        totalDroppedFrames = 0L
+        totalSkippedVsync = 0L
+        pacedSkippedVsync = 0L
+        missedMapRenderFrames = 0L
         frameTimeList.clear()
       }
   }
@@ -92,9 +101,33 @@ class RenderThreadStats private constructor(
    */
   val totalFrames: Long,
   /**
-   * Total number of dropped frames.
+   * Number of VSYNC pulses skipped because a render missed its deadline (took too long).
+   *
+   * @deprecated Renamed to [totalSkippedVsync]. This field never included intentional pacing
+   * skips from [setMaximumFps][com.mapbox.maps.MapboxMap.setMaximumFps] - see [pacedSkippedVsync]
+   * for those, tracked separately.
    */
+  @Deprecated(
+    message = "Renamed to totalSkippedVsync. This field only counts missed-render-deadline VSYNCs; see pacedSkippedVsync for intentional pacing skips.",
+    replaceWith = ReplaceWith("totalSkippedVsync")
+  )
   val totalDroppedFrames: Long,
+  /**
+   * Number of VSYNC pulses skipped because a render missed its deadline (took too long).
+   * Does not include intentional pacing skips from [setMaximumFps][com.mapbox.maps.MapboxMap.setMaximumFps] -
+   * see [pacedSkippedVsync] for those. Replacement for the deprecated [totalDroppedFrames].
+   */
+  val totalSkippedVsync: Long,
+  /**
+   * Number of VSYNC pulses intentionally skipped due to frame pacing (i.e., [setMaximumFps][com.mapbox.maps.MapboxMap.setMaximumFps] is active).
+   * These are not missed render deadlines — they are expected skips.
+   */
+  val pacedSkippedVsync: Long,
+  /**
+   * Number of map render frames missed because the render took longer than the target frame time.
+   * This counts misses relative to the map render frame rate (which may differ from the screen refresh rate when [setMaximumFps][com.mapbox.maps.MapboxMap.setMaximumFps] is set).
+   */
+  val missedMapRenderFrames: Long,
   /**
    * List of rendered frames times in milliseconds.
    */
@@ -120,7 +153,7 @@ class RenderThreadStats private constructor(
    * @return Returns a string representation of the object.
    */
   override fun toString() =
-    "RenderThreadStats(totalTime=$totalTime, totalFrames=$totalFrames, totalDroppedFrames=$totalDroppedFrames, frameTimeList=$frameTimeList, percentile50=$percentile50, percentile90=$percentile90, percentile95=$percentile95, percentile99=$percentile99)"
+    "RenderThreadStats(totalTime=$totalTime, totalFrames=$totalFrames, totalDroppedFrames=$totalDroppedFrames, totalSkippedVsync=$totalSkippedVsync, pacedSkippedVsync=$pacedSkippedVsync, missedMapRenderFrames=$missedMapRenderFrames, frameTimeList=$frameTimeList, percentile50=$percentile50, percentile90=$percentile90, percentile95=$percentile95, percentile99=$percentile99)"
 
   /**
    * @return Returns true if the object is equal to the other object.
@@ -134,6 +167,9 @@ class RenderThreadStats private constructor(
     if (totalTime != other.totalTime) return false
     if (totalFrames != other.totalFrames) return false
     if (totalDroppedFrames != other.totalDroppedFrames) return false
+    if (totalSkippedVsync != other.totalSkippedVsync) return false
+    if (pacedSkippedVsync != other.pacedSkippedVsync) return false
+    if (missedMapRenderFrames != other.missedMapRenderFrames) return false
     if (percentile50 != other.percentile50) return false
     if (percentile90 != other.percentile90) return false
     if (percentile95 != other.percentile95) return false
@@ -150,6 +186,9 @@ class RenderThreadStats private constructor(
     totalTime,
     totalFrames,
     totalDroppedFrames,
+    totalSkippedVsync,
+    pacedSkippedVsync,
+    missedMapRenderFrames,
     percentile50,
     percentile90,
     percentile95,
@@ -160,6 +199,9 @@ class RenderThreadStats private constructor(
     private var totalTime: Long = 0
     private var totalFrames: Long = 0
     private var totalDroppedFrames: Long = 0
+    private var totalSkippedVsync: Long = 0
+    private var pacedSkippedVsync: Long = 0
+    private var missedMapRenderFrames: Long = 0
     private var frameTimeList: List<Double> = emptyList()
     private var percentile50: Double? = null
     private var percentile90: Double? = null
@@ -171,6 +213,10 @@ class RenderThreadStats private constructor(
     fun setTotalDroppedFrames(totalDroppedFrames: Long) =
       apply { this.totalDroppedFrames = totalDroppedFrames }
 
+    fun setTotalSkippedVsync(totalSkippedVsync: Long) = apply { this.totalSkippedVsync = totalSkippedVsync }
+    fun setPacedSkippedVsync(pacedSkippedVsync: Long) = apply { this.pacedSkippedVsync = pacedSkippedVsync }
+    fun setMissedMapRenderFrames(missedMapRenderFrames: Long) = apply { this.missedMapRenderFrames = missedMapRenderFrames }
+
     fun setFrameTimeList(frameTimeList: List<Double>) = apply { this.frameTimeList = frameTimeList }
     fun setPercentile50(percentile50: Double?) = apply { this.percentile50 = percentile50 }
     fun setPercentile90(percentile90: Double?) = apply { this.percentile90 = percentile90 }
@@ -182,6 +228,9 @@ class RenderThreadStats private constructor(
         totalTime,
         totalFrames,
         totalDroppedFrames,
+        totalSkippedVsync,
+        pacedSkippedVsync,
+        missedMapRenderFrames,
         frameTimeList,
         percentile50,
         percentile90,

maps-sdk/src/test/java/com/mapbox/maps/renderer/FpsManagerTest.kt

@@ -278,6 +278,77 @@ class FpsManagerTest {
     )
   }
 
+  @Test
+  fun pacingSkipsNowMatchesRenderedPattern() {
+    fpsManager.setUserRefreshRate(24)
+    pauseHandler()
+    val renderedPattern = mutableListOf<Boolean>()
+    val pacingSkipsPattern = mutableListOf<Int>()
+    idleHandler(vsyncCount = 10) {
+      val rendered = fpsManager.preRender(it)
+      renderedPattern.add(rendered)
+      pacingSkipsPattern.add(fpsManager.pacingSkipsNow)
+      fpsManager.postRender()
+    }
+    Assert.assertArrayEquals(
+      arrayOf(
+        false, false, true, false, true,
+        false, false, true, false, true
+      ),
+      renderedPattern.toTypedArray()
+    )
+    // pacingSkipsNow must be exactly 1 on ticks where preRender skipped rendering for pacing,
+    // and 0 on ticks where it actually rendered.
+    renderedPattern.forEachIndexed { index, rendered ->
+      Assert.assertEquals(
+        "pacingSkipsNow mismatch at tick $index",
+        if (rendered) 0 else 1,
+        pacingSkipsPattern[index]
+      )
+    }
+  }
+
+  @Test
+  fun unpacedRenderingReportsNoSkipsOrMisses() {
+    pauseHandler()
+    idleHandler(vsyncCount = 10) {
+      assert(fpsManager.preRender(it, recorderStarted = true))
+      Assert.assertEquals(0, fpsManager.pacingSkipsNow)
+      Assert.assertEquals(0, fpsManager.missedMapRenderFramesNow)
+      fpsManager.postRender()
+    }
+  }
+
+  @Test
+  fun missedMapRenderFramesNowOnSlowRender() {
+    // 60 Hz -> ONE_SECOND_NS(1_000_000_000) / 60 = 16_666_666 ns period (integer division),
+    // same computation FpsManager.setScreenRefreshRate performs internally (see
+    // `setScreenRefreshRate passes the raw refresh period to the performance hint reporter`).
+    val screenRefreshPeriodNs = 16_666_666L
+    val t0 = 1_000_000_000L
+    // Establish a baseline timestamp; recorderStarted=true forces updateFrameStats() to run even
+    // though no user refresh rate / fpsChangedListener is set (mirrors MapboxRenderThread.doFrame
+    // passing renderThreadStatsRecorder?.isRecording == true).
+    fpsManager.preRender(t0, recorderStarted = true)
+    Assert.assertEquals(0, fpsManager.missedMapRenderFramesNow)
+
+    // Jump far enough ahead (10 refresh periods) to guarantee a slow-render gap that exceeds the
+    // map-render-frame budget (unpaced, so budget == screenRefreshPeriodNs).
+    val slowFrameTimeNs = t0 + 10 * screenRefreshPeriodNs
+    fpsManager.preRender(slowFrameTimeNs, recorderStarted = true)
+
+    val frameElapsedTimeNs = slowFrameTimeNs - t0
+    val expectedMissedFrames = (frameElapsedTimeNs / (screenRefreshPeriodNs + 1_000_000L)).toInt()
+    Assert.assertTrue("Expected a positive missed map render frame delta", expectedMissedFrames > 0)
+    Assert.assertEquals(expectedMissedFrames, fpsManager.missedMapRenderFramesNow)
+    Assert.assertEquals(0, fpsManager.pacingSkipsNow)
+
+    // The very next, normally-spaced tick must reset missedMapRenderFramesNow back to 0 - proves
+    // updateFrameStats()'s per-tick reset, not just that the delta can go positive once.
+    fpsManager.preRender(slowFrameTimeNs + screenRefreshPeriodNs, recorderStarted = true)
+    Assert.assertEquals(0, fpsManager.missedMapRenderFramesNow)
+  }
+
   private fun mapIdleTest() {
     // pattern is [0, 1, 1, 1, 1]
     fpsManager.setUserRefreshRate(48)

maps-sdk/src/test/java/com/mapbox/maps/renderer/GLMapboxRenderThreadTest.kt

@@ -365,6 +365,29 @@ class GLMapboxRenderThreadTest {
     }
   }
 
+  @Test
+  @OptIn(MapboxExperimental::class)
+  fun doFrameWiresPacingAndMissedRenderCountsIntoRecorder() {
+    initRenderThread()
+    provideValidSurface()
+    // the shared initRenderThread() stub only covers preRender(any(), eq(false)); a started
+    // recorder makes MapboxRenderThread pass recorderStarted = true, which needs its own stub
+    every { fpsManager.preRender(any(), true) } returns true
+    every { fpsManager.skippedNow } returns 2
+    every { fpsManager.pacingSkipsNow } returns 1
+    every { fpsManager.missedMapRenderFramesNow } returns 3
+    val recorder = RenderThreadStatsRecorder()
+    recorder.start()
+    mapboxRenderThread.renderThreadStatsRecorder = recorder
+    pauseHandler()
+    mapboxRenderThread.queueRenderEvent(MapboxRenderThread.repaintRenderEvent)
+    idleHandler()
+    val stats = recorder.end()
+    assertEquals(2L, stats.totalSkippedVsync)
+    assertEquals(1L, stats.pacedSkippedVsync)
+    assertEquals(3L, stats.missedMapRenderFrames)
+  }
+
   @Test
   fun setUserRefreshRateTest() {
     initRenderThread()