Stabilize libgui RegionSamplingTests

libgui RegionSamplingTests fail on physical devices due to
incorrect sampled luma values. The incorrect region was
being sampled due to other active listeners that were not
cleared. Modify test API to get all existing active listeners,
cache them and clear the list to create a blank test slate, and
re-add the cached listeners to restore state after a test is done.

Bug: b/365708032
Test: atest RegionSamplingTest in libgui_test, libgui_test
Flag: EXEMPT, test fix
Change-Id: I70eb3bae070174b7db87ee16d8343bbc1e81bad0

Author: Melody Hsu

libs/gui/SurfaceComposerClient.cpp

@@ -3007,13 +3007,34 @@ status_t SurfaceComposerClient::addRegionSamplingListener(
     return statusTFromBinderStatus(status);
 }
 
+status_t SurfaceComposerClient::addRegionSamplingListenerWithStopLayerId(
+        const Rect& samplingArea, const int32_t stopLayerId,
+        const sp<IRegionSamplingListener>& listener) {
+    gui::ARect rect;
+    rect.left = samplingArea.left;
+    rect.top = samplingArea.top;
+    rect.right = samplingArea.right;
+    rect.bottom = samplingArea.bottom;
+    binder::Status status =
+            ComposerServiceAIDL::getComposerService()
+                    ->addRegionSamplingListenerWithStopLayerId(rect, stopLayerId, listener);
+    return statusTFromBinderStatus(status);
+}
+
 status_t SurfaceComposerClient::removeRegionSamplingListener(
         const sp<IRegionSamplingListener>& listener) {
     binder::Status status =
             ComposerServiceAIDL::getComposerService()->removeRegionSamplingListener(listener);
     return statusTFromBinderStatus(status);
 }
 
