FileDocCategorySizeDatePackage
Picture.javaAPI DocAndroid 5.1 API8076Thu Mar 12 22:22:30 GMT 2015android.graphics

Picture

public class Picture extends Object
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.

Fields Summary
private Canvas
mRecordingCanvas
private final long
mNativePicture
private static final int
WORKING_STREAM_STORAGE
Constructors Summary
public Picture()
Creates an empty picture that is ready to record.


                  
      
        this(nativeConstructor(0));
public Picture(Picture src)
Create a picture by making a copy of what has already been recorded in src. The contents of src are unchanged, and if src changes later, those changes will not be reflected in this picture.

        this(nativeConstructor(src != null ? src.mNativePicture : 0));
private Picture(long nativePicture)

        if (nativePicture == 0) {
            throw new RuntimeException();
        }
        mNativePicture = nativePicture;
Methods Summary
public CanvasbeginRecording(int width, int height)
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. {@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.

        long ni = nativeBeginRecording(mNativePicture, width, height);
        mRecordingCanvas = new RecordingCanvas(this, ni);
        return mRecordingCanvas;
public static android.graphics.PicturecreateFromStream(java.io.InputStream stream)
Create a new picture (already recorded) from the data in the stream. This 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.

Note: 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 raw or compressed pixels.

        return new Picture(nativeCreateFromStream(stream, new byte[WORKING_STREAM_STORAGE]));
public voiddraw(Canvas canvas)
Draw this picture on the canvas.

Prior to {@link android.os.Build.VERSION_CODES#LOLLIPOP}, this call could have the side effect of changing the matrix and clip of the canvas if this picture had imbalanced saves/restores.

Note: 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

        if (canvas.isHardwareAccelerated()) {
            throw new IllegalArgumentException(
                    "Picture playback is only supported on software canvas.");
        }

        if (mRecordingCanvas != null) {
            endRecording();
        }
        nativeDraw(canvas.getNativeCanvasWrapper(), mNativePicture);
public voidendRecording()
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 used anymore. This is automatically called if {@link Picture#draw} or {@link Canvas#drawPicture(Picture)} is called.

        if (mRecordingCanvas != null) {
            mRecordingCanvas = null;
            nativeEndRecording(mNativePicture);
        }
protected voidfinalize()

        try {
            nativeDestructor(mNativePicture);
        } finally {
            super.finalize();
        }
public intgetHeight()
Get the height of the picture as passed to beginRecording. This does not reflect (per se) the content of the picture.

      return nativeGetHeight(mNativePicture);
public intgetWidth()
Get the width of the picture as passed to beginRecording. This does not reflect (per se) the content of the picture.

      return nativeGetWidth(mNativePicture);
private static native longnativeBeginRecording(long nativeCanvas, int w, int h)

private static native longnativeConstructor(long nativeSrcOr0)
private static native longnativeCreateFromStream(java.io.InputStream stream, byte[] storage)
private static native voidnativeDestructor(long nativePicture)
private static native voidnativeDraw(long nativeCanvas, long nativePicture)
private static native voidnativeEndRecording(long nativeCanvas)
private static native intnativeGetHeight(long nativePicture)
private static native intnativeGetWidth(long nativePicture)
private static native booleannativeWriteToStream(long nativePicture, java.io.OutputStream stream, byte[] storage)
public voidwriteToStream(java.io.OutputStream stream)
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 resulting stream is NOT to be persisted across device restarts as
there is no guarantee that the Picture can be successfully reconstructed.



Note: a picture created from an input stream cannot be
replayed on a hardware accelerated canvas.
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.
        // do explicit check before calling the native method
        if (stream == null) {
            throw new NullPointerException();
        }
        if (!nativeWriteToStream(mNativePicture, stream,
                             new byte[WORKING_STREAM_STORAGE])) {
            throw new RuntimeException();
        }