SkPicture.h revision ca2622ba051829fed5f30facd74c5b41cd4b931c 
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 "SkImageDecoder.h"
12#include "SkRefCnt.h"
13#include "SkTypes.h"
14
15class GrContext;
16class SkBigPicture;
17class SkBitmap;
18class SkCanvas;
19class SkPictureData;
20class SkPixelSerializer;
21class SkRefCntSet;
22class SkStream;
23class SkTypefacePlayback;
24class SkWStream;
25struct SkPictInfo;
26
27#define SK_SUPPORT_LEGACY_PICTURE_PTR
28
29/** \class SkPicture
30
31    An SkPicture records drawing commands made to a canvas to be played back at a later time.
32    This base class handles serialization and a few other miscellany.
33*/
34class SK_API SkPicture : public SkRefCnt {
35public:
36    virtual ~SkPicture();
37
38    /**
39     *  Function signature defining a function that sets up an SkBitmap from encoded data. On
40     *  success, the SkBitmap should have its Config, width, height, rowBytes and pixelref set.
41     *  If the installed pixelref has decoded the data into pixels, then the src buffer need not be
42     *  copied. If the pixelref defers the actual decode until its lockPixels() is called, then it
43     *  must make a copy of the src buffer.
44     *  @param src Encoded data.
45     *  @param length Size of the encoded data, in bytes.
46     *  @param dst SkBitmap to install the pixel ref on.
47     *  @param bool Whether or not a pixel ref was successfully installed.
48     */
49    typedef bool (*InstallPixelRefProc)(const void* src, size_t length, SkBitmap* dst);
50
51    /**
52     *  Recreate a picture that was serialized into a stream.
53     *  @param SkStream Serialized picture data. Ownership is unchanged by this call.
54     *  @param proc Function pointer for installing pixelrefs on SkBitmaps representing the
55     *              encoded bitmap data from the stream.
56     *  @return A new SkPicture representing the serialized data, or NULL if the stream is
57     *          invalid.
58     */
59    static sk_sp<SkPicture> MakeFromStream(SkStream*, InstallPixelRefProc proc);
60
61    /**
62     *  Recreate a picture that was serialized into a stream.
63     *
64     *  Any serialized images in the stream will be passed to
65     *  SkImageGenerator::NewFromEncoded.
66     *
67     *  @param SkStream Serialized picture data. Ownership is unchanged by this call.
68     *  @return A new SkPicture representing the serialized data, or NULL if the stream is
69     *          invalid.
70     */
71    static sk_sp<SkPicture> MakeFromStream(SkStream*);
72
73    /**
74     *  Recreate a picture that was serialized into a buffer. If the creation requires bitmap
75     *  decoding, the decoder must be set on the SkReadBuffer parameter by calling
76     *  SkReadBuffer::setBitmapDecoder() before calling SkPicture::CreateFromBuffer().
77     *  @param SkReadBuffer Serialized picture data.
78     *  @return A new SkPicture representing the serialized data, or NULL if the buffer is
79     *          invalid.
80     */
81    static sk_sp<SkPicture> MakeFromBuffer(SkReadBuffer&);
82
83    /**
84    *  Subclasses of this can be passed to playback(). During the playback
85    *  of the picture, this callback will periodically be invoked. If its
86    *  abort() returns true, then picture playback will be interrupted.
87    *
88    *  The resulting drawing is undefined, as there is no guarantee how often the
89    *  callback will be invoked. If the abort happens inside some level of nested
90    *  calls to save(), restore will automatically be called to return the state
91    *  to the same level it was before the playback call was made.
92    */
93    class SK_API AbortCallback {
94    public:
95        AbortCallback() {}
96        virtual ~AbortCallback() {}
97        virtual bool abort() = 0;
98    };
99
100    /** Replays the drawing commands on the specified canvas. Note that
101        this has the effect of unfurling this picture into the destination
102        canvas. Using the SkCanvas::drawPicture entry point gives the destination
103        canvas the option of just taking a ref.
104        @param canvas the canvas receiving the drawing commands.
105        @param callback a callback that allows interruption of playback
106    */
107    virtual void playback(SkCanvas*, AbortCallback* = NULL) const = 0;
108
109    /** Return a cull rect for this picture.
110        Ops recorded into this picture that attempt to draw outside the cull might not be drawn.
111     */
112    virtual SkRect cullRect() const = 0;
113
114    /** Returns a non-zero value unique among all pictures. */
115    uint32_t uniqueID() const;
116
117    /**
118     *  Serialize to a stream. If non NULL, serializer will be used to serialize
119     *  bitmaps and images in the picture.
120     */
121    void serialize(SkWStream*, SkPixelSerializer* = NULL) 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    /** Return true if this picture contains text.
142     */
143    virtual bool hasText() const = 0;
144
145    /** Returns the approximate byte size of this picture, not including large ref'd objects. */
146    virtual size_t approximateBytesUsed() const = 0;
147
148    /** Return true if the SkStream/Buffer represents a serialized picture, and
149        fills out SkPictInfo. After this function returns, the data source is not
150        rewound so it will have to be manually reset before passing to
151        CreateFromStream or CreateFromBuffer. Note, CreateFromStream and
152        CreateFromBuffer perform this check internally so these entry points are
153        intended for stand alone tools.
154        If false is returned, SkPictInfo is unmodified.
155    */
156    static bool InternalOnly_StreamIsSKP(SkStream*, SkPictInfo*);
157    static bool InternalOnly_BufferIsSKP(SkReadBuffer*, SkPictInfo*);
158
159    /** Return true if the picture is suitable for rendering on the GPU.  */
160    bool suitableForGpuRasterization(GrContext*, const char** whyNot = NULL) const;
161
162    // Sent via SkMessageBus from destructor.
163    struct DeletionMessage { int32_t fUniqueID; };  // TODO: -> uint32_t?
164
165    // Returns NULL if this is not an SkBigPicture.
166    virtual const SkBigPicture* asSkBigPicture() const { return NULL; }
167
168    // Global setting to enable or disable security precautions for serialization.
169    static void SetPictureIOSecurityPrecautionsEnabled_Dangerous(bool set);
170    static bool PictureIOSecurityPrecautionsEnabled();
171
172#ifdef SK_SUPPORT_LEGACY_PICTURE_PTR
173    static SkPicture* CreateFromStream(SkStream* stream, InstallPixelRefProc proc) {
174        return MakeFromStream(stream, proc).release();
175    }
176    static SkPicture* CreateFromStream(SkStream* stream) {
177        return MakeFromStream(stream).release();
178    }
179    static SkPicture* CreateFromBuffer(SkReadBuffer& rbuf) {
180        return MakeFromBuffer(rbuf).release();
181    }
182#endif
183
184private:
185    // Subclass whitelist.
186    SkPicture();
187    friend class SkBigPicture;
188    friend class SkEmptyPicture;
189    template <typename> friend class SkMiniPicture;
190
191    void serialize(SkWStream*, SkPixelSerializer*, SkRefCntSet* typefaces) const;
192    static sk_sp<SkPicture> MakeFromStream(SkStream*, InstallPixelRefProc, SkTypefacePlayback*);
193    friend class SkPictureData;
194
195    virtual int numSlowPaths() const = 0;
196    friend struct SkPathCounter;
197
198    // V35: Store SkRect (rather then width & height) in header
199    // V36: Remove (obsolete) alphatype from SkColorTable
200    // V37: Added shadow only option to SkDropShadowImageFilter (last version to record CLEAR)
201    // V38: Added PictureResolution option to SkPictureImageFilter
202    // V39: Added FilterLevel option to SkPictureImageFilter
203    // V40: Remove UniqueID serialization from SkImageFilter.
204    // V41: Added serialization of SkBitmapSource's filterQuality parameter
205    // V42: Added a bool to SkPictureShader serialization to indicate did-we-serialize-a-picture?
206    // V43: Added DRAW_IMAGE and DRAW_IMAGE_RECT opt codes to serialized data
207    // V44: Move annotations from paint to drawAnnotation
208
209    // Only SKPs within the min/current picture version range (inclusive) can be read.
210    static const uint32_t     MIN_PICTURE_VERSION = 35;     // Produced by Chrome M39.
211    static const uint32_t CURRENT_PICTURE_VERSION = 44;
212
213    static_assert(MIN_PICTURE_VERSION <= 41,
214                  "Remove kFontFileName and related code from SkFontDescriptor.cpp.");
215
216    static_assert(MIN_PICTURE_VERSION <= 42,
217                  "Remove COMMENT API handlers from SkPicturePlayback.cpp");
218
219    static_assert(MIN_PICTURE_VERSION <= 43,
220                  "Remove SkBitmapSourceDeserializer.");
221
222    static bool IsValidPictInfo(const SkPictInfo& info);
223    static sk_sp<SkPicture> Forwardport(const SkPictInfo&, const SkPictureData*);
224
225    SkPictInfo createHeader() const;
226    SkPictureData* backport() const;
227
228    mutable uint32_t fUniqueID;
229};
230
231#endif
232