+status_t SurfaceComposerClient::getRegionSamplingListeners(
+        std::vector<gui::RegionSamplingDescriptor>* listeners) {
+    binder::Status status =
+            ComposerServiceAIDL::getComposerService()->getRegionSamplingListeners(listeners);
+    return statusTFromBinderStatus(status);
+}
+
 status_t SurfaceComposerClient::addFpsListener(int32_t taskId,
                                                const sp<gui::IFpsListener>& listener) {
     binder::Status status =

libs/gui/aidl/android/gui/ISurfaceComposer.aidl

@@ -47,6 +47,7 @@ import android.gui.IJankListener;
 import android.gui.LayerCaptureArgs;
 import android.gui.OverlayProperties;
 import android.gui.PullAtomData;
+import android.gui.RegionSamplingDescriptor;
 import android.gui.ScreenCaptureResults;
 import android.gui.ARect;
 import android.gui.SchedulingPolicy;
@@ -350,19 +351,42 @@ interface ISurfaceComposer {
      * The sampling area is bounded by both samplingArea and the given stopLayerHandle
      * (i.e., only layers behind the stop layer will be captured and sampled).
      *
-     * Multiple listeners may be provided so long as they have independent listeners.
-     * If multiple listeners are provided, the effective sampling region for each listener will
-     * be bounded by whichever stop layer has a lower Z value.
+     * Multiple listeners for the same sampling region may be provided so long as they have
+     * independent IRegionSamplingListener objects. If multiple listeners are provided, the
+     * effective sampling region for each listener will be bounded by whichever stop layer has
+     * a lower Z-value.
      *
      * Requires the same permissions as captureLayers and captureScreen.
      */
     void addRegionSamplingListener(in ARect samplingArea, @nullable IBinder stopLayerHandle, IRegionSamplingListener listener);
 
+    /**
+     * Registers a listener by stopLayerId to stream median luma updates from SurfaceFlinger.
+     *
+     * The sampling area is bounded by both samplingArea and the given stopLayerId
+     * (i.e., only layers behind the stop layer will be captured and sampled).
+     *
+     * Multiple listeners for the same sampling region may be provided so long as they have
+     * independent IRegionSamplingListener objects. If multiple listeners are provided, the
+     * effective sampling region for each listener will be bounded by whichever stop layer has
+     * a lower Z-value.
+     *
+     * Requires the ACCESS_SURFACE_FLINGER permission.
+     */
+    void addRegionSamplingListenerWithStopLayerId(in ARect samplingArea, int stopLayerId, IRegionSamplingListener listener);
+
     /**
      * Removes a listener that was streaming median luma updates from SurfaceFlinger.
      */
     void removeRegionSamplingListener(IRegionSamplingListener listener);
 
+    /**
+     * Gets all listeners that are streaming median luma updates from SurfaceFlinger.
+     *
+     * Requires the ACCESS_SURFACE_FLINGER permission.
+     */
+    List<RegionSamplingDescriptor> getRegionSamplingListeners();
+
     /**
      * Registers a listener that streams fps updates from SurfaceFlinger.
      *

libs/gui/aidl/android/gui/RegionSamplingDescriptor.aidl

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+ package android.gui;
+
+ import android.gui.ARect;
+ import android.gui.IRegionSamplingListener;
+
+ /** @hide */
+parcelable RegionSamplingDescriptor {
+    // Sampling area region
+    ARect area;
+
+    // All layers under this layer ID will be sampled from
+    int stopLayerId;
+
+    // Listener receiving median luma notifications
+    IRegionSamplingListener listener;
+}

libs/gui/include/gui/SurfaceComposerClient.h

@@ -45,6 +45,7 @@
 
 #include <android/gui/BnJankListener.h>
 #include <android/gui/ISurfaceComposerClient.h>
+#include <android/gui/RegionSamplingDescriptor.h>
 
 #include <gui/BufferReleaseChannel.h>
 #include <gui/CpuConsumer.h>
@@ -835,7 +836,11 @@ class SurfaceComposerClient : public RefBase
     static status_t addRegionSamplingListener(const Rect& samplingArea,
                                               const sp<IBinder>& stopLayerHandle,
                                               const sp<IRegionSamplingListener>& listener);
+    static status_t addRegionSamplingListenerWithStopLayerId(
+            const Rect& samplingArea, const int32_t stopLayerId,
+            const sp<IRegionSamplingListener>& listener);
     static status_t removeRegionSamplingListener(const sp<IRegionSamplingListener>& listener);
+    static status_t getRegionSamplingListeners(std::vector<gui::RegionSamplingDescriptor>*);
     static status_t addFpsListener(int32_t taskId, const sp<gui::IFpsListener>& listener);
     static status_t removeFpsListener(const sp<gui::IFpsListener>& listener);
     static status_t addTunnelModeEnabledListener(

libs/gui/tests/RegionSampling_test.cpp

@@ -212,6 +212,23 @@ struct RegionSamplingTest : ::testing::Test {
                 .setPosition(mTopLayer, 0, 0)
                 .show(mBackgroundLayer)
                 .apply();
+
+        // Cache any existing listeners that could impact luma sampling test results
+        sp<gui::ISurfaceComposer> composer = ComposerServiceAIDL::getComposerService();
+        composer->getRegionSamplingListeners(&mExistingListeners);
+        for (const auto& descriptor : mExistingListeners) {
+            composer->removeRegionSamplingListener(descriptor.listener);
+        }
+    }
+
+    void TearDown() override {
+        // Restore device state by re-adding listeners that were present prior to the test run
+        sp<gui::ISurfaceComposer> composer = ComposerServiceAIDL::getComposerService();
+        for (const auto& descriptor : mExistingListeners) {
+            composer->addRegionSamplingListenerWithStopLayerId(descriptor.area,
+                                                               descriptor.stopLayerId,
+                                                               descriptor.listener);
+        }
     }
 
     void fill_render(uint32_t rgba_value) {
@@ -234,6 +251,7 @@ struct RegionSamplingTest : ::testing::Test {
     sp<SurfaceControl> mBackgroundLayer;
     sp<SurfaceControl> mContentLayer;
     sp<SurfaceControl> mTopLayer;
+    std::vector<gui::RegionSamplingDescriptor> mExistingListeners;
 
     uint32_t const rgba_green = 0xFF00FF00;
     float const luma_green = 0.7152;

libs/gui/tests/Surface_test.cpp

@@ -858,11 +858,22 @@ class FakeSurfaceComposerAIDL : public gui::ISurfaceComposer {
         return binder::Status::ok();
     }
 
+    binder::Status addRegionSamplingListenerWithStopLayerId(
+            const gui::ARect& /*samplingArea*/, const int32_t /*stopLayerId*/,
+            const sp<gui::IRegionSamplingListener>& /*listener*/) override {
+        return binder::Status::ok();
+    }
+
     binder::Status removeRegionSamplingListener(
             const sp<gui::IRegionSamplingListener>& /*listener*/) override {
         return binder::Status::ok();
     }
 
+    binder::Status getRegionSamplingListeners(
+            std::vector<gui::RegionSamplingDescriptor>*) override {
+        return binder::Status::ok();
+    }
+
     binder::Status addFpsListener(int32_t /*taskId*/,
                                   const sp<gui::IFpsListener>& /*listener*/) override {
         return binder::Status::ok();

services/surfaceflinger/RegionSamplingThread.cpp

@@ -141,6 +141,25 @@ void RegionSamplingThread::removeListener(const sp<IRegionSamplingListener>& lis
     mDescriptors.erase(wp<IBinder>(IInterface::asBinder(listener)));
 }
 
+const std::vector<gui::RegionSamplingDescriptor> RegionSamplingThread::getListeners() {
+    std::lock_guard lock(mSamplingMutex);
+    std::vector<gui::RegionSamplingDescriptor> listeners;
+    for (const auto& [listener, descriptor] : mDescriptors) {
+        gui::ARect guiRect;
+        guiRect.left = descriptor.area.left;
+        guiRect.top = descriptor.area.top;
+        guiRect.right = descriptor.area.right;
+        guiRect.bottom = descriptor.area.bottom;
+
+        gui::RegionSamplingDescriptor guiDescriptor;
+        guiDescriptor.area = guiRect;
+        guiDescriptor.stopLayerId = descriptor.stopLayerId;
+        guiDescriptor.listener = descriptor.listener;
+        listeners.emplace_back(guiDescriptor);
+    }
+    return listeners;
+}
+
 void RegionSamplingThread::checkForStaleLuma() {
     std::lock_guard lock(mThreadControlMutex);
 

services/surfaceflinger/RegionSamplingThread.h

@@ -18,6 +18,7 @@
 
 #include <android-base/thread_annotations.h>
 #include <android/gui/IRegionSamplingListener.h>
+#include <android/gui/RegionSamplingDescriptor.h>
 #include <binder/IBinder.h>
 #include <renderengine/ExternalTexture.h>
 #include <ui/GraphicBuffer.h>
@@ -77,6 +78,8 @@ class RegionSamplingThread : public IBinder::DeathRecipient {
                      const sp<IRegionSamplingListener>& listener);
     // Remove the listener to stop receiving median luma notifications.
     void removeListener(const sp<IRegionSamplingListener>& listener);
+    // Gets all listeners that are receiving median luma notifications.
+    const std::vector<gui::RegionSamplingDescriptor> getListeners();
 
     // Notifies sampling engine that composition is done and new content is
     // available, and the deadline for the sampling work on the main thread to

services/surfaceflinger/SurfaceFlinger.cpp

@@ -2056,6 +2056,18 @@ status_t SurfaceFlinger::addRegionSamplingListener(const Rect& samplingArea,
     return NO_ERROR;
 }
 
+status_t SurfaceFlinger::addRegionSamplingListenerWithStopLayerId(
+        const Rect& samplingArea, const int32_t stopLayerId,
+        const sp<IRegionSamplingListener>& listener) {
+    if (!listener || samplingArea == Rect::INVALID_RECT || samplingArea.isEmpty()) {
+        return BAD_VALUE;
+    }
+
+    mRegionSamplingThread->addListener(samplingArea,
+                                       stopLayerId ? stopLayerId : UNASSIGNED_LAYER_ID, listener);
+    return NO_ERROR;
+}
+
 status_t SurfaceFlinger::removeRegionSamplingListener(const sp<IRegionSamplingListener>& listener) {
     if (!listener) {
         return BAD_VALUE;
@@ -2064,6 +2076,12 @@ status_t SurfaceFlinger::removeRegionSamplingListener(const sp<IRegionSamplingLi
     return NO_ERROR;
 }
 
+status_t SurfaceFlinger::getRegionSamplingListeners(
+        std::vector<gui::RegionSamplingDescriptor>* listeners) const {
+    *listeners = mRegionSamplingThread->getListeners();
+    return NO_ERROR;
+}
+
 status_t SurfaceFlinger::addFpsListener(int32_t taskId, const sp<gui::IFpsListener>& listener) {
     if (!listener) {
         return BAD_VALUE;
@@ -9359,6 +9377,22 @@ binder::Status SurfaceComposerAIDL::addRegionSamplingListener(
     return binderStatusFromStatusT(status);
 }
 
+binder::Status SurfaceComposerAIDL::addRegionSamplingListenerWithStopLayerId(
+        const gui::ARect& samplingArea, const int32_t stopLayerId,
+        const sp<gui::IRegionSamplingListener>& listener) {
+    status_t status = checkAccessPermission();
+    if (status != OK) {
+        return binderStatusFromStatusT(status);
+    }
+    android::Rect rect;
+    rect.left = samplingArea.left;
+    rect.top = samplingArea.top;
+    rect.right = samplingArea.right;
+    rect.bottom = samplingArea.bottom;
+    status = mFlinger->addRegionSamplingListenerWithStopLayerId(rect, stopLayerId, listener);
+    return binderStatusFromStatusT(status);
+}
+
 binder::Status SurfaceComposerAIDL::removeRegionSamplingListener(
         const sp<gui::IRegionSamplingListener>& listener) {
     status_t status = checkReadFrameBufferPermission();
@@ -9368,6 +9402,15 @@ binder::Status SurfaceComposerAIDL::removeRegionSamplingListener(
     return binderStatusFromStatusT(status);
 }
 
+binder::Status SurfaceComposerAIDL::getRegionSamplingListeners(
+        std::vector<gui::RegionSamplingDescriptor>* listeners) {
+    status_t status = checkAccessPermission();
+    if (status == OK) {
+        status = mFlinger->getRegionSamplingListeners(listeners);
+    }
+    return binderStatusFromStatusT(status);
+}
+
 binder::Status SurfaceComposerAIDL::addFpsListener(int32_t taskId,
                                                    const sp<gui::IFpsListener>& listener) {
     status_t status = checkReadFrameBufferPermission();

services/surfaceflinger/SurfaceFlinger.h

@@ -602,7 +602,12 @@ class SurfaceFlinger : public BnSurfaceComposer,
     status_t isWideColorDisplay(const sp<IBinder>& displayToken, bool* outIsWideColorDisplay) const;
     status_t addRegionSamplingListener(const Rect& samplingArea, const sp<IBinder>& stopLayerHandle,
                                        const sp<IRegionSamplingListener>& listener);
+    status_t addRegionSamplingListenerWithStopLayerId(const Rect& samplingArea,
+                                                      const int32_t stopLayerId,
+                                                      const sp<IRegionSamplingListener>& listener);
     status_t removeRegionSamplingListener(const sp<IRegionSamplingListener>& listener);
+    status_t getRegionSamplingListeners(
+            std::vector<gui::RegionSamplingDescriptor>* listeners) const;
     status_t addFpsListener(int32_t taskId, const sp<gui::IFpsListener>& listener);
     status_t removeFpsListener(const sp<gui::IFpsListener>& listener);
     status_t addTunnelModeEnabledListener(const sp<gui::ITunnelModeEnabledListener>& listener);
@@ -1648,8 +1653,12 @@ class SurfaceComposerAIDL : public gui::BnSurfaceComposer {
     binder::Status addRegionSamplingListener(
             const gui::ARect& samplingArea, const sp<IBinder>& stopLayerHandle,
             const sp<gui::IRegionSamplingListener>& listener) override;
+    binder::Status addRegionSamplingListenerWithStopLayerId(
+            const gui::ARect& samplingArea, const int32_t stopLayerId,
+            const sp<gui::IRegionSamplingListener>& listener) override;
     binder::Status removeRegionSamplingListener(
             const sp<gui::IRegionSamplingListener>& listener) override;
+    binder::Status getRegionSamplingListeners(std::vector<gui::RegionSamplingDescriptor>*) override;
     binder::Status addFpsListener(int32_t taskId, const sp<gui::IFpsListener>& listener) override;
     binder::Status removeFpsListener(const sp<gui::IFpsListener>& listener) override;
     binder::Status addTunnelModeEnabledListener(