Cleanup/document Shaders for UI rendering module

Bug: 156636925
Test: make

Remove UnsupportedAppUsage false-positives from Shader and BitmapShader.

Change public/package-protected methods that should only be called by
subclasses to protected and mark them @hide.

Document why other @hide methods must be @hide.

Remove unnecessary if statement in BitmapShader constructor.

Change-Id: If3e87c45cbbab1df180387dd6ccfda1ec2ecb153

graphics/java/android/graphics/BitmapShader.java

@@ -17,7 +17,6 @@
 package android.graphics;
 
 import android.annotation.NonNull;
-import android.compat.annotation.UnsupportedAppUsage;
 
 /**
  * Shader used to draw a bitmap as a texture. The bitmap can be repeated or
@@ -26,15 +25,10 @@ import android.compat.annotation.UnsupportedAppUsage;
 public class BitmapShader extends Shader {
     /**
      * Prevent garbage collection.
-     * @hide
      */
-    @SuppressWarnings({"FieldCanBeLocal", "UnusedDeclaration"})
-    @UnsupportedAppUsage
-    public Bitmap mBitmap;
+    /*package*/ Bitmap mBitmap;
 
-    @UnsupportedAppUsage
     private int mTileX;
-    @UnsupportedAppUsage
     private int mTileY;
 
     /**
@@ -52,16 +46,14 @@ public class BitmapShader extends Shader {
         if (bitmap == null) {
             throw new IllegalArgumentException("Bitmap must be non-null");
         }
-        if (bitmap == mBitmap && tileX == mTileX && tileY == mTileY) {
-            return;
-        }
         mBitmap = bitmap;
         mTileX = tileX;
         mTileY = tileY;
     }
 
+    /** @hide */
     @Override
