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/** \class SkPicture
28
29    An SkPicture records drawing commands made to a canvas to be played back at a later time.
30    This base class handles serialization and a few other miscellany.
31*/
32class SK_API SkPicture : public SkRefCnt {
33public:
34    virtual ~SkPicture();
35
36    /**
37     *  Function signature defining a function that sets up an SkBitmap from encoded data. On
38     *  success, the SkBitmap should have its Config, width, height, rowBytes and pixelref set.
39     *  If the installed pixelref has decoded the data into pixels, then the src buffer need not be
40     *  copied. If the pixelref defers the actual decode until its lockPixels() is called, then it
41     *  must make a copy of the src buffer.
42     *  @param src Encoded data.
43     *  @param length Size of the encoded data, in bytes.
44     *  @param dst SkBitmap to install the pixel ref on.
45     *  @param bool Whether or not a pixel ref was successfully installed.
46     */
47    typedef bool (*InstallPixelRefProc)(const void* src, size_t length, SkBitmap* dst);
48
49    /**
50     *  Recreate a picture that was serialized into a stream.
51     *  @param SkStream Serialized picture data. Ownership is unchanged by this call.
52     *  @param proc Function pointer for installing pixelrefs on SkBitmaps representing the
53     *              encoded bitmap data from the stream.
54     *  @return A new SkPicture representing the serialized data, or NULL if the stream is
55     *          invalid.
56     */
57    static SkPicture* CreateFromStream(SkStream*, InstallPixelRefProc proc);
58
59    /**
60     *  Recreate a picture that was serialized into a stream.
61     *
62     *  Any serialized images in the stream will be passed to
63     *  SkImageGenerator::NewFromEncoded.
64     *
65     *  @param SkStream Serialized picture data. Ownership is unchanged by this call.
66     *  @return A new SkPicture representing the serialized data, or NULL if the stream is
67     *          invalid.
68     */
69    static SkPicture* CreateFromStream(SkStream*);
70
71    /**
72     *  Recreate a picture that was serialized into a buffer. If the creation requires bitmap
73     *  decoding, the decoder must be set on the SkReadBuffer parameter by calling
74     *  SkReadBuffer::setBitmapDecoder() before calling SkPicture::CreateFromBuffer().
75     *  @param SkReadBuffer Serialized picture data.
76     *  @return A new SkPicture representing the serialized data, or NULL if the buffer is
77     *          invalid.
78     */
79    static SkPicture* CreateFromBuffer(SkReadBuffer&);
80
81    /**
82    *  Subclasses of this can be passed to playback(). During the playback
83    *  of the picture, this callback will periodically be invoked. If its
84    *  abort() returns true, then picture playback will be interrupted.
85    *
86    *  The resulting drawing is undefined, as there is no guarantee how often the
87    *  callback will be invoked. If the abort happens inside some level of nested
88    *  calls to save(), restore will automatically be called to return the state
89    *  to the same level it was before the playback call was made.
90    */
91    class SK_API AbortCallback {
92    public:
93        AbortCallback() {}
94        virtual ~AbortCallback() {}
95        virtual bool abort() = 0;
96    };
97
98    /** Replays the drawing commands on the specified canvas. Note that
99        this has the effect of unfurling this picture into the destination
100        canvas. Using the SkCanvas::drawPicture entry point gives the destination
101        canvas the option of just taking a ref.
102        @param canvas the canvas receiving the drawing commands.
103        @param callback a callback that allows interruption of playback
104    */
105    virtual void playback(SkCanvas*, AbortCallback* = NULL) const = 0;
106
107    /** Return a cull rect for this picture.
108        Ops recorded into this picture that attempt to draw outside the cull might not be drawn.
109     */
110    virtual SkRect cullRect() const = 0;
111
112    /** Returns a non-zero value unique among all pictures. */
113    uint32_t uniqueID() const;
114
115    /**
116     *  Serialize to a stream. If non NULL, serializer will be used to serialize
117     *  bitmaps and images in the picture.
118     */
119    void serialize(SkWStream*, SkPixelSerializer* = NULL) const;
120
121    /**
122     *  Serialize to a buffer.
123     */
124    void flatten(SkWriteBuffer&) const;
125
126    /**
127     * Returns true if any bitmaps may be produced when this SkPicture
128     * is replayed.
129     */
130    virtual bool willPlayBackBitmaps() const = 0;
131
132    /** Return the approximate number of operations in this picture.  This
133     *  number may be greater or less than the number of SkCanvas calls
134     *  recorded: some calls may be recorded as more than one operation, or some
135     *  calls may be optimized away.
136     */
137    virtual int approximateOpCount() const = 0;
138
139    /** Return true if this picture contains text.
140     */
141    virtual bool hasText() const = 0;
142
143    /** Returns the approximate byte size of this picture, not including large ref'd objects. */
144    virtual size_t approximateBytesUsed() const = 0;
145
146    /** Return true if the SkStream/Buffer represents a serialized picture, and
147        fills out SkPictInfo. After this function returns, the data source is not
148        rewound so it will have to be manually reset before passing to
149        CreateFromStream or CreateFromBuffer. Note, CreateFromStream and
150        CreateFromBuffer perform this check internally so these entry points are
151        intended for stand alone tools.
152        If false is returned, SkPictInfo is unmodified.
153    */
154    static bool InternalOnly_StreamIsSKP(SkStream*, SkPictInfo*);
155    static bool InternalOnly_BufferIsSKP(SkReadBuffer*, SkPictInfo*);
156
157    /** Return true if the picture is suitable for rendering on the GPU.  */
158    bool suitableForGpuRasterization(GrContext*, const char** whyNot = NULL) const;
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 SkPicture* CreateFromStream(SkStream*,
179                                       InstallPixelRefProc proc,
180                                       SkTypefacePlayback*);
181    friend class SkPictureData;
182
183    virtual int numSlowPaths() const = 0;
184    friend struct SkPathCounter;
185
186    // V35: Store SkRect (rather then width & height) in header
187    // V36: Remove (obsolete) alphatype from SkColorTable
188    // V37: Added shadow only option to SkDropShadowImageFilter (last version to record CLEAR)
189    // V38: Added PictureResolution option to SkPictureImageFilter
190    // V39: Added FilterLevel option to SkPictureImageFilter
191    // V40: Remove UniqueID serialization from SkImageFilter.
192    // V41: Added serialization of SkBitmapSource's filterQuality parameter
193    // V42: Added a bool to SkPictureShader serialization to indicate did-we-serialize-a-picture?
194    // V43: Added DRAW_IMAGE and DRAW_IMAGE_RECT opt codes to serialized data
195
196    // Only SKPs within the min/current picture version range (inclusive) can be read.
197    static const uint32_t     MIN_PICTURE_VERSION = 35;     // Produced by Chrome M39.
198    static const uint32_t CURRENT_PICTURE_VERSION = 43;
199
200    static_assert(MIN_PICTURE_VERSION <= 41,
201                  "Remove kFontFileName and related code from SkFontDescriptor.cpp.");
202
203    static_assert(MIN_PICTURE_VERSION <= 42,
204                  "Remove COMMENT API handlers from SkPicturePlayback.cpp");
205
206    static_assert(MIN_PICTURE_VERSION <= 43,
207                  "Remove SkBitmapSourceDeserializer.");
208
209    static bool IsValidPictInfo(const SkPictInfo& info);
210    static SkPicture* Forwardport(const SkPictInfo&, const SkPictureData*);
211
212    SkPictInfo createHeader() const;
213    SkPictureData* backport() const;
214
215    mutable uint32_t fUniqueID;
216};
217
218#endif
219