1 /*
2  * Copyright (C) 2011 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef _UI_SPRITES_H
18 #define _UI_SPRITES_H
19 
20 #include <utils/RefBase.h>
21 #include <utils/Looper.h>
22 
23 #include <gui/SurfaceComposerClient.h>
24 
25 #include <SkBitmap.h>
26 
27 namespace android {
28 
29 /*
30  * Transformation matrix for a sprite.
31  */
32 struct SpriteTransformationMatrix {
SpriteTransformationMatrixSpriteTransformationMatrix33     inline SpriteTransformationMatrix() : dsdx(1.0f), dtdx(0.0f), dsdy(0.0f), dtdy(1.0f) { }
SpriteTransformationMatrixSpriteTransformationMatrix34     inline SpriteTransformationMatrix(float dsdx, float dtdx, float dsdy, float dtdy) :
35             dsdx(dsdx), dtdx(dtdx), dsdy(dsdy), dtdy(dtdy) { }
36 
37     float dsdx;
38     float dtdx;
39     float dsdy;
40     float dtdy;
41 
42     inline bool operator== (const SpriteTransformationMatrix& other) {
43         return dsdx == other.dsdx
44                 && dtdx == other.dtdx
45                 && dsdy == other.dsdy
46                 && dtdy == other.dtdy;
47     }
48 
49     inline bool operator!= (const SpriteTransformationMatrix& other) {
50         return !(*this == other);
51     }
52 };
53 
54 /*
55  * Icon that a sprite displays, including its hotspot.
56  */
57 struct SpriteIcon {
SpriteIconSpriteIcon58     inline SpriteIcon() : hotSpotX(0), hotSpotY(0) { }
SpriteIconSpriteIcon59     inline SpriteIcon(const SkBitmap& bitmap, float hotSpotX, float hotSpotY) :
60             bitmap(bitmap), hotSpotX(hotSpotX), hotSpotY(hotSpotY) { }
61 
62     SkBitmap bitmap;
63     float hotSpotX;
64     float hotSpotY;
65 
copySpriteIcon66     inline SpriteIcon copy() const {
67         SkBitmap bitmapCopy;
68         bitmap.copyTo(&bitmapCopy, kN32_SkColorType);
69         return SpriteIcon(bitmapCopy, hotSpotX, hotSpotY);
70     }
71 
resetSpriteIcon72     inline void reset() {
73         bitmap.reset();
74         hotSpotX = 0;
75         hotSpotY = 0;
76     }
77 
isValidSpriteIcon78     inline bool isValid() const {
79         return !bitmap.isNull() && !bitmap.empty();
80     }
81 };
82 
83 /*
84  * A sprite is a simple graphical object that is displayed on-screen above other layers.
85  * The basic sprite class is an interface.
86  * The implementation is provided by the sprite controller.
87  */
88 class Sprite : public RefBase {
89 protected:
Sprite()90     Sprite() { }
~Sprite()91     virtual ~Sprite() { }
92 
93 public:
94     enum {
95         // The base layer for pointer sprites.
96         BASE_LAYER_POINTER = 0, // reserve space for 1 pointer
97 
98         // The base layer for spot sprites.
99         BASE_LAYER_SPOT = 1, // reserve space for MAX_POINTER_ID spots
100     };
101 
102     /* Sets the bitmap that is drawn by the sprite.
103      * The sprite retains a copy of the bitmap for subsequent rendering. */
104     virtual void setIcon(const SpriteIcon& icon) = 0;
105 
clearIcon()106     inline void clearIcon() {
107         setIcon(SpriteIcon());
108     }
109 
110     /* Sets whether the sprite is visible. */
111     virtual void setVisible(bool visible) = 0;
112 
113     /* Sets the sprite position on screen, relative to the sprite's hot spot. */
114     virtual void setPosition(float x, float y) = 0;
115 
116     /* Sets the layer of the sprite, relative to the system sprite overlay layer.
117      * Layer 0 is the overlay layer, > 0 appear above this layer. */
118     virtual void setLayer(int32_t layer) = 0;
119 
120     /* Sets the sprite alpha blend ratio between 0.0 and 1.0. */
121     virtual void setAlpha(float alpha) = 0;
122 
123     /* Sets the sprite transformation matrix. */
124     virtual void setTransformationMatrix(const SpriteTransformationMatrix& matrix) = 0;
125 };
126 
127 /*
128  * Displays sprites on the screen.
129  *
130  * This interface is used by PointerController and SpotController to draw pointers or
131  * spot representations of fingers.  It is not intended for general purpose use
132  * by other components.
133  *
134  * All sprite position updates and rendering is performed asynchronously.
135  *
136  * Clients are responsible for animating sprites by periodically updating their properties.
137  */
138 class SpriteController : public MessageHandler {
139 protected:
140     virtual ~SpriteController();
141 
142 public:
143     SpriteController(const sp<Looper>& looper, int32_t overlayLayer);
144 
145     /* Creates a new sprite, initially invisible. */
146     sp<Sprite> createSprite();
147 
148     /* Opens or closes a transaction to perform a batch of sprite updates as part of
149      * a single operation such as setPosition and setAlpha.  It is not necessary to
150      * open a transaction when updating a single property.
151      * Calls to openTransaction() nest and must be matched by an equal number
152      * of calls to closeTransaction(). */
153     void openTransaction();
154     void closeTransaction();
155 
156 private:
157     enum {
158         MSG_UPDATE_SPRITES,
159         MSG_DISPOSE_SURFACES,
160     };
161 
162     enum {
163         DIRTY_BITMAP = 1 << 0,
164         DIRTY_ALPHA = 1 << 1,
165         DIRTY_POSITION = 1 << 2,
166         DIRTY_TRANSFORMATION_MATRIX = 1 << 3,
167         DIRTY_LAYER = 1 << 4,
168         DIRTY_VISIBILITY = 1 << 5,
169         DIRTY_HOTSPOT = 1 << 6,
170     };
171 
172     /* Describes the state of a sprite.
173      * This structure is designed so that it can be copied during updates so that
174      * surfaces can be resized and redrawn without blocking the client by holding a lock
175      * on the sprites for a long time.
176      * Note that the SkBitmap holds a reference to a shared (and immutable) pixel ref. */
177     struct SpriteState {
SpriteStateSpriteState178         inline SpriteState() :
179                 dirty(0), visible(false),
180                 positionX(0), positionY(0), layer(0), alpha(1.0f),
181                 surfaceWidth(0), surfaceHeight(0), surfaceDrawn(false), surfaceVisible(false) {
182         }
183 
184         uint32_t dirty;
185 
186         SpriteIcon icon;
187         bool visible;
188         float positionX;
189         float positionY;
190         int32_t layer;
191         float alpha;
192         SpriteTransformationMatrix transformationMatrix;
193 
194         sp<SurfaceControl> surfaceControl;
195         int32_t surfaceWidth;
196         int32_t surfaceHeight;
197         bool surfaceDrawn;
198         bool surfaceVisible;
199 
wantSurfaceVisibleSpriteState200         inline bool wantSurfaceVisible() const {
201             return visible && alpha > 0.0f && icon.isValid();
202         }
203     };
204 
205     /* Client interface for a sprite.
206      * Requests acquire a lock on the controller, update local state and request the
207      * controller to invalidate the sprite.
208      * The real heavy lifting of creating, resizing and redrawing surfaces happens
209      * asynchronously with no locks held except in short critical section to copy
210      * the sprite state before the work and update the sprite surface control afterwards.
211      */
212     class SpriteImpl : public Sprite {
213     protected:
214         virtual ~SpriteImpl();
215 
216     public:
217         SpriteImpl(const sp<SpriteController> controller);
218 
219         virtual void setIcon(const SpriteIcon& icon);
220         virtual void setVisible(bool visible);
221         virtual void setPosition(float x, float y);
222         virtual void setLayer(int32_t layer);
223         virtual void setAlpha(float alpha);
224         virtual void setTransformationMatrix(const SpriteTransformationMatrix& matrix);
225 
getStateLocked()226         inline const SpriteState& getStateLocked() const {
227             return mLocked.state;
228         }
229 
resetDirtyLocked()230         inline void resetDirtyLocked() {
231             mLocked.state.dirty = 0;
232         }
233 
setSurfaceLocked(const sp<SurfaceControl> & surfaceControl,int32_t width,int32_t height,bool drawn,bool visible)234         inline void setSurfaceLocked(const sp<SurfaceControl>& surfaceControl,
235                 int32_t width, int32_t height, bool drawn, bool visible) {
236             mLocked.state.surfaceControl = surfaceControl;
237             mLocked.state.surfaceWidth = width;
238             mLocked.state.surfaceHeight = height;
239             mLocked.state.surfaceDrawn = drawn;
240             mLocked.state.surfaceVisible = visible;
241         }
242 
243     private:
244         sp<SpriteController> mController;
245 
246         struct Locked {
247             SpriteState state;
248         } mLocked; // guarded by mController->mLock
249 
250         void invalidateLocked(uint32_t dirty);
251     };
252 
253     /* Stores temporary information collected during the sprite update cycle. */
254     struct SpriteUpdate {
SpriteUpdateSpriteUpdate255         inline SpriteUpdate() : surfaceChanged(false) { }
SpriteUpdateSpriteUpdate256         inline SpriteUpdate(const sp<SpriteImpl> sprite, const SpriteState& state) :
257                 sprite(sprite), state(state), surfaceChanged(false) {
258         }
259 
260         sp<SpriteImpl> sprite;
261         SpriteState state;
262         bool surfaceChanged;
263     };
264 
265     mutable Mutex mLock;
266 
267     sp<Looper> mLooper;
268     const int32_t mOverlayLayer;
269     sp<WeakMessageHandler> mHandler;
270 
271     sp<SurfaceComposerClient> mSurfaceComposerClient;
272 
273     struct Locked {
274         Vector<sp<SpriteImpl> > invalidatedSprites;
275         Vector<sp<SurfaceControl> > disposedSurfaces;
276         uint32_t transactionNestingCount;
277         bool deferredSpriteUpdate;
278     } mLocked; // guarded by mLock
279 
280     void invalidateSpriteLocked(const sp<SpriteImpl>& sprite);
281     void disposeSurfaceLocked(const sp<SurfaceControl>& surfaceControl);
282 
283     void handleMessage(const Message& message);
284     void doUpdateSprites();
285     void doDisposeSurfaces();
286 
287     void ensureSurfaceComposerClient();
288     sp<SurfaceControl> obtainSurface(int32_t width, int32_t height);
289 };
290 
291 } // namespace android
292 
293 #endif // _UI_SPRITES_H
294