-    long createNativeInstance(long nativeMatrix) {
+    protected long createNativeInstance(long nativeMatrix) {
         return nativeCreate(nativeMatrix, mBitmap.getNativeInstance(), mTileX, mTileY);
     }
 

graphics/java/android/graphics/ComposeShader.java

@@ -84,8 +84,9 @@ public class ComposeShader extends Shader {
         mPorterDuffMode = nativeMode;
     }
 
+    /** @hide */
     @Override
-    long createNativeInstance(long nativeMatrix) {
+    protected long createNativeInstance(long nativeMatrix) {
         mNativeInstanceShaderA = mShaderA.getNativeInstance();
         mNativeInstanceShaderB = mShaderB.getNativeInstance();
         return nativeCreate(nativeMatrix,

graphics/java/android/graphics/LinearGradient.java

@@ -151,8 +151,9 @@ public class LinearGradient extends Shader {
         this(x0, y0, x1, y1, new long[] {color0, color1}, null, tile);
     }
 
+    /** @hide */
     @Override
-    long createNativeInstance(long nativeMatrix) {
+    protected long createNativeInstance(long nativeMatrix) {
         return nativeCreate(nativeMatrix, mX0, mY0, mX1, mY1,
                 mColorLongs, mPositions, mTileMode.nativeInt,
                 colorSpace().getNativeInstance());

graphics/java/android/graphics/RadialGradient.java

@@ -147,8 +147,9 @@ public class RadialGradient extends Shader {
         this(centerX, centerY, radius, new long[] {centerColor, edgeColor}, null, tileMode);
     }
 
+    /** @hide */
     @Override
-    long createNativeInstance(long nativeMatrix) {
+    protected long createNativeInstance(long nativeMatrix) {
         return nativeCreate(nativeMatrix, mX, mY, mRadius,
                 mColorLongs, mPositions, mTileMode.nativeInt,
                 colorSpace().getNativeInstance());

graphics/java/android/graphics/RuntimeShader.java

@@ -74,8 +74,9 @@ public class RuntimeShader extends Shader {
         discardNativeInstance();
     }
 
+    /** @hide */
     @Override
-    long createNativeInstance(long nativeMatrix) {
+    protected long createNativeInstance(long nativeMatrix) {
         return nativeCreate(mNativeInstanceRuntimeShaderFactory, nativeMatrix, mUniforms,
                 colorSpace().getNativeInstance(), mIsOpaque);
     }

graphics/java/android/graphics/Shader.java

@@ -20,12 +20,11 @@ import android.annotation.ColorInt;
 import android.annotation.ColorLong;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
-import android.compat.annotation.UnsupportedAppUsage;
 
 import libcore.util.NativeAllocationRegistry;
 
 /**
- * Shader is the based class for objects that return horizontal spans of colors
+ * Shader is the base class for objects that return horizontal spans of colors
  * during drawing. A subclass of Shader is installed in a Paint calling
  * paint.setShader(shader). After that any object (other than a bitmap) that is
  * drawn with that paint will get its color(s) from the shader.
@@ -47,9 +46,9 @@ public class Shader {
     }
 
     /**
-     * @hide
+     * @hide Only to be used by subclasses in android.graphics.
      */
-    public Shader(ColorSpace colorSpace) {
+    protected Shader(ColorSpace colorSpace) {
         mColorSpace = colorSpace;
         if (colorSpace == null) {
             throw new IllegalArgumentException(
@@ -63,7 +62,7 @@ public class Shader {
     private final ColorSpace mColorSpace;
 
     /**
-     * @hide
+     * @hide Only to be used by subclasses in android.graphics.
      */
     protected ColorSpace colorSpace() {
         return mColorSpace;
@@ -97,11 +96,10 @@ public class Shader {
          * mirror images so that adjacent images always seam
          */
         MIRROR  (2);
-    
+
         TileMode(int nativeInt) {
             this.nativeInt = nativeInt;
         }
-        @UnsupportedAppUsage
         final int nativeInt;
     }
 
@@ -142,11 +140,16 @@ public class Shader {
         }
     }
 
-    long createNativeInstance(long nativeMatrix) {
+    /**
+     *  @hide Only to be used by subclasses in the graphics package.
+     */
+    protected long createNativeInstance(long nativeMatrix) {
         return 0;
     }
 
-    /** @hide */
+    /**
+     *  @hide Only to be used by subclasses in the graphics package.
+     */
     protected final void discardNativeInstance() {
         if (mNativeInstance != 0) {
             mCleaner.run();
@@ -158,14 +161,15 @@ public class Shader {
     /**
      * Callback for subclasses to call {@link #discardNativeInstance()} if the most recently
      * constructed native instance is no longer valid.
-     * @hide
+     *  @hide Only to be used by subclasses in the graphics package.
      */
     protected void verifyNativeInstance() {
     }
 
 
     /**
-     * @hide
+     * @hide so it can be called by android.graphics.drawable but must not be called from outside
+     * the module.
      */
     public final long getNativeInstance() {
         // verify mNativeInstance is valid
@@ -183,9 +187,9 @@ public class Shader {
     }
 
     /**
-     * @hide
+     * @hide Only to be called by subclasses in the android.graphics package.
      */
-    public static @ColorLong long[] convertColors(@NonNull @ColorInt int[] colors) {
+    protected static @ColorLong long[] convertColors(@NonNull @ColorInt int[] colors) {
         if (colors.length < 2) {
             throw new IllegalArgumentException("needs >= 2 number of colors");
         }
@@ -204,9 +208,9 @@ public class Shader {
      * @throws IllegalArgumentException if the colors do not all share the same,
      *      valid ColorSpace, or if there are less than 2 colors.
      *
-     * @hide
+     * @hide Only to be called by subclasses in the android.graphics package.
      */
-    public static ColorSpace detectColorSpace(@NonNull @ColorLong long[] colors) {
+    protected static ColorSpace detectColorSpace(@NonNull @ColorLong long[] colors) {
         if (colors.length < 2) {
             throw new IllegalArgumentException("needs >= 2 number of colors");
         }

graphics/java/android/graphics/SweepGradient.java

@@ -130,8 +130,9 @@ public class SweepGradient extends Shader {
         this(cx, cy, new long[] {color0, color1}, null);
     }
 
+    /** @hide */
     @Override
-    long createNativeInstance(long nativeMatrix) {
+    protected long createNativeInstance(long nativeMatrix) {
         return nativeCreate(nativeMatrix, mCx, mCy, mColorLongs, mPositions,
                 colorSpace().getNativeInstance());
     }