Ensure getParentSurfaceControl and getSurfaceControl return valid or null SC

Many places (like SurfaceAnimator#reset) expect that these SC will be valid or
null, but various implementors of Animatable were not fulfilling this contract.
Fulfill the contract and update the java-doc. Since everyone follows function
documentation this will never happen again.

Test: Existing tests pass. go/wm-smoke
Bug: 129949355
Change-Id: I5acb6b3209158c4c5b258a06c5d60d9e06bb6db1

services/core/java/com/android/server/wm/Dimmer.java

@@ -130,6 +130,7 @@ class Dimmer {
             mSurfaceAnimator = new SurfaceAnimator(dimAnimatable, () -> {
                 if (!mDimming) {
                     dimAnimatable.getPendingTransaction().remove(mDimLayer);
+                    mDimLayer = null;
                 }
             }, mHost.mWmService);
         }

services/core/java/com/android/server/wm/SurfaceAnimator.java

@@ -410,11 +410,13 @@ class SurfaceAnimator {
 
         /**
          * @return The surface of the object to be animated.
+         *         This SurfaceControl must be valid if non-null.
          */
         @Nullable SurfaceControl getSurfaceControl();
 
         /**
          * @return The parent of the surface object to be animated.
+         *         This SurfaceControl must be valid if non-null.
          */
         @Nullable SurfaceControl getParentSurfaceControl();
 

services/core/java/com/android/server/wm/TaskScreenshotAnimatable.java

@@ -93,6 +93,7 @@ class TaskScreenshotAnimatable implements SurfaceAnimator.Animatable {
     @Override
     public void onAnimationLeashDestroyed(SurfaceControl.Transaction t) {
         t.remove(mSurfaceControl);
+        mSurfaceControl = null;
     }
 
     @Override

services/core/java/com/android/server/wm/WindowContainer.java

@@ -1003,7 +1003,10 @@ class WindowContainer<E extends WindowContainer> extends ConfigurationContainer<
         return p.makeChildSurface(child)
                 .setParent(mSurfaceControl);
     }
-
+    /*
+     * @return The SurfaceControl parent for this containers SurfaceControl.
+     *         The SurfaceControl must be valid if non-null.
+     */
     @Override
     public SurfaceControl getParentSurfaceControl() {
         final WindowContainer parent = getParent();
@@ -1210,6 +1213,10 @@ class WindowContainer<E extends WindowContainer> extends ConfigurationContainer<
         }
     }
 
+    /**
+     * @return The SurfaceControl for this container.
+     *         The SurfaceControl must be valid if non-null.
+     */
     @Override
     public SurfaceControl getSurfaceControl() {
         return mSurfaceControl;