Update Picture documentation

Enhanced comment

Given that the SkPictures should no longer have unbalanced saves and restores
there should be no inadvertent leakage of matrix or clip state.

Note that the existing documentation was vague enough that no real substantive
changes were required to make it match the new behavior.

Change-Id: Ic2d440b3e6318ec9687c607caba05de928e08503

1 files changed, 14 insertions, 11 deletions

diff --git a/graphics/java/android/graphics/Picture.java b/graphics/java/android/graphics/Picture.java
index de458af..a021165 100644
--- a/graphics/java/android/graphics/Picture.java
+++ b/graphics/java/android/graphics/Picture.java
@@ -53,7 +53,7 @@ public class Picture {
     public Picture(Picture src) {
         this(nativeConstructor(src != null ? src.mNativePicture : 0), false);
     }
-    
+
     /**
      * To record a picture, call beginRecording() and then draw into the Canvas
      * that is returned. Nothing we appear on screen, but all of the draw
@@ -67,7 +67,7 @@ public class Picture {
         mRecordingCanvas = new RecordingCanvas(this, ni);
         return mRecordingCanvas;
     }
-    
+
     /**
      * Call endRecording when the picture is built. After this call, the picture
      * may be drawn, but the canvas that was returned by beginRecording must not
@@ -92,16 +92,19 @@ public class Picture {
      * does not reflect (per se) the content of the picture.
      */
     public native int getHeight();
-    
+
     /**
-     * Draw this picture on the canvas. The picture may have the side effect
-     * of changing the matrix and clip of the canvas.
-     * 
+     * Draw this picture on the canvas.
+     * <p>
+     * Prior to {@link android.os.Build.VERSION_CODES#L}, this call could
+     * have the side effect of changing the matrix and clip of the canvas
+     * if this picture had imbalanced saves/restores.
+     *
      * <p>
      * <strong>Note:</strong> This forces the picture to internally call
      * {@link Picture#endRecording()} in order to prepare for playback.
      *
-     * @param canvas  The picture is drawn to this canvas 
+     * @param canvas  The picture is drawn to this canvas
      */
     public void draw(Canvas canvas) {
         if (mRecordingCanvas != null) {
@@ -119,7 +122,7 @@ public class Picture {
      * <p>
      * <strong>Note:</strong> a picture created from an input stream cannot be
      * replayed on a hardware accelerated canvas.
-     * 
+     *
      * @see #writeToStream(java.io.OutputStream)
      * @deprecated The recommended alternative is to not use writeToStream and
      * instead draw the picture into a Bitmap from which you can persist it as
@@ -167,7 +170,7 @@ public class Picture {
     final long ni() {
         return mNativePicture;
     }
-    
+
     private Picture(long nativePicture, boolean fromStream) {
         if (nativePicture == 0) {
             throw new RuntimeException();
@@ -187,7 +190,7 @@ public class Picture {
     private static native boolean nativeWriteToStream(long nativePicture,
                                            OutputStream stream, byte[] storage);
     private static native void nativeDestructor(long nativePicture);
-    
+
     private static class RecordingCanvas extends Canvas {
         private final Picture mPicture;
 
@@ -195,7 +198,7 @@ public class Picture {
             super(nativeCanvas);
             mPicture = pict;
         }
-        
+
         @Override
         public void setBitmap(Bitmap bitmap) {
             throw new RuntimeException(