feat(replay): Capture SurfaceView content (experimental)

romtsn · claude · romtsn · commit df58de195ac8 · 2026-04-23T22:17:31.000+02:00
SurfaceView (used by Unity, video players, maps, and similar) renders to
a separate Surface that is composited by SurfaceFlinger outside of the
View hierarchy. PixelCopy.request(window, ...) only captures the Window
surface, so SurfaceView regions appeared as transparent/black holes in
Session Replay recordings.

When the experimental option options.sessionReplay.isCaptureSurfaceViews
is enabled, each visible SurfaceView is now captured separately via
PixelCopy.request(surfaceView, ...) and composited onto the screenshot
using PorterDuff.DST_OVER, so the SurfaceView content draws behind the
Window content (which has transparent holes where the SurfaceViews are).

Because SurfaceView redraws do not trigger ViewTreeObserver.OnDrawListener,
the recorder bypasses the contentChanged guard when SurfaceViews are
present, so subsequent frames are re-captured at the configured frame rate
instead of reusing the last screenshot.

The option defaults to false to preserve existing behavior.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## 8.40.0
 
+### Features
+
+- Session Replay: experimental support for capturing `SurfaceView` content (e.g. Unity, video players, maps) ([#5333](https://github.com/getsentry/sentry-java/pull/5333))
+  - To enable, set `options.sessionReplay.isCaptureSurfaceViews = true`
+
 ### Fixes
 
 - Fix `NoSuchMethodError` for `LayoutCoordinates.localBoundingBoxOf$default` on Compose touch dispatch with AGP 8.13 and `minSdk < 24` ([#5302](https://github.com/getsentry/sentry-java/pull/5302))
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
@@ -70,7 +70,7 @@ internal class ScreenshotRecorder(
       )
     }
 
-    if (!contentChanged.get()) {
+    if (!contentChanged.get() && !screenshotStrategy.hasSurfaceViews()) {
       screenshotStrategy.emitLastScreenshot()
       return
     }
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/screenshot/PixelCopyStrategy.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/screenshot/PixelCopyStrategy.kt
@@ -2,7 +2,13 @@ package io.sentry.android.replay.screenshot
 
 import android.annotation.SuppressLint
 import android.graphics.Bitmap
+import android.graphics.Canvas
 import android.graphics.Matrix
+import android.graphics.Paint
+import android.graphics.PorterDuff
+import android.graphics.PorterDuffXfermode
+import android.graphics.Rect
+import android.graphics.RectF
 import android.view.PixelCopy
 import android.view.View
 import io.sentry.SentryLevel.DEBUG
@@ -19,6 +25,7 @@ import io.sentry.android.replay.util.ReplayRunnable
 import io.sentry.android.replay.util.traverse
 import io.sentry.android.replay.viewhierarchy.ViewHierarchyNode
 import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
 import kotlin.LazyThreadSafetyMode.NONE
 
 @SuppressLint("UseKtx")
@@ -40,6 +47,16 @@ internal class PixelCopyStrategy(
   private val maskRenderer = MaskRenderer()
   private val contentChanged = AtomicBoolean(false)
   private val isClosed = AtomicBoolean(false)
+  private val hasSurfaceViews = AtomicBoolean(false)
+  private val dstOverPaint by
+    lazy(NONE) { Paint().apply { xfermode = PorterDuffXfermode(PorterDuff.Mode.DST_OVER) } }
+  private val screenshotCanvas by lazy(NONE) { Canvas(screenshot) }
+  private val tmpSrcRect = Rect()
+  private val tmpDstRect = RectF()
+  private val windowLocation = IntArray(2)
+  private val svLocation = IntArray(2)
+
+  private class SurfaceViewCapture(val bitmap: Bitmap, val x: Int, val y: Int)
 
   @SuppressLint("NewApi")
   override fun capture(root: View) {
@@ -81,31 +98,22 @@ internal class PixelCopyStrategy(
 
           // TODO: disableAllMasking here and dont traverse?
           val viewHierarchy = ViewHierarchyNode.fromView(root, null, 0, options.sessionReplay)
-          root.traverse(viewHierarchy, options.sessionReplay, options.logger)
-
-          executor.submit(
-            ReplayRunnable("screenshot_recorder.mask") {
-              if (isClosed.get() || screenshot.isRecycled) {
-                options.logger.log(DEBUG, "PixelCopyStrategy is closed, skipping masking")
-                return@ReplayRunnable
-              }
+          val captureSurfaceViewsEnabled = options.sessionReplay.isCaptureSurfaceViews
+          val surfaceViewNodes =
+            if (captureSurfaceViewsEnabled) {
+              mutableListOf<ViewHierarchyNode.SurfaceViewHierarchyNode>()
+            } else {
+              null
+            }
+          root.traverse(viewHierarchy, options.sessionReplay, options.logger, surfaceViewNodes)
 
-              val debugMasks = maskRenderer.renderMasks(screenshot, viewHierarchy, prescaledMatrix)
+          hasSurfaceViews.set(surfaceViewNodes?.isNotEmpty() == true)
 
-              if (options.replayController.isDebugMaskingOverlayEnabled()) {
-                mainLooperHandler.post {
-                  if (debugOverlayDrawable.callback == null) {
-                    root.overlay.add(debugOverlayDrawable)
-                  }
-                  debugOverlayDrawable.updateMasks(debugMasks)
-                  root.postInvalidate()
-                }
-              }
-              screenshotRecorderCallback?.onScreenshotRecorded(screenshot)
-              lastCaptureSuccessful.set(true)
-              contentChanged.set(false)
-            }
-          )
+          if (surfaceViewNodes.isNullOrEmpty()) {
+            submitMaskingAndCallback(root, viewHierarchy)
+          } else {
+            captureSurfaceViews(root, surfaceViewNodes, viewHierarchy)
+          }
         },
         mainLooperHandler.handler,
       )
@@ -115,6 +123,123 @@ internal class PixelCopyStrategy(
     }
   }
 
+  private fun submitMaskingAndCallback(root: View, viewHierarchy: ViewHierarchyNode) {
+    executor.submit(
+      ReplayRunnable("screenshot_recorder.mask") { applyMaskingAndNotify(root, viewHierarchy) }
+    )
+  }
+
+  private fun applyMaskingAndNotify(root: View, viewHierarchy: ViewHierarchyNode) {
+    if (isClosed.get() || screenshot.isRecycled) {
+      options.logger.log(DEBUG, "PixelCopyStrategy is closed, skipping masking")
+      return
+    }
+
+    val debugMasks = maskRenderer.renderMasks(screenshot, viewHierarchy, prescaledMatrix)
+
+    if (options.replayController.isDebugMaskingOverlayEnabled()) {
+      mainLooperHandler.post {
+        if (debugOverlayDrawable.callback == null) {
+          root.overlay.add(debugOverlayDrawable)
+        }
+        debugOverlayDrawable.updateMasks(debugMasks)
+        root.postInvalidate()
+      }
+    }
+    screenshotRecorderCallback?.onScreenshotRecorded(screenshot)
+    lastCaptureSuccessful.set(true)
+    contentChanged.set(false)
+  }
+
+  @SuppressLint("NewApi")
+  private fun captureSurfaceViews(
+    root: View,
+    surfaceViewNodes: List<ViewHierarchyNode.SurfaceViewHierarchyNode>,
+    viewHierarchy: ViewHierarchyNode,
+  ) {
+    root.getLocationOnScreen(windowLocation)
+
+    val captures = arrayOfNulls<SurfaceViewCapture>(surfaceViewNodes.size)
+    val remaining = AtomicInteger(surfaceViewNodes.size)
+
+    fun onCaptureComplete() {
+      if (remaining.decrementAndGet() == 0) {
+        compositeSurfaceViewsAndMask(root, captures, viewHierarchy)
+      }
+    }
+
+    for ((index, node) in surfaceViewNodes.withIndex()) {
+      val surfaceView = node.surfaceViewRef.get()
+      if (surfaceView == null || !surfaceView.holder.surface.isValid) {
+        onCaptureComplete()
+        continue
+      }
+
+      try {
+        val svBitmap =
+          Bitmap.createBitmap(surfaceView.width, surfaceView.height, Bitmap.Config.ARGB_8888)
+
+        surfaceView.getLocationOnScreen(svLocation)
+        val capturedX = svLocation[0]
+        val capturedY = svLocation[1]
+
+        PixelCopy.request(
+          surfaceView,
+          svBitmap,
+          { copyResult: Int ->
+            if (copyResult == PixelCopy.SUCCESS) {
+              captures[index] = SurfaceViewCapture(svBitmap, capturedX, capturedY)
+            } else {
+              svBitmap.recycle()
+              options.logger.log(INFO, "Failed to capture SurfaceView: %d", copyResult)
+            }
+            onCaptureComplete()
+          },
+          mainLooperHandler.handler,
+        )
+      } catch (e: Throwable) {
+        options.logger.log(WARNING, "Failed to capture SurfaceView", e)
+        onCaptureComplete()
+      }
+    }
+  }
+
+  private fun compositeSurfaceViewsAndMask(
+    root: View,
+    captures: Array<SurfaceViewCapture?>,
+    viewHierarchy: ViewHierarchyNode,
+  ) {
+    executor.submit(
+      ReplayRunnable("screenshot_recorder.composite") {
+        if (isClosed.get() || screenshot.isRecycled) {
+          options.logger.log(DEBUG, "PixelCopyStrategy is closed, skipping compositing")
+          return@ReplayRunnable
+        }
+
+        for (capture in captures) {
+          if (capture == null) continue
+          if (capture.bitmap.isRecycled) continue
+
+          val left = (capture.x - windowLocation[0]) * config.scaleFactorX
+          val top = (capture.y - windowLocation[1]) * config.scaleFactorY
+          tmpSrcRect.set(0, 0, capture.bitmap.width, capture.bitmap.height)
+          tmpDstRect.set(
+            left,
+            top,
+            left + capture.bitmap.width * config.scaleFactorX,
+            top + capture.bitmap.height * config.scaleFactorY,
+          )
+
+          // DST_OVER draws the SurfaceView content behind the existing Window content
+          screenshotCanvas.drawBitmap(capture.bitmap, tmpSrcRect, tmpDstRect, dstOverPaint)
+          capture.bitmap.recycle()
+        }
+
+        applyMaskingAndNotify(root, viewHierarchy)
+      }
+    )
+  }
+
   override fun onContentChanged() {
     contentChanged.set(true)
   }
@@ -123,6 +248,10 @@ internal class PixelCopyStrategy(
     return lastCaptureSuccessful.get()
   }
 
+  override fun hasSurfaceViews(): Boolean {
+    return hasSurfaceViews.get()
+  }
+
   override fun emitLastScreenshot() {
     if (lastCaptureSuccessful() && !screenshot.isRecycled) {
       screenshotRecorderCallback?.onScreenshotRecorded(screenshot)
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/screenshot/ScreenshotStrategy.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/screenshot/ScreenshotStrategy.kt
@@ -12,4 +12,11 @@ internal interface ScreenshotStrategy {
   fun lastCaptureSuccessful(): Boolean
 
   fun emitLastScreenshot()
+
+  /**
+   * Whether the last capture detected SurfaceViews that render independently of the View tree. When
+   * true, the recorder bypasses the contentChanged guard since SurfaceView redraws don't trigger
+   * ViewTreeObserver.OnDrawListener.
+   */
+  fun hasSurfaceViews(): Boolean = false
 }
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/util/Views.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/util/Views.kt
@@ -34,10 +34,12 @@ import java.lang.NullPointerException
  * @param logger Logger for error reporting during Compose traversal
  */
 @SuppressLint("UseKtx")
+@JvmOverloads
 internal fun View.traverse(
   parentNode: ViewHierarchyNode,
   options: SentryMaskingOptions,
   logger: ILogger,
+  surfaceViewNodes: MutableList<ViewHierarchyNode.SurfaceViewHierarchyNode>? = null,
 ) {
   if (this !is ViewGroup) {
     return
@@ -59,7 +61,14 @@ internal fun View.traverse(
     if (child != null) {
       val childNode = ViewHierarchyNode.fromView(child, parentNode, indexOfChild(child), options)
       childNodes.add(childNode)
-      child.traverse(childNode, options, logger)
+      if (
+        surfaceViewNodes != null &&
+          childNode is ViewHierarchyNode.SurfaceViewHierarchyNode &&
+          childNode.isVisible
+      ) {
+        surfaceViewNodes.add(childNode)
+      }
+      child.traverse(childNode, options, logger, surfaceViewNodes)
     }
   }
   parentNode.children = childNodes
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/viewhierarchy/ViewHierarchyNode.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/viewhierarchy/ViewHierarchyNode.kt
@@ -3,6 +3,7 @@ package io.sentry.android.replay.viewhierarchy
 import android.annotation.SuppressLint
 import android.annotation.TargetApi
 import android.graphics.Rect
+import android.view.SurfaceView
 import android.view.View
 import android.view.ViewParent
 import android.widget.ImageView
@@ -15,6 +16,7 @@ import io.sentry.android.replay.util.isMaskable
 import io.sentry.android.replay.util.isVisibleToUser
 import io.sentry.android.replay.util.toOpaque
 import io.sentry.android.replay.util.totalPaddingTopSafe
+import java.lang.ref.WeakReference
 
 @SuppressLint("UseRequiresApi")
 @TargetApi(26)
@@ -121,6 +123,34 @@ internal sealed class ViewHierarchyNode(
       visibleRect,
     )
 
+  class SurfaceViewHierarchyNode(
+    val surfaceViewRef: WeakReference<SurfaceView>,
+    x: Float,
+    y: Float,
+    width: Int,
+    height: Int,
+    elevation: Float,
+    distance: Int,
+    parent: ViewHierarchyNode? = null,
+    shouldMask: Boolean = false,
+    isImportantForContentCapture: Boolean = false,
+    isVisible: Boolean = false,
+    visibleRect: Rect? = null,
+  ) :
+    ViewHierarchyNode(
+      x,
+      y,
+      width,
+      height,
+      elevation,
+      distance,
+      parent,
+      shouldMask,
+      isImportantForContentCapture,
+      isVisible,
+      visibleRect,
+    )
+
   /**
    * Basically replicating this:
    * https://developer.android.com/reference/android/view/View#isImportantForContentCapture() but
@@ -379,6 +409,24 @@ internal sealed class ViewHierarchyNode(
             visibleRect = visibleRect,
           )
         }
+
+        is SurfaceView -> {
+          parent?.setImportantForCaptureToAncestors(true)
+          return SurfaceViewHierarchyNode(
+            surfaceViewRef = WeakReference(view),
+            x = view.x,
+            y = view.y,
+            width = view.width,
+            height = view.height,
+            elevation = (parent?.elevation ?: 0f) + view.elevation,
+            distance = distance,
+            parent = parent,
+            shouldMask = shouldMask,
+            isImportantForContentCapture = true,
+            isVisible = isVisible,
+            visibleRect = visibleRect,
+          )
+        }
       }
 
       return GenericViewHierarchyNode(
diff --git a/sentry/src/main/java/io/sentry/SentryReplayOptions.java b/sentry/src/main/java/io/sentry/SentryReplayOptions.java
@@ -146,6 +146,14 @@ public enum SentryReplayQuality {
   @ApiStatus.Experimental
   private @NotNull ScreenshotStrategyType screenshotStrategy = ScreenshotStrategyType.PIXEL_COPY;
 
+  /**
+   * Whether to capture SurfaceView content (e.g. Unity, video players, maps) during replay
+   * recording. When enabled, each SurfaceView in the view hierarchy will be captured separately via
+   * PixelCopy and composited onto the screenshot. Only applies when {@link #screenshotStrategy} is
+   * {@link ScreenshotStrategyType#PIXEL_COPY}. Default is disabled.
+   */
+  @ApiStatus.Experimental private boolean captureSurfaceViews = false;
+
   /**
    * Capture request and response details for XHR and fetch requests that match the given URLs.
    * Default is empty (network details not collected).
@@ -383,6 +391,26 @@ public void setScreenshotStrategy(final @NotNull ScreenshotStrategyType screensh
     this.screenshotStrategy = screenshotStrategy;
   }
 
+  /**
+   * Whether SurfaceView capture is enabled. See {@link #captureSurfaceViews}.
+   *
+   * @return true if SurfaceView capture is enabled
+   */
+  @ApiStatus.Experimental
+  public boolean isCaptureSurfaceViews() {
+    return captureSurfaceViews;
+  }
+
+  /**
+   * Enables or disables SurfaceView capture. See {@link #captureSurfaceViews}.
+   *
+   * @param captureSurfaceViews true to enable SurfaceView capture
+   */
+  @ApiStatus.Experimental
+  public void setCaptureSurfaceViews(final boolean captureSurfaceViews) {
+    this.captureSurfaceViews = captureSurfaceViews;
+  }
+
   /**
    * Gets the list of URLs for which network request and response details should be captured.
    *

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,7 @@ internal class ScreenshotRecorder(`
`70`	`70`	`)`
`71`	`71`	`}`
`72`	`72`
`73`		`- if (!contentChanged.get()) {`
	`73`	`+ if (!contentChanged.get() && !screenshotStrategy.hasSurfaceViews()) {`
`74`	`74`	`screenshotStrategy.emitLastScreenshot()`
`75`	`75`	`return`
`76`	`76`	`}`