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 | |
15 | class GrBackendDrawableInfo; |
16 | class SkCanvas; |
17 | class SkMatrix; |
18 | class SkPicture; |
19 | enum class GrBackendApi : unsigned; |
20 | struct 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 | */ |
29 | class SK_API SkDrawable : public SkFlattenable { |
30 | public: |
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 | |
131 | protected: |
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 | |
156 | private: |
157 | int32_t fGenerationID; |
158 | }; |
159 | |
160 | #endif |
161 | |