Deprecate read/write Pictures to streams.

bug: 8241089
Change-Id: I435a534f5110cb2b8aba87c047b509020a22fd67

2 files changed, 42 insertions, 18 deletions

diff --git a/graphics/java/android/graphics/Canvas.java b/graphics/java/android/graphics/Canvas.java
index fc84715..2d36f14 100644
--- a/graphics/java/android/graphics/Canvas.java
+++ b/graphics/java/android/graphics/Canvas.java
@@ -1563,6 +1563,10 @@ public class Canvas {
      * Save the canvas state, draw the picture, and restore the canvas state.
      * This differs from picture.draw(canvas), which does not perform any
      * save/restore.
+     *
+     * <p>
+     * <strong>Note:</strong> This forces the picture to internally call
+     * {@link Picture#endRecording} in order to prepare for playback.
      * 
      * @param picture  The picture to be drawn
      */
diff --git a/graphics/java/android/graphics/Picture.java b/graphics/java/android/graphics/Picture.java
index 997141d..71e02f6 100644
--- a/graphics/java/android/graphics/Picture.java
+++ b/graphics/java/android/graphics/Picture.java
@@ -20,13 +20,12 @@ import java.io.InputStream;
 import java.io.OutputStream;
 
 /**
- * A picture records drawing calls (via the canvas returned by beginRecording)
- * and can then play them back (via picture.draw(canvas) or canvas.drawPicture).
- * The picture's contents can also be written to a stream, and then later
- * restored to a new picture (via writeToStream / createFromStream). For most
- * content (esp. text, lines, rectangles), drawing a sequence from a picture can
- * be faster than the equivalent API calls, since the picture performs its
- * playback without incurring any java-call overhead.
+ * A Picture records drawing calls (via the canvas returned by beginRecording)
+ * and can then play them back into Canvas (via {@link Picture#draw(Canvas)} or 
+ * {@link Canvas#drawPicture(Picture)}).For most content (e.g. text, lines, rectangles),
+ * drawing a sequence from a picture can be faster than the equivalent API
+ * calls, since the picture performs its playback without incurring any
+ * method-call overhead.
  */
 public class Picture {
     private Canvas mRecordingCanvas;
@@ -39,6 +38,9 @@ public class Picture {
 
     private static final int WORKING_STREAM_STORAGE = 16 * 1024;
 
+    /**
+     * Creates an empty picture that is ready to record.
+     */
     public Picture() {
         this(nativeConstructor(0), false);
     }
@@ -55,9 +57,10 @@ public class Picture {
     /**
      * 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
-     * commands (e.g. drawRect(...)) will be recorded. To stop recording, call
-     * endRecording(). At this point the Canvas that was returned must no longer
-     * be referenced, and nothing should be drawn into it.
+     * commands (e.g. {@link Canvas#drawRect(Rect, Paint)}) will be recorded.
+     * To stop recording, call endRecording(). After endRecording() the Canvas
+     * that was returned must no longer be used, and nothing should be drawn
+     * into it.
      */
     public Canvas beginRecording(int width, int height) {
         int ni = nativeBeginRecording(mNativePicture, width, height);
@@ -68,8 +71,8 @@ public class Picture {
     /**
      * 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
-     * be referenced anymore. This is automatically called if Picture.draw() or
-     * Canvas.drawPicture() is called.
+     * be used anymore. This is automatically called if {@link Picture#draw}
+     * or {@link Canvas#drawPicture(Picture)} is called.
      */
     public void endRecording() {
         if (mRecordingCanvas != null) {
@@ -94,6 +97,10 @@ public class Picture {
      * Draw this picture on the canvas. The picture may have the side effect
      * of changing the matrix and clip of the canvas.
      * 
+     * <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 
      */
     public void draw(Canvas canvas) {
@@ -105,26 +112,39 @@ public class Picture {
 
     /**
      * Create a new picture (already recorded) from the data in the stream. This
-     * data was generated by a previous call to writeToStream().
-     * 
+     * data was generated by a previous call to writeToStream(). Pictures that
+     * have been persisted across device restarts are not guaranteed to decode
+     * properly and are highly discouraged.
+     *
+     * <p>
      * <strong>Note:</strong> a picture created from an input stream cannot be
      * replayed on a hardware accelerated canvas.
      * 
-     * @see #writeToStream(java.io.OutputStream) 
+     * @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
+     * raw or compressed pixels.
      */
+    @Deprecated
     public static Picture createFromStream(InputStream stream) {
         return new Picture(nativeCreateFromStream(stream, new byte[WORKING_STREAM_STORAGE]), true);
     }
 
     /**
      * Write the picture contents to a stream. The data can be used to recreate
-     * the picture in this or another process by calling createFromStream.
+     * the picture in this or another process by calling createFromStream(...)
+     * The resulting stream is NOT to be persisted across device restarts as
+     * there is no guarantee that the Picture can be successfully reconstructed.
      *
+     * <p>
      * <strong>Note:</strong> a picture created from an input stream cannot be
      * replayed on a hardware accelerated canvas.
-     * 
-     * @see #createFromStream(java.io.InputStream) 
+     *
+     * @see #createFromStream(java.io.InputStream)
+     * @deprecated The recommended alternative is to draw the picture into a
+     * Bitmap from which you can persist it as raw or compressed pixels.
      */
+    @Deprecated
     public void writeToStream(OutputStream stream) {
         // do explicit check before calling the native method
         if (stream == null) {