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 "include/core/SkRect.h" 12 #include "include/core/SkRefCnt.h" 13 #include "include/core/SkTileMode.h" 14 #include "include/core/SkTypes.h" 15 16 class SkCanvas; 17 class SkData; 18 struct SkDeserialProcs; 19 class SkImage; 20 class SkMatrix; 21 struct SkSerialProcs; 22 class SkShader; 23 class SkStream; 24 class SkWStream; 25 26 /** \class SkPicture 27 SkPicture records drawing commands made to SkCanvas. The command stream may be 28 played in whole or in part at a later time. 29 30 SkPicture is an abstract class. SkPicture may be generated by SkPictureRecorder 31 or SkDrawable, or from SkPicture previously saved to SkData or SkStream. 32 33 SkPicture may contain any SkCanvas drawing command, as well as one or more 34 SkCanvas matrix or SkCanvas clip. SkPicture has a cull SkRect, which is used as 35 a bounding box hint. To limit SkPicture bounds, use SkCanvas clip when 36 recording or drawing SkPicture. 37 */ 38 class SK_API SkPicture : public SkRefCnt { 39 public: 40 41 /** Recreates SkPicture that was serialized into a stream. Returns constructed SkPicture 42 if successful; otherwise, returns nullptr. Fails if data does not permit 43 constructing valid SkPicture. 44 45 procs->fPictureProc permits supplying a custom function to decode SkPicture. 46 If procs->fPictureProc is nullptr, default decoding is used. procs->fPictureCtx 47 may be used to provide user context to procs->fPictureProc; procs->fPictureProc 48 is called with a pointer to data, data byte length, and user context. 49 50 @param stream container for serial data 51 @param procs custom serial data decoders; may be nullptr 52 @return SkPicture constructed from stream data 53 */ 54 static sk_sp<SkPicture> MakeFromStream(SkStream* stream, 55 const SkDeserialProcs* procs = nullptr); 56 57 /** Recreates SkPicture that was serialized into data. Returns constructed SkPicture 58 if successful; otherwise, returns nullptr. Fails if data does not permit 59 constructing valid SkPicture. 60 61 procs->fPictureProc permits supplying a custom function to decode SkPicture. 62 If procs->fPictureProc is nullptr, default decoding is used. procs->fPictureCtx 63 may be used to provide user context to procs->fPictureProc; procs->fPictureProc 64 is called with a pointer to data, data byte length, and user context. 65 66 @param data container for serial data 67 @param procs custom serial data decoders; may be nullptr 68 @return SkPicture constructed from data 69 */ 70 static sk_sp<SkPicture> MakeFromData(const SkData* data, 71 const SkDeserialProcs* procs = nullptr); 72 73 /** 74 75 @param data pointer to serial data 76 @param size size of data 77 @param procs custom serial data decoders; may be nullptr 78 @return SkPicture constructed from data 79 */ 80 static sk_sp<SkPicture> MakeFromData(const void* data, size_t size, 81 const SkDeserialProcs* procs = nullptr); 82 83 /** \class SkPicture::AbortCallback 84 AbortCallback is an abstract class. An implementation of AbortCallback may 85 passed as a parameter to SkPicture::playback, to stop it before all drawing 86 commands have been processed. 87 88 If AbortCallback::abort returns true, SkPicture::playback is interrupted. 89 */ 90 class SK_API AbortCallback { 91 public: 92 93 /** Has no effect. 94 95 @return abstract class cannot be instantiated 96 */ AbortCallback()97 AbortCallback() {} 98 99 /** Has no effect. 100 */ ~AbortCallback()101 virtual ~AbortCallback() {} 102 103 /** Stops SkPicture playback when some condition is met. A subclass of 104 AbortCallback provides an override for abort() that can stop SkPicture::playback. 105 106 The part of SkPicture drawn when aborted is undefined. SkPicture instantiations are 107 free to stop drawing at different points during playback. 108 109 If the abort happens inside one or more calls to SkCanvas::save(), stack 110 of SkCanvas matrix and SkCanvas clip values is restored to its state before 111 SkPicture::playback was called. 112 113 @return true to stop playback 114 */ 115 virtual bool abort() = 0; 116 }; 117 118 /** Replays the drawing commands on the specified canvas. In the case that the 119 commands are recorded, each command in the SkPicture is sent separately to canvas. 120 121 To add a single command to draw SkPicture to recording canvas, call 122 SkCanvas::drawPicture instead. 123 124 @param canvas receiver of drawing commands 125 @param callback allows interruption of playback 126 */ 127 virtual void playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const = 0; 128 129 /** Returns cull SkRect for this picture, passed in when SkPicture was created. 130 Returned SkRect does not specify clipping SkRect for SkPicture; cull is hint 131 of SkPicture bounds. 132 133 SkPicture is free to discard recorded drawing commands that fall outside 134 cull. 135 136 @return bounds passed when SkPicture was created 137 */ 138 virtual SkRect cullRect() const = 0; 139 140 /** Returns a non-zero value unique among SkPicture in Skia process. 141 142 @return identifier for SkPicture 143 */ uniqueID()144 uint32_t uniqueID() const { return fUniqueID; } 145 146 /** Returns storage containing SkData describing SkPicture, using optional custom 147 encoders. 148 149 procs->fPictureProc permits supplying a custom function to encode SkPicture. 150 If procs->fPictureProc is nullptr, default encoding is used. procs->fPictureCtx 151 may be used to provide user context to procs->fPictureProc; procs->fPictureProc 152 is called with a pointer to SkPicture and user context. 153 154 @param procs custom serial data encoders; may be nullptr 155 @return storage containing serialized SkPicture 156 */ 157 sk_sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const; 158 159 /** Writes picture to stream, using optional custom encoders. 160 161 procs->fPictureProc permits supplying a custom function to encode SkPicture. 162 If procs->fPictureProc is nullptr, default encoding is used. procs->fPictureCtx 163 may be used to provide user context to procs->fPictureProc; procs->fPictureProc 164 is called with a pointer to SkPicture and user context. 165 166 @param stream writable serial data stream 167 @param procs custom serial data encoders; may be nullptr 168 */ 169 void serialize(SkWStream* stream, const SkSerialProcs* procs = nullptr) const; 170 171 /** Returns a placeholder SkPicture. Result does not draw, and contains only 172 cull SkRect, a hint of its bounds. Result is immutable; it cannot be changed 173 later. Result identifier is unique. 174 175 Returned placeholder can be intercepted during playback to insert other 176 commands into SkCanvas draw stream. 177 178 @param cull placeholder dimensions 179 @return placeholder with unique identifier 180 */ 181 static sk_sp<SkPicture> MakePlaceholder(SkRect cull); 182 183 /** Returns the approximate number of operations in SkPicture. Returned value 184 may be greater or less than the number of SkCanvas calls 185 recorded: some calls may be recorded as more than one operation, other 186 calls may be optimized away. 187 188 @return approximate operation count 189 */ 190 virtual int approximateOpCount() const = 0; 191 192 /** Returns the approximate byte size of SkPicture. Does not include large objects 193 referenced by SkPicture. 194 195 @return approximate size 196 */ 197 virtual size_t approximateBytesUsed() const = 0; 198 199 /** Return a new shader that will draw with this picture. 200 * 201 * @param tmx The tiling mode to use when sampling in the x-direction. 202 * @param tmy The tiling mode to use when sampling in the y-direction. 203 * @param localMatrix Optional matrix used when sampling 204 * @param tile The tile rectangle in picture coordinates: this represents the subset 205 * (or superset) of the picture used when building a tile. It is not 206 * affected by localMatrix and does not imply scaling (only translation 207 * and cropping). If null, the tile rect is considered equal to the picture 208 * bounds. 209 * @return Returns a new shader object. Note: this function never returns null. 210 */ 211 sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, 212 const SkMatrix* localMatrix, const SkRect* tileRect) const; 213 sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, 214 const SkMatrix* localMatrix = nullptr) const; 215 216 private: 217 // Subclass whitelist. 218 SkPicture(); 219 friend class SkBigPicture; 220 friend class SkEmptyPicture; 221 friend class SkPicturePriv; 222 template <typename> friend class SkMiniPicture; 223 224 void serialize(SkWStream*, const SkSerialProcs*, class SkRefCntSet* typefaces, 225 bool textBlobsOnly=false) const; 226 static sk_sp<SkPicture> MakeFromStream(SkStream*, const SkDeserialProcs*, 227 class SkTypefacePlayback*); 228 friend class SkPictureData; 229 230 /** Return true if the SkStream/Buffer represents a serialized picture, and 231 fills out SkPictInfo. After this function returns, the data source is not 232 rewound so it will have to be manually reset before passing to 233 MakeFromStream or MakeFromBuffer. Note, MakeFromStream and 234 MakeFromBuffer perform this check internally so these entry points are 235 intended for stand alone tools. 236 If false is returned, SkPictInfo is unmodified. 237 */ 238 static bool StreamIsSKP(SkStream*, struct SkPictInfo*); 239 static bool BufferIsSKP(class SkReadBuffer*, struct SkPictInfo*); 240 friend bool SkPicture_StreamIsSKP(SkStream*, struct SkPictInfo*); 241 242 // Returns NULL if this is not an SkBigPicture. asSkBigPicture()243 virtual const class SkBigPicture* asSkBigPicture() const { return nullptr; } 244 245 friend struct SkPathCounter; 246 247 static bool IsValidPictInfo(const struct SkPictInfo& info); 248 static sk_sp<SkPicture> Forwardport(const struct SkPictInfo&, 249 const class SkPictureData*, 250 class SkReadBuffer* buffer); 251 252 struct SkPictInfo createHeader() const; 253 class SkPictureData* backport() const; 254 255 uint32_t fUniqueID; 256 }; 257 258 #endif 259