services/input/SpriteController.h

   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 {
  33     inline SpriteTransformationMatrix() : dsdx(1.0f), dtdx(0.0f), dsdy(0.0f), dtdy(1.0f) { }
  34     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 {
  58     inline SpriteIcon() : hotSpotX(0), hotSpotY(0) { }
  59     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
  66     inline SpriteIcon copy() const {
  67         SkBitmap bitmapCopy;
  68         bitmap.copyTo(&bitmapCopy, SkBitmap::kARGB_8888_Config);
  69         return SpriteIcon(bitmapCopy, hotSpotX, hotSpotY);
  70     }
  71
  72     inline void reset() {
  73         bitmap.reset();
  74         hotSpotX = 0;
  75         hotSpotY = 0;
  76     }
  77
  78     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:
  90     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
 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 {
 178         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
 200         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
 226         inline const SpriteState& getStateLocked() const {
 227             return mLocked.state;
 228         }
 229
 230         inline void resetDirtyLocked() {
 231             mLocked.state.dirty = 0;
 232         }
 233
 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 {
 255         inline SpriteUpdate() : surfaceChanged(false) { }
 256         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