SkPicture.h revision a9ca05ca5e604b9ee18e9cce19b059085ca0e22c 
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#ifdef SK_SUPPORT_LEGACY_PICTUREINSTALLPIXELREF
56    /**
57     *  Recreate a picture that was serialized into a stream.
58     *  @param SkStream Serialized picture data. Ownership is unchanged by this call.
59     *  @param proc Function pointer for installing pixelrefs on SkBitmaps representing the
60     *              encoded bitmap data from the stream.
61     *  @return A new SkPicture representing the serialized data, or NULL if the stream is
62     *          invalid.
63     */
64    static sk_sp<SkPicture> MakeFromStream(SkStream*, InstallPixelRefProc proc);
65    static sk_sp<SkPicture> MakeFromStream(SkStream* stream, std::nullptr_t) {
66        return MakeFromStream(stream);
67    }
68#endif
69
70    /**
71     *  Recreate a picture that was serialized into a stream.
72     *
73     *  Any serialized images in the stream will be passed the image-deserializer, or if that is
74     *  null, to the default deserializer that will call SkImage::MakeFromEncoded().
75     */
76    static sk_sp<SkPicture> MakeFromStream(SkStream*, SkImageDeserializer*);
77    static sk_sp<SkPicture> MakeFromStream(SkStream*);
78
79    /**
80     *  Recreate a picture that was serialized into a buffer. If the creation requires bitmap
81     *  decoding, the decoder must be set on the SkReadBuffer parameter by calling
82     *  SkReadBuffer::setBitmapDecoder() before calling SkPicture::CreateFromBuffer().
83     *  @param SkReadBuffer Serialized picture data.
84     *  @return A new SkPicture representing the serialized data, or NULL if the buffer is
85     *          invalid.
86     */
87    static sk_sp<SkPicture> MakeFromBuffer(SkReadBuffer&);
88
89    /**
90    *  Subclasses of this can be passed to playback(). During the playback
91    *  of the picture, this callback will periodically be invoked. If its
92    *  abort() returns true, then picture playback will be interrupted.
93    *
94    *  The resulting drawing is undefined, as there is no guarantee how often the
95    *  callback will be invoked. If the abort happens inside some level of nested
96    *  calls to save(), restore will automatically be called to return the state
97    *  to the same level it was before the playback call was made.
98    */
99    class SK_API AbortCallback {
100    public:
101        AbortCallback() {}
102        virtual ~AbortCallback() {}
103        virtual bool abort() = 0;
104    };
105
106    /** Replays the drawing commands on the specified canvas. Note that
107        this has the effect of unfurling this picture into the destination
108        canvas. Using the SkCanvas::drawPicture entry point gives the destination
109        canvas the option of just taking a ref.
110        @param canvas the canvas receiving the drawing commands.
111        @param callback a callback that allows interruption of playback
112    */
113    virtual void playback(SkCanvas*, AbortCallback* = NULL) const = 0;
114
115    /** Return a cull rect for this picture.
116        Ops recorded into this picture that attempt to draw outside the cull might not be drawn.
117     */
118    virtual SkRect cullRect() const = 0;
119
120    /** Returns a non-zero value unique among all pictures. */
121    uint32_t uniqueID() const;
122
123    /**
124     *  Serialize to a stream. If non NULL, serializer will be used to serialize
125     *  bitmaps and images in the picture.
126     */
127    void serialize(SkWStream*, SkPixelSerializer* = NULL) const;
128
129    /**
130     *  Serialize to a buffer.
131     */
132    void flatten(SkWriteBuffer&) const;
133
134    /**
135     * Returns true if any bitmaps may be produced when this SkPicture
136     * is replayed.
137     */
138    virtual bool willPlayBackBitmaps() const = 0;
139
140    /** Return the approximate number of operations in this picture.  This
141     *  number may be greater or less than the number of SkCanvas calls
142     *  recorded: some calls may be recorded as more than one operation, or some
143     *  calls may be optimized away.
144     */
145    virtual int approximateOpCount() const = 0;
146
147    /** Returns the approximate byte size of this picture, not including large ref'd objects. */
148    virtual size_t approximateBytesUsed() const = 0;
149
150    /** Return true if the SkStream/Buffer represents a serialized picture, and
151        fills out SkPictInfo. After this function returns, the data source is not
152        rewound so it will have to be manually reset before passing to
153        CreateFromStream or CreateFromBuffer. Note, CreateFromStream and
154        CreateFromBuffer perform this check internally so these entry points are
155        intended for stand alone tools.
156        If false is returned, SkPictInfo is unmodified.
157    */
158    static bool InternalOnly_StreamIsSKP(SkStream*, SkPictInfo*);
159    static bool InternalOnly_BufferIsSKP(SkReadBuffer*, SkPictInfo*);
160
161#ifdef SK_SUPPORT_LEGACY_PICTURE_GPUVETO
162    /** Return true if the picture is suitable for rendering on the GPU.  */
163    bool suitableForGpuRasterization(GrContext*, const char** whyNot = NULL) const;
164#endif
165
166    // Sent via SkMessageBus from destructor.
167    struct DeletionMessage { int32_t fUniqueID; };  // TODO: -> uint32_t?
168
169    // Returns NULL if this is not an SkBigPicture.
170    virtual const SkBigPicture* asSkBigPicture() const { return NULL; }
171
172    // Global setting to enable or disable security precautions for serialization.
173    static void SetPictureIOSecurityPrecautionsEnabled_Dangerous(bool set);
174    static bool PictureIOSecurityPrecautionsEnabled();
175
176#ifdef SK_SUPPORT_LEGACY_PICTURE_PTR
177    static SkPicture* CreateFromStream(SkStream* stream, InstallPixelRefProc proc) {
178        return MakeFromStream(stream, proc).release();
179    }
180    static SkPicture* CreateFromStream(SkStream* stream) {
181        return MakeFromStream(stream).release();
182    }
183    static SkPicture* CreateFromBuffer(SkReadBuffer& rbuf) {
184        return MakeFromBuffer(rbuf).release();
185    }
186#endif
187
188private:
189    // Subclass whitelist.
190    SkPicture();
191    friend class SkBigPicture;
192    friend class SkEmptyPicture;
193    template <typename> friend class SkMiniPicture;
194
195    void serialize(SkWStream*, SkPixelSerializer*, SkRefCntSet* typefaces) const;
196    static sk_sp<SkPicture> MakeFromStream(SkStream*, SkImageDeserializer*, SkTypefacePlayback*);
197    friend class SkPictureData;
198
199    virtual int numSlowPaths() const = 0;
200    friend class SkPictureGpuAnalyzer;
201    friend struct SkPathCounter;
202
203    // V35: Store SkRect (rather then width & height) in header
204    // V36: Remove (obsolete) alphatype from SkColorTable
205    // V37: Added shadow only option to SkDropShadowImageFilter (last version to record CLEAR)
206    // V38: Added PictureResolution option to SkPictureImageFilter
207    // V39: Added FilterLevel option to SkPictureImageFilter
208    // V40: Remove UniqueID serialization from SkImageFilter.
209    // V41: Added serialization of SkBitmapSource's filterQuality parameter
210    // V42: Added a bool to SkPictureShader serialization to indicate did-we-serialize-a-picture?
211    // V43: Added DRAW_IMAGE and DRAW_IMAGE_RECT opt codes to serialized data
212    // V44: Move annotations from paint to drawAnnotation
213    // V45: Add invNormRotation to SkLightingShader.
214    // V46: Add drawTextRSXform
215    // V47: Add occluder rect to SkBlurMaskFilter
216
217    // Only SKPs within the min/current picture version range (inclusive) can be read.
218    static const uint32_t     MIN_PICTURE_VERSION = 35;     // Produced by Chrome M39.
219    static const uint32_t CURRENT_PICTURE_VERSION = 47;
220
221    static_assert(MIN_PICTURE_VERSION <= 41,
222                  "Remove kFontFileName and related code from SkFontDescriptor.cpp.");
223
224    static_assert(MIN_PICTURE_VERSION <= 42,
225                  "Remove COMMENT API handlers from SkPicturePlayback.cpp");
226
227    static_assert(MIN_PICTURE_VERSION <= 43,
228                  "Remove SkBitmapSourceDeserializer.");
229
230    static_assert(MIN_PICTURE_VERSION <= 45,
231                  "Remove decoding of old SkTypeface::Style from SkFontDescriptor.cpp.");
232
233    static bool IsValidPictInfo(const SkPictInfo& info);
234    static sk_sp<SkPicture> Forwardport(const SkPictInfo&,
235                                        const SkPictureData*,
236                                        const SkReadBuffer* buffer);
237
238    SkPictInfo createHeader() const;
239    SkPictureData* backport() const;
240
241    mutable uint32_t fUniqueID;
242};
243
244#endif
245