Picture.javaAPI DocAndroid 1.5 API6442Wed May 06 22:42:00 BST


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

Fields Summary
private Canvas
private final int
private static final int
Constructors Summary
public Picture()

private Picture(int nativePicture)

        if (nativePicture == 0) {
            throw new RuntimeException();
        mNativePicture = nativePicture;
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));
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. 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.

        int ni = nativeBeginRecording(mNativePicture, width, height);
        mRecordingCanvas = new RecordingCanvas(this, ni);
        return mRecordingCanvas;
public static stream)
Create a new picture (already recorded) from the data in the stream. This data was generated by a previous call to writeToStream().

        return new Picture(
            nativeCreateFromStream(stream, new byte[WORKING_STREAM_STORAGE]));
public voiddraw(Canvas canvas)
Draw this picture on the canvas. The picture may have the side effect of changing the matrix and clip of the canvas.

canvas The picture is drawn to this canvas

        if (mRecordingCanvas != null) {
        nativeDraw(canvas.mNativeCanvas, 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 referenced anymore. This is automatically called if Picture.draw() or Canvas.drawPicture() is called.

        if (mRecordingCanvas != null) {
            mRecordingCanvas = null;
protected voidfinalize()

public native intgetHeight()
Get the height of the picture as passed to beginRecording. This does not reflect (per se) the content of the picture.

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

private static native intnativeBeginRecording(int nativeCanvas, int w, int h)

private static native intnativeConstructor(int nativeSrcOr0)

private static native intnativeCreateFromStream( stream, byte[] storage)

private static native voidnativeDestructor(int nativePicture)

private static native voidnativeDraw(int nativeCanvas, int nativePicture)

private static native voidnativeEndRecording(int nativeCanvas)

private static native booleannativeWriteToStream(int nativePicture, stream, byte[] storage)

final intni()

        return mNativePicture;
public voidwriteToStream( 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.

        // 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();