include/core/SkBitmap.h

   1 /*
   2  * Copyright 2006 The Android Open Source Project
   3  *
   4  * Use of this source code is governed by a BSD-style license that can be
   5  * found in the LICENSE file.
   6  */
   7
   8 #ifndef SkBitmap_DEFINED
   9 #define SkBitmap_DEFINED
  10
  11 #include "SkColor.h"
  12 #include "SkColorTable.h"
  13 #include "SkImageInfo.h"
  14 #include "SkPoint.h"
  15 #include "SkRefCnt.h"
  16
  17 struct SkMask;
  18 struct SkIRect;
  19 struct SkRect;
  20 class SkPaint;
  21 class SkPixelRef;
  22 class SkPixelRefFactory;
  23 class SkRegion;
  24 class SkString;
  25 class GrTexture;
  26
  27 /** \class SkBitmap
  28
  29     The SkBitmap class specifies a raster bitmap. A bitmap has an integer width
  30     and height, and a format (colortype), and a pointer to the actual pixels.
  31     Bitmaps can be drawn into a SkCanvas, but they are also used to specify the
  32     target of a SkCanvas' drawing operations.
  33     A const SkBitmap exposes getAddr(), which lets a caller write its pixels;
  34     the constness is considered to apply to the bitmap's configuration, not
  35     its contents.
  36 */
  37 class SK_API SkBitmap {
  38 public:
  39     class SK_API Allocator;
  40
  41     /**
  42      *  Default construct creates a bitmap with zero width and height, and no pixels.
  43      *  Its colortype is set to kUnknown_SkColorType.
  44      */
  45     SkBitmap();
  46
  47     /**
  48      *  Copy the settings from the src into this bitmap. If the src has pixels
  49      *  allocated, they will be shared, not copied, so that the two bitmaps will
  50      *  reference the same memory for the pixels. If a deep copy is needed,
  51      *  where the new bitmap has its own separate copy of the pixels, use
  52      *  deepCopyTo().
  53      */
  54     SkBitmap(const SkBitmap& src);
  55
  56     ~SkBitmap();
  57
  58     /** Copies the src bitmap into this bitmap. Ownership of the src bitmap's pixels remains
  59         with the src bitmap.
  60     */
  61     SkBitmap& operator=(const SkBitmap& src);
  62     /** Swap the fields of the two bitmaps. This routine is guaranteed to never fail or throw.
  63     */
  64     //  This method is not exported to java.
  65     void swap(SkBitmap& other);
  66
  67     ///////////////////////////////////////////////////////////////////////////
  68
  69     const SkImageInfo& info() const { return fInfo; }
  70
  71     int width() const { return fInfo.width(); }
  72     int height() const { return fInfo.height(); }
  73     SkColorType colorType() const { return fInfo.colorType(); }
  74     SkAlphaType alphaType() const { return fInfo.alphaType(); }
  75     SkColorProfileType profileType() const { return fInfo.profileType(); }
  76
  77     /**
  78      *  Return the number of bytes per pixel based on the colortype. If the colortype is
  79      *  kUnknown_SkColorType, then 0 is returned.
  80      */
  81     int bytesPerPixel() const { return fInfo.bytesPerPixel(); }
  82
  83     /**
  84      *  Return the rowbytes expressed as a number of pixels (like width and height).
  85      *  If the colortype is kUnknown_SkColorType, then 0 is returned.
  86      */
  87     int rowBytesAsPixels() const {
  88         return fRowBytes >> this->shiftPerPixel();
  89     }
  90
  91     /**
  92      *  Return the shift amount per pixel (i.e. 0 for 1-byte per pixel, 1 for 2-bytes per pixel
  93      *  colortypes, 2 for 4-bytes per pixel colortypes). Return 0 for kUnknown_SkColorType.
  94      */
  95     int shiftPerPixel() const { return this->bytesPerPixel() >> 1; }
  96
  97     ///////////////////////////////////////////////////////////////////////////
  98
  99     /** Return true iff the bitmap has empty dimensions.
 100      *  Hey!  Before you use this, see if you really want to know drawsNothing() instead.
 101      */
 102     bool empty() const { return fInfo.isEmpty(); }
 103
 104     /** Return true iff the bitmap has no pixelref. Note: this can return true even if the
 105      *  dimensions of the bitmap are > 0 (see empty()).
 106      *  Hey!  Before you use this, see if you really want to know drawsNothing() instead.
 107      */
 108     bool isNull() const { return NULL == fPixelRef; }
 109
 110     /** Return true iff drawing this bitmap has no effect.
 111      */
 112     bool drawsNothing() const { return this->empty() || this->isNull(); }
 113
 114     /** Return the number of bytes between subsequent rows of the bitmap. */
 115     size_t rowBytes() const { return fRowBytes; }
 116
 117     /**
 118      *  Set the bitmap's alphaType, returning true on success. If false is
 119      *  returned, then the specified new alphaType is incompatible with the
 120      *  colortype, and the current alphaType is unchanged.
 121      *
 122      *  Note: this changes the alphatype for the underlying pixels, which means
 123      *  that all bitmaps that might be sharing (subsets of) the pixels will
 124      *  be affected.
 125      */
 126     bool setAlphaType(SkAlphaType);
 127
 128     /** Return the address of the pixels for this SkBitmap.
 129     */
 130     void* getPixels() const { return fPixels; }
 131
 132     /** Return the byte size of the pixels, based on the height and rowBytes.
 133         Note this truncates the result to 32bits. Call getSize64() to detect
 134         if the real size exceeds 32bits.
 135     */
 136     size_t getSize() const { return fInfo.height() * fRowBytes; }
 137
 138     /** Return the number of bytes from the pointer returned by getPixels()
 139         to the end of the allocated space in the buffer. Required in
 140         cases where extractSubset has been called.
 141     */
 142     size_t getSafeSize() const { return fInfo.getSafeSize(fRowBytes); }
 143
 144     /**
 145      *  Return the full size of the bitmap, in bytes.
 146      */
 147     int64_t computeSize64() const {
 148         return sk_64_mul(fInfo.height(), fRowBytes);
 149     }
 150
 151     /**
 152      *  Return the number of bytes from the pointer returned by getPixels()
 153      *  to the end of the allocated space in the buffer. This may be smaller
 154      *  than computeSize64() if there is any rowbytes padding beyond the width.
 155      */
 156     int64_t computeSafeSize64() const {
 157         return fInfo.getSafeSize64(fRowBytes);
 158     }
 159
 160     /** Returns true if this bitmap is marked as immutable, meaning that the
 161         contents of its pixels will not change for the lifetime of the bitmap.
 162     */
 163     bool isImmutable() const;
 164
 165     /** Marks this bitmap as immutable, meaning that the contents of its
 166         pixels will not change for the lifetime of the bitmap and of the
 167         underlying pixelref. This state can be set, but it cannot be
 168         cleared once it is set. This state propagates to all other bitmaps
 169         that share the same pixelref.
 170     */
 171     void setImmutable();
 172
 173     /** Returns true if the bitmap is opaque (has no translucent/transparent pixels).
 174     */
 175     bool isOpaque() const {
 176         return SkAlphaTypeIsOpaque(this->alphaType());
 177     }
 178
 179     /** Returns true if the bitmap is volatile (i.e. should not be cached by devices.)
 180     */
 181     bool isVolatile() const;
 182
 183     /** Specify whether this bitmap is volatile. Bitmaps are not volatile by
 184         default. Temporary bitmaps that are discarded after use should be
 185         marked as volatile. This provides a hint to the device that the bitmap
 186         should not be cached. Providing this hint when appropriate can
 187         improve performance by avoiding unnecessary overhead and resource
 188         consumption on the device.
 189     */
 190     void setIsVolatile(bool);
 191
 192     /** Reset the bitmap to its initial state (see default constructor). If we are a (shared)
 193         owner of the pixels, that ownership is decremented.
 194     */
 195     void reset();
 196
 197     /**
 198      *  This will brute-force return true if all of the pixels in the bitmap
 199      *  are opaque. If it fails to read the pixels, or encounters an error,
 200      *  it will return false.
 201      *
 202      *  Since this can be an expensive operation, the bitmap stores a flag for
 203      *  this (isOpaque). Only call this if you need to compute this value from
 204      *  "unknown" pixels.
 205      */
 206     static bool ComputeIsOpaque(const SkBitmap&);
 207
 208     /**
 209      *  Return the bitmap's bounds [0, 0, width, height] as an SkRect
 210      */
 211     void getBounds(SkRect* bounds) const;
 212     void getBounds(SkIRect* bounds) const;
 213
 214     SkIRect bounds() const { return fInfo.bounds(); }
 215     SkISize dimensions() const { return fInfo.dimensions(); }
 216
 217     bool setInfo(const SkImageInfo&, size_t rowBytes = 0);
 218
 219     /**
 220      *  Allocate the bitmap's pixels to match the requested image info. If the Factory
 221      *  is non-null, call it to allcoate the pixelref. If the ImageInfo requires
 222      *  a colortable, then ColorTable must be non-null, and will be ref'd.
 223      *  On failure, the bitmap will be set to empty and return false.
 224      */
 225     bool SK_WARN_UNUSED_RESULT tryAllocPixels(const SkImageInfo&, SkPixelRefFactory*, SkColorTable*);
 226
 227     void allocPixels(const SkImageInfo& info, SkPixelRefFactory* factory, SkColorTable* ctable) {
 228         if (!this->tryAllocPixels(info, factory, ctable)) {
 229             sk_throw();
 230         }
 231     }
 232
 233     /**
 234      *  Allocate the bitmap's pixels to match the requested image info and
 235      *  rowBytes. If the request cannot be met (e.g. the info is invalid or
 236      *  the requested rowBytes are not compatible with the info
 237      *  (e.g. rowBytes < info.minRowBytes() or rowBytes is not aligned with
 238      *  the pixel size specified by info.colorType()) then false is returned
 239      *  and the bitmap is set to empty.
 240      */
 241     bool SK_WARN_UNUSED_RESULT tryAllocPixels(const SkImageInfo& info, size_t rowBytes);
 242
 243     void allocPixels(const SkImageInfo& info, size_t rowBytes) {
 244         if (!this->tryAllocPixels(info, rowBytes)) {
 245             sk_throw();
 246         }
 247     }
 248
 249     bool SK_WARN_UNUSED_RESULT tryAllocPixels(const SkImageInfo& info) {
 250         return this->tryAllocPixels(info, info.minRowBytes());
 251     }
 252
 253     void allocPixels(const SkImageInfo& info) {
 254         this->allocPixels(info, info.minRowBytes());
 255     }
 256
 257     bool SK_WARN_UNUSED_RESULT tryAllocN32Pixels(int width, int height, bool isOpaque = false) {
 258         SkImageInfo info = SkImageInfo::MakeN32(width, height,
 259                                             isOpaque ? kOpaque_SkAlphaType : kPremul_SkAlphaType);
 260         return this->tryAllocPixels(info);
 261     }
 262
 263     void allocN32Pixels(int width, int height, bool isOpaque = false) {
 264         SkImageInfo info = SkImageInfo::MakeN32(width, height,
 265                                             isOpaque ? kOpaque_SkAlphaType : kPremul_SkAlphaType);
 266         this->allocPixels(info);
 267     }
 268
 269     /**
 270      *  Install a pixelref that wraps the specified pixels and rowBytes, and
 271      *  optional ReleaseProc and context. When the pixels are no longer
 272      *  referenced, if releaseProc is not null, it will be called with the
 273      *  pixels and context as parameters.
 274      *  On failure, the bitmap will be set to empty and return false.
 275      */
 276     bool installPixels(const SkImageInfo&, void* pixels, size_t rowBytes, SkColorTable*,
 277                        void (*releaseProc)(void* addr, void* context), void* context);
 278
 279     /**
 280      *  Call installPixels with no ReleaseProc specified. This means that the
 281      *  caller must ensure that the specified pixels are valid for the lifetime
 282      *  of the created bitmap (and its pixelRef).
 283      */
 284     bool installPixels(const SkImageInfo& info, void* pixels, size_t rowBytes) {
 285         return this->installPixels(info, pixels, rowBytes, NULL, NULL, NULL);
 286     }
 287
 288     /**
 289      *  Calls installPixels() with the value in the SkMask. The caller must
 290      *  ensure that the specified mask pixels are valid for the lifetime
 291      *  of the created bitmap (and its pixelRef).
 292      */
 293     bool installMaskPixels(const SkMask&);
 294
 295     /** Use this to assign a new pixel address for an existing bitmap. This
 296         will automatically release any pixelref previously installed. Only call
 297         this if you are handling ownership/lifetime of the pixel memory.
 298
 299         If the bitmap retains a reference to the colortable (assuming it is
 300         not null) it will take care of incrementing the reference count.
 301
 302         @param pixels   Address for the pixels, managed by the caller.
 303         @param ctable   ColorTable (or null) that matches the specified pixels
 304     */
 305     void setPixels(void* p, SkColorTable* ctable = NULL);
 306
 307     /** Copies the bitmap's pixels to the location pointed at by dst and returns
 308         true if possible, returns false otherwise.
 309
 310         In the case when the dstRowBytes matches the bitmap's rowBytes, the copy
 311         may be made faster by copying over the dst's per-row padding (for all
 312         rows but the last). By setting preserveDstPad to true the caller can
 313         disable this optimization and ensure that pixels in the padding are not
 314         overwritten.
 315
 316         Always returns false for RLE formats.
 317
 318         @param dst      Location of destination buffer.
 319         @param dstSize  Size of destination buffer. Must be large enough to hold
 320                         pixels using indicated stride.
 321         @param dstRowBytes  Width of each line in the buffer. If 0, uses
 322                             bitmap's internal stride.
 323         @param preserveDstPad Must we preserve padding in the dst
 324     */
 325     bool copyPixelsTo(void* const dst, size_t dstSize, size_t dstRowBytes = 0,
 326                       bool preserveDstPad = false) const;
 327
 328     /** Use the standard HeapAllocator to create the pixelref that manages the
 329         pixel memory. It will be sized based on the current ImageInfo.
 330         If this is called multiple times, a new pixelref object will be created
 331         each time.
 332
 333         If the bitmap retains a reference to the colortable (assuming it is
 334         not null) it will take care of incrementing the reference count.
 335
 336         @param ctable   ColorTable (or null) to use with the pixels that will
 337                         be allocated. Only used if colortype == kIndex_8_SkColorType
 338         @return true if the allocation succeeds. If not the pixelref field of
 339                      the bitmap will be unchanged.
 340     */
 341     bool SK_WARN_UNUSED_RESULT tryAllocPixels(SkColorTable* ctable = NULL) {
 342         return this->tryAllocPixels(NULL, ctable);
 343     }
 344
 345     void allocPixels(SkColorTable* ctable = NULL) {
 346         this->allocPixels(NULL, ctable);
 347     }
 348
 349     /** Use the specified Allocator to create the pixelref that manages the
 350         pixel memory. It will be sized based on the current ImageInfo.
 351         If this is called multiple times, a new pixelref object will be created
 352         each time.
 353
 354         If the bitmap retains a reference to the colortable (assuming it is
 355         not null) it will take care of incrementing the reference count.
 356
 357         @param allocator The Allocator to use to create a pixelref that can
 358                          manage the pixel memory for the current ImageInfo.
 359                          If allocator is NULL, the standard HeapAllocator will be used.
 360         @param ctable   ColorTable (or null) to use with the pixels that will
 361                         be allocated. Only used if colortype == kIndex_8_SkColorType.
 362                         If it is non-null and the colortype is not indexed, it will
 363                         be ignored.
 364         @return true if the allocation succeeds. If not the pixelref field of
 365                      the bitmap will be unchanged.
 366     */
 367     bool SK_WARN_UNUSED_RESULT tryAllocPixels(Allocator* allocator, SkColorTable* ctable);
 368
 369     void allocPixels(Allocator* allocator, SkColorTable* ctable) {
 370         if (!this->tryAllocPixels(allocator, ctable)) {
 371             sk_throw();
 372         }
 373     }
 374
 375     /**
 376      *  Return the current pixelref object or NULL if there is none. This does
 377      *  not affect the refcount of the pixelref.
 378      */
 379     SkPixelRef* pixelRef() const { return fPixelRef; }
 380
 381     /**
 382      *  A bitmap can reference a subset of a pixelref's pixels. That means the
 383      *  bitmap's width/height can be <= the dimensions of the pixelref. The
 384      *  pixelref origin is the x,y location within the pixelref's pixels for
 385      *  the bitmap's top/left corner. To be valid the following must be true:
 386      *
 387      *  origin_x + bitmap_width  <= pixelref_width
 388      *  origin_y + bitmap_height <= pixelref_height
 389      *
 390      *  pixelRefOrigin() returns this origin, or (0,0) if there is no pixelRef.
 391      */
 392     SkIPoint pixelRefOrigin() const { return fPixelRefOrigin; }
 393
 394     /**
 395      *  Assign a pixelref and origin to the bitmap. Pixelrefs are reference,
 396      *  so the existing one (if any) will be unref'd and the new one will be
 397      *  ref'd. (x,y) specify the offset within the pixelref's pixels for the
 398      *  top/left corner of the bitmap. For a bitmap that encompases the entire
 399      *  pixels of the pixelref, these will be (0,0).
 400      */
 401     SkPixelRef* setPixelRef(SkPixelRef* pr, int dx, int dy);
 402
 403     SkPixelRef* setPixelRef(SkPixelRef* pr, const SkIPoint& origin) {
 404         return this->setPixelRef(pr, origin.fX, origin.fY);
 405     }
 406
 407     SkPixelRef* setPixelRef(SkPixelRef* pr) {
 408         return this->setPixelRef(pr, 0, 0);
 409     }
 410
 411     /** Call this to ensure that the bitmap points to the current pixel address
 412         in the pixelref. Balance it with a call to unlockPixels(). These calls
 413         are harmless if there is no pixelref.
 414     */
 415     void lockPixels() const;
 416     /** When you are finished access the pixel memory, call this to balance a
 417         previous call to lockPixels(). This allows pixelrefs that implement
 418         cached/deferred image decoding to know when there are active clients of
 419         a given image.
 420     */
 421     void unlockPixels() const;
 422
 423     /**
 424      *  Some bitmaps can return a copy of their pixels for lockPixels(), but
 425      *  that copy, if modified, will not be pushed back. These bitmaps should
 426      *  not be used as targets for a raster device/canvas (since all pixels
 427      *  modifications will be lost when unlockPixels() is called.)
 428      */
 429     bool lockPixelsAreWritable() const;
 430
 431     /** Call this to be sure that the bitmap is valid enough to be drawn (i.e.
 432         it has non-null pixels, and if required by its colortype, it has a
 433         non-null colortable. Returns true if all of the above are met.
 434     */
 435     bool readyToDraw() const {
 436         return this->getPixels() != NULL &&
 437                (this->colorType() != kIndex_8_SkColorType || fColorTable);
 438     }
 439
 440     /** Returns the pixelRef's texture, or NULL
 441      */
 442     GrTexture* getTexture() const;
 443
 444     /** Return the bitmap's colortable, if it uses one (i.e. colorType is
 445         Index_8) and the pixels are locked.
 446         Otherwise returns NULL. Does not affect the colortable's
 447         reference count.
 448     */
 449     SkColorTable* getColorTable() const { return fColorTable; }
 450
 451     /** Returns a non-zero, unique value corresponding to the pixels in our
 452         pixelref. Each time the pixels are changed (and notifyPixelsChanged
 453         is called), a different generation ID will be returned. Finally, if
 454         there is no pixelRef then zero is returned.
 455     */
 456     uint32_t getGenerationID() const;
 457
 458     /** Call this if you have changed the contents of the pixels. This will in-
 459         turn cause a different generation ID value to be returned from
 460         getGenerationID().
 461     */
 462     void notifyPixelsChanged() const;
 463
 464     /**
 465      *  Fill the entire bitmap with the specified color.
 466      *  If the bitmap's colortype does not support alpha (e.g. 565) then the alpha
 467      *  of the color is ignored (treated as opaque). If the colortype only supports
 468      *  alpha (e.g. A1 or A8) then the color's r,g,b components are ignored.
 469      */
 470     void eraseColor(SkColor c) const {
 471         this->eraseARGB(SkColorGetA(c), SkColorGetR(c), SkColorGetG(c),
 472                         SkColorGetB(c));
 473     }
 474
 475     /**
 476      *  Fill the entire bitmap with the specified color.
 477      *  If the bitmap's colortype does not support alpha (e.g. 565) then the alpha
 478      *  of the color is ignored (treated as opaque). If the colortype only supports
 479      *  alpha (e.g. A1 or A8) then the color's r,g,b components are ignored.
 480      */
 481     void eraseARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b) const;
 482
 483     SK_ATTR_DEPRECATED("use eraseARGB or eraseColor")
 484     void eraseRGB(U8CPU r, U8CPU g, U8CPU b) const {
 485         this->eraseARGB(0xFF, r, g, b);
 486     }
 487
 488     /**
 489      *  Fill the specified area of this bitmap with the specified color.
 490      *  If the bitmap's colortype does not support alpha (e.g. 565) then the alpha
 491      *  of the color is ignored (treated as opaque). If the colortype only supports
 492      *  alpha (e.g. A1 or A8) then the color's r,g,b components are ignored.
 493      */
 494     void eraseArea(const SkIRect& area, SkColor c) const;
 495
 496     /** Scroll (a subset of) the contents of this bitmap by dx/dy. If there are
 497         no pixels allocated (i.e. getPixels() returns null) the method will
 498         still update the inval region (if present). If the bitmap is immutable,
 499         do nothing and return false.
 500
 501         @param subset The subset of the bitmap to scroll/move. To scroll the
 502                       entire contents, specify [0, 0, width, height] or just
 503                       pass null.
 504         @param dx The amount to scroll in X
 505         @param dy The amount to scroll in Y
 506         @param inval Optional (may be null). Returns the area of the bitmap that
 507                      was scrolled away. E.g. if dx = dy = 0, then inval would
 508                      be set to empty. If dx >= width or dy >= height, then
 509                      inval would be set to the entire bounds of the bitmap.
 510         @return true if the scroll was doable. Will return false if the colortype is kUnkown or
 511                      if the bitmap is immutable.
 512                      If no pixels are present (i.e. getPixels() returns false)
 513                      inval will still be updated, and true will be returned.
 514     */
 515     bool scrollRect(const SkIRect* subset, int dx, int dy,
 516                     SkRegion* inval = NULL) const;
 517
 518     /**
 519      *  Return the SkColor of the specified pixel.  In most cases this will
 520      *  require un-premultiplying the color.  Alpha only colortypes (e.g. kAlpha_8_SkColorType)
 521      *  return black with the appropriate alpha set.  The value is undefined
 522      *  for kUnknown_SkColorType or if x or y are out of bounds, or if the bitmap
 523      *  does not have any pixels (or has not be locked with lockPixels()).
 524      */
 525     SkColor getColor(int x, int y) const;
 526
 527     /** Returns the address of the specified pixel. This performs a runtime
 528         check to know the size of the pixels, and will return the same answer
 529         as the corresponding size-specific method (e.g. getAddr16). Since the
 530         check happens at runtime, it is much slower than using a size-specific
 531         version. Unlike the size-specific methods, this routine also checks if
 532         getPixels() returns null, and returns that. The size-specific routines
 533         perform a debugging assert that getPixels() is not null, but they do
 534         not do any runtime checks.
 535     */
 536     void* getAddr(int x, int y) const;
 537
 538     /** Returns the address of the pixel specified by x,y for 32bit pixels.
 539      *  In debug build, this asserts that the pixels are allocated and locked,
 540      *  and that the colortype is 32-bit, however none of these checks are performed
 541      *  in the release build.
 542      */
 543     inline uint32_t* getAddr32(int x, int y) const;
 544
 545     /** Returns the address of the pixel specified by x,y for 16bit pixels.
 546      *  In debug build, this asserts that the pixels are allocated and locked,
 547      *  and that the colortype is 16-bit, however none of these checks are performed
 548      *  in the release build.
 549      */
 550     inline uint16_t* getAddr16(int x, int y) const;
 551
 552     /** Returns the address of the pixel specified by x,y for 8bit pixels.
 553      *  In debug build, this asserts that the pixels are allocated and locked,
 554      *  and that the colortype is 8-bit, however none of these checks are performed
 555      *  in the release build.
 556      */
 557     inline uint8_t* getAddr8(int x, int y) const;
 558
 559     /** Returns the color corresponding to the pixel specified by x,y for
 560      *  colortable based bitmaps.
 561      *  In debug build, this asserts that the pixels are allocated and locked,
 562      *  that the colortype is indexed, and that the colortable is allocated,
 563      *  however none of these checks are performed in the release build.
 564      */
 565     inline SkPMColor getIndex8Color(int x, int y) const;
 566
 567     /** Set dst to be a setset of this bitmap. If possible, it will share the
 568         pixel memory, and just point into a subset of it. However, if the colortype
 569         does not support this, a local copy will be made and associated with
 570         the dst bitmap. If the subset rectangle, intersected with the bitmap's
 571         dimensions is empty, or if there is an unsupported colortype, false will be
 572         returned and dst will be untouched.
 573         @param dst  The bitmap that will be set to a subset of this bitmap
 574         @param subset The rectangle of pixels in this bitmap that dst will
 575                       reference.
 576         @return true if the subset copy was successfully made.
 577     */
 578     bool extractSubset(SkBitmap* dst, const SkIRect& subset) const;
 579
 580     /** Makes a deep copy of this bitmap, respecting the requested colorType,
 581      *  and allocating the dst pixels on the cpu.
 582      *  Returns false if either there is an error (i.e. the src does not have
 583      *  pixels) or the request cannot be satisfied (e.g. the src has per-pixel
 584      *  alpha, and the requested colortype does not support alpha).
 585      *  @param dst The bitmap to be sized and allocated
 586      *  @param ct The desired colorType for dst
 587      *  @param allocator Allocator used to allocate the pixelref for the dst
 588      *                   bitmap. If this is null, the standard HeapAllocator
 589      *                   will be used.
 590      *  @return true if the copy was made.
 591      */
 592     bool copyTo(SkBitmap* dst, SkColorType ct, Allocator* = NULL) const;
 593
 594     bool copyTo(SkBitmap* dst, Allocator* allocator = NULL) const {
 595         return this->copyTo(dst, this->colorType(), allocator);
 596     }
 597
 598     /**
 599      *  Copy the bitmap's pixels into the specified buffer (pixels + rowBytes),
 600      *  converting them into the requested format (SkImageInfo). The src pixels are read
 601      *  starting at the specified (srcX,srcY) offset, relative to the top-left corner.
 602      *
 603      *  The specified ImageInfo and (srcX,srcY) offset specifies a source rectangle
 604      *
 605      *      srcR.setXYWH(srcX, srcY, dstInfo.width(), dstInfo.height());
 606      *
 607      *  srcR is intersected with the bounds of the bitmap. If this intersection is not empty,
 608      *  then we have two sets of pixels (of equal size). Replace the dst pixels with the
 609      *  corresponding src pixels, performing any colortype/alphatype transformations needed
 610      *  (in the case where the src and dst have different colortypes or alphatypes).
 611      *
 612      *  This call can fail, returning false, for several reasons:
 613      *  - If srcR does not intersect the bitmap bounds.
 614      *  - If the requested colortype/alphatype cannot be converted from the src's types.
 615      *  - If the src pixels are not available.
 616      */
 617     bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
 618                     int srcX, int srcY) const;
 619
 620     /**
 621      *  Returns true if this bitmap's pixels can be converted into the requested
 622      *  colorType, such that copyTo() could succeed.
 623      */
 624     bool canCopyTo(SkColorType colorType) const;
 625
 626     /** Makes a deep copy of this bitmap, keeping the copied pixels
 627      *  in the same domain as the source: If the src pixels are allocated for
 628      *  the cpu, then so will the dst. If the src pixels are allocated on the
 629      *  gpu (typically as a texture), the it will do the same for the dst.
 630      *  If the request cannot be fulfilled, returns false and dst is unmodified.
 631      */
 632     bool deepCopyTo(SkBitmap* dst) const;
 633
 634 #ifdef SK_BUILD_FOR_ANDROID
 635     bool hasHardwareMipMap() const {
 636         return (fFlags & kHasHardwareMipMap_Flag) != 0;
 637     }
 638
 639     void setHasHardwareMipMap(bool hasHardwareMipMap) {
 640         if (hasHardwareMipMap) {
 641             fFlags |= kHasHardwareMipMap_Flag;
 642         } else {
 643             fFlags &= ~kHasHardwareMipMap_Flag;
 644         }
 645     }
 646 #endif
 647
 648     bool extractAlpha(SkBitmap* dst) const {
 649         return this->extractAlpha(dst, NULL, NULL, NULL);
 650     }
 651
 652     bool extractAlpha(SkBitmap* dst, const SkPaint* paint,
 653                       SkIPoint* offset) const {
 654         return this->extractAlpha(dst, paint, NULL, offset);
 655     }
 656
 657     /** Set dst to contain alpha layer of this bitmap. If destination bitmap
 658         fails to be initialized, e.g. because allocator can't allocate pixels
 659         for it, dst will not be modified and false will be returned.
 660
 661         @param dst The bitmap to be filled with alpha layer
 662         @param paint The paint to draw with
 663         @param allocator Allocator used to allocate the pixelref for the dst
 664                          bitmap. If this is null, the standard HeapAllocator
 665                          will be used.
 666         @param offset If not null, it is set to top-left coordinate to position
 667                       the returned bitmap so that it visually lines up with the
 668                       original
 669     */
 670     bool extractAlpha(SkBitmap* dst, const SkPaint* paint, Allocator* allocator,
 671                       SkIPoint* offset) const;
 672
 673     SkDEBUGCODE(void validate() const;)
 674
 675     class Allocator : public SkRefCnt {
 676     public:
 677         SK_DECLARE_INST_COUNT(Allocator)
 678
 679         /** Allocate the pixel memory for the bitmap, given its dimensions and
 680             colortype. Return true on success, where success means either setPixels
 681             or setPixelRef was called. The pixels need not be locked when this
 682             returns. If the colortype requires a colortable, it also must be
 683             installed via setColorTable. If false is returned, the bitmap and
 684             colortable should be left unchanged.
 685         */
 686         virtual bool allocPixelRef(SkBitmap*, SkColorTable*) = 0;
 687     private:
 688         typedef SkRefCnt INHERITED;
 689     };
 690
 691     /** Subclass of Allocator that returns a pixelref that allocates its pixel
 692         memory from the heap. This is the default Allocator invoked by
 693         allocPixels().
 694     */
 695     class HeapAllocator : public Allocator {
 696     public:
 697         bool allocPixelRef(SkBitmap*, SkColorTable*) override;
 698     };
 699
 700     class RLEPixels {
 701     public:
 702         RLEPixels(int width, int height);
 703         virtual ~RLEPixels();
 704
 705         uint8_t* packedAtY(int y) const {
 706             SkASSERT((unsigned)y < (unsigned)fHeight);
 707             return fYPtrs[y];
 708         }
 709
 710         // called by subclasses during creation
 711         void setPackedAtY(int y, uint8_t* addr) {
 712             SkASSERT((unsigned)y < (unsigned)fHeight);
 713             fYPtrs[y] = addr;
 714         }
 715
 716     private:
 717         uint8_t** fYPtrs;
 718         int       fHeight;
 719     };
 720
 721     SK_TO_STRING_NONVIRT()
 722
 723 private:
 724     mutable SkPixelRef* fPixelRef;
 725     mutable int         fPixelLockCount;
 726     // These are just caches from the locked pixelref
 727     mutable void*       fPixels;
 728     mutable SkColorTable* fColorTable;    // only meaningful for kIndex8
 729
 730     SkIPoint    fPixelRefOrigin;
 731
 732     enum Flags {
 733         kImageIsVolatile_Flag   = 0x02,
 734 #ifdef SK_BUILD_FOR_ANDROID
 735         /* A hint for the renderer responsible for drawing this bitmap
 736          * indicating that it should attempt to use mipmaps when this bitmap
 737          * is drawn scaled down.
 738          */
 739         kHasHardwareMipMap_Flag = 0x08,
 740 #endif
 741     };
 742
 743     SkImageInfo fInfo;
 744
 745     uint32_t    fRowBytes;
 746
 747     uint8_t     fFlags;
 748
 749     void internalErase(const SkIRect&, U8CPU a, U8CPU r, U8CPU g, U8CPU b)const;
 750
 751     /*  Unreference any pixelrefs or colortables
 752     */
 753     void freePixels();
 754     void updatePixelsFromRef() const;
 755
 756     static void WriteRawPixels(SkWriteBuffer*, const SkBitmap&);
 757     static bool ReadRawPixels(SkReadBuffer*, SkBitmap*);
 758
 759     friend class SkBitmapSource;    // unflatten
 760     friend class SkReadBuffer;      // unflatten, rawpixels
 761     friend class SkWriteBuffer;     // rawpixels
 762     friend struct SkBitmapProcState;
 763 };
 764
 765 class SkAutoLockPixels : SkNoncopyable {
 766 public:
 767     SkAutoLockPixels(const SkBitmap& bm, bool doLock = true) : fBitmap(bm) {
 768         fDidLock = doLock;
 769         if (doLock) {
 770             bm.lockPixels();
 771         }
 772     }
 773     ~SkAutoLockPixels() {
 774         if (fDidLock) {
 775             fBitmap.unlockPixels();
 776         }
 777     }
 778
 779 private:
 780     const SkBitmap& fBitmap;
 781     bool            fDidLock;
 782 };
 783 //TODO(mtklein): uncomment when 71713004 lands and Chromium's fixed.
 784 //#define SkAutoLockPixels(...) SK_REQUIRE_LOCAL_VAR(SkAutoLockPixels)
 785
 786 ///////////////////////////////////////////////////////////////////////////////
 787
 788 inline uint32_t* SkBitmap::getAddr32(int x, int y) const {
 789     SkASSERT(fPixels);
 790     SkASSERT(4 == this->bytesPerPixel());
 791     SkASSERT((unsigned)x < (unsigned)this->width() && (unsigned)y < (unsigned)this->height());
 792     return (uint32_t*)((char*)fPixels + y * fRowBytes + (x << 2));
 793 }
 794
 795 inline uint16_t* SkBitmap::getAddr16(int x, int y) const {
 796     SkASSERT(fPixels);
 797     SkASSERT(2 == this->bytesPerPixel());
 798     SkASSERT((unsigned)x < (unsigned)this->width() && (unsigned)y < (unsigned)this->height());
 799     return (uint16_t*)((char*)fPixels + y * fRowBytes + (x << 1));
 800 }
 801
 802 inline uint8_t* SkBitmap::getAddr8(int x, int y) const {
 803     SkASSERT(fPixels);
 804     SkASSERT(1 == this->bytesPerPixel());
 805     SkASSERT((unsigned)x < (unsigned)this->width() && (unsigned)y < (unsigned)this->height());
 806     return (uint8_t*)fPixels + y * fRowBytes + x;
 807 }
 808
 809 inline SkPMColor SkBitmap::getIndex8Color(int x, int y) const {
 810     SkASSERT(fPixels);
 811     SkASSERT(kIndex_8_SkColorType == this->colorType());
 812     SkASSERT((unsigned)x < (unsigned)this->width() && (unsigned)y < (unsigned)this->height());
 813     SkASSERT(fColorTable);
 814     return (*fColorTable)[*((const uint8_t*)fPixels + y * fRowBytes + x)];
 815 }
 816
 817 #endif