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 using ParentSurfaceProvider = std::function<sp<SurfaceControl>(int /*displayId*/)>; 118 SpriteController(const sp<Looper>& looper, int32_t overlayLayer, ParentSurfaceProvider parent); 119 120 /* Creates a new sprite, initially invisible. */ 121 virtual sp<Sprite> createSprite(); 122 123 /* Opens or closes a transaction to perform a batch of sprite updates as part of 124 * a single operation such as setPosition and setAlpha. It is not necessary to 125 * open a transaction when updating a single property. 126 * Calls to openTransaction() nest and must be matched by an equal number 127 * of calls to closeTransaction(). */ 128 virtual void openTransaction(); 129 virtual void closeTransaction(); 130 131 private: 132 enum { 133 MSG_UPDATE_SPRITES, 134 MSG_DISPOSE_SURFACES, 135 }; 136 137 enum { 138 DIRTY_BITMAP = 1 << 0, 139 DIRTY_ALPHA = 1 << 1, 140 DIRTY_POSITION = 1 << 2, 141 DIRTY_TRANSFORMATION_MATRIX = 1 << 3, 142 DIRTY_LAYER = 1 << 4, 143 DIRTY_VISIBILITY = 1 << 5, 144 DIRTY_HOTSPOT = 1 << 6, 145 DIRTY_DISPLAY_ID = 1 << 7, 146 DIRTY_ICON_STYLE = 1 << 8, 147 }; 148 149 /* Describes the state of a sprite. 150 * This structure is designed so that it can be copied during updates so that 151 * surfaces can be resized and redrawn without blocking the client by holding a lock 152 * on the sprites for a long time. 153 * Note that the SpriteIcon holds a reference to a shared (and immutable) bitmap. */ 154 struct SpriteState { SpriteStateSpriteState155 inline SpriteState() : 156 dirty(0), visible(false), 157 positionX(0), positionY(0), layer(0), alpha(1.0f), displayId(ADISPLAY_ID_DEFAULT), 158 surfaceWidth(0), surfaceHeight(0), surfaceDrawn(false), surfaceVisible(false) { 159 } 160 161 uint32_t dirty; 162 163 SpriteIcon icon; 164 bool visible; 165 float positionX; 166 float positionY; 167 int32_t layer; 168 float alpha; 169 SpriteTransformationMatrix transformationMatrix; 170 int32_t displayId; 171 172 sp<SurfaceControl> surfaceControl; 173 int32_t surfaceWidth; 174 int32_t surfaceHeight; 175 bool surfaceDrawn; 176 bool surfaceVisible; 177 wantSurfaceVisibleSpriteState178 inline bool wantSurfaceVisible() const { 179 return visible && alpha > 0.0f && icon.isValid(); 180 } 181 }; 182 183 /* Client interface for a sprite. 184 * Requests acquire a lock on the controller, update local state and request the 185 * controller to invalidate the sprite. 186 * The real heavy lifting of creating, resizing and redrawing surfaces happens 187 * asynchronously with no locks held except in short critical section to copy 188 * the sprite state before the work and update the sprite surface control afterwards. 189 */ 190 class SpriteImpl : public Sprite { 191 protected: 192 virtual ~SpriteImpl(); 193 194 public: 195 explicit SpriteImpl(const sp<SpriteController> controller); 196 197 virtual void setIcon(const SpriteIcon& icon); 198 virtual void setVisible(bool visible); 199 virtual void setPosition(float x, float y); 200 virtual void setLayer(int32_t layer); 201 virtual void setAlpha(float alpha); 202 virtual void setTransformationMatrix(const SpriteTransformationMatrix& matrix); 203 virtual void setDisplayId(int32_t displayId); 204 getStateLocked()205 inline const SpriteState& getStateLocked() const { 206 return mLocked.state; 207 } 208 resetDirtyLocked()209 inline void resetDirtyLocked() { 210 mLocked.state.dirty = 0; 211 } 212 setSurfaceLocked(const sp<SurfaceControl> & surfaceControl,int32_t width,int32_t height,bool drawn,bool visible)213 inline void setSurfaceLocked(const sp<SurfaceControl>& surfaceControl, 214 int32_t width, int32_t height, bool drawn, bool visible) { 215 mLocked.state.surfaceControl = surfaceControl; 216 mLocked.state.surfaceWidth = width; 217 mLocked.state.surfaceHeight = height; 218 mLocked.state.surfaceDrawn = drawn; 219 mLocked.state.surfaceVisible = visible; 220 } 221 222 private: 223 sp<SpriteController> mController; 224 225 struct Locked { 226 SpriteState state; 227 } mLocked; // guarded by mController->mLock 228 229 void invalidateLocked(uint32_t dirty); 230 }; 231 232 /* Stores temporary information collected during the sprite update cycle. */ 233 struct SpriteUpdate { SpriteUpdateSpriteUpdate234 inline SpriteUpdate() : surfaceChanged(false) { } SpriteUpdateSpriteUpdate235 inline SpriteUpdate(const sp<SpriteImpl> sprite, const SpriteState& state) : 236 sprite(sprite), state(state), surfaceChanged(false) { 237 } 238 239 sp<SpriteImpl> sprite; 240 SpriteState state; 241 bool surfaceChanged; 242 }; 243 244 mutable Mutex mLock; 245 246 sp<Looper> mLooper; 247 const int32_t mOverlayLayer; 248 sp<WeakMessageHandler> mHandler; 249 ParentSurfaceProvider mParentSurfaceProvider; 250 251 sp<SurfaceComposerClient> mSurfaceComposerClient; 252 253 struct Locked { 254 std::vector<sp<SpriteImpl>> invalidatedSprites; 255 std::vector<sp<SurfaceControl>> disposedSurfaces; 256 uint32_t transactionNestingCount; 257 bool deferredSpriteUpdate; 258 } mLocked; // guarded by mLock 259 260 void invalidateSpriteLocked(const sp<SpriteImpl>& sprite); 261 void disposeSurfaceLocked(const sp<SurfaceControl>& surfaceControl); 262 263 void handleMessage(const Message& message); 264 void doUpdateSprites(); 265 void doDisposeSurfaces(); 266 267 void ensureSurfaceComposerClient(); 268 sp<SurfaceControl> obtainSurface(int32_t width, int32_t height); 269 }; 270 271 } // namespace android 272 273 #endif // _UI_SPRITES_H 274