1/* 2 * Copyright (C) 2007 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.graphics; 18 19import java.io.InputStream; 20import java.io.OutputStream; 21 22/** 23 * A Picture records drawing calls (via the canvas returned by beginRecording) 24 * and can then play them back into Canvas (via {@link Picture#draw(Canvas)} or 25 * {@link Canvas#drawPicture(Picture)}).For most content (e.g. text, lines, rectangles), 26 * drawing a sequence from a picture can be faster than the equivalent API 27 * calls, since the picture performs its playback without incurring any 28 * method-call overhead. 29 */ 30public class Picture { 31 private Canvas mRecordingCanvas; 32 private long mNativePicture; 33 34 private static final int WORKING_STREAM_STORAGE = 16 * 1024; 35 36 /** 37 * Creates an empty picture that is ready to record. 38 */ 39 public Picture() { 40 this(nativeConstructor(0)); 41 } 42 43 /** 44 * Create a picture by making a copy of what has already been recorded in 45 * src. The contents of src are unchanged, and if src changes later, those 46 * changes will not be reflected in this picture. 47 */ 48 public Picture(Picture src) { 49 this(nativeConstructor(src != null ? src.mNativePicture : 0)); 50 } 51 52 private Picture(long nativePicture) { 53 if (nativePicture == 0) { 54 throw new RuntimeException(); 55 } 56 mNativePicture = nativePicture; 57 } 58 59 @Override 60 protected void finalize() throws Throwable { 61 try { 62 nativeDestructor(mNativePicture); 63 mNativePicture = 0; 64 } finally { 65 super.finalize(); 66 } 67 } 68 69 /** 70 * To record a picture, call beginRecording() and then draw into the Canvas 71 * that is returned. Nothing we appear on screen, but all of the draw 72 * commands (e.g. {@link Canvas#drawRect(Rect, Paint)}) will be recorded. 73 * To stop recording, call endRecording(). After endRecording() the Canvas 74 * that was returned must no longer be used, and nothing should be drawn 75 * into it. 76 */ 77 public Canvas beginRecording(int width, int height) { 78 long ni = nativeBeginRecording(mNativePicture, width, height); 79 mRecordingCanvas = new RecordingCanvas(this, ni); 80 return mRecordingCanvas; 81 } 82 83 /** 84 * Call endRecording when the picture is built. After this call, the picture 85 * may be drawn, but the canvas that was returned by beginRecording must not 86 * be used anymore. This is automatically called if {@link Picture#draw} 87 * or {@link Canvas#drawPicture(Picture)} is called. 88 */ 89 public void endRecording() { 90 if (mRecordingCanvas != null) { 91 mRecordingCanvas = null; 92 nativeEndRecording(mNativePicture); 93 } 94 } 95 96 /** 97 * Get the width of the picture as passed to beginRecording. This 98 * does not reflect (per se) the content of the picture. 99 */ 100 public int getWidth() { 101 return nativeGetWidth(mNativePicture); 102 } 103 104 /** 105 * Get the height of the picture as passed to beginRecording. This 106 * does not reflect (per se) the content of the picture. 107 */ 108 public int getHeight() { 109 return nativeGetHeight(mNativePicture); 110 } 111 112 /** 113 * Draw this picture on the canvas. 114 * <p> 115 * Prior to {@link android.os.Build.VERSION_CODES#LOLLIPOP}, this call could 116 * have the side effect of changing the matrix and clip of the canvas 117 * if this picture had imbalanced saves/restores. 118 * 119 * <p> 120 * <strong>Note:</strong> This forces the picture to internally call 121 * {@link Picture#endRecording()} in order to prepare for playback. 122 * 123 * @param canvas The picture is drawn to this canvas 124 */ 125 public void draw(Canvas canvas) { 126 if (mRecordingCanvas != null) { 127 endRecording(); 128 } 129 nativeDraw(canvas.getNativeCanvasWrapper(), mNativePicture); 130 } 131 132 /** 133 * Create a new picture (already recorded) from the data in the stream. This 134 * data was generated by a previous call to writeToStream(). Pictures that 135 * have been persisted across device restarts are not guaranteed to decode 136 * properly and are highly discouraged. 137 * 138 * <p> 139 * <strong>Note:</strong> Prior to API level 23 a picture created from an 140 * input stream cannot be replayed on a hardware accelerated canvas. 141 * 142 * @see #writeToStream(java.io.OutputStream) 143 * @deprecated The recommended alternative is to not use writeToStream and 144 * instead draw the picture into a Bitmap from which you can persist it as 145 * raw or compressed pixels. 146 */ 147 @Deprecated 148 public static Picture createFromStream(InputStream stream) { 149 return new Picture(nativeCreateFromStream(stream, new byte[WORKING_STREAM_STORAGE])); 150 } 151 152 /** 153 * Write the picture contents to a stream. The data can be used to recreate 154 * the picture in this or another process by calling createFromStream(...) 155 * The resulting stream is NOT to be persisted across device restarts as 156 * there is no guarantee that the Picture can be successfully reconstructed. 157 * 158 * <p> 159 * <strong>Note:</strong> Prior to API level 23 a picture created from an 160 * input stream cannot be replayed on a hardware accelerated canvas. 161 * 162 * @see #createFromStream(java.io.InputStream) 163 * @deprecated The recommended alternative is to draw the picture into a 164 * Bitmap from which you can persist it as raw or compressed pixels. 165 */ 166 @Deprecated 167 public void writeToStream(OutputStream stream) { 168 // do explicit check before calling the native method 169 if (stream == null) { 170 throw new NullPointerException(); 171 } 172 if (!nativeWriteToStream(mNativePicture, stream, 173 new byte[WORKING_STREAM_STORAGE])) { 174 throw new RuntimeException(); 175 } 176 } 177 178 // return empty picture if src is 0, or a copy of the native src 179 private static native long nativeConstructor(long nativeSrcOr0); 180 private static native long nativeCreateFromStream(InputStream stream, byte[] storage); 181 private static native int nativeGetWidth(long nativePicture); 182 private static native int nativeGetHeight(long nativePicture); 183 private static native long nativeBeginRecording(long nativeCanvas, int w, int h); 184 private static native void nativeEndRecording(long nativeCanvas); 185 private static native void nativeDraw(long nativeCanvas, long nativePicture); 186 private static native boolean nativeWriteToStream(long nativePicture, 187 OutputStream stream, byte[] storage); 188 private static native void nativeDestructor(long nativePicture); 189 190 private static class RecordingCanvas extends Canvas { 191 private final Picture mPicture; 192 193 public RecordingCanvas(Picture pict, long nativeCanvas) { 194 super(nativeCanvas); 195 mPicture = pict; 196 } 197 198 @Override 199 public void setBitmap(Bitmap bitmap) { 200 throw new RuntimeException("Cannot call setBitmap on a picture canvas"); 201 } 202 203 @Override 204 public void drawPicture(Picture picture) { 205 if (mPicture == picture) { 206 throw new RuntimeException("Cannot draw a picture into its recording canvas"); 207 } 208 super.drawPicture(picture); 209 } 210 } 211} 212