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