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 /* Generated by tools/bookmaker from include/core/SkPicture.h and docs/SkPicture_Reference.bmh 9 on 2018-08-10 12:59:44. Additional documentation and examples can be found at: 10 https://skia.org/user/api/SkPicture_Reference 11 12 You may edit either file directly. Structural changes to public interfaces require 13 editing both files. After editing docs/SkPicture_Reference.bmh, run: 14 bookmaker -b docs -i include/core/SkPicture.h -p 15 to create an updated version of this file. 16 */ 17 18 #ifndef SkPicture_DEFINED 19 #define SkPicture_DEFINED 20 21 #include "SkRefCnt.h" 22 #include "SkRect.h" 23 #include "SkTypes.h" 24 25 class SkCanvas; 26 class SkData; 27 struct SkDeserialProcs; 28 class SkImage; 29 struct SkSerialProcs; 30 class SkStream; 31 class SkWStream; 32 33 /** \class SkPicture 34 SkPicture records drawing commands made to SkCanvas. The command stream may be 35 played in whole or in part at a later time. 36 37 SkPicture is an abstract class. SkPicture may be generated by SkPictureRecorder 38 or SkDrawable, or from SkPicture previously saved to SkData or SkStream. 39 40 SkPicture may contain any SkCanvas drawing command, as well as one or more 41 SkCanvas matrix or SkCanvas clip. SkPicture has a cull SkRect, which is used as 42 a bounding box hint. To limit SkPicture bounds, use SkCanvas clip when 43 recording or drawing SkPicture. 44 */ 45 class SK_API SkPicture : public SkRefCnt { 46 public: 47 48 /** Recreates SkPicture that was serialized into a stream. Returns constructed SkPicture 49 if successful; otherwise, returns nullptr. Fails if data does not permit 50 constructing valid SkPicture. 51 52 procs->fPictureProc permits supplying a custom function to decode SkPicture. 53 If procs->fPictureProc is nullptr, default decoding is used. procs->fPictureCtx 54 may be used to provide user context to procs->fPictureProc; procs->fPictureProc 55 is called with a pointer to data, data byte length, and user context. 56 57 @param stream container for serial data 58 @param procs custom serial data decoders; may be nullptr 59 @return SkPicture constructed from stream data 60 */ 61 static sk_sp<SkPicture> MakeFromStream(SkStream* stream, 62 const SkDeserialProcs* procs = nullptr); 63 64 /** Recreates SkPicture that was serialized into data. Returns constructed SkPicture 65 if successful; otherwise, returns nullptr. Fails if data does not permit 66 constructing valid SkPicture. 67 68 procs->fPictureProc permits supplying a custom function to decode SkPicture. 69 If procs->fPictureProc is nullptr, default decoding is used. procs->fPictureCtx 70 may be used to provide user context to procs->fPictureProc; procs->fPictureProc 71 is called with a pointer to data, data byte length, and user context. 72 73 @param data container for serial data 74 @param procs custom serial data decoders; may be nullptr 75 @return SkPicture constructed from data 76 */ 77 static sk_sp<SkPicture> MakeFromData(const SkData* data, 78 const SkDeserialProcs* procs = nullptr); 79 80 /** 81 82 @param data pointer to serial data 83 @param size size of data 84 @param procs custom serial data decoders; may be nullptr 85 @return SkPicture constructed from data 86 */ 87 static sk_sp<SkPicture> MakeFromData(const void* data, size_t size, 88 const SkDeserialProcs* procs = nullptr); 89 90 /** \class SkPicture::AbortCallback 91 AbortCallback is an abstract class. An implementation of AbortCallback may 92 passed as a parameter to SkPicture::playback, to stop it before all drawing 93 commands have been processed. 94 95 If AbortCallback::abort returns true, SkPicture::playback is interrupted. 96 */ 97 class SK_API AbortCallback { 98 public: 99 100 /** Has no effect. 101 102 @return abstract class cannot be instantiated 103 */ AbortCallback()104 AbortCallback() {} 105 106 /** Has no effect. 107 */ ~AbortCallback()108 virtual ~AbortCallback() {} 109 110 /** Stops SkPicture playback when some condition is met. A subclass of 111 AbortCallback provides an override for abort() that can stop SkPicture::playback. 112 113 The part of SkPicture drawn when aborted is undefined. SkPicture instantiations are 114 free to stop drawing at different points during playback. 115 116 If the abort happens inside one or more calls to SkCanvas::save(), stack 117 of SkCanvas matrix and SkCanvas clip values is restored to its state before 118 SkPicture::playback was called. 119 120 @return true to stop playback 121 */ 122 virtual bool abort() = 0; 123 }; 124 125 /** Replays the drawing commands on the specified canvas. In the case that the 126 commands are recorded, each command in the SkPicture is sent separately to canvas. 127 128 To add a single command to draw SkPicture to recording canvas, call 129 SkCanvas::drawPicture instead. 130 131 @param canvas receiver of drawing commands 132 @param callback allows interruption of playback 133 */ 134 virtual void playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const = 0; 135 136 /** Returns cull SkRect for this picture, passed in when SkPicture was created. 137 Returned SkRect does not specify clipping SkRect for SkPicture; cull is hint 138 of SkPicture bounds. 139 140 SkPicture is free to discard recorded drawing commands that fall outside 141 cull. 142 143 @return bounds passed when SkPicture was created 144 */ 145 virtual SkRect cullRect() const = 0; 146 147 /** Returns a non-zero value unique among SkPicture in Skia process. 148 149 @return identifier for SkPicture 150 */ uniqueID()151 uint32_t uniqueID() const { return fUniqueID; } 152 153 /** Returns storage containing SkData describing SkPicture, using optional custom 154 encoders. 155 156 procs->fPictureProc permits supplying a custom function to encode SkPicture. 157 If procs->fPictureProc is nullptr, default encoding is used. procs->fPictureCtx 158 may be used to provide user context to procs->fPictureProc; procs->fPictureProc 159 is called with a pointer to SkPicture and user context. 160 161 @param procs custom serial data encoders; may be nullptr 162 @return storage containing serialized SkPicture 163 */ 164 sk_sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const; 165 166 /** Writes picture to stream, using optional custom encoders. 167 168 procs->fPictureProc permits supplying a custom function to encode SkPicture. 169 If procs->fPictureProc is nullptr, default encoding is used. procs->fPictureCtx 170 may be used to provide user context to procs->fPictureProc; procs->fPictureProc 171 is called with a pointer to SkPicture and user context. 172 173 @param stream writable serial data stream 174 @param procs custom serial data encoders; may be nullptr 175 */ 176 void serialize(SkWStream* stream, const SkSerialProcs* procs = nullptr) const; 177 178 /** Returns a placeholder SkPicture. Result does not draw, and contains only 179 cull SkRect, a hint of its bounds. Result is immutable; it cannot be changed 180 later. Result identifier is unique. 181 182 Returned placeholder can be intercepted during playback to insert other 183 commands into SkCanvas draw stream. 184 185 @param cull placeholder dimensions 186 @return placeholder with unique identifier 187 */ 188 static sk_sp<SkPicture> MakePlaceholder(SkRect cull); 189 190 /** Returns the approximate number of operations in SkPicture. Returned value 191 may be greater or less than the number of SkCanvas calls 192 recorded: some calls may be recorded as more than one operation, other 193 calls may be optimized away. 194 195 @return approximate operation count 196 */ 197 virtual int approximateOpCount() const = 0; 198 199 /** Returns the approximate byte size of SkPicture. Does not include large objects 200 referenced by SkPicture. 201 202 @return approximate size 203 */ 204 virtual size_t approximateBytesUsed() const = 0; 205 206 private: 207 // Subclass whitelist. 208 SkPicture(); 209 friend class SkBigPicture; 210 friend class SkEmptyPicture; 211 friend class SkPicturePriv; 212 template <typename> friend class SkMiniPicture; 213 214 void serialize(SkWStream*, const SkSerialProcs*, class SkRefCntSet* typefaces) const; 215 static sk_sp<SkPicture> MakeFromStream(SkStream*, const SkDeserialProcs*, 216 class SkTypefacePlayback*); 217 friend class SkPictureData; 218 219 /** Return true if the SkStream/Buffer represents a serialized picture, and 220 fills out SkPictInfo. After this function returns, the data source is not 221 rewound so it will have to be manually reset before passing to 222 MakeFromStream or MakeFromBuffer. Note, MakeFromStream and 223 MakeFromBuffer perform this check internally so these entry points are 224 intended for stand alone tools. 225 If false is returned, SkPictInfo is unmodified. 226 */ 227 static bool StreamIsSKP(SkStream*, struct SkPictInfo*); 228 static bool BufferIsSKP(class SkReadBuffer*, struct SkPictInfo*); 229 friend bool SkPicture_StreamIsSKP(SkStream*, struct SkPictInfo*); 230 231 // Returns NULL if this is not an SkBigPicture. asSkBigPicture()232 virtual const class SkBigPicture* asSkBigPicture() const { return nullptr; } 233 234 friend struct SkPathCounter; 235 236 // V35: Store SkRect (rather then width & height) in header 237 // V36: Remove (obsolete) alphatype from SkColorTable 238 // V37: Added shadow only option to SkDropShadowImageFilter (last version to record CLEAR) 239 // V38: Added PictureResolution option to SkPictureImageFilter 240 // V39: Added FilterLevel option to SkPictureImageFilter 241 // V40: Remove UniqueID serialization from SkImageFilter. 242 // V41: Added serialization of SkBitmapSource's filterQuality parameter 243 // V42: Added a bool to SkPictureShader serialization to indicate did-we-serialize-a-picture? 244 // V43: Added DRAW_IMAGE and DRAW_IMAGE_RECT opt codes to serialized data 245 // V44: Move annotations from paint to drawAnnotation 246 // V45: Add invNormRotation to SkLightingShader. 247 // V46: Add drawTextRSXform 248 // V47: Add occluder rect to SkBlurMaskFilter 249 // V48: Read and write extended SkTextBlobs. 250 // V49: Gradients serialized as SkColor4f + SkColorSpace 251 // V50: SkXfermode -> SkBlendMode 252 // V51: more SkXfermode -> SkBlendMode 253 // V52: Remove SkTextBlob::fRunCount 254 // V53: SaveLayerRec clip mask 255 // V54: ComposeShader can use a Mode or a Lerp 256 // V55: Drop blendmode[] from MergeImageFilter 257 // V56: Add TileMode in SkBlurImageFilter. 258 // V57: Sweep tiling info. 259 // V58: No more 2pt conical flipping. 260 // V59: No more LocalSpace option on PictureImageFilter 261 // V60: Remove flags in picture header 262 // V61: Change SkDrawPictureRec to take two colors rather than two alphas 263 // V62: Don't negate size of custom encoded images (don't write origin x,y either) 264 // V63: Store image bounds (including origin) instead of just width/height to support subsets 265 // V64: Remove occluder feature from blur maskFilter 266 // V65: Float4 paint color 267 // V66: Add saveBehind 268 // V67: Blobs serialize fonts instead of paints 269 // V68: Paint doesn't serialize font-related stuff 270 271 // Only SKPs within the min/current picture version range (inclusive) can be read. 272 static const uint32_t MIN_PICTURE_VERSION = 56; // august 2017 273 static const uint32_t CURRENT_PICTURE_VERSION = 68; 274 275 static_assert(MIN_PICTURE_VERSION <= 62, "Remove kFontAxes_bad from SkFontDescriptor.cpp"); 276 277 static bool IsValidPictInfo(const struct SkPictInfo& info); 278 static sk_sp<SkPicture> Forwardport(const struct SkPictInfo&, 279 const class SkPictureData*, 280 class SkReadBuffer* buffer); 281 282 struct SkPictInfo createHeader() const; 283 class SkPictureData* backport() const; 284 285 uint32_t fUniqueID; 286 }; 287 288 #endif 289