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 "SpriteIcon.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  * A sprite is a simple graphical object that is displayed on-screen above other layers.
56  * The basic sprite class is an interface.
57  * The implementation is provided by the sprite controller.
58  */
59 class Sprite : public RefBase {
60 protected:
Sprite()61     Sprite() { }
~Sprite()62     virtual ~Sprite() { }
63 
64 public:
65     enum {
66         // The base layer for pointer sprites.
67         BASE_LAYER_POINTER = 0, // reserve space for 1 pointer
68 
69         // The base layer for spot sprites.
70         BASE_LAYER_SPOT = 1, // reserve space for MAX_POINTER_ID spots
71     };
72 
73     /* Sets the bitmap that is drawn by the sprite.
74      * The sprite retains a copy of the bitmap for subsequent rendering. */
75     virtual void setIcon(const SpriteIcon& icon) = 0;
76 
clearIcon()77     inline void clearIcon() {
78         setIcon(SpriteIcon());
79     }
80 
81     /* Sets whether the sprite is visible. */
82     virtual void setVisible(bool visible) = 0;
83 
84     /* Sets the sprite position on screen, relative to the sprite's hot spot. */
85     virtual void setPosition(float x, float y) = 0;
86 
87     /* Sets the layer of the sprite, relative to the system sprite overlay layer.
88      * Layer 0 is the overlay layer, > 0 appear above this layer. */
89     virtual void setLayer(int32_t layer) = 0;
90 
91     /* Sets the sprite alpha blend ratio between 0.0 and 1.0. */
92     virtual void setAlpha(float alpha) = 0;
93 
94     /* Sets the sprite transformation matrix. */
95     virtual void setTransformationMatrix(const SpriteTransformationMatrix& matrix) = 0;
96 
97     /* Sets the id of the display where the sprite should be shown. */
98     virtual void setDisplayId(int32_t displayId) = 0;
99 };
100 
101 /*
102  * Displays sprites on the screen.
103  *
104  * This interface is used by PointerController and SpotController to draw pointers or
105  * spot representations of fingers.  It is not intended for general purpose use
106  * by other components.
107  *
108  * All sprite position updates and rendering is performed asynchronously.
109  *
110  * Clients are responsible for animating sprites by periodically updating their properties.
111  */
112 class SpriteController : public MessageHandler {
113 protected:
114     virtual ~SpriteController();
115 
116 public:
117     SpriteController(const sp<Looper>& looper, int32_t overlayLayer);
118 
119     /* Creates a new sprite, initially invisible. */
120     virtual sp<Sprite> createSprite();
121 
122     /* Opens or closes a transaction to perform a batch of sprite updates as part of
123      * a single operation such as setPosition and setAlpha.  It is not necessary to
124      * open a transaction when updating a single property.
125      * Calls to openTransaction() nest and must be matched by an equal number
126      * of calls to closeTransaction(). */
127     virtual void openTransaction();
128     virtual void closeTransaction();
129 
130 private:
131     enum {
132         MSG_UPDATE_SPRITES,
133         MSG_DISPOSE_SURFACES,
134     };
135 
136     enum {
137         DIRTY_BITMAP = 1 << 0,
138         DIRTY_ALPHA = 1 << 1,
139         DIRTY_POSITION = 1 << 2,
140         DIRTY_TRANSFORMATION_MATRIX = 1 << 3,
141         DIRTY_LAYER = 1 << 4,
142         DIRTY_VISIBILITY = 1 << 5,
143         DIRTY_HOTSPOT = 1 << 6,
144         DIRTY_DISPLAY_ID = 1 << 7,
145         DIRTY_ICON_STYLE = 1 << 8,
146     };
147 
148     /* Describes the state of a sprite.
149      * This structure is designed so that it can be copied during updates so that
150      * surfaces can be resized and redrawn without blocking the client by holding a lock
151      * on the sprites for a long time.
152      * Note that the SpriteIcon holds a reference to a shared (and immutable) bitmap. */
153     struct SpriteState {
SpriteStateSpriteState154         inline SpriteState() :
155                 dirty(0), visible(false),
156                 positionX(0), positionY(0), layer(0), alpha(1.0f), displayId(ADISPLAY_ID_DEFAULT),
157                 surfaceWidth(0), surfaceHeight(0), surfaceDrawn(false), surfaceVisible(false) {
158         }
159 
160         uint32_t dirty;
161 
162         SpriteIcon icon;
163         bool visible;
164         float positionX;
165         float positionY;
166         int32_t layer;
167         float alpha;
168         SpriteTransformationMatrix transformationMatrix;
169         int32_t displayId;
170 
171         sp<SurfaceControl> surfaceControl;
172         int32_t surfaceWidth;
173         int32_t surfaceHeight;
174         bool surfaceDrawn;
175         bool surfaceVisible;
176 
wantSurfaceVisibleSpriteState177         inline bool wantSurfaceVisible() const {
178             return visible && alpha > 0.0f && icon.isValid();
179         }
180     };
181 
182     /* Client interface for a sprite.
183      * Requests acquire a lock on the controller, update local state and request the
184      * controller to invalidate the sprite.
185      * The real heavy lifting of creating, resizing and redrawing surfaces happens
186      * asynchronously with no locks held except in short critical section to copy
187      * the sprite state before the work and update the sprite surface control afterwards.
188      */
189     class SpriteImpl : public Sprite {
190     protected:
191         virtual ~SpriteImpl();
192 
193     public:
194         explicit SpriteImpl(const sp<SpriteController> controller);
195 
196         virtual void setIcon(const SpriteIcon& icon);
197         virtual void setVisible(bool visible);
198         virtual void setPosition(float x, float y);
199         virtual void setLayer(int32_t layer);
200         virtual void setAlpha(float alpha);
201         virtual void setTransformationMatrix(const SpriteTransformationMatrix& matrix);
202         virtual void setDisplayId(int32_t displayId);
203 
getStateLocked()204         inline const SpriteState& getStateLocked() const {
205             return mLocked.state;
206         }
207 
resetDirtyLocked()208         inline void resetDirtyLocked() {
209             mLocked.state.dirty = 0;
210         }
211 
setSurfaceLocked(const sp<SurfaceControl> & surfaceControl,int32_t width,int32_t height,bool drawn,bool visible)212         inline void setSurfaceLocked(const sp<SurfaceControl>& surfaceControl,
213                 int32_t width, int32_t height, bool drawn, bool visible) {
214             mLocked.state.surfaceControl = surfaceControl;
215             mLocked.state.surfaceWidth = width;
216             mLocked.state.surfaceHeight = height;
217             mLocked.state.surfaceDrawn = drawn;
218             mLocked.state.surfaceVisible = visible;
219         }
220 
221     private:
222         sp<SpriteController> mController;
223 
224         struct Locked {
225             SpriteState state;
226         } mLocked; // guarded by mController->mLock
227 
228         void invalidateLocked(uint32_t dirty);
229     };
230 
231     /* Stores temporary information collected during the sprite update cycle. */
232     struct SpriteUpdate {
SpriteUpdateSpriteUpdate233         inline SpriteUpdate() : surfaceChanged(false) { }
SpriteUpdateSpriteUpdate234         inline SpriteUpdate(const sp<SpriteImpl> sprite, const SpriteState& state) :
235                 sprite(sprite), state(state), surfaceChanged(false) {
236         }
237 
238         sp<SpriteImpl> sprite;
239         SpriteState state;
240         bool surfaceChanged;
241     };
242 
243     mutable Mutex mLock;
244 
245     sp<Looper> mLooper;
246     const int32_t mOverlayLayer;
247     sp<WeakMessageHandler> mHandler;
248 
249     sp<SurfaceComposerClient> mSurfaceComposerClient;
250 
251     struct Locked {
252         Vector<sp<SpriteImpl> > invalidatedSprites;
253         Vector<sp<SurfaceControl> > disposedSurfaces;
254         uint32_t transactionNestingCount;
255         bool deferredSpriteUpdate;
256     } mLocked; // guarded by mLock
257 
258     void invalidateSpriteLocked(const sp<SpriteImpl>& sprite);
259     void disposeSurfaceLocked(const sp<SurfaceControl>& surfaceControl);
260 
261     void handleMessage(const Message& message);
262     void doUpdateSprites();
263     void doDisposeSurfaces();
264 
265     void ensureSurfaceComposerClient();
266     sp<SurfaceControl> obtainSurface(int32_t width, int32_t height);
267 };
268 
269 } // namespace android
270 
271 #endif // _UI_SPRITES_H
272