diff options
Diffstat (limited to 'include/core/SkPicture.h')
| -rw-r--r-- | include/core/SkPicture.h | 125 |
1 files changed, 95 insertions, 30 deletions
diff --git a/include/core/SkPicture.h b/include/core/SkPicture.h index 1a9fe04f5c..a88c101eda 100644 --- a/include/core/SkPicture.h +++ b/include/core/SkPicture.h @@ -5,6 +5,16 @@ * found in the LICENSE file. */ +/* Generated by tools/bookmaker from include/core/SkPicture.h and docs/SkPicture_Reference.bmh + on 2018-07-13 08:15:11. Additional documentation and examples can be found at: + https://skia.org/user/api/SkPicture_Reference + + You may edit either file directly. Structural changes to public interfaces require + editing both files. After editing docs/SkPicture_Reference.bmh, run: + bookmaker -b docs -i include/core/SkPicture.h -p + to create an updated version of this file. + */ + #ifndef SkPicture_DEFINED #define SkPicture_DEFINED @@ -21,37 +31,68 @@ class SkStream; class SkWStream; /** \class SkPicture - An SkPicture records drawing commands made to a canvas to be played back at a later time. This base class handles serialization and a few other miscellany. */ class SK_API SkPicture : public SkRefCnt { public: - /** - * Recreate a picture that was serialized into a stream or data. - */ + /** Recreates a picture that was serialized into a stream. + + @param stream container for serial data + @param procs custom serial data decoders; may be nullptr + @return SkPicture constructed from stream data + */ static sk_sp<SkPicture> MakeFromStream(SkStream* stream, const SkDeserialProcs* procs = nullptr); + + /** Recreates a picture that was serialized into data. + + @param data container for serial data + @param procs custom serial data decoders; may be nullptr + @return SkPicture constructed from data + */ static sk_sp<SkPicture> MakeFromData(const SkData* data, const SkDeserialProcs* procs = nullptr); + + /** + + @param data pointer to serial data + @param size size of data + @param procs custom serial data decoders; may be nullptr + @return SkPicture constructed from data + */ static sk_sp<SkPicture> MakeFromData(const void* data, size_t size, const SkDeserialProcs* procs = nullptr); - /** - * Subclasses of this can be passed to playback(). During the playback - * of the picture, this callback will periodically be invoked. If its - * abort() returns true, then picture playback will be interrupted. - * - * The resulting drawing is undefined, as there is no guarantee how often the - * callback will be invoked. If the abort happens inside some level of nested - * calls to save(), restore will automatically be called to return the state - * to the same level it was before the playback call was made. + /** \class SkPicture::AbortCallback + Subclasses of this can be passed to playback(). During the playback + of the picture, this callback will periodically be invoked. If its + abort() returns true, then picture playback will be interrupted. + The resulting drawing is undefined, as there is no guarantee how often the + callback will be invoked. If the abort happens inside some level of nested + calls to save(), restore will automatically be called to return the state + to the same level it was before the playback call was made. */ class SK_API AbortCallback { public: + + /** Has no effect. + + @return abstract class cannot be instantiated + */ AbortCallback() {} + + /** Has no effect. + */ virtual ~AbortCallback() {} + + /** Stops SkPicture playback when some condition is met. A subclass of + AbortCallback provides an override for abort() that can stop playback() from + drawing the entire picture. + + @return true to stop playback + */ virtual bool abort() = 0; }; @@ -59,38 +100,62 @@ public: this has the effect of unfurling this picture into the destination canvas. Using the SkCanvas::drawPicture entry point gives the destination canvas the option of just taking a ref. - @param canvas the canvas receiving the drawing commands. - @param callback a callback that allows interruption of playback + + @param canvas receiver of drawing commands + @param callback allows interruption of playback */ virtual void playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const = 0; - /** Return a cull rect for this picture. + /** Returns cull SkRect for this picture. Ops recorded into this picture that attempt to draw outside the cull might not be drawn. - */ + + @return bounds passed when SkPicture was created + */ virtual SkRect cullRect() const = 0; - /** Returns a non-zero value unique among all pictures. */ + /** Returns a non-zero value unique among all pictures. + + @return identifier for SkPicture + */ uint32_t uniqueID() const; + /** Returns storage containing data describing SkPicture, using optional custom encoders. + + @param procs custom serial data encoders; may be nullptr + @return storage containing serialized SkPicture + */ sk_sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const; + + /** Writes picture to stream, using optional custom encoders. + + @param stream writable serial data stream + @param procs custom serial data encoders; may be nullptr + */ void serialize(SkWStream* stream, const SkSerialProcs* procs = nullptr) const; - /** - * Return a placeholder SkPicture. - * This placeholder does not draw anything itself. It has a distinct uniqueID() - * (just like all SkPictures) and will always be visible to SkSerialProcs. - * @param cull the placeholder's dimensions - */ + /** Returns a placeholder SkPicture. + This placeholder does not draw anything itself. It has a distinct uniqueID() + (just like all SkPicture) and will always be visible to SkSerialProcs. + + @param cull placeholder dimensions + @return placeholder with unique identifier + */ static sk_sp<SkPicture> MakePlaceholder(SkRect cull); - /** Return the approximate number of operations in this picture. This - * number may be greater or less than the number of SkCanvas calls - * recorded: some calls may be recorded as more than one operation, or some - * calls may be optimized away. - */ + /** Returns the approximate number of operations in this picture. This + number may be greater or less than the number of SkCanvas calls + recorded: some calls may be recorded as more than one operation, or some + calls may be optimized away. + + @return approximate operation count + */ virtual int approximateOpCount() const = 0; - /** Returns the approximate byte size of this picture, not including large ref'd objects. */ + /** Returns the approximate byte size of SkPicture. Does not include large objects + referenced SkPicture. + + @return approximate size + */ virtual size_t approximateBytesUsed() const = 0; private: |