Picture.java revision dcc64a4e6b96d15b8b966dcb62f29a370e562271
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 final long mNativePicture; 33 34 /** 35 * @hide 36 */ 37 public final boolean createdFromStream; 38 39 private static final int WORKING_STREAM_STORAGE = 16 * 1024; 40 41 /** 42 * Creates an empty picture that is ready to record. 43 */ 44 public Picture() { 45 this(nativeConstructor(0), false); 46 } 47 48 /** 49 * Create a picture by making a copy of what has already been recorded in 50 * src. The contents of src are unchanged, and if src changes later, those 51 * changes will not be reflected in this picture. 52 */ 53 public Picture(Picture src) { 54 this(nativeConstructor(src != null ? src.mNativePicture : 0), false); 55 } 56 57 /** 58 * To record a picture, call beginRecording() and then draw into the Canvas 59 * that is returned. Nothing we appear on screen, but all of the draw 60 * commands (e.g. {@link Canvas#drawRect(Rect, Paint)}) will be recorded. 61 * To stop recording, call endRecording(). After endRecording() the Canvas 62 * that was returned must no longer be used, and nothing should be drawn 63 * into it. 64 */ 65 public Canvas beginRecording(int width, int height) { 66 long ni = nativeBeginRecording(mNativePicture, width, height); 67 mRecordingCanvas = new RecordingCanvas(this, ni); 68 return mRecordingCanvas; 69 } 70 71 /** 72 * Call endRecording when the picture is built. After this call, the picture 73 * may be drawn, but the canvas that was returned by beginRecording must not 74 * be used anymore. This is automatically called if {@link Picture#draw} 75 * or {@link Canvas#drawPicture(Picture)} is called. 76 */ 77 public void endRecording() { 78 if (mRecordingCanvas != null) { 79 mRecordingCanvas = null; 80 nativeEndRecording(mNativePicture); 81 } 82 } 83 84 /** 85 * Get the width of the picture as passed to beginRecording. This 86 * does not reflect (per se) the content of the picture. 87 */ 88 public native int getWidth(); 89 90 /** 91 * Get the height of the picture as passed to beginRecording. This 92 * does not reflect (per se) the content of the picture. 93 */ 94 public native int getHeight(); 95 96 /** 97 * Draw this picture on the canvas. 98 * <p> 99 * Prior to {@link android.os.Build.VERSION_CODES#L}, this call could 100 * have the side effect of changing the matrix and clip of the canvas 101 * if this picture had imbalanced saves/restores. 102 * 103 * <p> 104 * <strong>Note:</strong> This forces the picture to internally call 105 * {@link Picture#endRecording()} in order to prepare for playback. 106 * 107 * @param canvas The picture is drawn to this canvas 108 */ 109 public void draw(Canvas canvas) { 110 if (mRecordingCanvas != null) { 111 endRecording(); 112 } 113 nativeDraw(canvas.getNativeCanvasWrapper(), mNativePicture); 114 } 115 116 /** 117 * Create a new picture (already recorded) from the data in the stream. This 118 * data was generated by a previous call to writeToStream(). Pictures that 119 * have been persisted across device restarts are not guaranteed to decode 120 * properly and are highly discouraged. 121 * 122 * <p> 123 * <strong>Note:</strong> a picture created from an input stream cannot be 124 * replayed on a hardware accelerated canvas. 125 * 126 * @see #writeToStream(java.io.OutputStream) 127 * @deprecated The recommended alternative is to not use writeToStream and 128 * instead draw the picture into a Bitmap from which you can persist it as 129 * raw or compressed pixels. 130 */ 131 @Deprecated 132 public static Picture createFromStream(InputStream stream) { 133 return new Picture(nativeCreateFromStream(stream, new byte[WORKING_STREAM_STORAGE]), true); 134 } 135 136 /** 137 * Write the picture contents to a stream. The data can be used to recreate 138 * the picture in this or another process by calling createFromStream(...) 139 * The resulting stream is NOT to be persisted across device restarts as 140 * there is no guarantee that the Picture can be successfully reconstructed. 141 * 142 * <p> 143 * <strong>Note:</strong> a picture created from an input stream cannot be 144 * replayed on a hardware accelerated canvas. 145 * 146 * @see #createFromStream(java.io.InputStream) 147 * @deprecated The recommended alternative is to draw the picture into a 148 * Bitmap from which you can persist it as raw or compressed pixels. 149 */ 150 @Deprecated 151 public void writeToStream(OutputStream stream) { 152 // do explicit check before calling the native method 153 if (stream == null) { 154 throw new NullPointerException(); 155 } 156 if (!nativeWriteToStream(mNativePicture, stream, 157 new byte[WORKING_STREAM_STORAGE])) { 158 throw new RuntimeException(); 159 } 160 } 161 162 protected void finalize() throws Throwable { 163 try { 164 nativeDestructor(mNativePicture); 165 } finally { 166 super.finalize(); 167 } 168 } 169 170 final long ni() { 171 return mNativePicture; 172 } 173 174 private Picture(long nativePicture, boolean fromStream) { 175 if (nativePicture == 0) { 176 throw new RuntimeException(); 177 } 178 mNativePicture = nativePicture; 179 createdFromStream = fromStream; 180 } 181 182 // return empty picture if src is 0, or a copy of the native src 183 private static native long nativeConstructor(long nativeSrcOr0); 184 private static native long nativeCreateFromStream(InputStream stream, 185 byte[] storage); 186 private static native long nativeBeginRecording(long nativeCanvas, 187 int w, int h); 188 private static native void nativeEndRecording(long nativeCanvas); 189 private static native void nativeDraw(long nativeCanvas, long nativePicture); 190 private static native boolean nativeWriteToStream(long nativePicture, 191 OutputStream stream, byte[] storage); 192 private static native void nativeDestructor(long nativePicture); 193 194 private static class RecordingCanvas extends Canvas { 195 private final Picture mPicture; 196 197 public RecordingCanvas(Picture pict, long nativeCanvas) { 198 super(nativeCanvas); 199 mPicture = pict; 200 } 201 202 @Override 203 public void setBitmap(Bitmap bitmap) { 204 throw new RuntimeException( 205 "Cannot call setBitmap on a picture canvas"); 206 } 207 208 @Override 209 public void drawPicture(Picture picture) { 210 if (mPicture == picture) { 211 throw new RuntimeException( 212 "Cannot draw a picture into its recording canvas"); 213 } 214 super.drawPicture(picture); 215 } 216 } 217} 218 219