1/*
2 * Copyright 2014 Google Inc.
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 SkDrawable_DEFINED
9#define SkDrawable_DEFINED
10
11#include "include/core/SkFlattenable.h"
12#include "include/core/SkImageInfo.h"
13#include "include/core/SkScalar.h"
14
15class GrBackendDrawableInfo;
16class SkCanvas;
17class SkMatrix;
18class SkPicture;
19enum class GrBackendApi : unsigned;
20struct SkRect;
21
22/**
23 * Base-class for objects that draw into SkCanvas.
24 *
25 * The object has a generation ID, which is guaranteed to be unique across all drawables. To
26 * allow for clients of the drawable that may want to cache the results, the drawable must
27 * change its generation ID whenever its internal state changes such that it will draw differently.
28 */
29class SK_API SkDrawable : public SkFlattenable {
30public:
31 /**
32 * Draws into the specified content. The drawing sequence will be balanced upon return
33 * (i.e. the saveLevel() on the canvas will match what it was when draw() was called,
34 * and the current matrix and clip settings will not be changed.
35 */
36 void draw(SkCanvas*, const SkMatrix* = nullptr);
37 void draw(SkCanvas*, SkScalar x, SkScalar y);
38
39 /**
40 * When using the GPU backend it is possible for a drawable to execute using the underlying 3D
41 * API rather than the SkCanvas API. It does so by creating a GpuDrawHandler. The GPU backend
42 * is deferred so the handler will be given access to the 3D API at the correct point in the
43 * drawing stream as the GPU backend flushes. Since the drawable may mutate, each time it is
44 * drawn to a GPU-backed canvas a new handler is snapped, representing the drawable's state at
45 * the time of the snap.
46 *
47 * When the GPU backend flushes to the 3D API it will call the draw method on the
48 * GpuDrawHandler. At this time the drawable may add commands to the stream of GPU commands for
49 * the unerlying 3D API. The draw function takes a GrBackendDrawableInfo which contains
50 * information about the current state of 3D API which the caller must respect. See
51 * GrBackendDrawableInfo for more specific details on what information is sent and the
52 * requirements for different 3D APIs.
53 *
54 * Additionaly there may be a slight delay from when the drawable adds its commands to when
55 * those commands are actually submitted to the GPU. Thus the drawable or GpuDrawHandler is
56 * required to keep any resources that are used by its added commands alive and valid until
57 * those commands are submitted to the GPU. The GpuDrawHandler will be kept alive and then
58 * deleted once the commands are submitted to the GPU. The dtor of the GpuDrawHandler is the
59 * signal to the drawable that the commands have all been submitted. Different 3D APIs may have
60 * additional requirements for certain resources which require waiting for the GPU to finish
61 * all work on those resources before reusing or deleting them. In this case, the drawable can
62 * use the dtor call of the GpuDrawHandler to add a fence to the GPU to track when the GPU work
63 * has completed.
64 *
65 * Currently this is only supported for the GPU Vulkan backend.
66 */
67
68 class GpuDrawHandler {
69 public:
70 virtual ~GpuDrawHandler() {}
71
72 virtual void draw(const GrBackendDrawableInfo&) {}
73 };
74
75 /**
76 * Snaps off a GpuDrawHandler to represent the state of the SkDrawable at the time the snap is
77 * called. This is used for executing GPU backend specific draws intermixed with normal Skia GPU
78 * draws. The GPU API, which will be used for the draw, as well as the full matrix, device clip
79 * bounds and imageInfo of the target buffer are passed in as inputs.
80 */
81 std::unique_ptr<GpuDrawHandler> snapGpuDrawHandler(GrBackendApi backendApi,
82 const SkMatrix& matrix,
83 const SkIRect& clipBounds,
84 const SkImageInfo& bufferInfo) {
85 return this->onSnapGpuDrawHandler(backendApi, matrix, clipBounds, bufferInfo);
86 }
87
88 SkPicture* newPictureSnapshot();
89
90 /**
91 * Return a unique value for this instance. If two calls to this return the same value,
92 * it is presumed that calling the draw() method will render the same thing as well.
93 *
94 * Subclasses that change their state should call notifyDrawingChanged() to ensure that
95 * a new value will be returned the next time it is called.
96 */
97 uint32_t getGenerationID();
98
99 /**
100 * Return the (conservative) bounds of what the drawable will draw. If the drawable can
101 * change what it draws (e.g. animation or in response to some external change), then this
102 * must return a bounds that is always valid for all possible states.
103 */
104 SkRect getBounds();
105
106 /**
107 * Calling this invalidates the previous generation ID, and causes a new one to be computed
108 * the next time getGenerationID() is called. Typically this is called by the object itself,
109 * in response to its internal state changing.
110 */
111 void notifyDrawingChanged();
112
113 static SkFlattenable::Type GetFlattenableType() {
114 return kSkDrawable_Type;
115 }
116
117 SkFlattenable::Type getFlattenableType() const override {
118 return kSkDrawable_Type;
119 }
120
121 static sk_sp<SkDrawable> Deserialize(const void* data, size_t size,
122 const SkDeserialProcs* procs = nullptr) {
123 return sk_sp<SkDrawable>(static_cast<SkDrawable*>(
124 SkFlattenable::Deserialize(
125 kSkDrawable_Type, data, size, procs).release()));
126 }
127
128 Factory getFactory() const override { return nullptr; }
129 const char* getTypeName() const override { return nullptr; }
130
131protected:
132 SkDrawable();
133
134 virtual SkRect onGetBounds() = 0;
135 virtual void onDraw(SkCanvas*) = 0;
136
137 virtual std::unique_ptr<GpuDrawHandler> onSnapGpuDrawHandler(GrBackendApi, const SkMatrix&,
138 const SkIRect& /*clipBounds*/,
139 const SkImageInfo&) {
140 return nullptr;
141 }
142
143 // TODO: Delete this once Android gets updated to take the clipBounds version above.
144 virtual std::unique_ptr<GpuDrawHandler> onSnapGpuDrawHandler(GrBackendApi, const SkMatrix&) {
145 return nullptr;
146 }
147
148 /**
149 * Default implementation calls onDraw() with a canvas that records into a picture. Subclasses
150 * may override if they have a more efficient way to return a picture for the current state
151 * of their drawable. Note: this picture must draw the same as what would be drawn from
152 * onDraw().
153 */
154 virtual SkPicture* onNewPictureSnapshot();
155
156private:
157 int32_t fGenerationID;
158};
159
160#endif
161