SkPicture.h revision 01b2b83aba10bc3767d660cd619c1da58b5eb0b5 
1/*
2 * Copyright 2007 The Android Open Source Project
3 *
4 * Use of this source code is governed by a BSD-style license that can be
5 * found in the LICENSE file.
6 */
7
8#ifndef SkPicture_DEFINED
9#define SkPicture_DEFINED
10
11#include "SkRefCnt.h"
12#include "SkRect.h"
13#include "SkTypes.h"
14
15class GrContext;
16class SkBigPicture;
17class SkBitmap;
18class SkCanvas;
19class SkData;
20class SkImage;
21class SkImageDeserializer;
22class SkPath;
23class SkPictureData;
24class SkPixelSerializer;
25class SkReadBuffer;
26class SkRefCntSet;
27class SkStream;
28class SkTypefacePlayback;
29class SkWStream;
30class SkWriteBuffer;
31struct SkPictInfo;
32
33/** \class SkPicture
34
35    An SkPicture records drawing commands made to a canvas to be played back at a later time.
36    This base class handles serialization and a few other miscellany.
37*/
38class SK_API SkPicture : public SkRefCnt {
39public:
40    virtual ~SkPicture();
41
42    /**
43     *  Function signature defining a function that sets up an SkBitmap from encoded data. On
44     *  success, the SkBitmap should have its Config, width, height, rowBytes and pixelref set.
45     *  If the installed pixelref has decoded the data into pixels, then the src buffer need not be
46     *  copied. If the pixelref defers the actual decode until its lockPixels() is called, then it
47     *  must make a copy of the src buffer.
48     *  @param src Encoded data.
49     *  @param length Size of the encoded data, in bytes.
50     *  @param dst SkBitmap to install the pixel ref on.
51     *  @param bool Whether or not a pixel ref was successfully installed.
52     */
53    typedef bool (*InstallPixelRefProc)(const void* src, size_t length, SkBitmap* dst);
54
55    /**
56     *  Recreate a picture that was serialized into a stream.
57     *
58     *  Any serialized images in the stream will be passed the image-deserializer, or if that is
59     *  null, to the default deserializer that will call SkImage::MakeFromEncoded().
60     */
61    static sk_sp<SkPicture> MakeFromStream(SkStream*, SkImageDeserializer*);
62    static sk_sp<SkPicture> MakeFromStream(SkStream*);
63    static sk_sp<SkPicture> MakeFromData(const void* data, size_t size,
64                                         SkImageDeserializer* = nullptr);
65    static sk_sp<SkPicture> MakeFromData(const SkData* data, SkImageDeserializer* = nullptr);
66
67    /**
68     *  Recreate a picture that was serialized into a buffer. If the creation requires bitmap
69     *  decoding, the decoder must be set on the SkReadBuffer parameter by calling
70     *  SkReadBuffer::setBitmapDecoder() before calling SkPicture::CreateFromBuffer().
71     *  @param SkReadBuffer Serialized picture data.
72     *  @return A new SkPicture representing the serialized data, or NULL if the buffer is
73     *          invalid.
74     */
75    static sk_sp<SkPicture> MakeFromBuffer(SkReadBuffer&);
76
77    /**
78    *  Subclasses of this can be passed to playback(). During the playback
79    *  of the picture, this callback will periodically be invoked. If its
80    *  abort() returns true, then picture playback will be interrupted.
81    *
82    *  The resulting drawing is undefined, as there is no guarantee how often the
83    *  callback will be invoked. If the abort happens inside some level of nested
84    *  calls to save(), restore will automatically be called to return the state
85    *  to the same level it was before the playback call was made.
86    */
87    class SK_API AbortCallback {
88    public:
89        AbortCallback() {}
90        virtual ~AbortCallback() {}
91        virtual bool abort() = 0;
92    };
93
94    /** Replays the drawing commands on the specified canvas. Note that
95        this has the effect of unfurling this picture into the destination
96        canvas. Using the SkCanvas::drawPicture entry point gives the destination
97        canvas the option of just taking a ref.
98        @param canvas the canvas receiving the drawing commands.
99        @param callback a callback that allows interruption of playback
100    */
101    virtual void playback(SkCanvas*, AbortCallback* = NULL) const = 0;
102
103    /** Return a cull rect for this picture.
104        Ops recorded into this picture that attempt to draw outside the cull might not be drawn.
105     */
106    virtual SkRect cullRect() const = 0;
107
108    /** Returns a non-zero value unique among all pictures. */
109    uint32_t uniqueID() const;
110
111    /**
112     *  Serialize the picture to SkData. If non nullptr, pixel-serializer will be used to
113     *  customize how images reference by the picture are serialized/compressed.
114     */
115    sk_sp<SkData> serialize(SkPixelSerializer* = nullptr) const;
116
117    /**
118     *  Serialize to a stream. If non nullptr, pixel-serializer will be used to
119     *  customize how images reference by the picture are serialized/compressed.
120     */
121    void serialize(SkWStream*, SkPixelSerializer* = nullptr) const;
122
123    /**
124     *  Serialize to a buffer.
125     */
126    void flatten(SkWriteBuffer&) const;
127
128    /**
129     * Returns true if any bitmaps may be produced when this SkPicture
130     * is replayed.
131     */
132    virtual bool willPlayBackBitmaps() const = 0;
133
134    /** Return the approximate number of operations in this picture.  This
135     *  number may be greater or less than the number of SkCanvas calls
136     *  recorded: some calls may be recorded as more than one operation, or some
137     *  calls may be optimized away.
138     */
139    virtual int approximateOpCount() const = 0;
140
141    /** Returns the approximate byte size of this picture, not including large ref'd objects. */
142    virtual size_t approximateBytesUsed() const = 0;
143
144    /** Return true if the SkStream/Buffer represents a serialized picture, and
145        fills out SkPictInfo. After this function returns, the data source is not
146        rewound so it will have to be manually reset before passing to
147        CreateFromStream or CreateFromBuffer. Note, CreateFromStream and
148        CreateFromBuffer perform this check internally so these entry points are
149        intended for stand alone tools.
150        If false is returned, SkPictInfo is unmodified.
151    */
152    static bool InternalOnly_StreamIsSKP(SkStream*, SkPictInfo*);
153    static bool InternalOnly_BufferIsSKP(SkReadBuffer*, SkPictInfo*);
154
155#ifdef SK_SUPPORT_LEGACY_PICTURE_GPUVETO
156    /** Return true if the picture is suitable for rendering on the GPU.  */
157    bool suitableForGpuRasterization(GrContext*, const char** whyNot = NULL) const;
158#endif
159
160    // Sent via SkMessageBus from destructor.
161    struct DeletionMessage { int32_t fUniqueID; };  // TODO: -> uint32_t?
162
163    // Returns NULL if this is not an SkBigPicture.
164    virtual const SkBigPicture* asSkBigPicture() const { return NULL; }
165
166    // Global setting to enable or disable security precautions for serialization.
167    static void SetPictureIOSecurityPrecautionsEnabled_Dangerous(bool set);
168    static bool PictureIOSecurityPrecautionsEnabled();
169
170private:
171    // Subclass whitelist.
172    SkPicture();
173    friend class SkBigPicture;
174    friend class SkEmptyPicture;
175    template <typename> friend class SkMiniPicture;
176
177    void serialize(SkWStream*, SkPixelSerializer*, SkRefCntSet* typefaces) const;
178    static sk_sp<SkPicture> MakeFromStream(SkStream*, SkImageDeserializer*, SkTypefacePlayback*);
179    friend class SkPictureData;
180
181    virtual int numSlowPaths() const = 0;
182    friend class SkPictureGpuAnalyzer;
183    friend struct SkPathCounter;
184
185    // V35: Store SkRect (rather then width & height) in header
186    // V36: Remove (obsolete) alphatype from SkColorTable
187    // V37: Added shadow only option to SkDropShadowImageFilter (last version to record CLEAR)
188    // V38: Added PictureResolution option to SkPictureImageFilter
189    // V39: Added FilterLevel option to SkPictureImageFilter
190    // V40: Remove UniqueID serialization from SkImageFilter.
191    // V41: Added serialization of SkBitmapSource's filterQuality parameter
192    // V42: Added a bool to SkPictureShader serialization to indicate did-we-serialize-a-picture?
193    // V43: Added DRAW_IMAGE and DRAW_IMAGE_RECT opt codes to serialized data
194    // V44: Move annotations from paint to drawAnnotation
195    // V45: Add invNormRotation to SkLightingShader.
196    // V46: Add drawTextRSXform
197    // V47: Add occluder rect to SkBlurMaskFilter
198    // V48: Read and write extended SkTextBlobs.
199    // V49: Gradients serialized as SkColor4f + SkColorSpace
200    // V50: SkXfermode -> SkBlendMode
201    // V51: more SkXfermode -> SkBlendMode
202    // V52: Remove SkTextBlob::fRunCount
203    // V53: SaveLayerRec clip mask
204    // V54: ComposeShader can use a Mode or a Lerp
205
206    // Only SKPs within the min/current picture version range (inclusive) can be read.
207    static const uint32_t     MIN_PICTURE_VERSION = 51;     // Produced by Chrome ~M56.
208    static const uint32_t CURRENT_PICTURE_VERSION = 54;
209
210    static bool IsValidPictInfo(const SkPictInfo& info);
211    static sk_sp<SkPicture> Forwardport(const SkPictInfo&,
212                                        const SkPictureData*,
213                                        SkReadBuffer* buffer);
214
215    SkPictInfo createHeader() const;
216    SkPictureData* backport() const;
217
218    mutable uint32_t fUniqueID;
219};
220
221#endif
222