src/third_party/skia/include/core/SkPixelRef.h

   1
   2 /*
   3  * Copyright 2008 The Android Open Source Project
   4  *
   5  * Use of this source code is governed by a BSD-style license that can be
   6  * found in the LICENSE file.
   7  */
   8
   9
  10 #ifndef SkPixelRef_DEFINED
  11 #define SkPixelRef_DEFINED
  12
  13 #include "SkBitmap.h"
  14 #include "SkRefCnt.h"
  15 #include "SkString.h"
  16 #include "SkFlattenable.h"
  17 #include "SkImageInfo.h"
  18 #include "SkTDArray.h"
  19
  20 //#define xed
  21
  22 #ifdef SK_DEBUG
  23     /**
  24      *  Defining SK_IGNORE_PIXELREF_SETPRELOCKED will force all pixelref
  25      *  subclasses to correctly handle lock/unlock pixels. For performance
  26      *  reasons, simple malloc-based subclasses call setPreLocked() to skip
  27      *  the overhead of implementing these calls.
  28      *
  29      *  This build-flag disables that optimization, to add in debugging our
  30      *  call-sites, to ensure that they correctly balance their calls of
  31      *  lock and unlock.
  32      */
  33 //    #define SK_IGNORE_PIXELREF_SETPRELOCKED
  34 #endif
  35
  36 class SkColorTable;
  37 class SkData;
  38 struct SkIRect;
  39 class SkMutex;
  40
  41 class GrTexture;
  42
  43 /** \class SkPixelRef
  44
  45     This class is the smart container for pixel memory, and is used with
  46     SkBitmap. A pixelref is installed into a bitmap, and then the bitmap can
  47     access the actual pixel memory by calling lockPixels/unlockPixels.
  48
  49     This class can be shared/accessed between multiple threads.
  50 */
  51 class SK_API SkPixelRef : public SkFlattenable {
  52 public:
  53     SK_DECLARE_INST_COUNT(SkPixelRef)
  54
  55     explicit SkPixelRef(const SkImageInfo&);
  56     SkPixelRef(const SkImageInfo&, SkBaseMutex* mutex);
  57     virtual ~SkPixelRef();
  58
  59     const SkImageInfo& info() const {
  60         return fInfo;
  61     }
  62
  63     /** Return the pixel memory returned from lockPixels, or null if the
  64         lockCount is 0.
  65     */
  66     void* pixels() const { return fRec.fPixels; }
  67
  68     /** Return the current colorTable (if any) if pixels are locked, or null.
  69     */
  70     SkColorTable* colorTable() const { return fRec.fColorTable; }
  71
  72     size_t rowBytes() const { return fRec.fRowBytes; }
  73
  74     /**
  75      *  To access the actual pixels of a pixelref, it must be "locked".
  76      *  Calling lockPixels returns a LockRec struct (on success).
  77      */
  78     struct LockRec {
  79         void*           fPixels;
  80         SkColorTable*   fColorTable;
  81         size_t          fRowBytes;
  82
  83         void zero() { sk_bzero(this, sizeof(*this)); }
  84
  85         bool isZero() const {
  86             return NULL == fPixels && NULL == fColorTable && 0 == fRowBytes;
  87         }
  88     };
  89
  90     /**
  91      *  Returns true if the lockcount > 0
  92      */
  93     bool isLocked() const { return fLockCount > 0; }
  94
  95     SkDEBUGCODE(int getLockCount() const { return fLockCount; })
  96
  97     /**
  98      *  Call to access the pixel memory. Return true on success. Balance this
  99      *  with a call to unlockPixels().
 100      */
 101     bool lockPixels();
 102
 103     /**
 104      *  Call to access the pixel memory. On success, return true and fill out
 105      *  the specified rec. On failure, return false and ignore the rec parameter.
 106      *  Balance this with a call to unlockPixels().
 107      */
 108     bool lockPixels(LockRec* rec);
 109
 110     /** Call to balanace a previous call to lockPixels(). Returns the pixels
 111         (or null) after the unlock. NOTE: lock calls can be nested, but the
 112         matching number of unlock calls must be made in order to free the
 113         memory (if the subclass implements caching/deferred-decoding.)
 114     */
 115     void unlockPixels();
 116
 117     /**
 118      *  Some bitmaps can return a copy of their pixels for lockPixels(), but
 119      *  that copy, if modified, will not be pushed back. These bitmaps should
 120      *  not be used as targets for a raster device/canvas (since all pixels
 121      *  modifications will be lost when unlockPixels() is called.)
 122      */
 123     bool lockPixelsAreWritable() const;
 124
 125     /** Returns a non-zero, unique value corresponding to the pixels in this
 126         pixelref. Each time the pixels are changed (and notifyPixelsChanged is
 127         called), a different generation ID will be returned.
 128     */
 129     uint32_t getGenerationID() const;
 130
 131     /** Call this if you have changed the contents of the pixels. This will in-
 132         turn cause a different generation ID value to be returned from
 133         getGenerationID().
 134     */
 135     void notifyPixelsChanged();
 136
 137     /** Returns true if this pixelref is marked as immutable, meaning that the
 138         contents of its pixels will not change for the lifetime of the pixelref.
 139     */
 140     bool isImmutable() const { return fIsImmutable; }
 141
 142     /** Marks this pixelref is immutable, meaning that the contents of its
 143         pixels will not change for the lifetime of the pixelref. This state can
 144         be set on a pixelref, but it cannot be cleared once it is set.
 145     */
 146     void setImmutable();
 147
 148     /** Return the optional URI string associated with this pixelref. May be
 149         null.
 150     */
 151     const char* getURI() const { return fURI.size() ? fURI.c_str() : NULL; }
 152
 153     /** Copy a URI string to this pixelref, or clear the URI if the uri is null
 154      */
 155     void setURI(const char uri[]) {
 156         fURI.set(uri);
 157     }
 158
 159     /** Copy a URI string to this pixelref
 160      */
 161     void setURI(const char uri[], size_t len) {
 162         fURI.set(uri, len);
 163     }
 164
 165     /** Assign a URI string to this pixelref.
 166     */
 167     void setURI(const SkString& uri) { fURI = uri; }
 168
 169     /**
 170      *  If the pixelRef has an encoded (i.e. compressed) representation,
 171      *  return a ref to its data. If the pixelRef
 172      *  is uncompressed or otherwise does not have this form, return NULL.
 173      *
 174      *  If non-null is returned, the caller is responsible for calling unref()
 175      *  on the data when it is finished.
 176      */
 177     SkData* refEncodedData() {
 178         return this->onRefEncodedData();
 179     }
 180
 181     /**
 182      *  Experimental -- tells the caller if it is worth it to call decodeInto().
 183      *  Just an optimization at this point, to avoid checking the cache first.
 184      *  We may remove/change this call in the future.
 185      */
 186     bool implementsDecodeInto() {
 187         return this->onImplementsDecodeInto();
 188     }
 189
 190     /**
 191      *  Return a decoded instance of this pixelRef in bitmap. If this cannot be
 192      *  done, return false and the bitmap parameter is ignored/unchanged.
 193      *
 194      *  pow2 is the requeste power-of-two downscale that the caller needs. This
 195      *  can be ignored, and the "original" size can be returned, but if the
 196      *  underlying codec can efficiently return a smaller size, that should be
 197      *  done. Some examples:
 198      *
 199      *  To request the "base" version (original scale), pass 0 for pow2
 200      *  To request 1/2 scale version (1/2 width, 1/2 height), pass 1 for pow2
 201      *  To request 1/4 scale version (1/4 width, 1/4 height), pass 2 for pow2
 202      *  ...
 203      *
 204      *  If this returns true, then bitmap must be "locked" such that
 205      *  bitmap->getPixels() will return the correct address.
 206      */
 207     bool decodeInto(int pow2, SkBitmap* bitmap) {
 208         SkASSERT(pow2 >= 0);
 209         return this->onDecodeInto(pow2, bitmap);
 210     }
 211
 212     /** Are we really wrapping a texture instead of a bitmap?
 213      */
 214     virtual GrTexture* getTexture() { return NULL; }
 215
 216     bool readPixels(SkBitmap* dst, const SkIRect* subset = NULL);
 217
 218     /**
 219      *  Makes a deep copy of this PixelRef, respecting the requested config.
 220      *  @param config Desired config.
 221      *  @param subset Subset of this PixelRef to copy. Must be fully contained within the bounds of
 222      *         of this PixelRef.
 223      *  @return A new SkPixelRef, or NULL if either there is an error (e.g. the destination could
 224      *          not be created with the given config), or this PixelRef does not support deep
 225      *          copies.
 226      */
 227     virtual SkPixelRef* deepCopy(SkBitmap::Config config, const SkIRect* subset = NULL) {
 228         return NULL;
 229     }
 230
 231 #ifdef SK_BUILD_FOR_ANDROID
 232     /**
 233      *  Acquire a "global" ref on this object.
 234      *  The default implementation just calls ref(), but subclasses can override
 235      *  this method to implement additional behavior.
 236      */
 237     virtual void globalRef(void* data=NULL);
 238
 239     /**
 240      *  Release a "global" ref on this object.
 241      *  The default implementation just calls unref(), but subclasses can override
 242      *  this method to implement additional behavior.
 243      */
 244     virtual void globalUnref();
 245 #endif
 246
 247     SK_DEFINE_FLATTENABLE_TYPE(SkPixelRef)
 248
 249     // Register a listener that may be called the next time our generation ID changes.
 250     //
 251     // We'll only call the listener if we're confident that we are the only SkPixelRef with this
 252     // generation ID.  If our generation ID changes and we decide not to call the listener, we'll
 253     // never call it: you must add a new listener for each generation ID change.  We also won't call
 254     // the listener when we're certain no one knows what our generation ID is.
 255     //
 256     // This can be used to invalidate caches keyed by SkPixelRef generation ID.
 257     struct GenIDChangeListener {
 258         virtual ~GenIDChangeListener() {}
 259         virtual void onChange() = 0;
 260     };
 261
 262     // Takes ownership of listener.
 263     void addGenIDChangeListener(GenIDChangeListener* listener);
 264
 265 protected:
 266 #ifdef SK_SUPPORT_LEGACY_ONLOCKPIXELS
 267     virtual void* onLockPixels(SkColorTable**);
 268     virtual bool onNewLockPixels(LockRec*);
 269 #else
 270     /**
 271      *  On success, returns true and fills out the LockRec for the pixels. On
 272      *  failure returns false and ignores the LockRec parameter.
 273      *
 274      *  The caller will have already acquired a mutex for thread safety, so this
 275      *  method need not do that.
 276      */
 277     virtual bool onNewLockPixels(LockRec*) = 0;
 278 #endif
 279
 280     /**
 281      *  Balancing the previous successful call to onNewLockPixels. The locked
 282      *  pixel address will no longer be referenced, so the subclass is free to
 283      *  move or discard that memory.
 284      *
 285      *  The caller will have already acquired a mutex for thread safety, so this
 286      *  method need not do that.
 287      */
 288     virtual void onUnlockPixels() = 0;
 289
 290     /** Default impl returns true */
 291     virtual bool onLockPixelsAreWritable() const;
 292
 293     // returns false;
 294     virtual bool onImplementsDecodeInto();
 295     // returns false;
 296     virtual bool onDecodeInto(int pow2, SkBitmap* bitmap);
 297
 298     /**
 299      *  For pixelrefs that don't have access to their raw pixels, they may be
 300      *  able to make a copy of them (e.g. if the pixels are on the GPU).
 301      *
 302      *  The base class implementation returns false;
 303      */
 304     virtual bool onReadPixels(SkBitmap* dst, const SkIRect* subsetOrNull);
 305
 306     // default impl returns NULL.
 307     virtual SkData* onRefEncodedData();
 308
 309     /**
 310      *  Returns the size (in bytes) of the internally allocated memory.
 311      *  This should be implemented in all serializable SkPixelRef derived classes.
 312      *  SkBitmap::fPixelRefOffset + SkBitmap::getSafeSize() should never overflow this value,
 313      *  otherwise the rendering code may attempt to read memory out of bounds.
 314      *
 315      *  @return default impl returns 0.
 316      */
 317     virtual size_t getAllocatedSizeInBytes() const;
 318
 319     /** Return the mutex associated with this pixelref. This value is assigned
 320         in the constructor, and cannot change during the lifetime of the object.
 321     */
 322     SkBaseMutex* mutex() const { return fMutex; }
 323
 324     // serialization
 325     SkPixelRef(SkFlattenableReadBuffer&, SkBaseMutex*);
 326     virtual void flatten(SkFlattenableWriteBuffer&) const SK_OVERRIDE;
 327
 328     // only call from constructor. Flags this to always be locked, removing
 329     // the need to grab the mutex and call onLockPixels/onUnlockPixels.
 330     // Performance tweak to avoid those calls (esp. in multi-thread use case).
 331     void setPreLocked(void*, size_t rowBytes, SkColorTable*);
 332
 333 private:
 334     SkBaseMutex*    fMutex; // must remain in scope for the life of this object
 335
 336     const SkImageInfo fInfo;
 337
 338     // LockRec is only valid if we're in a locked state (isLocked())
 339     LockRec         fRec;
 340     int             fLockCount;
 341
 342     mutable uint32_t fGenerationID;
 343     mutable bool     fUniqueGenerationID;
 344
 345     SkTDArray<GenIDChangeListener*> fGenIDChangeListeners;  // pointers are owned
 346
 347     SkString    fURI;
 348
 349     // can go from false to true, but never from true to false
 350     bool    fIsImmutable;
 351     // only ever set in constructor, const after that
 352     bool    fPreLocked;
 353
 354     void needsNewGenID();
 355     void callGenIDChangeListeners();
 356
 357     void setMutex(SkBaseMutex* mutex);
 358
 359     // When copying a bitmap to another with the same shape and config, we can safely
 360     // clone the pixelref generation ID too, which makes them equivalent under caching.
 361     friend class SkBitmap;  // only for cloneGenID
 362     void cloneGenID(const SkPixelRef&);
 363
 364     typedef SkFlattenable INHERITED;
 365 };
 366
 367 class SkPixelRefFactory : public SkRefCnt {
 368 public:
 369     /**
 370      *  Allocate a new pixelref matching the specified ImageInfo, allocating
 371      *  the memory for the pixels. If the ImageInfo requires a ColorTable,
 372      *  the pixelref will ref() the colortable.
 373      *  On failure return NULL.
 374      */
 375     virtual SkPixelRef* create(const SkImageInfo&, SkColorTable*) = 0;
 376 };
 377
 378 #endif